feat(orchestration): compose security scenarios
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb
This commit is contained in:
parent
ad46cc89fc
commit
d96aab2321
20 changed files with 1464 additions and 30 deletions
78
canon/schemas/security-scenario_v0.1.schema.json
Normal file
78
canon/schemas/security-scenario_v0.1.schema.json
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://netkingdom.local/schemas/security-scenario_v0.1.schema.json",
|
||||
"title": "NetKingdom Security Scenario v0.1",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "authority", "requires"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^scenario:[a-z0-9][a-z0-9._:-]*$"
|
||||
},
|
||||
"authority": {
|
||||
"enum": ["platform", "netkingdom", "tenant"]
|
||||
},
|
||||
"initial_trust": {
|
||||
"$ref": "#/$defs/trustStates"
|
||||
},
|
||||
"requires": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["capabilities"],
|
||||
"properties": {
|
||||
"capabilities": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"uniqueItems": true,
|
||||
"items": {"$ref": "#/$defs/capability"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"providers": {
|
||||
"type": "object",
|
||||
"propertyNames": {"$ref": "#/$defs/capability"},
|
||||
"additionalProperties": {"type": "string", "minLength": 1}
|
||||
},
|
||||
"parameter_overrides": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"capability": {
|
||||
"enum": [
|
||||
"s1.os-baseline",
|
||||
"s1.secret-bootstrap",
|
||||
"s2.cluster-runtime",
|
||||
"s3.platform-services",
|
||||
"c0.bootstrap-identity",
|
||||
"c1.lightweight-sso",
|
||||
"c2a.light-2fa",
|
||||
"c2b.token-authority",
|
||||
"c3.runtime-secrets",
|
||||
"c4.fine-grained-authorization",
|
||||
"c5.enterprise-federation",
|
||||
"c6.self-optimizing-audit"
|
||||
]
|
||||
},
|
||||
"trustStates": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"items": {
|
||||
"enum": [
|
||||
"bare_host_trust",
|
||||
"cluster_trust",
|
||||
"bootstrap_secret_trust",
|
||||
"bootstrap_identity_trust",
|
||||
"runtime_secret_trust",
|
||||
"runtime_identity_trust",
|
||||
"runtime_authorization_trust",
|
||||
"tenant_onboarding_trust"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -6,7 +6,7 @@ domain: netkingdom
|
|||
status: accepted
|
||||
version: "0.1"
|
||||
created: "2026-05-22"
|
||||
updated: "2026-05-22"
|
||||
updated: "2026-08-23"
|
||||
scope: meta-orchestration
|
||||
adr:
|
||||
- docs/adr/ADR-0012-playbook-capability-contract-ownership.md
|
||||
|
|
@ -161,6 +161,12 @@ Security-sensitive and secret-reference parameters MUST NOT be
|
|||
`tenant_tunable`. Secret-reference defaults must be references or paths,
|
||||
not plaintext secret values.
|
||||
|
||||
For executable validation, a `secret_reference` value MUST be a non-whitespace
|
||||
URI such as `openbao://kv/platform/example` or
|
||||
`kubernetes://namespace/name#key`, or an explicit absolute/relative path
|
||||
beginning with `/`, `./`, or `../`. Bare strings are rejected because the
|
||||
composer cannot distinguish them from secret values.
|
||||
|
||||
Supported constraints:
|
||||
|
||||
| Constraint | Applies to | Meaning |
|
||||
|
|
@ -244,7 +250,8 @@ separate playbook runner execute safely.
|
|||
|
||||
## Scenario Shape
|
||||
|
||||
The validator supports a small scenario file for conformance demos:
|
||||
The validator supports a small scenario file for single-provider conformance
|
||||
demos:
|
||||
|
||||
```yaml
|
||||
id: scenario:s1-host-bootstrap-reference
|
||||
|
|
@ -263,6 +270,13 @@ Allowed scenario authorities are `platform`, `netkingdom`, and `tenant`.
|
|||
Tenant authority cannot override `platform_only`,
|
||||
`security_sensitive`, or `secret_reference` parameters.
|
||||
|
||||
The demo composer refuses ambiguous providers and overrides aimed at unselected
|
||||
declarations. Deterministic multi-provider selection, explicit provider pins,
|
||||
trust sequencing, responsibility maps, and owner-routed readiness handoffs are
|
||||
defined by `security-scenario-composition_v0.1.md` and implemented by
|
||||
`tools/security-scenario-composer/`. Use that contract for operational planning;
|
||||
the demo path does not authorize or execute playbooks.
|
||||
|
||||
## Conformance
|
||||
|
||||
A declaration conforms when it passes:
|
||||
|
|
|
|||
142
canon/standards/security-scenario-composition_v0.1.md
Normal file
142
canon/standards/security-scenario-composition_v0.1.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
---
|
||||
id: netkingdom-security-scenario-composition-v0.1
|
||||
type: standard
|
||||
title: "NetKingdom Security Scenario Composition v0.1"
|
||||
domain: netkingdom
|
||||
status: proposed
|
||||
version: "0.1"
|
||||
owner: net-kingdom
|
||||
created: "2026-08-23"
|
||||
updated: "2026-08-23"
|
||||
last_reviewed: "2026-08-23"
|
||||
review_interval: 3m
|
||||
scope: meta-orchestration
|
||||
schema:
|
||||
- canon/schemas/security-scenario_v0.1.schema.json
|
||||
validator:
|
||||
- tools/security-scenario-composer/security_scenario_composer.py
|
||||
adr:
|
||||
- docs/adr/ADR-0007-security-orchestration-boundary.md
|
||||
- docs/adr/ADR-0012-playbook-capability-contract-ownership.md
|
||||
related:
|
||||
- canon/standards/playbook-capability-contract_v0.1.md
|
||||
---
|
||||
|
||||
# NetKingdom Security Scenario Composition v0.1
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This contract defines the deterministic, plan-only boundary between a requested
|
||||
NetKingdom capability set and the independently owned playbook entry points that
|
||||
can realize it. It consumes conformant Playbook Capability Contract v0.1
|
||||
declarations and produces an owner-routed responsibility, trust, parameter, and
|
||||
readiness handoff.
|
||||
|
||||
Composition answers **what is selected, in which trust order, with which safe
|
||||
parameters, and who must execute and evidence it**. It does not run a playbook,
|
||||
mint a credential, infer authority, or declare a runtime ready.
|
||||
|
||||
## 2. Authority boundary
|
||||
|
||||
- NetKingdom owns scenario intent, provider selection, parameter-policy checks,
|
||||
trust sequencing, and the composed responsibility map.
|
||||
- The declaration owner owns the playbook or stable entry point, execution,
|
||||
rollback, and readiness evidence.
|
||||
- Railiance retains deployment execution for Railiance-owned declarations.
|
||||
- A composed plan is not authorization to execute. Any approval, custody,
|
||||
credential, or change-window gate named by an owner remains in force.
|
||||
|
||||
## 3. Scenario input
|
||||
|
||||
Scenario files conform to
|
||||
`canon/schemas/security-scenario_v0.1.schema.json`:
|
||||
|
||||
```yaml
|
||||
id: scenario:c0-local-identity-reference
|
||||
authority: netkingdom
|
||||
initial_trust:
|
||||
- bare_host_trust
|
||||
requires:
|
||||
capabilities:
|
||||
- c0.bootstrap-identity
|
||||
providers:
|
||||
c0.bootstrap-identity: net-kingdom.local-identity
|
||||
parameter_overrides:
|
||||
net-kingdom.local-identity:
|
||||
bootstrap_username: bootstrap-admin
|
||||
```
|
||||
|
||||
`authority` uses the Playbook Capability Contract vocabulary: `platform`,
|
||||
`netkingdom`, or `tenant`. Parameter sensitivity and tuning-authority rules are
|
||||
applied before a plan is emitted.
|
||||
|
||||
`initial_trust` lists trust states established outside this composition. The
|
||||
composer never assumes an initial trust state. A required state must be present
|
||||
there or be satisfied by an earlier selected declaration.
|
||||
|
||||
`providers` pins a required capability to an exact declaration id. A pin is
|
||||
mandatory when more than one valid declaration provides the capability. A pin
|
||||
may not name an unrequested capability or a declaration that does not provide
|
||||
the keyed capability.
|
||||
|
||||
## 4. Fail-closed selection rules
|
||||
|
||||
Composition fails when any of the following is true:
|
||||
|
||||
- a declaration is invalid or declaration ids are duplicated;
|
||||
- a capability is unknown, duplicated, or has no provider;
|
||||
- multiple providers match and the scenario does not pin one;
|
||||
- a provider pin does not match the requested capability;
|
||||
- an override targets an unselected declaration or unknown parameter;
|
||||
- an override violates type, constraint, sensitivity, or tuning authority;
|
||||
- a required parameter has neither a default nor an override;
|
||||
- a required trust state cannot be established without a cycle or inference.
|
||||
|
||||
Selection order never resolves ambiguity. Filesystem order, catalog order,
|
||||
lexical order, and prior deployment state are not provider authority.
|
||||
|
||||
## 5. Trust sequencing
|
||||
|
||||
The composer starts only with the scenario's explicit `initial_trust` set. It
|
||||
then selects the lexically first **eligible** declaration, where eligible means
|
||||
all of that declaration's required trust states have already been established.
|
||||
After the step, and only for composition purposes, the declaration's satisfied
|
||||
states become available to later steps.
|
||||
|
||||
Lexical ordering makes independent eligible steps reproducible; it does not
|
||||
grant one provider precedence during selection. If no remaining declaration is
|
||||
eligible, composition fails and reports the unresolved trust states.
|
||||
|
||||
Readiness checks attached to a satisfied state are obligations for the owning
|
||||
executor. They are not marked satisfied merely because the plan contains them.
|
||||
|
||||
## 6. Composition output
|
||||
|
||||
A successful output has
|
||||
`apiVersion: netkingdom.io/security-scenario-composition/v0.1` and
|
||||
`kind: SecurityScenarioComposition`. It contains:
|
||||
|
||||
- the requested capabilities and exact selected declaration ids;
|
||||
- effective parameter values with their source, sensitivity, and tuning
|
||||
authority;
|
||||
- ordered execution handoffs containing owner, repository, entry point,
|
||||
required trust, produced trust, and readiness obligations;
|
||||
- a flattened responsibility map attributable to declaration ids;
|
||||
- the final *planned* trust-state set;
|
||||
- an explicit `execution.permitted: false` boundary.
|
||||
|
||||
The output is non-secret planning material. Declarations and scenarios must use
|
||||
secret references rather than secret values as required by the Playbook
|
||||
Capability Contract.
|
||||
|
||||
## 7. Conformance
|
||||
|
||||
Use the canonical tool:
|
||||
|
||||
```text
|
||||
python3 tools/security-scenario-composer/security_scenario_composer.py \
|
||||
--scenario <scenario.yaml> <declaration.yaml> [<declaration.yaml> ...]
|
||||
```
|
||||
|
||||
Exit zero means the declarations and scenario compose deterministically. It
|
||||
does not mean the plan was executed or its readiness evidence was observed.
|
||||
Loading…
Add table
Add a link
Reference in a new issue