diff --git a/README.md b/README.md index b765ffb..7080f12 100644 --- a/README.md +++ b/README.md @@ -1,623 +1,187 @@ # Gate House -**Deterministic authority control system for human and agentic coding and operations.** +**The council where NetKingdom's security and defence doctrine is established, documented, taught, and supervised.** -Gate House is a NetKingdom security control-plane project and the reference implementation of the **Active Secrets Management (ASM) Plane**. +Gate House is a NetKingdom **Staff**-layer repository and the home of the +Active Secrets Management (ASM) Canon. It is the headquarters of the +operational staff that does the chores of IT security in NetKingdom. -Think of Gate House as observability for vault managed secrets based on sound governance policy best practices. +A word about the name, because it argues the other way. A gate house sounds +like the thing requests pass through. It is not. In a real castle the gate +house is where the guard is quartered, the watch is set, and the porter's rules +are posted — the rules of entry are decided there, and the gate itself is held +by someone else. -Its job is deliberately narrow: +> **Gate House does not stand in the gate. It decides what the gate is for, who +> may be asked to open it, and how we know it held.** -> **Gate House decides whether a human, workload, or agent is allowed to perform a requested action against a protected resource — under explicit, deterministic, auditable rules.** - -It does **not** replace an identity provider, secrets vault, policy engine, operations framework, or adaptive security system. It connects those responsibilities through a common authority model. +Its artifacts are specifications, decisions, workplans, and tasks. It holds no +runtime position, renders no authorization decision, and stores no state that +anything depends on at runtime. --- -## Why? +## Where it sits -Agentic development changes the operational risk profile of software engineering. - -Human-only development is naturally rate-limited by human execution. - -Interactive coding agents increase change velocity while a developer or operator remains actively involved. - -Autonomous agents remove much of that human friction entirely and therefore require explicit identities, mandates, authority ceilings, budgets, circuit breakers, and governance. - -At the same time, modern tooling such as MCP makes infrastructure capabilities increasingly easy for agents to discover and invoke. - -The central Gate House rule is therefore: - -> **Tool availability is not permission.** - -And more generally: - -> **Cognition may be probabilistic. Authority must be deterministically constrained.** - ---- - -## Core Architecture +NetKingdom's IT security is layered by determinism and by the kind of artifact +each layer produces — see +[`net-kingdom/canon/standards/security-layer-model_v0.1.md`](../net-kingdom/canon/standards/security-layer-model_v0.1.md). ```text - Cognitive Plane -┌──────────────────────────────────────────┐ -│ humans │ -│ LLMs / coding agents │ -│ operations agents │ -│ MCP / A2A │ -│ King's Guard │ -└───────────────────┬──────────────────────┘ - │ request - ▼ -══════════════════════════════════════════════ - GATE HOUSE -┌──────────────────────────────────────────┐ -│ principal │ -│ actor │ -│ tenant / environment │ -│ mandate / delegation │ -│ resource / action │ -│ policy │ -│ approval │ -│ posture │ -│ TTL / quotas / budgets │ -│ authority ceiling │ -└───────────────────┬──────────────────────┘ - │ GRANT / DENY - ▼ -══════════════════════════════════════════════ - Execution Plane -┌──────────────────────────────────────────┐ -│ Git / CI/CD │ -│ Kubernetes │ -│ cloud APIs │ -│ databases │ -│ SaaS / production services │ -└──────────────────────────────────────────┘ +Taxonomy cross-cutting language info-tech-canon, net-kingdom canon +Tooling deterministic state key-cape (authelia, lldap, privacy-idea), OpenBao +Engines deterministic APIs user / tenant / zone / secrets / access-engine +Staff interactive, non-deterministic gate-house, ops-mason, ops-warden, + kings-guard, whitehat-security ``` -A short version: +Read by determinism, those layers reproduce the Canon's three planes — which is +the point: > **Cognition proposes. Authority disposes. Infrastructure executes.** +The rule that binds every repository: + +> **Staff never touches Tooling directly. It acts only through Engine APIs.** + +## Why Gate House is not the decision point + +Gate House was seeded as a deterministic authority plane — an `/authorize` API, +grant storage, a revocation service. That was withdrawn on its own argument: + +> **A decision point inside Gate House would place the deterministic authority +> boundary inside the non-deterministic management layer, violating INV-02, "No +> Privilege from Cognition" — the first invariant this repository exists to +> defend.** + +NetKingdom already has a policy decision point: `access-engine` (currently +`flex-auth`). It stays the only one. Gate House writes the doctrine that +decision point implements, and checks that it did. + +The boundary, in one line: + +> **The mandate and the operating mode are Gate House's. The decision is +> access-engine's. The credential is secrets-engine's. The perimeter is +> ops-mason's and ops-warden's.** + --- -## What Gate House Owns +## What Gate House owns -Gate House owns the deterministic authority decision. +- **The doctrine** — the ASM Canon, its invariants, and the argument behind + them. Invariants graduate into `net-kingdom/canon/standards/`. +- **The authority context** — principal, actor, runtime identity, tenant, + environment, mandate, task, operating mode. Defined here, consumed by + access-engine as input claims. +- **The agentic operating modes** — assistant and autonomous as distinct + security regimes. +- **Mandates, authority ceilings, and kill switches** for autonomous actors, as + a model and a governance obligation. +- **The Change Dynamics Envelope** — how much change the organization tolerates. +- **The MCP doctrine** — tool availability is not permission. +- **The posture contract** with kings-guard, including its asymmetry. +- **Conformance review** — whether authority in practice matches the declared + mandate and ceiling. +- **The assurance specifications** T-01…T-10, executed by whitehat-security. +- **The security curriculum.** -It should answer questions such as: +## What Gate House does not own + +The authorization decision or any `/authorize` surface; policy engines, +packages, or rollout; grants, credentials, leases, or revocation; identity, +tenancy, zone, or user lifecycle; secret storage or PKI; anomaly detection or +threat intelligence; access lanes, SSH certificates, or host hardening; +deployment or remediation execution; and other repositories' workplans. + +| Component | Layer | Responsibility | +|---|---|---| +| info-tech-canon | Taxonomy | ecosystem-wide semantic contracts | +| net-kingdom | Taxonomy | NetKingdom standards of record | +| key-cape | Tooling | packaged identity tooling; IAM profile; authentication | +| OpenBao | Tooling | secret storage, leases, PKI | +| user-engine | Engine | users, accounts, memberships | +| tenant-engine | Engine | tenant-as-an-entity facts | +| zone-engine | Engine | zone identity and membership | +| secrets-engine | Engine | credential abstraction, custody, lifecycle | +| **access-engine** | Engine | **the decision — the only decision point** | +| **gate-house** | **Staff** | **doctrine, authority context, conformance, curriculum** | +| ops-mason | Staff | builds and tears down access routes and perimeters | +| ops-warden | Staff | operational access lanes, stewardship, runbooks | +| kings-guard | Staff | adaptive defence, observation, containment | +| whitehat-security | Staff | offensive validation | + +Two words that must not drift: **ops-warden and ops-mason own access lanes** — +how a worker reaches a host. **access-engine owns access rules** — whether they +may. + +--- + +## The doctrine in fifteen lines + +1. No privilege from cognition. +2. Every privileged action crosses a deterministic authority boundary. +3. Tool availability is not permission. +4. Principal and actor remain distinguishable. +5. Assistant and autonomous operation are different security modes. +6. Autonomous agents use independent identities and explicit mandates. +7. Authority is least-privileged, scoped, and time-bounded. +8. Delegation attenuates. +9. Security posture may reduce authority but must not expand it. +10. Emergency revocation works without agent cooperation. +11. Agents do not casually modify the policies defining their own ceiling. +12. Credentials are ephemeral implementation artifacts of authorization. +13. Audit evidence is protected from the actor being audited. +14. Failure of critical policy or authorization dependencies fails closed. +15. Production guarantees must survive incorrect agent behavior. + +## Agentic operating modes + +The distinction Gate House exists to keep sharp. + +**Assistant** — a human is engaged and can redirect or stop at human latency. +The human remains the principal; the agent remains a visible actor. *A human +disconnecting must never silently promote the session into autonomous +privileged operation.* + +**Autonomous** — a scheduled or triggered agent acts without supervision, and +therefore requires unique identity, a named owner, an explicit mandate, an +authority ceiling, runtime and concurrency limits, budgets, an independent kill +switch, and audit reconstruction. + +## The conformance loop + +Doctrine that no engine implements is fiction. Gate House is only real if this +turns: ```text -WHO - principal - actor - runtime identity - -WHERE - tenant - environment - resource - -WHAT - requested operation - -WHY - task - mandate - delegation - -UNDER WHICH CONDITIONS - policy - approval - posture - quotas - budgets - -UNTIL WHEN - TTL - -→ GRANT or DENY +gate-house asserts an invariant + → the engines implement it + → whitehat-security tries to break it + → kings-guard observes it in operation + → findings return to gate-house as doctrine change ``` -Gate House should provide: - -- deterministic authorization; -- principal/actor separation; -- delegation and attenuation; -- authority ceilings; -- tenant and environment constraints; -- task- and resource-scoped grants; -- short-lived authority; -- approval binding; -- posture-dependent restrictions; -- quotas and change-rate controls; -- independent circuit breakers; -- credential-binding integration; -- explainable decisions; -- protected audit evidence. - --- -## What Gate House Does Not Own +## Repository map -Gate House is intentionally **not** a security monolith. - -| System | Responsibility | +| Path | What it is | |---|---| -| **User Engine** | users, identities, memberships | -| **Tenant Engine** | tenant and organizational boundaries | -| **Key Cape** | authentication and federation | -| **Gate House** | deterministic authorization | -| **Secrets Engine** | credential abstraction and lifecycle orchestration | -| **OpenBao** | secret storage, PKI, leases, dynamic secret engines | -| **Ops Warden** | operational execution | -| **Ops Mason** | construction, reconciliation, recovery | -| **King's Guard** | adaptive security observation and response | -| **Whitehat Security** | adversarial testing and validation | +| [`INTENT.md`](INTENT.md) | why this repository exists; the re-cut in full | +| [`SCOPE.md`](SCOPE.md) | in scope / out of scope | +| [`spec/ActiveSecretsManagementCanon_v0.3.md`](spec/ActiveSecretsManagementCanon_v0.3.md) | the working canon — invariants, controls, profiles, assurance tests | +| [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) | architecture; **predates the re-cut and is being revised** | +| [`decisions/decisions.md`](decisions/decisions.md) | decision records — start with GH-DEC-2026-001 | +| [`history/`](history/) | reference notes; the 2026-08-28 review is the origin of the current shape | +| [`workplans/`](workplans/) | work in flight | -A useful shorthand: - -```text -User Engine identifies -Tenant Engine contextualizes -Key Cape authenticates -Gate House authorizes -Secrets Engine provisions -OpenBao protects -Ops Warden operates -Ops Mason constructs / restores -King's Guard observes / defends / adapts -Whitehat Security attacks / validates -``` +**Status.** Specification-only; no code, by design. `INTENT.md`, the decision +record, and the canon standard reflect the current shape. +`ArchitectureBlueprint.md` still describes the withdrawn engine framing in its +component, evaluation-order, API, and storage sections; its domain model, +operating modes, change dynamics, MCP integration, and test program survive. --- -## Agentic Operating Modes - -Gate House treats two agentic modes as distinct security regimes. - -### Agent Assistant Coding - -A human developer or operator remains actively engaged with the agent. - -```text -human principal - ↓ -assistant agent - ↓ -Gate House - ↓ -bounded delegated authority - ↓ -execution -``` - -The human remains the primary operational principal, but Gate House should preserve the agent as an actor where practical. - -A human session ending must not silently convert the workflow into privileged autonomy. - -### Autonomous Agent Coding - -A scheduled or triggered agent operates without continuous human supervision. - -```text -governance mandate - ↓ -agent/workload identity - ↓ -Gate House - ↓ -task-scoped authority - ↓ -execution -``` - -Autonomous agents require: - -- unique identity; -- named owner; -- explicit mandate; -- explicit authority ceiling; -- runtime limit; -- credential TTL; -- concurrency limit; -- token/compute/tool-call budgets; -- independent kill switch; -- audit trail; -- lifecycle termination. - ---- - -## Deterministic Security Substrate - -Gate House follows one non-negotiable design rule: - -> **No protected action succeeds merely because an intelligent system believes it should.** - -An LLM may decide: - -> "I should restart the production service." - -It may not decide: - -> "Therefore I am authorized to restart the production service." - -Authorization belongs to deterministic policy enforcement. - -That policy may be dynamic: - -```text -ALLOW production.restart -IF - actor.role == "operations-agent" -AND environment == "production" -AND service.team == actor.team -AND incident.status == "active" -AND approval.valid == true -AND approval.action == request.action -AND approval.target == request.target -AND now < approval.expiry -``` - -For the same authoritative input state, the result must be reproducible and auditable. - ---- - -## King's Guard Integration - -King's Guard is the adaptive security system around Gate House. - -King's Guard may detect: - -- anomalous tool usage; -- unexpected behavioral drift; -- compromised workloads; -- unusual change velocity; -- cross-tenant disturbance; -- declining confidence in an actor. - -It may then publish a bounded posture signal. - -Example: - -```text -actor: agent-934 -posture: DEGRADED -confidence: 0.72 -reason: anomalous-tool-usage -``` - -Gate House converts that posture into deterministic authority consequences: - -```text -IF posture == DEGRADED -THEN - deny production.write - allow production.read - require step_up for staging.write -``` - -Adaptive systems may automatically **reduce** authority. - -They must not probabilistically manufacture additional authority. - ---- - -## Secrets Engine and OpenBao Integration - -Gate House separates authorization from credential materialization. - -```text -agent requests DB read - │ - ▼ - Gate House - │ - GRANT SELECT - orders-prod - TTL 15m - │ - ▼ - Secrets Engine - │ - choose credential mechanism - │ - ▼ - OpenBao - │ - issue leased credential - │ - ▼ - execution gateway -``` - -The credential is an implementation artifact of the grant. - -This keeps organizational authorization outside the vault itself while still using OpenBao as the protected credential engine. - ---- - -## Domain Model - -Initial concepts: - -- **Principal** — who authority originates from; -- **Actor** — who attempts the action; -- **Runtime Identity** — concrete executing workload; -- **Mandate** — standing organizational authorization; -- **Delegation** — scoped transfer of authority; -- **Authority Ceiling** — maximum authority an actor can obtain; -- **Grant** — positive scoped authorization; -- **Denial** — negative authorization decision; -- **Approval** — independent authorization artifact; -- **Posture** — trusted security-state input; -- **Credential Binding** — mapping from grant to technical credential; -- **Decision Evidence** — audit record of why a decision occurred. - ---- - -## Example Authority Request - -Conceptually: - -```yaml -principal: - id: user:alice@example -actor: - id: agent:deploy-agent-22 -runtime: - id: spiffe://netkingdom/prod/deployer/22 - -tenant: tenant:acme -environment: production - -task: - id: release-7.2.1 - -request: - action: production.deploy - resource: cluster/payments - -mandate: - id: release-automation - -approval: - id: approval-9432 - -constraints: - ttl: 20m - max_mutations: 1 -``` - -Possible decision: - -```yaml -decision: GRANT -policy_version: authz-2026-08-24 - -authority: - action: production.deploy - resource: cluster/payments - expires_in: 20m - mutation_limit: 1 - -credential_binding: - type: aws-sts - provider: secrets-engine -``` - -The exact wire format is not fixed yet. - ---- - -## Change Dynamics - -Agentic systems change infrastructure faster than humans can. - -Gate House should therefore support a **Change Dynamics Envelope**. - -Potential dimensions: - -- concurrent mutating agents; -- maximum actions per grant; -- maximum resources per task; -- task duration; -- credential TTL; -- agent-chain depth; -- deployment frequency; -- destructive-action quota; -- token and compute spend; -- external-service spend; -- read/write separation. - -Budgets are useful blast-radius controls. - -They are not authorization. - ---- - -## Circuit Breakers - -Autonomous write authority should be independently suspendable. - -```text -NORMAL - ↓ -threshold / invariant violation - ↓ -AUTONOMOUS WRITE DISABLED - ↓ -READ / DIAGNOSE AVAILABLE - ↓ -STEP-UP / HUMAN INTERVENTION -``` - -When degraded, preserve observability before mutation authority. - ---- - -## Initial Reference Scenarios - -### 1. Human-Assisted Kubernetes Diagnostics - -A developer uses a coding agent to inspect production logs. - -- human principal retained; -- agent actor visible; -- read-only authority; -- short TTL; -- no mutation rights; -- auditable tool use. - -### 2. Autonomous Release Agent - -A scheduled agent deploys an approved release. - -- independent workload identity; -- release mandate; -- workload federation; -- production deployment only; -- no IAM modification; -- bounded runtime; -- complete audit chain. - -### 3. Dynamic Database Access - -An agent requests temporary `SELECT` access. - -- Gate House authorizes; -- Secrets Engine materializes; -- OpenBao generates leased credentials; -- credentials are kept outside LLM context; -- lease expires automatically. - -### 4. King's Guard Containment - -King's Guard marks an actor as degraded. - -- Gate House removes write authority; -- Ops Warden performs authorized containment; -- King's Guard verifies the result. - -### 5. Policy Self-Escalation - -An agent attempts to broaden its own permission boundary. - -- Gate House denies; -- event is audited; -- security telemetry may be forwarded to King's Guard. - ---- - -## Initial Implementation Areas - -The first prototype will likely need: - -```text -gate-house/ -├── api/ -│ ├── authorization-request -│ ├── decision -│ └── grant -├── domain/ -│ ├── principal -│ ├── actor -│ ├── mandate -│ ├── delegation -│ ├── authority -│ └── posture -├── policy/ -│ ├── engine -│ ├── policies -│ └── test -├── grants/ -│ ├── issuance -│ ├── ttl -│ └── revocation -├── approvals/ -├── limits/ -│ ├── quota -│ ├── budget -│ └── concurrency -├── integrations/ -│ ├── user-engine -│ ├── tenant-engine -│ ├── key-cape -│ ├── secrets-engine -│ ├── openbao -│ ├── kings-guard -│ └── ops-warden -├── audit/ -├── test/ -│ ├── deterministic -│ ├── adversarial -│ └── integration -└── docs/ -``` - -This is a direction, not yet a mandatory repository structure. - ---- - -## Design Principles - -1. **Small control plane, explicit boundaries.** -2. **Deterministic final authorization.** -3. **Least authority by default.** -4. **Principal and actor are not collapsed.** -5. **Delegation attenuates.** -6. **Credentials are implementation artifacts, not authority.** -7. **Short-lived authority beats standing privilege.** -8. **Tool discovery never implies authorization.** -9. **Adaptive security may restrict; it does not invent privilege.** -10. **Agents cannot casually edit their own authority ceiling.** -11. **Emergency controls do not depend on agent cooperation.** -12. **Security decisions are explainable and auditable.** -13. **Production guarantees must survive incorrect agent behavior.** - ---- - -## Non-Goals for the First Prototype - -The first implementation does not need to: - -- implement a new identity provider; -- replace OpenBao; -- implement a complete secrets manager; -- implement King's Guard; -- implement a general SIEM; -- perform anomaly detection; -- solve every cloud authorization model; -- become an IAM suite; -- invent a new policy language; -- support every agent protocol; -- provide autonomous remediation. - -It should prove that a clean deterministic authority plane can coordinate these systems. - ---- - -## Success - -Gate House succeeds when a developer can look at any privileged action and answer: - -> **Who acted? On whose behalf? Under which mandate? Against what resource? For what action? Under which policy and constraints? For how long? And why was it allowed?** - -And when the system can also prove: - -> **An agent could not have exceeded that authority merely by deciding to do so.** - ---- - -## Status - -Gate House is currently at the **reference architecture / research prototype** stage. - -The Active Secrets Management Canon provides the initial conceptual baseline. The next step is to turn the authority model into executable contracts, policy decisions, and end-to-end reference scenarios. - ---- - -## Motto - -> **Agents decide what to attempt. Gate House decides what may cross the boundary.** +> **Agents decide what to attempt. Engines decide what may cross the boundary. +> Gate House decides what the boundary is for.**