From 3a39e4ca126c178e20e764244afb37e683da6637 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Sun, 15 Nov 2026 16:40:56 -0800 Subject: [PATCH 1/7] Add threat model security object --- spec_objects_security/manifest.yaml | 54 +++- .../schemas/DecisionState.json | 11 + spec_objects_security/schemas/Risk.json | 43 ++- .../schemas/ThreatModel.json | 58 ++++ .../schemas/ThreatModelMethod.json | 10 + spec_objects_security/skeletons/risk.md | 5 +- .../skeletons/threat_model.md | 41 +++ tests/conftest.py | 5 +- tests/test_manifest_semantic.py | 3 +- tests/test_role_schemas.py | 15 +- tests/test_security_rules.py | 8 +- tests/test_threat_model.py | 280 ++++++++++++++++++ typespec/main.tsp | 51 +++- 13 files changed, 571 insertions(+), 13 deletions(-) create mode 100644 spec_objects_security/schemas/DecisionState.json create mode 100644 spec_objects_security/schemas/ThreatModel.json create mode 100644 spec_objects_security/schemas/ThreatModelMethod.json create mode 100644 spec_objects_security/skeletons/threat_model.md create mode 100644 tests/test_threat_model.py diff --git a/spec_objects_security/manifest.yaml b/spec_objects_security/manifest.yaml index 41debf1..7fb6633 100644 --- a/spec_objects_security/manifest.yaml +++ b/spec_objects_security/manifest.yaml @@ -31,6 +31,7 @@ semantic: - audit_finding - soup_record - scope_exclusion + - threat_model imports: {} targets: [json-schema, markdown] mappings: [typed-table, sysml-fence, ocl-clause, record-sections] @@ -45,6 +46,9 @@ nav: label: Security icon: ShieldCheck order: 54 +edge_types: + covers: { description: "A source document covers a target: the target is in its scope.", category: governance } + considers: { description: "Threat model considers the threat at the target.", category: governance } archetypes: [] grammars: [] artifact_types: [] @@ -423,7 +427,7 @@ object_types: required: false - name: threat allowed_links: - threatens: [asset, attack_surface] + threatens: [asset, attack_surface, connection, data_sink, trust_boundary] exploits: [vulnerability] data_schema: schema: schemas/Threat.json @@ -515,6 +519,16 @@ object_types: path: - impact required: true + decision: + from: frontmatter_field + path: + - decision + required: true + decided_by: + from: frontmatter_field + path: + - decided_by + required: false # FR-005: the typed `## Properties` table the # semantic layer reads. Optional, so existing artifacts stay valid. properties: @@ -694,6 +708,44 @@ object_types: from: section_body after_heading: Expires at required: false +- name: threat_model + allowed_links: + covers: [part, connection, data_sink, trust_boundary] + considers: [threat] + data_schema: + schema: schemas/ThreatModel.json + body_extraction: + yield_pattern: + match: + id: *id004 + title: *id005 + type: *id006 + method: + from: frontmatter_field + path: + - method + required: true + reviewed_by: + from: frontmatter_field + path: + - reviewed_by + required: true + scope: + from: section_body + after_heading: Scope + required: true + assumptions: + from: section_body + after_heading: Assumptions + required: true + out_of_scope: + from: section_body + after_heading: Out of scope + required: true + properties: + from: section_body + after_heading: Properties + required: false # FR-043: concrete-term lexicon — security / identity / auth objects. # FR-058 (quire-rs): upward-trace completeness — the second half of diff --git a/spec_objects_security/schemas/DecisionState.json b/spec_objects_security/schemas/DecisionState.json new file mode 100644 index 0000000..884f19c --- /dev/null +++ b/spec_objects_security/schemas/DecisionState.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/DecisionState.json", + "type": "string", + "enum": [ + "undecided", + "accepted", + "not_accepted" + ], + "description": "The decision a person records on a risk. There is no default." +} diff --git a/spec_objects_security/schemas/Risk.json b/spec_objects_security/schemas/Risk.json index d719f2c..d4278b1 100644 --- a/spec_objects_security/schemas/Risk.json +++ b/spec_objects_security/schemas/Risk.json @@ -36,10 +36,18 @@ "items": { "$ref": "https://schemas.agent-ix.org/semantic-core/0.4.4/SemanticId.json" } + }, + "decision": { + "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/DecisionState.json" + }, + "decided_by": { + "type": "string", + "minLength": 1 } }, "required": [ - "fields" + "fields", + "decision" ], "unevaluatedProperties": { "not": {} @@ -74,6 +82,39 @@ } } } + }, + { + "if": { + "properties": { + "decision": { + "enum": [ + "accepted", + "not_accepted" + ] + } + } + }, + "then": { + "required": [ + "decided_by" + ] + } + }, + { + "if": { + "properties": { + "decision": { + "const": "undecided" + } + } + }, + "then": { + "not": { + "required": [ + "decided_by" + ] + } + } } ] } diff --git a/spec_objects_security/schemas/ThreatModel.json b/spec_objects_security/schemas/ThreatModel.json new file mode 100644 index 0000000..dea8248 --- /dev/null +++ b/spec_objects_security/schemas/ThreatModel.json @@ -0,0 +1,58 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/ThreatModel.json", + "type": "object", + "properties": { + "fields": { + "type": "array", + "items": { + "$ref": "https://schemas.agent-ix.org/semantic-core/0.4.4/FieldDecl.json" + }, + "minItems": 1, + "contains": { + "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/IdentityField.json" + } + }, + "clauses": { + "type": "array", + "items": { + "$ref": "https://schemas.agent-ix.org/semantic-core/0.4.4/ClauseRef.json" + } + }, + "relations": { + "type": "array", + "items": { + "$ref": "https://schemas.agent-ix.org/semantic-core/0.4.4/RelationDecl.json" + } + }, + "method": { + "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/ThreatModelMethod.json" + }, + "reviewed_by": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "fields", + "method", + "reviewed_by" + ], + "unevaluatedProperties": { + "not": {} + }, + "description": "A scoped threat analysis a person wrote. `covers` and `considers` are edges\nauthored in the document's relationships, not members here. There is no\ndefault for `method` or `reviewed_by`.", + "allOf": [ + { + "properties": { + "fields": { + "items": { + "not": { + "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/DefaultedField.json" + } + } + } + } + } + ] +} diff --git a/spec_objects_security/schemas/ThreatModelMethod.json b/spec_objects_security/schemas/ThreatModelMethod.json new file mode 100644 index 0000000..6696ce0 --- /dev/null +++ b/spec_objects_security/schemas/ThreatModelMethod.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/ThreatModelMethod.json", + "type": "string", + "enum": [ + "stride_per_element", + "stride_per_interaction" + ], + "description": "How a threat model was worked: STRIDE applied to each element, or to each\ninteraction between elements. There is no `unknown` or `none` member." +} diff --git a/spec_objects_security/skeletons/risk.md b/spec_objects_security/skeletons/risk.md index 2283c9c..18bb3d4 100644 --- a/spec_objects_security/skeletons/risk.md +++ b/spec_objects_security/skeletons/risk.md @@ -5,11 +5,14 @@ type: risk object: risk likelihood: possible impact: major +decision: undecided --- diff --git a/spec_objects_security/skeletons/threat_model.md b/spec_objects_security/skeletons/threat_model.md new file mode 100644 index 0000000..9cfe171 --- /dev/null +++ b/spec_objects_security/skeletons/threat_model.md @@ -0,0 +1,41 @@ +--- +id: TM-001 +title: "TokenServiceThreatModel" +type: threat_model +object: threat_model +method: stride_per_interaction +reviewed_by: "A. Person" +--- + +# [TM-001] TokenServiceThreatModel + +## Scope + +The token endpoint and the tenant network edge, analysed per interaction with STRIDE. + +## Assumptions + +The tenant database is reachable only from inside the tenant VPC. + +## Out of scope + +The tenant browser and the identity provider. + +## Properties + +| Field | Type | Multiplicity | Constraints | +|---|---|---|---| +| threat_model_id | UUID | 1..1 | identity | +| method | String | 1..1 | minLength: 1 | +| reviewed_by | String | 1..1 | minLength: 1 | diff --git a/tests/conftest.py b/tests/conftest.py index 054def9..522ab7a 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -92,6 +92,7 @@ def engine_tool(name: str) -> str: "audit_finding", "soup_record", "scope_exclusion", + "threat_model", ) MODEL_OF = { @@ -120,6 +121,7 @@ def engine_tool(name: str) -> str: "audit_finding": "AuditFinding", "soup_record": "SoupRecord", "scope_exclusion": "ScopeExclusion", + "threat_model": "ThreatModel", } MARKER_MODELS = ( @@ -199,7 +201,7 @@ def engine_tool(name: str) -> str: # `TrustBoundary` whose `trust_level` defaulted to `trusted`, and defaulted # grant rows on `role`, `permission` and `scope` all validated. The ticket gate # reads "No schema default grants permission, trust, or control effectiveness", -# so the guard is now on all twenty-five (FR-006). +# so the guard is now on all twenty-six (FR-006). DEFAULT_REFUSING = OBJECT_TYPES FIELD_BEARING = ( @@ -222,6 +224,7 @@ def engine_tool(name: str) -> str: "control", "audit_event", "soup_record", + "threat_model", ) CLAUSE_BEARING = ( diff --git a/tests/test_manifest_semantic.py b/tests/test_manifest_semantic.py index e38edd5..7b24ef3 100644 --- a/tests/test_manifest_semantic.py +++ b/tests/test_manifest_semantic.py @@ -121,7 +121,8 @@ def test_two_records_of_different_types_are_distinguishable_by_schema_alone( field("risk_id", "UUID", identity=True), field("likelihood"), field("impact"), - ] + ], + "decision": "undecided", } assert schema_registry("Secret").is_valid(secret) assert not schema_registry("Risk").is_valid(secret) diff --git a/tests/test_role_schemas.py b/tests/test_role_schemas.py index b0b9663..d1e979a 100644 --- a/tests/test_role_schemas.py +++ b/tests/test_role_schemas.py @@ -111,9 +111,10 @@ def test_the_assessment_types_require_the_rows_that_score_them(schema_registry): assert not vuln.is_valid({"fields": [identity]}) risk = schema_registry("Risk") both = [identity, field("likelihood"), field("impact")] - assert risk.is_valid({"fields": both}) - assert not risk.is_valid({"fields": [identity, field("likelihood")]}) - assert not risk.is_valid({"fields": [identity, field("impact")]}) + decided = {"decision": "undecided"} + assert risk.is_valid({"fields": both, **decided}) + assert not risk.is_valid({"fields": [identity, field("likelihood")], **decided}) + assert not risk.is_valid({"fields": [identity, field("impact")], **decided}) finding = schema_registry("AuditFinding") assert finding.is_valid({"fields": [identity, field("status")]}) assert not finding.is_valid({"fields": [identity]}) @@ -205,7 +206,8 @@ def test_the_empty_record_fails_every_type(schema_registry): field("a", "UUID", identity=True), field("likelihood"), field("impact"), - ] + ], + "decision": "undecided", }, "AuditFinding": {"fields": [field("a", "UUID", identity=True), field("status")]}, "DataClassification": { @@ -223,6 +225,11 @@ def test_the_empty_record_fails_every_type(schema_registry): "AuthFlow": {"operations": [OPERATION]}, "AuditEvent": {"fields": [field("occurred_at", "Timestamp")]}, "SoupRecord": {"fields": [field("a", "UUID", identity=True), field("purl")]}, + "ThreatModel": { + "fields": [field("a", "UUID", identity=True)], + "method": "stride_per_element", + "reviewed_by": "A. Person", + }, "ScopeExclusion": { "set": "example.invalid/std@1", "clause": "EX-1", diff --git a/tests/test_security_rules.py b/tests/test_security_rules.py index d5dc007..30306dc 100644 --- a/tests/test_security_rules.py +++ b/tests/test_security_rules.py @@ -46,7 +46,8 @@ field("id", "UUID", identity=True), field("likelihood"), field("impact"), - ] + ], + "decision": "undecided", }, ), "Impact": ( @@ -57,7 +58,8 @@ field("id", "UUID", identity=True), field("likelihood"), field("impact"), - ] + ], + "decision": "undecided", }, ), "StrideCategory": ( @@ -184,7 +186,7 @@ def test_no_shipped_schema_carries_a_default_keyword(): @pytest.mark.trace("TC-073", "FR-006-AC-4", "FR-006-CON-2") def test_no_declaration_admits_a_defaulted_field_or_param(schema_registry): - """Every one of the twenty-five types, not only the sensitive four. + """Every one of the twenty-six types, not only the sensitive four. The rule began on `secret`, `encryption_key`, `jwt_claim` and `csrf_token`, which left it off exactly the rows that grant: a `Control` whose diff --git a/tests/test_threat_model.py b/tests/test_threat_model.py new file mode 100644 index 0000000..b53a7e4 --- /dev/null +++ b/tests/test_threat_model.py @@ -0,0 +1,280 @@ +"""The `threat_model` object type, wider `threat.threatens` targets, and the +`risk` decision fields (FR-026, FR-004).""" + +from __future__ import annotations + +import json +import re +import subprocess + +import pytest +import yaml + +from tests.conftest import ( + MANIFEST_PATH, + PACKAGE_ROOT, + SCHEMAS_DIR, + SKELETONS_DIR, + engine_tool, + field, +) + +def target_doc(kind: str, ident: str) -> str: + front = f'id: {ident}\ntitle: "{ident}"\ntype: {kind}\nobject: {kind}\n' + return f"---\n{front}---\n# {ident}\n' + + +def edges(*pairs: tuple[str, str]) -> str: + if not pairs: + return "" + lines = "".join(f" - target: {t}\n type: {v}\n" for v, t in pairs) + return f"relationships:\n{lines}" + + +def threat_model( + *, + method: str | None = "stride_per_element", + reviewed_by: str | None = '"A. Person"', + relationships: tuple[tuple[str, str], ...] = (("covers", "CONN-1"),), + sections: tuple[str, ...] = ("Scope", "Assumptions", "Out of scope"), +) -> str: + front = 'id: TM-1\ntitle: "TM"\ntype: threat_model\nobject: threat_model\n' + if method is not None: + front += f"method: {method}\n" + if reviewed_by is not None: + front += f"reviewed_by: {reviewed_by}\n" + front += edges(*relationships) + body = "".join(f"\n## {name}\n\nText for {name}.\n" for name in sections) + return ( + f"---\n{front}---\n# [TM-1] TM\n{body}\n## Properties\n\n" + "| Field | Type | Multiplicity | Constraints |\n|---|---|---|---|\n" + "| threat_model_id | UUID | 1..1 | identity |\n" + ) + + +def validate(tmp_path, documents: dict[str, str]) -> subprocess.CompletedProcess: + for name, text in documents.items(): + (tmp_path / name).write_text(text) + return subprocess.run( + [engine_tool("quire"), "validate", "--okf", "--module", str(PACKAGE_ROOT)] + + [str(tmp_path)], + capture_output=True, + text=True, + ) + + +def world() -> dict[str, str]: + return { + "conn.md": target_doc("connection", "CONN-1"), + "role.md": target_doc("role", "ROLE-1"), + "queue.md": target_doc("queue", "QUEUE-1"), + "threat.md": (SKELETONS_DIR / "threat.md") + .read_text() + .replace("THREAT-001", "THREAT-1"), + } + + +def errors(result: subprocess.CompletedProcess) -> list[str]: + return [ + line + for line in (result.stdout + result.stderr).splitlines() + if line + and not line.startswith(("warning:", "UnknownEdgeType:", "UnknownRole:")) + ] + + +def test_threat_model_with_covers_and_considers_validates(tmp_path): + docs = { + **world(), + "tm.md": threat_model( + relationships=(("covers", "CONN-1"), ("considers", "THREAT-1")) + ), + } + result = validate(tmp_path, docs) + assert result.returncode == 0 and not errors(result), result.stderr + + +def test_the_skeleton_validates(tmp_path): + result = validate( + tmp_path, {"tm.md": (SKELETONS_DIR / "threat_model.md").read_text()} + ) + assert not errors(result), result.stderr + + +def validate_doc(quire_engine, object_type: str, text: str) -> dict: + return quire_engine.validate_document(object_type, str(PACKAGE_ROOT), text) + + +def messages(result: dict) -> str: + return "\n".join(e["message"] for e in result["errors"]) + + +def test_method_guesswork_fails_naming_method(quire_engine): + result = validate_doc( + quire_engine, "threat_model", threat_model(method="guesswork") + ) + assert not result["is_valid"] + assert "method" in messages(result), result["errors"] + + +def test_missing_or_empty_reviewed_by_fails_naming_it(quire_engine): + for value in (None, '""'): + result = validate_doc( + quire_engine, "threat_model", threat_model(reviewed_by=value) + ) + assert not result["is_valid"], value + assert "reviewed_by" in messages(result), result["errors"] + + +@pytest.mark.parametrize("missing", ["Scope", "Assumptions", "Out of scope"]) +def test_a_missing_body_section_fails_naming_it(quire_engine, missing): + sections = tuple( + n for n in ("Scope", "Assumptions", "Out of scope") if n != missing + ) + result = validate_doc(quire_engine, "threat_model", threat_model(sections=sections)) + assert not result["is_valid"] + assert missing in messages(result), result["errors"] + + +def test_covers_to_a_role_is_a_wrong_kind_link(tmp_path): + result = validate( + tmp_path, + {**world(), "tm.md": threat_model(relationships=(("covers", "ROLE-1"),))}, + ) + out = result.stdout + result.stderr + assert "disallowed-edge-target" in out and "covers" in out, out + + +def test_considers_to_a_missing_id_is_dangling(tmp_path): + result = validate( + tmp_path, + { + **world(), + "tm.md": threat_model( + relationships=(("covers", "CONN-1"), ("considers", "THREAT-404")) + ), + }, + ) + out = result.stdout + result.stderr + assert "THREAT-404" in out, out + + +def threat_threatening(target: str) -> str: + threat = (SKELETONS_DIR / "threat.md").read_text().replace("THREAT-001", "THREAT-2") + return threat.replace( + "object: threat\n", "object: threat\n" + edges(("threatens", target)), 1 + ) + + +def test_threatens_a_connection_validates_and_a_queue_fails(tmp_path): + ok = validate( + tmp_path, + { + "conn.md": target_doc("connection", "CONN-1"), + "threat.md": threat_threatening("CONN-1"), + }, + ) + assert "disallowed-edge-target" not in ok.stdout + ok.stderr, ok.stderr + bad = validate( + tmp_path, + { + "queue.md": target_doc("queue", "QUEUE-1"), + "threat.md": threat_threatening("QUEUE-1"), + }, + ) + assert "disallowed-edge-target" in bad.stdout + bad.stderr, bad.stderr + + +def test_manifest_declares_the_verbs_and_the_link_targets(): + manifest = yaml.safe_load(MANIFEST_PATH.read_text()) + assert {"covers", "considers"} <= set(manifest["edge_types"]) + assert manifest["edge_types"]["considers"]["category"] == "governance" + types = {o["name"]: o for o in manifest["object_types"]} + assert types["threat_model"]["allowed_links"] == { + "covers": ["part", "connection", "data_sink", "trust_boundary"], + "considers": ["threat"], + } + assert types["threat"]["allowed_links"]["threatens"] == [ + "asset", + "attack_surface", + "connection", + "data_sink", + "trust_boundary", + ] + assert "threat_model" in manifest["semantic"]["exports"] + + +def test_method_enum_is_exactly_the_two_members(): + schema = json.loads((SCHEMAS_DIR / "ThreatModelMethod.json").read_text()) + assert schema["enum"] == ["stride_per_element", "stride_per_interaction"] + + +def test_threat_model_schema_requires_method_and_reviewed_by_and_has_no_default( + schema_registry, +): + text = (SCHEMAS_DIR / "ThreatModel.json").read_text() + assert '"default"' not in text + validator = schema_registry("ThreatModel") + record = { + "fields": [field("a", "UUID", identity=True)], + "method": "stride_per_interaction", + "reviewed_by": "A. Person", + } + assert validator.is_valid(record) + assert not validator.is_valid({}) + assert not validator.is_valid({**record, "method": "guesswork"}) + assert not validator.is_valid({**record, "reviewed_by": ""}) + assert not validator.is_valid( + {k: v for k, v in record.items() if k != "reviewed_by"} + ) + + +@pytest.mark.parametrize( + ("extra", "valid"), + [ + ({"decision": "accepted", "decided_by": "A. Person"}, True), + ({"decision": "not_accepted", "decided_by": "A. Person"}, True), + ({"decision": "undecided"}, True), + ({"decision": "accepted"}, False), + ({"decision": "undecided", "decided_by": "A. Person"}, False), + ({"decision": "maybe"}, False), + ({}, False), + ], +) +def test_risk_decision_rules(schema_registry, extra, valid): + record = { + "fields": [ + field("a", "UUID", identity=True), + field("likelihood"), + field("impact"), + ], + **extra, + } + assert schema_registry("Risk").is_valid(record) is valid + + +def risk_doc(**front) -> str: + text = (SKELETONS_DIR / "risk.md").read_text() + text = re.sub(r"^decision: .*\n", "", text, flags=re.M) + extra = "".join(f"{k}: {v}\n" for k, v in front.items()) + return text.replace("\n---\n