Expand threat-model support for Kivaar's complete M0 model

[scottescue]

Outcome

tracedoc can validate, render, and compare the complete Kivaar M0 system threat model required by kivaar#5, so Kivaar can replace the repository-local tools/reqmatrix implementation in kivaar#38 without losing structured content, validation guarantees, or human-review output.

Kivaar is the primary consumer and acceptance target for this work. Reuse by other repositories is desirable, but must not reduce or fragment the Kivaar artifact.

Context

The threat-model document type added in #2 establishes useful core mechanics, but the published shape is not sufficient for Kivaar's actual #5 artifact.

The current schema validates assets, trust boundaries, threats, ownership routing, mitigation identifiers, requirement links, and threat supersessions. Kivaar additionally requires a reviewable architecture-level model of actors, attacker capabilities, components, data flows, entry points, abuse paths, controls, planned evidence, observability, and diagrams. It also requires unresolved control and risk links to fail validation.

Several current semantics do not match the Kivaar contract:

• threat owner records milestone/workstream routing but not the accountable principal required for residual-risk ownership;
• past-tense dispositions such as mitigated and accepted describe outcome state, while Kivaar needs explicit treatment decisions such as mitigate, accept, avoid, and transfer;
• controls, risks, decisions, and planned evidence are not declared entities, so their links cannot be resolved;
• actors, attacker capabilities, components, flows, entry points, and observability expectations cannot be represented;
• strict unknown-field rejection means Kivaar cannot supply this information through document extensions or a custom template.

This repository is still evolving its pre-release contract. Expand the existing threat-model document and configuration in place. Keep the current document_type, threat-model schema_version, config_version, and CLI contract numbers. Multi-schema migration support is not part of this issue.

Required document support

Context and ownership

Support:

• document status, accountable principal, summary, scope, assumptions, and open questions;
• ownership that distinguishes an accountable principal from milestone, issue, and workstream routing;
• Kivaar's draft/acceptance workflow without implying that planned controls are implemented.

Architecture graph

Support declared, uniquely identified records for:

• components;
• actors;
• attacker capabilities and non-capabilities;
• assets and security objectives;
• trust boundaries, including source/destination components, data, channels, planned guarantees, validation, implementation state, and evidence;
• data flows, including ordered sequence, boundary links, and data handled;
• entry points, including their boundary and flow links.

Diagram generation and Mermaid parsing remain out of scope. The document may carry safe repository-relative diagram references, or another bounded representation sufficient to link the reviewed data-flow/trust-boundary diagram into the generated companion.

Assurance records

Support declared records for:

• decisions/ADRs;
• risks;
• controls;
• planned tests or evidence;
• observability expectations.

Controls must be able to link to requirements, decisions, risks, and planned evidence. Observability must capture the surface, required signals, redaction rules, alert condition, and related controls.

Each declared link must resolve. Individual control traceability categories may be empty, but a control must retain meaningful aggregate traceability.

Threats and abuse paths

Support structured threats with:

• stable ID and title;
• source, prerequisites, action, impact, and ordered abuse path;
• likelihood, impact/severity, priority, and rationales;
• explicit treatment/disposition;
• accountable owner and residual risk;
• affected actors, assets, boundaries, flows, controls, risks, and planned evidence;
• gaps, recommended mitigations, and detection ideas where retained by the final schema.

Vocabulary and coupling rules should remain schema-owned when validation depends on their exact meaning. Consumer-specific patterns and finite vocabularies may remain bounded configuration fields; do not introduce a general validation DSL.

Validation requirements

The validator must:

• retain the existing strict lexical, unknown-field, duplicate-member, size, depth, and single-value protections;
• reject duplicate IDs for every declared entity type;
• resolve every local reference against the correct entity collection;
• resolve requirement links against an active validated requirements document and reject retired or unknown IDs;
• reject unresolved control, decision, risk, and planned-evidence links;
• require trust-boundary endpoints to resolve to components;
• require data flows to resolve their boundaries;
• require entry points to resolve their boundary and flows;
• consider an entry point covered only when one threat references both its boundary and at least one of its flows;
• require declared assets, boundaries, flows, controls, and risks to be covered according to the Kivaar policy;
• require every threat to have accountable ownership, explicit treatment, residual-risk text, and planned evidence where the Kivaar policy requires it;
• enforce treatment coupling, including a risk record and rationale for accepted risk and mitigation/control evidence for mitigated risk;
• preserve threat supersession and stable-ID continuity checks.

Configuration may expose a finite set of named coverage switches if needed for secondary consumers. Kivaar's configuration must enable the complete coverage policy.

Rendering requirements

The default threat-model renderer and its template view must expose every supported record and produce one complete human-review companion containing:

• executive context and scope;
• actors and attacker model;
• architecture topology and diagram reference;
• assets, boundaries, flows, and entry points;
• prioritized threats and abuse paths;
• control and evidence traceability;
• residual risk and ownership;
• observability and redaction expectations;
• supersessions.

Rendering must remain deterministic and injection-resistant. Custom templates remain trusted consumer input, but Kivaar must not need a template to compensate for data the schema cannot represent.

Comparison requirements

compare must continue to enforce:

• threat deletion only through retained supersession;
• no reuse of retired threat IDs;
• immutable replacement sets;
• document-version and review-date transition policy over the complete expanded document.

Cross-version supersession ledgers for every non-threat entity are not required by this issue. Their IDs must still be unique and reference-safe within a snapshot.

Acceptance criteria

• The current Kivaar chore: rename the module and command to tracedoc #5 model can be represented without an unvalidated sidecar or loss of issue-required content.
• A complete consumer-neutral fixture exercises every new record type and relationship.
• CLI-level negative tests reject duplicate threat IDs, unsupported likelihood/severity/priority/treatment values, missing accountable owners, and unresolved requirement, control, decision, risk, and planned-evidence links.
• Topology tests reject unresolved components/boundaries/flows and false-positive entry-point coverage.
• Coverage tests reject declared but unanalyzed assets, boundaries, flows, controls, and risks under Kivaar's policy.
• Treatment-coupling and residual-risk rules have positive and negative tests.
• Default and custom rendering remain deterministic, escaped, and freshness-checkable.
• Threat supersession and full-document comparison tests continue to pass.
• CLI, schema, configuration, rendering, and versioning documentation describe the expanded contract.
• The race-enabled, dependency-free suite and both document self-checks pass.
• Kivaar can migrate both matrices to tracedoc and remove tools/reqmatrix after consuming the resulting release.

Non-goals

• A general-purpose schema or validation-rule language.
• Weakening Kivaar requirements to preserve the current compact threat schema.
• Complete support for arbitrary governance-document types.
• Diagram generation or a Mermaid parser.
• Authoring Kivaar's threat content in this repository.
• Multi-schema migration support or incrementing the current schema, configuration, or CLI contract numbers.

References

• kivaar#5
• kivaar#38
• Add a threat-model document type with cross-document requirement link validation #2
• Multi-schema-version reading to make require_major_on_schema_change reachable #4 (not required for this work)

[charles-fineman]

🤖 Starting work on this issue

[charles-fineman]

Deferred scope from this issue is tracked in #9: the four collections in Kivaar's model that this issue's "Required document support" does not list (criticality, focus_paths, quality_checks, top_abuse_path_links). That is the only gap between PR #8 and a zero-content-loss Kivaar migration.

Two migration edits Kivaar will need regardless, both mechanical:

• Asset IDs ASSET-NNN → AST-NNN (each collection has a distinct schema-owned prefix so links resolve unambiguously).
• Inline Mermaid diagram: []string moves into its own file, referenced as diagrams[].path. Diagram generation and Mermaid parsing stay out of scope per this issue; the schema carries the reference and renders it as a link.

[charles-fineman]

✅ Work completed. PR #8 is ready for final review.

Summary:

• All peer reviews addressed ✅ (security, Go, tests, documentation, architecture, doc-vs-code compliance)
• Follow-up issues created: [Architecture] Decide whether review-process collections belong in the threat-model schema #9 (deferred kivaar collections), [Documentation] Close remaining doc-vs-code gaps on the requirements matrix #10 (remaining requirements-matrix doc gaps)
• CI green; gofmt/go vet/race tests clean; all six fixture self-checks pass

Acceptance criteria: all met except the first, which is met apart from the four collections deferred to #9 by agreement — criticality, focus_paths, quality_checks, top_abuse_path_links. Those are the only gap between this PR and a zero-content-loss Kivaar migration.

Two fixes reach beyond this issue's scope, both found by review and both affecting the released v0.1.0 shape:

• Control characters were accepted in every scalar prose field on both document types, contradicting the guarantee in docs/schema.md and the 0.1.0 changelog. Fixed, which tightens validation for the requirements matrix too.
• risks[].id allowed Markdown injection that defeated the new reference_hosts allowlist through a field that is not a reference.

Kivaar migration notes: rename ASSET- IDs to AST-, and move inline Mermaid into a file referenced by diagrams[].path.

Next steps:

• Awaiting final approval from @scottescue
• Recommended next issue: [Architecture] Decide whether review-process collections belong in the threat-model schema #9, since it closes the Kivaar migration gap