Choreo.ThreatModel (Choreo v0.9.0)

Copy Markdown View Source

STRIDE threat-modeling builder on top of Yog.

Choreo.ThreatModel extends dataflow diagrams with security semantics: trust boundaries, element classification, and automated STRIDE threat generation.

When to use

Use Choreo.ThreatModel during security review, threat-modeling sessions, or compliance audits. It automatically generates STRIDE threats, flags unencrypted boundary crossings, and surfaces attack paths from external entities to sensitive data stores.

Element types (per Microsoft Threat Modeling Tool)

  • :external_entity — user, browser, third-party system (outside your control)
  • :process — application, service, function (code you own)
  • :data_store — database, file, cache, queue (data at rest)

Trust boundaries

Trust boundaries are clusters that group elements by security domain. Data flows that cross a boundary are automatically flagged for elevated scrutiny.

Further reading

Quick Start

model =
  Choreo.ThreatModel.new()
  |> Choreo.ThreatModel.add_trust_boundary("internet", label: "Internet", level: 0)
  |> Choreo.ThreatModel.add_trust_boundary("app", label: "Application", level: 2)
  |> Choreo.ThreatModel.add_trust_boundary("db", label: "Database Zone", level: 3)
  |> Choreo.ThreatModel.add_external_entity(:user, label: "User", boundary: "internet")
  |> Choreo.ThreatModel.add_process(:api, label: "API Gateway", boundary: "app")
  |> Choreo.ThreatModel.add_data_store(:postgres, label: "Postgres", boundary: "db")
  |> Choreo.ThreatModel.data_flow(:user, :api, label: "HTTPS request")
  |> Choreo.ThreatModel.data_flow(:api, :postgres, label: "SQL query")

threats = Choreo.ThreatModel.Analysis.stride_threats(model)
dot = Choreo.ThreatModel.to_dot(model)

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; user [label="User", penwidth="2.0", fillcolor="#64748b", shape="box"]; api [label="API Gateway", fillcolor="#3b82f6", shape="circle"]; postgres [label="Postgres", fillcolor="#f59e0b", shape="cylinder"]; subgraph cluster_app { label="Application"; style=dashed; fillcolor="#f8fafc"; color="#ef4444"; api; } subgraph cluster_db { label="Database Zone"; style=dashed; fillcolor="#f8fafc"; color="#ef4444"; postgres; } subgraph cluster_internet { label="Internet"; style=dashed; fillcolor="#f8fafc"; color="#ef4444"; user; } user -> api [label="HTTPS request", style="dashed", penwidth="2.0", fontcolor="#ef4444", color="#ef4444"]; api -> postgres [label="SQL query", style="dashed", penwidth="2.0", fontcolor="#ef4444", color="#ef4444"]; }

Summary

Types

t()

Functions

add_data_store(model, id, opts \\ [])

Adds a data store (database, file, cache, queue).

add_external_entity(model, id, opts \\ [])

Adds an external entity (user, browser, third-party system).

add_process(model, id, opts \\ [])

Adds a process (application, service, function).

add_trust_boundary(model, name, opts \\ [])

Defines a trust boundary (security zone).

boundary_of(threat_model, id)

Returns the trust boundary name for an element, or nil.

crosses_boundary?(model, from, to)

Checks whether a data flow crosses a trust boundary.

data_flow(model, from, to, opts \\ [])

Creates a data-flow edge between two elements.

edges_with_meta(threat_model)

Returns all edges with their metadata as {from, to, weight, meta} tuples.

elements(threat_model)

Returns all element IDs in the model.

elements_of_type(threat_model, type)

Returns all elements of a given type.

flows(threat_model)

Returns all data flows as {from, to, label} tuples.

new(opts \\ [])

Creates a new empty threat model.

theme(name \\ :default, overrides \\ [])

Returns a theme for Choreo.ThreatModel.

to_dot(model, opts \\ [])

Renders the threat model to DOT format.

to_graph(threat_model)

Returns the raw Yog.Graph struct underpinning the model.

to_mermaid(model, opts \\ [])

Renders the threat model to Mermaid.js flowchart syntax.

to_plantuml(model, opts \\ [])

Renders the data flows in a threat model to a PlantUML sequence diagram string.

to_sequence(model, opts \\ [])

Renders the data flows in a threat model to a Mermaid sequence diagram string.

to_simple_graph(threat_model, opts \\ [])

Collapses parallel edges into a simple Graph for algorithm analysis.

trust_level(model, id)

Returns the numeric trust level of an element's boundary, or nil.

Types

t()

@type t() :: %Choreo.ThreatModel{
  clusters: %{required(String.t()) => map()},
  edge_meta: %{optional(Yog.Multi.Graph.edge_id()) => map()},
  graph: Yog.Multi.Graph.t(),
  strict: boolean()
}

Functions

add_data_store(model, id, opts \\ [])

Adds a data store (database, file, cache, queue).

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_data_store(model, :db, label: "Postgres", sensitivity: :confidential)
iex> Choreo.ThreatModel.elements(model)
[:db]
iex> Map.get(model.graph.nodes, :db).element_type
:data_store
iex> Map.get(model.graph.nodes, :db).sensitivity
:confidential

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; db [label="Postgres [confidential]", fillcolor="#f59e0b", shape="cylinder"]; }

add_external_entity(model, id, opts \\ [])

Adds an external entity (user, browser, third-party system).

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_external_entity(model, :user, label: "User")
iex> Choreo.ThreatModel.elements(model)
[:user]
iex> Map.get(model.graph.nodes, :user).element_type
:external_entity
iex> Map.get(model.graph.nodes, :user).label
"User"

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; user [label="User", penwidth="2.0", fillcolor="#64748b", shape="box"]; }

add_process(model, id, opts \\ [])

Adds a process (application, service, function).

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_process(model, :api, label: "API", privilege: :admin)
iex> Choreo.ThreatModel.elements(model)
[:api]
iex> Map.get(model.graph.nodes, :api).element_type
:process
iex> Map.get(model.graph.nodes, :api).privilege
:admin

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; api [label="API (admin)", fillcolor="#3b82f6", shape="circle"]; }

add_trust_boundary(model, name, opts \\ [])

@spec add_trust_boundary(t(), String.t(), keyword()) :: t()

Defines a trust boundary (security zone).

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_trust_boundary(model, "dmz", label: "DMZ", level: 1)
iex> model.clusters["cluster_dmz"].label
"DMZ"
iex> model.clusters["cluster_dmz"].level
1

boundary_of(threat_model, id)

@spec boundary_of(t(), Yog.node_id()) :: String.t() | nil

Returns the trust boundary name for an element, or nil.

The internal cluster_ prefix is stripped so the returned name matches the name originally passed to add_trust_boundary/3.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_trust_boundary("app")
...>   |> Choreo.ThreatModel.add_process(:api, boundary: "app")
iex> Choreo.ThreatModel.boundary_of(model, :api)
"app"

crosses_boundary?(model, from, to)

@spec crosses_boundary?(t(), Yog.node_id(), Yog.node_id()) :: boolean()

Checks whether a data flow crosses a trust boundary.

Returns false if either element has no assigned boundary, since a crossing requires both sides to be in defined security zones.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_trust_boundary("internet", level: 0)
...>   |> Choreo.ThreatModel.add_trust_boundary("app", level: 2)
...>   |> Choreo.ThreatModel.add_external_entity(:user, boundary: "internet")
...>   |> Choreo.ThreatModel.add_process(:api, boundary: "app")
...>   |> Choreo.ThreatModel.add_process(:worker, boundary: "app")
...>   |> Choreo.ThreatModel.data_flow(:user, :api)
...>   |> Choreo.ThreatModel.data_flow(:api, :worker)
iex> Choreo.ThreatModel.crosses_boundary?(model, :user, :api)
true
iex> Choreo.ThreatModel.crosses_boundary?(model, :api, :worker)
false

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; user [label="user", penwidth="2.0", fillcolor="#64748b", shape="box"]; worker [label="worker", fillcolor="#3b82f6", shape="circle"]; api [label="api", fillcolor="#3b82f6", shape="circle"]; subgraph cluster_app { label="cluster_app"; style=dashed; fillcolor="#f8fafc"; color="#ef4444"; worker; api; } subgraph cluster_internet { label="cluster_internet"; style=dashed; fillcolor="#f8fafc"; color="#ef4444"; user; } user -> api [label="", style="dashed", penwidth="2.0", fontcolor="#ef4444", color="#ef4444"]; api -> worker [label="", penwidth="1.0", fontcolor="#64748b", color="#64748b"]; }

data_flow(model, from, to, opts \\ [])

Creates a data-flow edge between two elements.

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user)
...>   |> Choreo.ThreatModel.add_process(:api)
...>   |> Choreo.ThreatModel.data_flow(:user, :api, label: "request")
iex> Choreo.ThreatModel.flows(model)
[{:user, :api, "request"}]
iex> [{_, _, _, meta}] = Choreo.ThreatModel.edges_with_meta(model)
iex> meta.label
"request"
iex> meta.encrypted
false

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=0.6, ranksep=1.2]; node [shape=box, style=filled, fillcolor="white", fontname="Helvetica", fontsize=12, fontcolor="white"]; edge [arrowhead=normal, color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; user [label="user", penwidth="2.0", fillcolor="#64748b", shape="box"]; api [label="api", fillcolor="#3b82f6", shape="circle"]; user -> api [label="request", penwidth="1.0", fontcolor="#64748b", color="#64748b"]; }

edges_with_meta(threat_model)

@spec edges_with_meta(t()) :: [{Yog.node_id(), Yog.node_id(), any(), map()}]

Returns all edges with their metadata as {from, to, weight, meta} tuples.

elements(threat_model)

@spec elements(t()) :: [Yog.node_id()]

Returns all element IDs in the model.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user)
...>   |> Choreo.ThreatModel.add_process(:api)
iex> Enum.sort(Choreo.ThreatModel.elements(model))
[:api, :user]

elements_of_type(threat_model, type)

@spec elements_of_type(t(), atom()) :: [Yog.node_id()]

Returns all elements of a given type.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user)
...>   |> Choreo.ThreatModel.add_process(:api)
iex> Choreo.ThreatModel.elements_of_type(model, :external_entity)
[:user]
iex> Choreo.ThreatModel.elements_of_type(model, :process)
[:api]
iex> Choreo.ThreatModel.elements_of_type(model, :data_store)
[]

flows(threat_model)

@spec flows(t()) :: [{Yog.node_id(), Yog.node_id(), any()}]

Returns all data flows as {from, to, label} tuples.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user)
...>   |> Choreo.ThreatModel.add_process(:api)
...>   |> Choreo.ThreatModel.data_flow(:user, :api)
iex> Choreo.ThreatModel.flows(model)
[{:user, :api, ""}]

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new empty threat model.

Options

  • :strict — if true, data_flow/4 raises when an endpoint does not already exist. Default false (auto-creates missing elements as :process).

Examples

iex> model = Choreo.ThreatModel.new()
iex> Choreo.ThreatModel.elements(model)
[]
iex> Choreo.ThreatModel.flows(model)
[]

theme(name \\ :default, overrides \\ [])

@spec theme(
  atom(),
  keyword()
) :: Choreo.Theme.t()

Returns a theme for Choreo.ThreatModel.

Examples

iex> theme = Choreo.ThreatModel.theme(:default, graph_rankdir: :tb)
iex> theme.graph_rankdir
:tb

to_dot(model, opts \\ [])

@spec to_dot(
  t(),
  keyword()
) :: String.t()

Renders the threat model to DOT format.

Options

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user, label: "User")
...>   |> Choreo.ThreatModel.add_process(:api, label: "API")
...>   |> Choreo.ThreatModel.data_flow(:user, :api, label: "HTTPS")
iex> dot = Choreo.ThreatModel.to_dot(model)
iex> String.contains?(dot, "digraph")
true
iex> String.contains?(dot, "User")
true
iex> String.contains?(dot, "API")
true

to_graph(threat_model)

@spec to_graph(t()) :: Yog.graph()

Returns the raw Yog.Graph struct underpinning the model.

Examples

iex> model = Choreo.ThreatModel.new()
iex> graph = Choreo.ThreatModel.to_graph(model)
iex> graph.kind
:directed

to_mermaid(model, opts \\ [])

@spec to_mermaid(
  t(),
  keyword()
) :: String.t()

Renders the threat model to Mermaid.js flowchart syntax.

Options

  • :theme — :default, :dark, :warm, :forest, :ocean, or a Choreo.Theme struct
  • :direction — :lr (default), :td, :rl, :bt

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_external_entity(:user, label: "User")
...>   |> Choreo.ThreatModel.add_process(:api, label: "API")
...>   |> Choreo.ThreatModel.data_flow(:user, :api, label: "HTTPS")
iex> mermaid = Choreo.ThreatModel.to_mermaid(model)
iex> String.contains?(mermaid, "graph LR")
true

to_plantuml(model, opts \\ [])

@spec to_plantuml(
  t(),
  keyword()
) :: String.t()

Renders the data flows in a threat model to a PlantUML sequence diagram string.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_external_entity(model, :user, label: "Customer")
iex> model = Choreo.ThreatModel.add_process(model, :web_api, label: "Web API")
iex> model = Choreo.ThreatModel.data_flow(model, :user, :web_api, label: "HTTPS login")
iex> puml = Choreo.ThreatModel.to_plantuml(model)
iex> String.contains?(puml, "@startuml")
true
iex> String.contains?(puml, "user -> web_api")
true

to_sequence(model, opts \\ [])

@spec to_sequence(
  t(),
  keyword()
) :: String.t()

Renders the data flows in a threat model to a Mermaid sequence diagram string.

External entities render as actor, processes and data stores as participant. Unencrypted flows crossing trust boundaries use dashed arrows (-->) to visually flag insecure communication.

Options

No options are currently used, but the argument is reserved for future use.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = Choreo.ThreatModel.add_external_entity(model, :user, label: "Customer")
iex> model = Choreo.ThreatModel.add_process(model, :web_api, label: "Web API")
iex> model = Choreo.ThreatModel.data_flow(model, :user, :web_api, label: "HTTPS login")
iex> seq = Choreo.ThreatModel.to_sequence(model)
iex> String.contains?(seq, "sequenceDiagram")
true
iex> String.contains?(seq, "actor user")
true

to_simple_graph(threat_model, opts \\ [])

@spec to_simple_graph(
  t(),
  keyword()
) :: Yog.Graph.t()

Collapses parallel edges into a simple Graph for algorithm analysis.

trust_level(model, id)

@spec trust_level(t(), Yog.node_id()) :: integer() | nil

Returns the numeric trust level of an element's boundary, or nil.

Examples

iex> model = Choreo.ThreatModel.new()
iex> model = model
...>   |> Choreo.ThreatModel.add_trust_boundary("dmz", level: 1)
...>   |> Choreo.ThreatModel.add_process(:api, boundary: "dmz")
iex> Choreo.ThreatModel.trust_level(model, :api)
1