diff --git a/README.md b/README.md index 40a22e3..80682f3 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,9 @@ The dynamic, self-optimizing security platform is the long-term direction in - [Security layer model](canon/standards/security-layer-model_v0.6.md) — how the security estate is layered (Taxonomy / Tooling / Engines / Staff) and what each layer may own +- [Agent companion](canon/standards/security-layer-model-companion_v0.1.md) — the + operative two-page form of that standard: what to declare, what binds you, what + you may never claim - [Security scenario composition](canon/standards/security-scenario-composition_v0.1.md) — deterministic, plan-only capability and trust composition - [Posture feedback](canon/standards/posture-feedback_v0.1.md) — deterministic, diff --git a/canon/standards/security-layer-model-companion_v0.1.md b/canon/standards/security-layer-model-companion_v0.1.md new file mode 100644 index 0000000..b82f2df --- /dev/null +++ b/canon/standards/security-layer-model-companion_v0.1.md @@ -0,0 +1,192 @@ +--- +id: netkingdom-security-layer-model-companion-v0.1 +type: standard-companion +title: "NetKingdom Security Layer Model — Agent Companion v0.1" +domain: netkingdom +status: proposed +version: "0.1" +companion_to: canon/standards/security-layer-model_v0.6.md +owner: gate-house +publication_owner: net-kingdom +created: "2026-08-29" +updated: "2026-08-29" +review_interval: 3m +standard_token: security-layer-model-companion_v0.1 +--- + +# Security Layer Model — Agent Companion + +**This is the operative form of `security-layer-model_v0.6.md`.** Same rules, no +change log, no review history. The statute governs where the two disagree; if you +find a disagreement, report it — that is a finding, not a formatting problem. + +Read this if you are an agent or an operator working in a NetKingdom repository, +or if your repository has been asked to declare its layer. + +--- + +## 1. The four layers + +| Layer | You are this if you produce | Deterministic | +| --- | --- | --- | +| **Taxonomy** | terms, semantic contracts, standards | n/a | +| **Tooling** | state and persistence | yes | +| **Engine** | a deterministic API for one modeled concept | yes | +| **Staff** | specifications, decisions, workplans, tasks | **no** | + +One test decides it: **given the same authoritative inputs, do you always return +the same result?** If your core function is inference or judgment, you are Staff +— however much of your work happens at runtime. + +Engines carry a role: **PDP** (decides — `access-engine` only), **PIP** +(supplies facts as claims), **Evidence** (`audit-core`), **Lifecycle** (an API +over Tooling it owns). A new engine is a PIP unless the statute says otherwise. + +## 2. Declare your layer + +Put this in your `INTENT.md` frontmatter. A layer someone else stated about you +is not a declaration. + +```yaml +layer: Staff # Taxonomy | Tooling | Engine | Staff +role: null # Engines only: PDP | PIP | Evidence | Lifecycle +``` + +Then state it in prose, in your own voice, in the body. Contest the proposed +layer if it is wrong — a correction is worth more than a label. + +Reference implementation of the machine-readable form: `ops-warden`'s +`layer.yaml`, `scripts/check_layer_conformance.py`, and +`tests/test_layer_conformance.py`. + +## 3. The rules that bind everyone + +1. **One decision point.** `access-engine` renders authorization decisions. No + other repository, in any layer, renders or caches one. +2. **Compiled data that determines an outcome is still deciding.** A registry, + cache, or schema that resolves a result before the engine runs has decided + early. +3. **Doctrine arrives as a claim.** Anything that changes an outcome — an + authority ceiling, a zone stance, a posture, a maturity level — reaches the + decision as a request claim or a versioned policy rule, never by a side + channel. +4. **Adaptive systems may only tighten.** Reduce authority, require step-up, + request containment — never manufacture authority. +5. **Staff never touches Tooling directly.** It acts through Engine APIs. See §4. +6. **Every allow has a lifetime.** A TTL, or a binding to a session or + obligation that ends. + +## 4. If you touch Tooling + +"Tooling" means a system catalogued as Tooling in the statute's §4 — today +`key-cape` and `OpenBao`. Uncatalogued infrastructure (the State Hub, +`llm-connect`) is outside this rule, but list it anyway so your check is total. + +Three sanctioned shapes. Anything else is a violation: + +| Shape | When | You must | +| --- | --- | --- | +| **Read-only diagnostic** | no engine exposes the read | declare it; no writes; treat it as a gap to close | +| **Conduit** | you run the *owner's* tool under the *caller's* identity | present no credential of your own, widen nothing, stay reconstructable as the caller | +| **Declared gap** | you must contact Tooling and no engine exposes it | declare `capability`, `intended_owner`, `blocked_on`, `review` — machine-readably | + +A conduit that presents its own token is not a conduit. A declared gap is +**tracked non-conformance**, not conformance — but declaring it is always better +than hiding it, and it will never be scored below silence. + +## 5. If you cause side effects (you are PEP-shaped) + +Being PEP-shaped does not change your layer. `ops-warden` issuing a certificate +and `ops-mason` opening a route are both Staff and both PEP-shaped. + +1. **No side effect without a decision record** naming the request it was + rendered for. +2. **Never cache the verdict.** Caching an input claim under its own freshness + rule is fine; caching the answer is a second decision point. +3. **Publish your unreachable-engine stance** — total, per zone or equivalent, + no implicit default, no per-call discretion. Reference shape: `ops-warden` + `ADR-0009`. +4. **Stay reconstructable**, within the bound in §6. + +If `access-engine` is reachable but degraded, the fallback is the engine's. If it +is unreachable, the behaviour is necessarily yours — which is why it must be +declared in advance rather than decided in the moment. + +## 6. What you may never claim about evidence + +An append-only archive with a verified chain proves records were **not altered +or truncated after arrival**. It proves nothing about an event never sent. + +- ✗ "the audit record proves it happened" +- ✗ "there is no record, so it did not happen" +- ✓ "the archive proves the records it holds were not altered or truncated after arrival" + +The event an adversary most wants missing is the negative one — a revocation, a +denial, a containment action. If a control's soundness depends on an event being +present, that evidence is **load-bearing** and its emission must be atomic with +the state change, queued locally. Otherwise it is **attributive**: seek +atomicity, and if you trade it away deliberately, declare the trade and never +describe the trail as complete. + +If you emit adaptive-relevant events, publish an expected cadence. A drop below +it is a finding. Silence is a signal. + +## 7. If you are an agent + +Same layer as your human colleagues, different blast radius: + +1. **No standing credential.** Authority is per task, time-bounded, attributable. +2. **Tool use is a conduit or an Engine API.** There is no third route. +3. **Your memory is not a state plane.** Memory, tool-call traces, and prompt + caches must not become state another layer depends on unless catalogued. +4. **Every action is reconstructable as the caller's action.** + +Tool availability is not permission. A tool being callable says the operation +exists, not that you may invoke it. + +## 8. Conformance: four states + +| State | Meaning | +| --- | --- | +| **Conforming** | no Tooling contact, or only declared diagnostic/conduit shapes | +| **Blocked-clean** | the capability does not exist because no engine exposes it, and you make no Tooling contact | +| **Declared gap** | a declared §5.3 contact — tracked non-conformance | +| **Undeclared violation** | anything else | + +**Blocked-clean is not worse than conforming.** Declining a shortcut and leaving +a capability at zero is compliance at cost. It will never be ranked below a +repository that quietly opened a client and said nothing. + +## 9. Consuming NetKingdom security from outside + +Operations is **HelixForge's** responsibility — its reef, rail, rapp, and rein +concepts — and NetKingdom provides the security and approval framework those +operations consume. + +**That interface is not specified yet.** What holds today is only what holds for +any consumer: authorization decisions come from `access-engine`, approvals are +objects in `approval-engine` consumed as claims, credentials are materialized by +`secrets-engine` after a decision, and evidence goes to `audit-core` under the +bound in §6. A HelixForge component that causes a protected side effect is +PEP-shaped and §5 applies to it. + +What is **not** settled: how a reef, rail, rapp, or rein maps onto the layer +model — whether they are subjects a decision is rendered about, principals that +request, PEP-shaped consumers, or none of these. Until that is written, do not +assume a mapping. Raising it is welcome. + +## 10. Two things the estate cannot do yet + +Stated so nobody plans around a capability that does not exist: + +- **Nothing is observed in production.** `kings-guard` has reported that it has + never seen a real event. Do not cite "observed in operation" as evidence. +- **Nothing can be contained automatically.** There is no actuation surface — + no API to reduce authority, require step-up, or isolate a workload. The + capability is at zero, not degraded. + +--- + +**Statute:** `canon/standards/security-layer-model_v0.6.md`. +**Owner:** gate-house. **Report a disagreement between this and the statute as a +finding.**