threat-model.yaml reference

threat-model.yaml is the canonical, machine-readable threat model of one feature. It is a valid Open Threat Model 0.2 document extended with four ThreatSpec keys. The JSON Schema is schemas/threat-model.schema.json; the engine validates against it and against the reference rules below on every write.

πŸ”—Top level

KeyOriginPurpose
otmVersionOTM"0.2.0"
projectOTMid, name, optional description, attributes
threatspecThreatSpecversion, generated, profiles, extends, sources, actors, surfaces, dispositions, exclusions
trustZonesOTMzones with risk.trustRating 0–100
assetsOTMdata and capabilities with risk.{confidentiality,integrity,availability} and attributes.{type,classification,source,capabilities}
componentsOTMtype, parent.trustZone, optional threats[] with state and mitigations[]
dataflowsOTMsource, destination (component, actor, or trust zone id), assets, attributes.crosses
threatsOTM + attributessee below
mitigationsOTM + attributessee below
requirementsThreatSpecSR-### security requirements
verificationThreatSpecappend-only evidence history
decisionsThreatSpecaccepted or transferred risks

πŸ”—Identifiers

EntityPatternExample
actoractor.<slug>actor.content-author
trust zonetz.<slug>tz.internal
assetasset.<slug>asset.rag-corpus
componentcomponent.<slug>component.agent
data flowflow.<slug>flow.retrieved-context
threatthreat.<slug>threat.rag-poisoning
mitigationmitigation.<slug>mitigation.context-isolation
requirementSR-###SR-003
verificationverification.<slug>verification.sr-003.2026-09-21
decisiondecision.<slug>decision.model-extraction

Ids are immutable. A renamed or superseded threat keeps its entry with attributes.status: retired and attributes.superseded_by.

πŸ”—threats[]

- id: threat.rag-poisoning
  name: A content author plants instructions in a document that steer the agent
  categories: [Tampering]                 # STRIDE or LINDDUN
  cwes: [CWE-1427]
  risk: { likelihood: 75, impact: 90 }    # 0–100; severity derived by the engine
  attributes:
    technique: prompt-injection-indirect  # profile technique id
    profile: llm
    mappings: { owasp-llm-2026: [LLM01, LLM08], owasp-asi-2026: [ASI01] }
    disposition: threat                   # threat | needs-clarification
    actor: actor.content-author
    assets: [asset.document]
    elements: [flow.retrieved-context]
    severity: critical                    # computed; override with severity_override {level, reason}; 'unrated' for needs-clarification
    constitution: "Principle III"         # optional: MUST principle at stake
    source: "spec.md#FR-003"              # evidence
    status: open                          # open | mitigated | accepted | transferred | retired

A threat with attributes.disposition: needs-clarification is a question, not a rated threat: give it risk: {likelihood: 0, impact: 0}, the engine sets severity: unrated, excludes it from severity counts and from C3/C10, and reports it as C12.

status is human- and engine-owned: the model command never sets mitigated; the converge command does when every linked requirement is verified.

πŸ”—mitigations[]

- id: mitigation.context-isolation
  name: Isolate retrieved content from instructions
  riskReduction: 60
  attributes:
    threats: [threat.rag-poisoning]       # required, β‰₯1
    kind: preventive                      # preventive | detective | corrective | deterrent
    touchpoints: [src/agent/prompt_builder.py]
    requirements: [SR-001]
    status: required                      # required | planned | implemented | verified | rejected

πŸ”—requirements[]

- id: SR-001
  statement: Retrieved documents MUST be delimited as untrusted data and MUST NOT alter tool-call policy.
  priority: P1
  mitigations: [mitigation.context-isolation]
  acceptance:
    - given: a corpus document containing an injected instruction
      when: the user asks an unrelated question
      then: no tool call is issued and the attempt is logged
  tasks: [T011, T012]                     # optional; tasks tagged [SR-001] (or [SR-001, SR-002]) in tasks.md count too; prose mentions do not

πŸ”—verification[] (append-only)

- id: verification.sr-001.2026-09-21
  requirement: SR-001
  method: test                            # test | review | scan | manual | evidence
  evidence: tests/agent/test_prompt_injection.py::test_corpus_injection_blocked
  result: pass                            # pass | fail | partial | inconclusive
  verdict: verified                       # verified | implemented-unverified | partial | missing
  justification: Test asserts no tool call on injected corpus content.
  verified_at: "2026-09-21T14:03:00Z"
  commit: a1b2c3d

πŸ”—decisions[]

- id: decision.model-extraction
  threat: threat.model-extraction
  status: accepted                        # accepted | transferred
  owner: "@hupe"
  rationale: Hosted third-party model; low impact
  expires: 2027-03-01

πŸ”—Reference rules (check C2)

  • components[].parent.trustZone β†’ trustZones[]
  • dataflows[].source/destination β†’ a component, actor, or trust zone
  • dataflows[].assets, threats[].attributes.assets, components[].attributes.tools β†’ assets[]
  • threats[].attributes.elements β†’ components, actors, trust zones, or dataflows
  • mitigations[].attributes.threats β†’ threats[]; mitigations[].attributes.requirements β†’ requirements[]
  • requirements[].mitigations β†’ mitigations[]
  • verification[].requirement β†’ requirements[]; decisions[].threat β†’ threats[]
  • A feature requirements[].id must not reuse an SR-### the baseline defines (validate, merge, and check reject it)

πŸ”—Requirement id scope

SR-### ids are local to a feature, the same as Spec Kit’s FR-###. Features are often developed on separate branches by different people and merged later, so no project-wide sequence can be kept, and two features may both define SR-001. Only the baseline is shared: a feature continues after the baseline’s highest id and must not reuse one.

Outside its feature, a requirement is identified as <feature-dir>/SR-###, e.g. 007-rag-assistant/SR-001. Evidence collection follows the same rule:

Marker in a test fileCounts as evidence for
SR-001 (bare)the feature that defines SR-001, if no other feature does. If several do, the file is reported under ambiguous_test_files and is not evidence.
rag-assistant/SR-001, 007-rag-assistant/SR-001, @pytest.mark.sr("rag-assistant/SR-001")that feature only
test_rag_assistant_sr_001 (identifier form)that feature only

The qualifier is the feature directory or its slug (the name without the numeric or timestamp prefix), joined by / or _, compared without regard to case or to -, _, .. A slug shared by two features (003-auth, 009-auth) does not qualify; use the full directory name. A qualifier that names no feature (as in docs/SR-001 or test_sr_001) is ignored and the marker counts as bare.

converge-scan reports the form to use as evidence.marker and lists files marked only for other features under evidence.other_feature_test_files; remediation tasks name the marker, and converge-apply rejects a verified verdict whose evidence pointer (path::test, path:line, path#L…) is an ambiguous file or another feature’s file. CamelCase identifiers (TestRagAssistantSR001) are not recognised as qualified; use a comment. Bare markers keep working while the number is not shared; new tests should be qualified from the start, which the companion preset’s tasks instruction asks for.

πŸ”—Exclusions

threatspec:
  exclusions:
    - entity: Open Event
      reason: Folded into a counter column on Link; no separate asset

A spec key entity listed here is deliberately out of the model, and check C8 skips it. The reason is mandatory.

πŸ”—Baseline inheritance

threatspec.extends may point at a project-level model (by convention .specify/memory/threat-model.yaml). Entities from the baseline are visible for reference resolution and rendering; the feature model wins on id clashes, except for requirements: baseline SR-### ids are shared by every feature, so a feature requirement that reuses a baseline id is a C2 error. Ids defined by other features are not visible and may repeat (see Requirement id scope). The baseline is never written by feature commands.

πŸ”—Drift hashes

threatspec.sources[] records a SHA-256 per source file. The hash is computed on universal-newline text with trailing newlines trimmed, so a CRLF checkout on Windows produces the same digest as an LF one. For spec.md the ThreatSpec-managed block (between <!-- threatspec:begin --> and <!-- threatspec:end -->) is removed first, so rendering the SR block never counts as drift; any edit outside the markers does.

πŸ”—Determinism

The engine writes entities sorted by id with a fixed key order, so regenerating an unchanged model yields a byte-identical file and diffs stay reviewable.

Edit this page on GitHub