Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions spec/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
60 changes: 59 additions & 1 deletion spec_objects_security/manifest.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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: []
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
11 changes: 11 additions & 0 deletions spec_objects_security/schemas/DecisionState.json
Original file line number Diff line number Diff line change
@@ -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."
}
43 changes: 42 additions & 1 deletion spec_objects_security/schemas/Risk.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {}
Expand Down Expand Up @@ -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"
]
}
}
}
]
}
58 changes: 58 additions & 0 deletions spec_objects_security/schemas/ThreatModel.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
}
]
}
10 changes: 10 additions & 0 deletions spec_objects_security/schemas/ThreatModelMethod.json
Original file line number Diff line number Diff line change
@@ -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."
}
5 changes: 4 additions & 1 deletion spec_objects_security/skeletons/risk.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,14 @@ type: risk
object: risk
likelihood: possible
impact: major
decision: undecided
---
<!-- risk authoring skeleton (spec-objects-security). Fill every section with
substantive content. Contract (manifest body_extraction asserts):
- Frontmatter MUST carry id, title, type: risk, object: risk,
likelihood and impact.
likelihood, impact and decision (undecided, accepted or
not_accepted; `decided_by` is required unless undecided, refused when
undecided).
- "## Properties" (H2): the typed declaration. Risk.json requires both a
`likelihood` row and an `impact` row: a risk scored on one axis is
not scored. -->
Expand Down
41 changes: 41 additions & 0 deletions spec_objects_security/skeletons/threat_model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
id: TM-001
title: "TokenServiceThreatModel"
type: threat_model
object: threat_model
method: stride_per_interaction
reviewed_by: "A. Person"
---
<!-- threat_model authoring skeleton (spec-objects-security). Fill every section
with substantive content. Contract (manifest body_extraction asserts):
- Frontmatter MUST carry id, title, type: threat_model,
object: threat_model, method (stride_per_element or
stride_per_interaction) and reviewed_by (the person who led the analysis).
- "## Properties" (H2): the typed declaration; ThreatModel.json requires
an identity row.
- Author at least one `covers` edge (part, connection, data_sink or
trust_boundary) in `relationships`; `considers` edges (threat) are
optional.
- "## Scope", "## Assumptions" and "## Out of scope" (H2) are required and
non-empty free text. -->
# [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 |
5 changes: 4 additions & 1 deletion tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ def engine_tool(name: str) -> str:
"audit_finding",
"soup_record",
"scope_exclusion",
"threat_model",
)

MODEL_OF = {
Expand Down Expand Up @@ -120,6 +121,7 @@ def engine_tool(name: str) -> str:
"audit_finding": "AuditFinding",
"soup_record": "SoupRecord",
"scope_exclusion": "ScopeExclusion",
"threat_model": "ThreatModel",
}

MARKER_MODELS = (
Expand Down Expand Up @@ -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 = (
Expand All @@ -222,6 +224,7 @@ def engine_tool(name: str) -> str:
"control",
"audit_event",
"soup_record",
"threat_model",
)

CLAUSE_BEARING = (
Expand Down
5 changes: 5 additions & 0 deletions tests/test_manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"

Expand All @@ -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"]
Expand Down
Loading
Loading