diff --git a/spec/tests.md b/spec/tests.md index 1ea66ee..d09b06a 100644 --- a/spec/tests.md +++ b/spec/tests.md @@ -154,6 +154,8 @@ the Python package only: neither Node script is measured by it. | FR-024 | FR-024-AC-1..7 | TC-220..TC-223 | ✅ | | NFR-004 | NFR-004-AC-1..3, NFR-004-M-1..2 | TC-207, TC-211, TC-213, TC-214 | ✅ | | FR-017 | FR-017-AC-1..7 | TC-175..TC-186 | ✅ `quire clauses` loads strictly and cannot load the real module (the object-type edges come from another module), so TC-181, TC-183, TC-185 and TC-186 evaluate a module that holds only the set files | +| FR-026 | FR-026-AC-1..7, FR-026-AC-9..10 | TC-224..TC-236, TC-242..TC-243 | ✅ | +| FR-027 | FR-027-AC-6..7 | TC-237..TC-241 | ✅ | ### Integration Test Coverage @@ -344,6 +346,26 @@ the Python package only: neither Node script is measured by it. | TC-221 | trust_boundary requires frontmatter trust_level and refuses an absent or out-of-vocabulary value | Unit | P0 | FR-024-AC-1, FR-024-AC-2, FR-024-AC-3 | ✅ | | TC-222 | trust_level is extracted from frontmatter to the typed record key and is not derived from the Properties row | Unit | P0 | FR-024-AC-4, FR-024-AC-7 | ✅ | | TC-223 | the trust_boundary skeleton states an authored trust_level and validates | Unit | P0 | FR-024-AC-6 | ✅ | +| TC-224 | A threat model with a method, reviewer, covered connection, considered threat and all required sections validates | Integration | P0 | FR-026-AC-1 | ✅ | +| TC-225 | The threat-model skeleton validates | Integration | P0 | FR-026-AC-1, FR-026-AC-10 | ✅ | +| TC-226 | `method: guesswork` fails validation naming `method` | Integration | P0 | FR-026-AC-2 | ✅ | +| TC-227 | `ThreatModelMethod.json` has exactly the two declared members | Unit | P0 | FR-026-AC-2 | ✅ | +| TC-228 | A missing or empty `reviewed_by` fails validation naming the field | Integration | P0 | FR-026-AC-3 | ✅ | +| TC-229 | A threat model without a `covers` edge fails with the declared completeness diagnostic | Integration | P0 | FR-026-AC-4 | ✅ | +| TC-230 | `covers` edges to a part, connection, data sink and trust boundary validate | Integration | P0 | FR-026-AC-4 | ✅ | +| TC-231 | `covers` to a risk and `considers` to a control each yield a link diagnostic | Integration | P0 | FR-026-AC-5 | ✅ | +| TC-232 | A threat model with a `covers` edge and no `considers` edge validates | Integration | P0 | FR-026-AC-5 | ✅ | +| TC-233 | The manifest declares the scope and consideration links and the expanded threat targets | Unit | P0 | FR-026-AC-4, FR-026-AC-9, FR-027-AC-7 | ✅ | +| TC-234 | A missing required threat-model section fails naming that section | Integration | P0 | FR-026-AC-6 | ✅ | +| TC-235 | The threat-model schema has no defaults, requires its authored fields and extraction preserves their authored values | Integration | P0 | FR-026-AC-7, FR-026-AC-10 | ✅ | +| TC-236 | Removing either declared threat-model edge verb causes module loading to report the undeclared verb | Integration | P0 | FR-026-AC-9 | ✅ | +| TC-237 | A threat edge to a connection validates | Integration | P0 | FR-027-AC-7 | ✅ | +| TC-238 | A threat edge to a queue yields a disallowed-target diagnostic | Integration | P0 | FR-027-AC-7 | ✅ | +| TC-239 | Risk decision schema accepts valid decisions and rejects missing or inconsistent decision fields | Unit | P0 | FR-027-AC-6 | ✅ | +| TC-240 | Risk documents validate only when `decision` and `decided_by` satisfy the authored decision rule | Integration | P0 | FR-027-AC-6 | ✅ | +| TC-241 | The risk skeleton states `decision: undecided` | Unit | P0 | FR-027-AC-6 | ✅ | +| TC-242 | An empty `## Out of scope` section fails validation naming the section | Integration | P0 | FR-026-AC-6 | ✅ | +| TC-243 | `semantic.exports` contains twenty-six types including `threat_model` | Unit | P0 | FR-026-AC-10 | ✅ | ## Test Environment diff --git a/spec_objects_security/manifest.yaml b/spec_objects_security/manifest.yaml index 68348ee..cca68cf 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: [] @@ -427,7 +431,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 @@ -519,6 +523,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: @@ -698,6 +712,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 @@ -762,6 +814,12 @@ traceability: to: [FR, NFR, StR] direction: outgoing check: soup-serves-no-requirement + - name: threat-model-covers-something + from: threat_model + edges: [covers] + to: [] + direction: outgoing + check: threat-model-covers-nothing # # A risk that transitively arises from itself states nothing, and no # per-document check can see it: the defect is a property of the graph. 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.py b/tests/test_manifest.py index bb9dde3..ce6a97a 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -111,6 +111,7 @@ def test_threat_and_risk_coverage_is_declared_not_coded() -> None: "risk-has-treatment", "security-nfr-has-mitigation-target", "soup-record-serves-requirement", + "threat-model-covers-something", } assert by_name["threat-has-control"]["from"] == "threat" assert by_name["risk-has-treatment"]["from"] == "risk" @@ -121,6 +122,7 @@ def test_threat_and_risk_coverage_is_declared_not_coded() -> None: "untreated-risk", "unjustified-security-nfr", "soup-serves-no-requirement", + "threat-model-covers-nothing", } assert len(checks) == len(by_name), "each relation is independently tunable" @@ -140,6 +142,9 @@ def test_threat_and_risk_coverage_is_declared_not_coded() -> None: # FR-013: the reviewer authors the edge on the record. assert relation["from"] == "soup_record" assert relation["direction"] == "outgoing" + elif name == "threat-model-covers-something": + assert relation["from"] == "threat_model" + assert relation["direction"] == "outgoing" else: assert relation["direction"] == "incoming" assert relation["from"] in declared, relation["from"] 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 1f51a33..f3754c7 100644 --- a/tests/test_role_schemas.py +++ b/tests/test_role_schemas.py @@ -110,9 +110,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]}) @@ -207,7 +208,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": { @@ -225,6 +227,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..27b4518 --- /dev/null +++ b/tests/test_threat_model.py @@ -0,0 +1,457 @@ +"""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 shutil +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], *, extra_object_types: tuple[str, ...] = () +) -> subprocess.CompletedProcess: + bundle = tmp_path / "bundle" + bundle.mkdir(exist_ok=True) + for name, text in documents.items(): + (bundle / name).write_text(text) + module = PACKAGE_ROOT + if extra_object_types: + module = tmp_path / "modules" / "spec_objects_security" + shutil.copytree(PACKAGE_ROOT, module) + manifest_path = module / "manifest.yaml" + manifest = yaml.safe_load(manifest_path.read_text()) + for object_type in extra_object_types: + schema_name = f"Test{object_type.title().replace('_', '')}.json" + manifest["semantic"]["exports"].append(object_type) + manifest["object_types"].append( + { + "name": object_type, + "data_schema": {"schema": f"schemas/{schema_name}"}, + "body_extraction": {"yield_pattern": {"match": {}}}, + } + ) + (module / "schemas" / schema_name).write_text( + json.dumps( + { + "$id": f"https://schemas.agent-ix.org/test/{schema_name}", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": True, + } + ) + ) + manifest_path.write_text(yaml.safe_dump(manifest, sort_keys=False)) + return subprocess.run( + [engine_tool("quire"), "validate", "--okf", "--module", str(module)] + + [str(bundle)], + 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:")) + ] + + +@pytest.mark.trace("TC-224", "FR-026-AC-1") +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 + + +@pytest.mark.trace("TC-225", "FR-026-AC-1", "FR-026-AC-10") +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"]) + + +@pytest.mark.trace("TC-226", "FR-026-AC-2") +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"] + + +@pytest.mark.trace("TC-228", "FR-026-AC-3") +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"]) +@pytest.mark.trace("TC-234", "FR-026-AC-6") +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"] + + +@pytest.mark.trace("TC-242", "FR-026-AC-6") +def test_empty_out_of_scope_section_fails_naming_it(quire_engine): + document = threat_model().replace( + "## Out of scope\n\nText for Out of scope.\n", "## Out of scope\n\n" + ) + result = validate_doc(quire_engine, "threat_model", document) + assert not result["is_valid"] + assert "Out of scope" in messages(result), result["errors"] + + +@pytest.mark.trace("TC-229", "FR-026-AC-4") +def test_no_covers_edge_fails(tmp_path): + result = validate(tmp_path, {**world(), "tm.md": threat_model(relationships=())}) + out = result.stdout + result.stderr + assert "threat-model-covers-nothing" in out, out + + +@pytest.mark.trace("TC-230", "FR-026-AC-4") +def test_covers_each_allowed_model_element(tmp_path): + targets = { + "part": "PART-1", + "connection": "CONN-1", + "data_sink": "SINK-1", + "trust_boundary": "BOUND-1", + } + docs = { + **{f"{kind}.md": target_doc(kind, ident) for kind, ident in targets.items()}, + "tm.md": threat_model( + relationships=tuple(("covers", ident) for ident in targets.values()) + ), + } + result = validate( + tmp_path, docs, extra_object_types=("part", "connection", "data_sink") + ) + out = result.stdout + result.stderr + assert "disallowed-edge-target" not in out, out + + +@pytest.mark.trace("TC-231", "FR-026-AC-5") +def test_covers_risk_and_considers_control_are_disallowed(tmp_path): + docs = { + **world(), + "risk.md": target_doc("risk", "RISK-1"), + "control.md": target_doc("control", "CONTROL-1"), + } + covers_risk = validate( + tmp_path, + {**docs, "tm.md": threat_model(relationships=(("covers", "RISK-1"),))}, + ) + covers_out = covers_risk.stdout + covers_risk.stderr + assert "disallowed-edge-target" in covers_out and "covers" in covers_out + + considers_control = validate( + tmp_path, + { + **docs, + "tm.md": threat_model( + relationships=(("covers", "CONN-1"), ("considers", "CONTROL-1")) + ), + }, + ) + considers_out = considers_control.stdout + considers_control.stderr + assert "disallowed-edge-target" in considers_out and "considers" in considers_out + + +@pytest.mark.trace("TC-232", "FR-026-AC-5") +def test_threat_model_with_covers_and_no_considers_validates(tmp_path): + result = validate( + tmp_path, + {**world(), "tm.md": threat_model(relationships=(("covers", "CONN-1"),))}, + ) + out = result.stdout + result.stderr + assert "disallowed-edge-target" not in out, out + + +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 + ) + + +@pytest.mark.trace("TC-237", "FR-027-AC-7") +def test_threatens_a_connection_validates(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 + + +@pytest.mark.trace("TC-238", "FR-027-AC-7") +def test_threatens_does_not_allow_a_queue_target(tmp_path): + result = validate( + tmp_path, + { + "queue.md": target_doc("queue", "QUEUE-1"), + "threat.md": threat_threatening("QUEUE-1"), + }, + extra_object_types=("queue",), + ) + out = result.stdout + result.stderr + assert "disallowed-edge-target" in out and "threatens" in out, out + + +@pytest.mark.trace("TC-233", "FR-026-AC-4", "FR-026-AC-9") +@pytest.mark.trace("TC-233", "FR-027-AC-7") +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", + ] + + +@pytest.mark.trace("TC-243", "FR-026-AC-10") +def test_threat_model_is_the_twenty_sixth_export(): + manifest = yaml.safe_load(MANIFEST_PATH.read_text()) + assert "threat_model" in manifest["semantic"]["exports"] + assert len(manifest["semantic"]["exports"]) == 26 + + +@pytest.mark.trace("TC-227", "FR-026-AC-2") +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"] + + +@pytest.mark.trace("TC-235", "FR-026-AC-7", "FR-026-AC-10") +def test_threat_model_schema_requires_method_and_reviewed_by_and_has_no_default( + schema_registry, tmp_path +): + 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"} + ) + document = tmp_path / "threat_model.md" + document.write_text(threat_model()) + extracted = subprocess.run( + [ + engine_tool("quire"), + "extract", + "--module", + str(PACKAGE_ROOT), + str(document), + ], + check=True, + capture_output=True, + text=True, + ) + extracted_record = json.loads(extracted.stdout)["extraction"]["records"][0] + assert extracted_record["method"] == "stride_per_element" + assert extracted_record["reviewed_by"] == "A. Person" + + +@pytest.mark.trace("TC-236", "FR-026-AC-9") +@pytest.mark.parametrize("verb", ["covers", "considers"]) +def test_module_load_reports_an_undeclared_threat_model_verb(tmp_path, verb): + module = tmp_path / "module" + shutil.copytree(PACKAGE_ROOT, module) + manifest_path = module / "manifest.yaml" + manifest = yaml.safe_load(manifest_path.read_text()) + del manifest["edge_types"][verb] + manifest_path.write_text(yaml.safe_dump(manifest, sort_keys=False)) + bundle = tmp_path / "bundle" + bundle.mkdir() + (bundle / "tm.md").write_text(threat_model()) + result = subprocess.run( + [ + engine_tool("quire"), + "validate", + "--okf", + "--module", + str(module), + str(bundle), + ], + capture_output=True, + text=True, + ) + assert verb in result.stderr and "UnknownEdgeType" in result.stderr + + +@pytest.mark.trace("TC-239", "FR-027-AC-6") +@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