diff --git a/spec/ActiveSecretsManagementCanon_v0.3.md b/spec/ActiveSecretsManagementCanon_v0.3.md new file mode 100644 index 0000000..3a6f1e1 --- /dev/null +++ b/spec/ActiveSecretsManagementCanon_v0.3.md @@ -0,0 +1,1335 @@ +# Active Secrets Management Canon + +**Version:** 0.3 +**Status:** Working Canon / Review Draft +**Date:** 2026-08-24 +**Scope:** Human, agent-assisted, and autonomous development and operations environments + +--- + +## 1. Purpose + +The Active Secrets Management Canon defines a practical security baseline for development and operations environments in which humans and software agents jointly create, change, operate, and secure information systems. + +The Canon starts from a simple observation: + +> **Secrets management is no longer primarily the secure storage of passwords, tokens, and keys. It is the controlled lifecycle of authority.** + +A modern system should minimize standing credentials, derive short-lived authority from verifiable identities and policy, constrain that authority at deterministic security boundaries, observe its use, detect credential exposure, revoke compromised authority, and prove that remediation is complete. + +The target lifecycle is: + +```text +identify + ↓ +authenticate + ↓ +authorize / delegate + ↓ +mint short-lived authority + ↓ +use + ↓ +expire / revoke + ↓ +observe + ↓ +detect exposure or misuse + ↓ +remediate + ↓ +verify closure + ↺ +``` + +The Canon is deliberately **agent-aware**. It distinguishes interactive agent assistance from autonomous agent operation and treats the increased velocity and concurrency of agentic change as a first-class security concern. + +--- + +## 2. Design Thesis + +The foundational design principle is: + +> **Cognition may be probabilistic. Authority must be deterministically constrained.** + +Large language models and agents may reason, plan, discover tools, propose actions, classify situations, and adapt behavior. They must not be the sole mechanism deciding whether a protected resource can be accessed or changed. + +A production-grade environment therefore separates: + +1. **Cognitive Plane** — what might usefully happen next; +2. **Authority Plane** — what is permitted to happen; +3. **Execution Plane** — what actually changes system state. + +A compact formulation is: + +> **Cognition proposes. Authority disposes. Infrastructure executes.** + +This does not imply that authorization policy must be static. It may be highly contextual and dynamic. The requirement is that access decisions are based on explicit, reproducible, auditable rules and enforced independently of the agent requesting the action. + +--- + +## 3. Normative Language + +The terms **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are used normatively: + +- **MUST / MUST NOT** — required for conformance to the stated profile. +- **SHOULD / SHOULD NOT** — expected unless a documented risk-based exception exists. +- **MAY** — optional or context dependent. + +The Canon is not a legal or regulatory standard. It is an engineering and governance baseline intended to support security assurance, auditability, and compliance evidence. + +--- + +## 4. Scope + +The Canon applies to: + +- human developers and operators; +- interactive coding and operations agents; +- scheduled, triggered, or event-driven autonomous agents; +- CI/CD systems; +- Kubernetes and cloud workloads; +- MCP and other tool-mediated agent interfaces; +- agent-to-agent interactions; +- databases, cloud APIs, SaaS APIs, and production services; +- static and dynamic secrets; +- workload identity, federation, and short-lived credentials; +- secret discovery, remediation, rotation, revocation, and audit. + +It is intended for environments ranging from a single engineering team to a multi-tenant production platform. + +--- + +## 5. Threat and Failure Model + +The Canon assumes that one or more agentic components can: + +- misunderstand intent; +- hallucinate; +- follow malicious or injected instructions; +- select the wrong tool; +- use the right tool with the wrong parameters; +- become stuck in loops; +- over-consume compute or token budget; +- expose credentials through prompts, logs, shell history, traces, or generated code; +- be induced to act as a confused deputy; +- chain unsafe actions across multiple agents; +- operate faster than human monitoring can reliably follow; +- attempt to broaden or alter their own authority; +- encounter compromised tools, dependencies, MCP servers, or data sources. + +A production security baseline MUST therefore remain meaningful even when an agent behaves incorrectly. + +The decisive review question is: + +> **If every participating model makes the wrong decision, which security guarantees still hold?** + +Those surviving guarantees constitute the actual security substrate. + +--- + +# Part I — Operating Model + +## 6. Human-Only, Agent Assistant, and Autonomous Modes + +### 6.1 Human-Only Development and Operations + +A human directly operates tools and infrastructure. Human effort, attention, and execution speed naturally limit change velocity. + +Credentials are associated primarily with human identities and workload identities. + +This remains the baseline against which agentic modes should be compared. + +--- + +### 6.2 Agent Assistant Coding + +**Agent Assistant Coding** is an interactive human-agent session in which a human developer or operator remains actively engaged with the agent and can monitor, redirect, approve, interrupt, or stop activity with human-scale latency. + +Typical characteristics: + +- a human initiates the session; +- the human provides intent and context; +- the human observes work as it occurs; +- the human can make decisions immediately; +- credentials often originate from the human's active session; +- the human remains the primary operational principal; +- the agent is an identifiable actor assisting that principal. + +Conceptually: + +```text +Human principal + │ + │ active supervision + ▼ +Assistant agent + │ + │ delegated/session authority + ▼ +Tools / code / infrastructure +``` + +Where technically practical, audit data SHOULD distinguish: + +```text +principal = human +actor = assistant agent +session = interactive session +``` + +The presence of a human in the loop reduces some risks but does **not** replace deterministic access controls. + +Human risk acceptance tends to act as an informal limiter of automation velocity: confidence increases delegation until incidents, near misses, or uncertainty reduce appetite for further speed. + +--- + +### 6.3 Autonomous Agent Coding + +**Autonomous Agent Coding** consists of scheduled, triggered, queued, event-driven, or machine-initiated coding and operations agents that can act without continuous human supervision. + +Examples include: + +- dependency update agents; +- autonomous refactoring; +- vulnerability remediation; +- test repair; +- release and deployment agents; +- infrastructure reconciliation; +- incident-response agents; +- routine operational agents; +- agent-to-agent development workflows. + +Autonomous agents require: + +- unique addressable identities; +- explicit access profiles; +- policy-bound mandates; +- defined ownership; +- resource and economic budgets; +- lifecycle management; +- bounded authority; +- deterministic circuit breakers; +- reconstructable audit evidence. + +Conceptually: + +```text +Organizational governance + │ + ▼ +Agent identity + mandate + │ + ▼ +Task authorization + │ + ▼ +Autonomous agent + │ + ▼ +Tools / infrastructure +``` + +The relevant question becomes: + +> **Under which organizational authority may agent X independently perform class Y of actions against resources Z?** + +--- + +### 6.4 Transition Between Modes + +Moving a workflow from Agent Assistant Coding to Autonomous Agent Coding is a **security architecture change**, not merely an automation improvement. + +Example: + +```text +"Human asks agent to deploy release" + ↓ +"Agent deploys every approved release overnight" +``` + +The second design requires an independent identity, mandate, authority ceiling, lifecycle, budget, governance owner, audit model, and failure controls. + +No workflow SHOULD silently become autonomous merely because the human session disconnects or times out. + +--- + +## 7. Change Dynamics + +Agentic development increases the **velocity, volume, duration, and concurrency of change**. + +Traditional human work contains accidental safety friction: + +- somebody must notice; +- understand; +- decide; +- edit; +- execute; +- test; +- deploy; +- observe. + +Agentic systems remove much of that friction. This improves productivity while simultaneously increasing the speed with which wrong decisions can propagate. + +### 7.1 Change Dynamics Envelope + +Every production environment SHOULD define a **Change Dynamics Envelope**: + +> The maximum rate, scope, duration, and concurrency of system change the security and governance system is designed to tolerate while maintaining its required invariants. + +Relevant dimensions include: + +- repositories and resources reachable; +- environments reachable; +- read versus write authority; +- reversible versus irreversible actions; +- number of concurrent agents; +- maximum tool calls; +- maximum runtime; +- credential TTL; +- maximum deployment frequency; +- token and compute budget; +- external-service spend; +- destructive-action quota; +- maximum propagation depth across agent chains. + +### 7.2 Assistant-Mode Limiter + +Assistant-mode change dynamics are constrained by: + +```text +agent capability +× human willingness to delegate +× observability +× human reaction speed +→ effective change velocity +``` + +### 7.3 Autonomous-Mode Limiter + +Autonomous-mode change dynamics are constrained by: + +```text +agent capability +× authorization +× governance +× resource limits +× token / compute budget +× runtime +× concurrency +→ effective change velocity +``` + +Budgets and quotas are useful blast-radius controls, but **never substitutes for authorization**. + +--- + +# Part II — Foundational Security Invariants + +## 8. Canon Invariants + +### INV-01 — Deterministic Authority Boundary + +Every privileged production action MUST ultimately cross a deterministic authorization and enforcement boundary. + +### INV-02 — No Privilege from Cognition + +An LLM, agent, prompt, model confidence score, or probabilistic classifier MUST NOT be able by itself to grant additional authority. + +### INV-03 — Tool Availability Is Not Permission + +The fact that an MCP server, plugin, shell, API, or agent exposes a capability conveys no authorization to use it. + +### INV-04 — Agent and Principal Are Distinct Facts + +Where an agent acts for a human or another system, the executing actor and delegating principal SHOULD remain distinguishable in identity and audit context. + +### INV-05 — Assistant and Autonomous Modes Are Different Security Regimes + +Interactive supervision and autonomous operation MUST NOT be treated as equivalent from an identity, credential, governance, or accountability perspective. + +### INV-06 — Human Supervision Is Not Access Control + +A human watching an agent MAY reduce operational risk but MUST NOT substitute for resource-side security enforcement. + +### INV-07 — Authority Has a Hard Ceiling + +Agentic reasoning MAY attenuate or decline available authority. It MUST NOT exceed the deterministic maximum authority granted by policy. + +### INV-08 — No Prompt-Only Security + +Prompts, personas, natural-language policies, or model instructions MUST NOT be treated as hard security controls. + +### INV-09 — Emergency Control Is Independent of the Agent + +Revocation, privilege suspension, kill switches, and circuit breakers MUST work without cooperation from the affected agent. + +### INV-10 — Security Evidence Is Agent-Resistant + +Agents MUST NOT be able to silently alter or erase authoritative evidence of their privileged actions. + +### INV-11 — Security Policy Is More Protected Than Workload State + +Changes to authorization policy, identity trust, secret backends, audit configuration, or circuit breakers MUST be governed more strongly than normal workload changes. + +### INV-12 — Production Claims Are Expressed as Invariants + +Security assurance SHOULD be stated in terms of enforceable properties, for example: + +> "This agent identity cannot delete production namespaces." + +not: + +> "The agent has been instructed not to delete production namespaces." + +--- + +## 9. Deterministic Does Not Mean Static + +A deterministic policy may incorporate dynamic context. + +Example: + +```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 +AND action_quota > 0 +``` + +The authorization outcome remains reproducible for the same evaluated state. + +Probabilistic signals MAY inform policy as advisory or restrictive inputs. They SHOULD NOT be the sole basis for granting additional privilege. + +For example: + +- a model-based anomaly score MAY trigger step-up approval; +- it MAY reduce available authority; +- it MAY pause autonomous writes; +- it SHOULD NOT by itself grant production administrator access. + +--- + +# Part III — Reference Architecture + +## 10. Three-Plane Architecture + +```text + COGNITIVE PLANE + ┌─────────────────────────────────┐ + │ LLM reasoning │ + │ planning │ + │ code generation │ + │ tool discovery │ + │ diagnostics │ + │ agent coordination │ + │ risk suggestions │ + └───────────────┬─────────────────┘ + │ requests action + ▼ +════════════════════════════════════════════════ + AUTHORITY PLANE + ┌─────────────────────────────────┐ + │ Identity │ + │ Authentication │ + │ Delegation │ + │ Deterministic policy │ + │ Approval │ + │ Vault / STS / credential mint │ + │ TTL / quotas / constraints │ + │ Circuit breakers │ + └───────────────┬─────────────────┘ + │ permits action + ▼ +════════════════════════════════════════════════ + EXECUTION PLANE + ┌─────────────────────────────────┐ + │ Git │ + │ CI/CD │ + │ Kubernetes │ + │ Cloud APIs │ + │ Databases │ + │ Production services │ + │ SaaS systems │ + └───────────────┬─────────────────┘ + │ + ▼ + Audit / telemetry + │ + ▼ + Detection / remediation + │ + └──────────► Authority plane +``` + +--- + +## 11. MCP and Agentic Infrastructure + +MCP is a capability interface, not a security authority. + +An MCP server may expose: + +```text +list_pods() +get_logs() +restart_service() +scale_deployment() +modify_network_policy() +rotate_database_password() +delete_namespace() +``` + +The tool catalog describes what can be requested. It does not determine who may execute each action. + +The expected pattern is: + +```text +Agent + │ + │ requests "restart service X" + ▼ +MCP tool / execution gateway + │ + ▼ +Deterministic authorization + ├── actor identity + ├── delegated principal + ├── task / session + ├── environment + ├── target resource + ├── operation + ├── policy + ├── approval + ├── TTL + ├── quota + └── budget + │ + ALLOW + │ + ▼ +Infrastructure API +``` + +This rule continues through recursive agent chains: + +```text +coding agent + ↓ +MCP + ↓ +operations agent + ↓ +cluster agent + ↓ +DETERMINISTIC POLICY ENFORCEMENT + ↓ +production infrastructure +``` + +Agentic infrastructure MAY provide flexibility above the boundary. It MUST NOT dissolve the boundary. + +--- + +# Part IV — Identity, Credentials, and Authority + +## 12. Core Terminology + +### Principal + +The human, organization, workload, or system on whose behalf authority is being exercised. + +### Actor + +The entity directly performing the action. + +Example: + +```text +principal = Alice +actor = deploy-agent-22 +``` + +### Runtime Identity + +The identity of the executing workload instance, pod, job, VM, process, or equivalent runtime. + +### Authority + +The right to perform a defined action against a defined resource under defined conditions. + +### Credential + +A transferable or presentable technical artifact used to authenticate or exercise authority, such as a token, key, certificate, password, or signed assertion. + +### Secret + +A credential or sensitive value whose security depends materially on confidentiality. + +### Delegation + +A transfer of some authority from one principal to an actor without collapsing their identities. + +### Capability + +A narrowly scoped authorization artifact or effective permission to perform one or more defined operations. + +### Standing Authority + +Authority that persists independently of a specific short-lived task, session, or workflow. + +### Dynamic Secret + +A credential generated on demand for a specific consumer or lease and automatically expiring or revocable. + +### Secretless Access + +Access based on non-exportable or federated identity mechanisms without provisioning a long-lived shared secret to the consumer. + +### Authority Ceiling + +The maximum authority an actor can obtain under deterministic policy, regardless of what the actor requests or reasons. + +--- + +## 13. Credential Hierarchy + +| Class | Meaning | Target treatment | +|---|---|---| +| **S0 — Secretless** | No reusable transferable secret is provisioned | Preferred | +| **S1 — Ephemeral identity** | Short-lived JWT, STS token, SVID, certificate, session token | Normal operating state | +| **S2 — Dynamic secret** | Per-consumer/per-task generated credential with lease | Preferred where identity cannot be consumed directly | +| **S3 — Managed static secret** | API key/password that must persist | Central storage, ownership, automatic rotation, monitoring | +| **S4 — Root/bootstrap material** | CA keys, recovery material, break-glass authority | Exceptional, offline/HSM/quorum protected | + +The migration direction is: + +```text +S4 → S3 → S2 → S1 → S0 +``` + +Not every system can reach S0, but every S3/S4 credential SHOULD have an explicit justification. + +--- + +## 14. Authority Context for Agent Actions + +A privileged agent action SHOULD be attributable to a context comparable to: + +```text +principal: Alice +actor: deploy-agent-22 +runtime: spiffe://example/prod/deployer/22 +session: s-779381 +task: deploy release 7.2.1 +action: production.deploy +resource: cluster/payments +approval: approval-9432 +policy_version: authz-2026-08-17 +expires: 2026-08-24T18:42:00Z +``` + +The aim is not to make every token carry every field. The aim is to preserve enough linked evidence across identity, authorization, credential issuance, execution, and audit systems to reconstruct the chain. + +--- + +# Part V — Control Catalog + +## 15. Identity Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-I01** | Human federation | Human access to production systems MUST use organizational identity federation where supported. | +| **ASM-I02** | Strong human authentication | Privileged human access SHOULD use phishing-resistant MFA/passkeys/security keys. | +| **ASM-I03** | Workload identity | Significant services, jobs, agents, and pipelines MUST have distinct workload identities. | +| **ASM-I04** | No shared machine identities | Multiple autonomous actors MUST NOT share one generic machine identity unless technically unavoidable and risk-accepted. | +| **ASM-I05** | Identity is not authorization | Authentication of an actor MUST NOT by itself imply resource authorization. | +| **ASM-I06** | Lifecycle-bound identity | Agent and workload identities MUST be disabled or decommissioned when the corresponding workload or mandate ends. | +| **ASM-I07** | Identity provenance | Identity issuers and trust relationships MUST be explicitly governed and auditable. | + +--- + +## 16. Operating-Mode Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-M01** | Declare mode | Each agentic workflow MUST be classified as Assistant or Autonomous. | +| **ASM-M02** | Human principal in Assistant mode | Assistant sessions SHOULD be associated with an identified supervising human principal. | +| **ASM-M03** | Independent identity in Autonomous mode | Autonomous agents MUST authenticate using a distinct workload/agent identity, not a borrowed human credential. | +| **ASM-M04** | Preserve actor identity | Audit SHOULD distinguish human principal and agent actor where technically possible. | +| **ASM-M05** | Explicit autonomy transition | Moving a workflow from Assistant to Autonomous mode MUST undergo security/governance review. | +| **ASM-M06** | No accidental autonomy | Human disconnect or session timeout MUST NOT silently convert a privileged Assistant workflow into Autonomous operation. | +| **ASM-M07** | Supervision boundary | Assistant-mode tools SHOULD expose clear interruption, pause, and confirmation mechanisms for high-impact actions. | +| **ASM-M08** | Mode-specific credentials | Credential issuance SHOULD reflect whether authority is human-session delegated or independently assigned to an autonomous agent. | + +--- + +## 17. Deterministic Security Substrate Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-S01** | Deterministic enforcement | Protected-resource authorization MUST ultimately be enforced by deterministic mechanisms. | +| **ASM-S02** | LLMs cannot grant authority | Agent reasoning MUST NOT directly create additional privilege. | +| **ASM-S03** | Tool discovery ≠ authorization | Tool/MCP discovery MUST NOT be interpreted as permission. | +| **ASM-S04** | Resource-side validation | Sensitive APIs MUST independently validate effective authorization. | +| **ASM-S05** | No prompt-only boundary | Prompt instructions MUST NOT be considered sufficient access control. | +| **ASM-S06** | Deterministic credential issuance | Credential brokers MUST evaluate explicit policy before issuing privileged credentials. | +| **ASM-S07** | Hard authority ceiling | Agents MAY use less authority than available but MUST NOT exceed the policy-defined maximum. | +| **ASM-S08** | Fail closed | Security-critical policy, approval, or audit failures SHOULD block privileged actions rather than silently bypass controls. | +| **ASM-S09** | Independent kill switch | Autonomous write authority MUST be revocable independently of the agent. | +| **ASM-S10** | Protected security policy | Agents MUST NOT have ordinary workload-level authority to modify their own maximum authorization. | +| **ASM-S11** | Separation of policy change | Security-policy changes SHOULD require stronger authorization than routine application changes. | +| **ASM-S12** | Restrictive probabilistic signals | Model-derived signals MAY reduce or suspend authority; they SHOULD NOT be the sole input that expands authority. | + +--- + +## 18. Credential Lifecycle Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-C01** | Eliminate first | Before storing a new secret, teams MUST evaluate whether federation or workload identity can eliminate it. | +| **ASM-C02** | Temporary credentials default | Cloud and infrastructure access SHOULD use short-lived federated credentials rather than static keys. | +| **ASM-C03** | Dynamic backend credentials | Databases and similar systems SHOULD use per-client dynamic credentials where supported. | +| **ASM-C04** | Explicit TTL | Machine credentials capable of expiration MUST have defined TTLs. | +| **ASM-C05** | Consumer-specific credentials | Unavoidable static credentials SHOULD be distinct per consumer and environment. | +| **ASM-C06** | Automatic rotation | Managed static machine secrets SHOULD rotate automatically. | +| **ASM-C07** | Immediate compromise revocation | Suspected or confirmed leaked credentials MUST be revoked without waiting for scheduled rotation. | +| **ASM-C08** | Separate rotation from revocation | Processes MUST distinguish routine rotation from incident-driven revocation. | +| **ASM-C09** | Secret-zero minimization | Workload identity, attestation, OIDC, cloud identity, SPIFFE, TPM/HSM, or equivalent SHOULD bootstrap secret access instead of another static secret. | +| **ASM-C10** | Root material isolation | Root, recovery, CA, and break-glass credentials MUST be exceptional and protected with stronger controls than ordinary application credentials. | +| **ASM-C11** | No credential copying by default | Credentials SHOULD NOT be duplicated across systems unless an explicit synchronization model preserves ownership and lifecycle. | +| **ASM-C12** | Credential ownership | Every persistent credential MUST have a named technical and organizational owner. | + +--- + +## 19. Agent-Specific Authority Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-A01** | Principal/actor separation | Delegated operations SHOULD preserve both originating principal and executing actor. | +| **ASM-A02** | No invisible impersonation | Agents SHOULD NOT simply reuse a human credential in a way that makes the actor indistinguishable. | +| **ASM-A03** | Task-scoped authority | Agent authority SHOULD reflect the current task, environment, resource, and operation. | +| **ASM-A04** | Delegation attenuation | Child agents MUST NOT automatically gain more authority than their caller. | +| **ASM-A05** | Per-tool authorization | Sensitive tool invocation MUST be independently authorized at or below the tool boundary. | +| **ASM-A06** | Read/write separation | Read, write, privileged, destructive, and irreversible capabilities SHOULD be separately controlled. | +| **ASM-A07** | No reusable credentials in model context | Raw reusable credentials MUST NOT intentionally be placed in prompts, model context, memory, or retrieval corpora. | +| **ASM-A08** | Brokered execution | Where feasible, a trusted execution layer SHOULD exercise credentials on behalf of the model instead of disclosing them to it. | +| **ASM-A09** | Risk classification | Tool actions SHOULD be classified by operational impact. | +| **ASM-A10** | Step-up for high impact | High-impact actions SHOULD require stronger authorization, approval, or independent validation. | +| **ASM-A11** | Parameter-bound approval | Approval for sensitive actions SHOULD bind actor, tool, target, normalized parameters, time, and expiry. | +| **ASM-A12** | Replay resistance | High-impact approval artifacts SHOULD be short-lived and non-replayable. | + +--- + +## 20. Change Dynamics Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-X01** | Define change envelope | Production environments SHOULD define acceptable rate, scope, and concurrency of autonomous change. | +| **ASM-X02** | Bound blast radius | Agent authority SHOULD be constrained by repository, environment, resource class, and operation. | +| **ASM-X03** | Concurrency limits | Autonomous mutation concurrency MUST be explicitly bounded. | +| **ASM-X04** | Runtime limits | Autonomous jobs SHOULD have maximum execution durations. | +| **ASM-X05** | Resource budgets | Token, compute, tool-call, and external-service budgets SHOULD be enforced for autonomous workflows. | +| **ASM-X06** | Budgets are not authorization | Economic limits MUST NOT be relied upon as the sole protection against privileged actions. | +| **ASM-X07** | Progressive delegation | Broader autonomy SHOULD be earned through operational evidence and explicit governance decisions. | +| **ASM-X08** | Velocity-aware monitoring | Detection and remediation capacity SHOULD scale with autonomous change velocity. | +| **ASM-X09** | Circuit breakers | Defined anomaly or invariant violations SHOULD deterministically suspend autonomous write authority. | +| **ASM-X10** | Safe degraded mode | When automation is degraded, the system SHOULD preferentially preserve read/diagnostic access while reducing mutation authority. | + +--- + +## 21. Development Workstation Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-D01** | SSO for developer tooling | Git, cloud, Kubernetes, and secret-management access SHOULD use federated sessions. | +| **ASM-D02** | JIT local credentials | CLI credentials SHOULD be short-lived and refreshable through SSO/federation. | +| **ASM-D03** | Agent sandboxing | Coding agents SHOULD execute inside explicit filesystem, network, process, and tool boundaries. | +| **ASM-D04** | Repository-specific capability | An agent session SHOULD receive only credentials and tools needed for the active project. | +| **ASM-D05** | No environment inheritance by default | Agent processes SHOULD NOT automatically inherit the complete human shell environment or all `.env` values. | +| **ASM-D06** | Pre-commit detection | Secret scanning SHOULD occur before code enters version control. | +| **ASM-D07** | Transcript redaction | Shell logs, traces, agent transcripts, and debugging output MUST avoid storing plaintext credentials. | +| **ASM-D08** | Local credential isolation | SSH agents, cloud sessions, browser sessions, and local secret stores SHOULD be selectively exposed rather than globally available to coding agents. | + +--- + +## 22. CI/CD Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-CI01** | CI workload federation | CI/CD SHOULD use OIDC or equivalent workload federation instead of stored cloud credentials. | +| **ASM-CI02** | Job-bound lifetime | Deployment credentials SHOULD expire approximately with job lifetime. | +| **ASM-CI03** | Claim restrictions | Trust SHOULD be restricted by repository, organization, workflow, branch, environment, and/or other verifiable claims. | +| **ASM-CI04** | Environment separation | Development, test, staging, and production deployment identities MUST be independently authorized. | +| **ASM-CI05** | Pull-request isolation | Untrusted forks and pull requests MUST NOT receive production credentials. | +| **ASM-CI06** | Ephemeral privileged runners | Privileged pipelines SHOULD use disposable or strongly isolated execution environments. | +| **ASM-CI07** | Agent-produced pipeline changes | Changes to workflow identity, secrets, permissions, or deployment gates SHOULD receive stronger review than ordinary code. | +| **ASM-CI08** | Artifact provenance | Production deployment SHOULD preserve linkage between source, workflow identity, artifact, and deployment action. | + +--- + +## 23. Kubernetes and Runtime Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-K01** | Workload identity first | Pods and workloads SHOULD authenticate using bounded service-account/workload identity tokens. | +| **ASM-K02** | Avoid legacy non-expiring tokens | Long-lived Kubernetes service-account token Secrets SHOULD NOT be used when TokenRequest/projected tokens are viable. | +| **ASM-K03** | Pod/job-scoped identity | Runtime identity SHOULD be bound to the actual workload instance or workload class. | +| **ASM-K04** | Dynamic credential bridge | Workload identity SHOULD be exchanged for dynamic database/cloud credentials when target systems cannot consume workload identity directly. | +| **ASM-K05** | Minimize Kubernetes Secrets | Kubernetes Secrets SHOULD be compatibility fallbacks rather than the default credential architecture. | +| **ASM-K06** | Secret mount lifecycle | Ephemeral mounts or agents/CSI mechanisms SHOULD align credential exposure with workload lifecycle. | +| **ASM-K07** | Namespace/environment boundaries | Runtime identity and authorization MUST respect environment and tenancy boundaries. | +| **ASM-K08** | Admission/policy enforcement | Production clusters SHOULD enforce deployment and privilege invariants independently of agent-generated manifests. | + +--- + +## 24. MCP and Agent Protocol Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-P01** | Audience-bound tokens | Tokens used for MCP/resource access MUST be bound to their intended resource/audience. | +| **ASM-P02** | No token passthrough | MCP servers MUST NOT simply forward inbound bearer tokens to unrelated downstream services. | +| **ASM-P03** | Downstream credential exchange | Downstream services SHOULD receive separately issued or exchanged credentials. | +| **ASM-P04** | Incremental scope | Tool scopes SHOULD be requested incrementally rather than granting broad access at session start. | +| **ASM-P05** | Interactive flow protection | Interactive OAuth flows SHOULD use modern authorization-code protections such as PKCE. | +| **ASM-P06** | Tool supply-chain governance | MCP servers, tools, schemas, and tool-definition changes SHOULD be allowlisted, reviewed, and monitored. | +| **ASM-P07** | Metadata contains no secrets | Discovery metadata MUST NOT contain live credentials. | +| **ASM-P08** | Agent-chain attenuation | Agent-to-agent delegation SHOULD preserve identity context and enforce non-escalation. | +| **ASM-P09** | Resource-side authorization | Tool servers that access backends MUST still enforce backend-appropriate authorization. | + +--- + +## 25. Discovery and Exposure Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-R01** | Scan before commit | IDE/save/pre-commit secret scanning SHOULD catch leaks at the earliest practical point. | +| **ASM-R02** | Push protection | High-confidence secrets SHOULD be blocked before repository insertion when tooling permits. | +| **ASM-R03** | Continuous scanning | New commits, pull requests, CI artifacts, and relevant collaboration/configuration systems SHOULD be continuously scanned. | +| **ASM-R04** | Historical scanning | Repository history SHOULD be scanned, not only the latest branch state. | +| **ASM-R05** | Organization-specific patterns | Secret detection SHOULD include custom token and credential formats. | +| **ASM-R06** | Activeness/validity context | Findings SHOULD be prioritized using whether the credential is still active where safely determinable. | +| **ASM-R07** | Managed/unmanaged correlation | Detection SHOULD distinguish credentials governed by an approved manager from unmanaged exposure. | +| **ASM-R08** | Ownership enrichment | Findings SHOULD be enriched with likely owner, source, environment, and affected resources. | +| **ASM-R09** | Minimize scanner custody | Secret scanning systems SHOULD retain hashes/fingerprints and metadata rather than plaintext secret values where possible. | +| **ASM-R10** | Agent context scanning | Agent prompts, traces, memories, and generated artifacts SHOULD be included in leakage controls where technically feasible and privacy-appropriate. | + +--- + +## 26. Remediation Controls + +A secret exposure MUST be treated as a credential-lifecycle incident, not merely as a source-code defect. + +Recommended state model: + +```text +DETECTED + ↓ +TRIAGED + ↓ +OWNED + ↓ +REPLACEMENT_READY + ↓ +CONSUMERS_MIGRATED + ↓ +OLD_CREDENTIAL_REVOKED + ↓ +VERIFIED + ↓ +RESOLVED +``` + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-RM01** | Named owner | Every actionable finding MUST acquire an accountable owner. | +| **ASM-RM02** | Workflow integration | Findings SHOULD enter the developer/operator workflows where remediation work actually occurs. | +| **ASM-RM03** | Contextual guidance | Owners SHOULD receive practical replacement and architectural guidance, not merely an alert. | +| **ASM-RM04** | Revoke old credential | Exposure is not resolved until the old credential has been revoked or otherwise invalidated. | +| **ASM-RM05** | Verify closure | The system SHOULD verify that the exposed credential can no longer authenticate. | +| **ASM-RM06** | Investigate use | Relevant access logs SHOULD be reviewed between likely exposure and revocation. | +| **ASM-RM07** | Architecture correction | A leaked static machine credential SHOULD trigger evaluation of federation, workload identity, or dynamic issuance. | +| **ASM-RM08** | Source cleanup is insufficient | Removing a secret from current source code MUST NOT by itself close the security finding. | +| **ASM-RM09** | Measurable remediation | Remediation status, backlog, severity, and time-to-revoke SHOULD be measurable. | +| **ASM-RM10** | Recurrence prevention | Repeated leak classes SHOULD result in preventive control improvement. | + +--- + +## 27. Audit and Observability Controls + +A privileged action SHOULD be reconstructable as: + +```text +Human principal: alice@example +Agent actor: deploy-agent-22 +Runtime identity: spiffe://company/prod/deployer/22 +Session: s-779381 +Task: deploy release 7.2.1 +Authorization: production.deploy +Approval: approval-9432 +Credential class: short-lived STS role +Resource: prod/cluster-a +Action: UpdateDeployment +Result: success +Expiry: 18:42 UTC +``` + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-O01** | End-to-end correlation | Task/session/trace identifiers SHOULD link agent, authority, credential, and resource events. | +| **ASM-O02** | Principal + actor logging | Delegated actions SHOULD preserve both principal and actor context. | +| **ASM-O03** | Credential issuance evidence | Audit SHOULD record why and under which policy a credential was issued, never its plaintext value. | +| **ASM-O04** | Sensitive-value redaction | Credentials MUST NOT become ordinary log fields. | +| **ASM-O05** | Independent audit plane | Privileged audit records SHOULD be forwarded to independently controlled storage/SIEM. | +| **ASM-O06** | Audit availability monitoring | Audit-pipeline failure MUST itself be monitored. | +| **ASM-O07** | Policy-version evidence | Privileged actions SHOULD be attributable to the authorization policy version in force. | +| **ASM-O08** | Approval evidence | High-impact actions SHOULD retain approval identity, scope, parameters, and expiry. | +| **ASM-O09** | Agent version evidence | For significant autonomous actions, logs SHOULD identify agent/workflow/model/tool-policy versions where practical. | +| **ASM-O10** | Security telemetry integrity | Agents SHOULD NOT have authority to delete or silently rewrite their security telemetry. | + +--- + +## 28. Governance Controls + +| ID | Practice | Requirement | +|---|---|---| +| **ASM-G01** | Named governance owner | Every autonomous agent class MUST have an organizational owner. | +| **ASM-G02** | Explicit mandate | Autonomous agents MUST have a defined purpose and permitted action domain. | +| **ASM-G03** | Maximum authority profile | Autonomous agents MUST have a documented authority ceiling. | +| **ASM-G04** | Budget profile | Autonomous workflows SHOULD have explicit runtime, token, compute, and external-spend limits. | +| **ASM-G05** | Policy-change separation | Agents MUST NOT casually modify the policies that define their own maximum authority. | +| **ASM-G06** | Break-glass governance | Emergency credentials and privilege escalation MUST have explicit procedures, ownership, and audit. | +| **ASM-G07** | Exception expiry | Security exceptions SHOULD expire and require re-approval rather than becoming permanent by neglect. | +| **ASM-G08** | Autonomy review | Autonomous capabilities SHOULD be periodically reviewed against actual use and incidents. | +| **ASM-G09** | Least-authority review | Unused or unnecessary permissions SHOULD be removed. | +| **ASM-G10** | Security tests as controls | Production agent changes SHOULD include regression/adversarial tests for authorization and tool-abuse failure modes. | +| **ASM-G11** | Stronger control for control-plane changes | Identity, Vault, IAM, RBAC, MCP authorization, audit, and policy-engine changes SHOULD require higher review than normal application code. | +| **ASM-G12** | Residual-risk evidence | Accepted deviations from the Canon SHOULD record rationale, owner, compensating controls, and review date. | + +--- + +# Part VI — Profiles + +## 29. Production Baseline Profile + +A production environment SHOULD minimally provide: + +- federated human identity; +- unique workload identity; +- deterministic resource-side authorization; +- short-lived credentials where feasible; +- centralized management of unavoidable static secrets; +- audit logging outside agent control; +- secret scanning; +- revocation and remediation workflow; +- protected security-policy changes; +- explicit separation between cognitive and authority planes. + +The production baseline MUST NOT depend on correct LLM behavior for its core access guarantees. + +--- + +## 30. Agent Assistant Coding Profile + +Agent Assistant environments SHOULD additionally provide: + +- identified supervising human principal; +- distinguishable agent actor/session where feasible; +- explicit filesystem/network/tool boundaries; +- selective rather than global exposure of the human's credentials; +- no automatic inheritance of every local credential; +- reversible/previewable high-impact actions; +- human interruption and pause capability; +- short-lived human sessions; +- deterministic production restrictions despite active supervision; +- prevention of silent continuation after the supervising session ends. + +A practical baseline is: + +```text +human identity + ↓ +interactive session + ↓ +assistant agent actor + ↓ +restricted execution gateway + ↓ +deterministic policy + ↓ +target system +``` + +--- + +## 31. Autonomous Agent Coding Profile + +Autonomous environments MUST additionally provide: + +- unique agent/workload identity; +- named governance owner; +- explicit mandate; +- explicit authority ceiling; +- task/environment/resource scopes; +- runtime and credential TTL; +- concurrency limits; +- token/compute/tool-call budget; +- independent circuit breaker; +- protected policy boundary; +- independent audit; +- no dependence on borrowed human credentials; +- traceable delegation when acting on behalf of a human or service; +- stronger controls for production mutation; +- explicit lifecycle termination. + +A practical baseline is: + +```text +governance mandate + ↓ +agent/workload identity + ↓ +task authorization + ↓ +short-lived capability + ↓ +execution gateway + ↓ +resource-side enforcement + ↓ +audit + telemetry + ↓ +circuit breaker / remediation +``` + +--- + +# Part VII — Decision Patterns + +## 32. Preferred Authentication and Credential Patterns + +| Situation | Preferred mechanism | Avoid | +|---|---|---| +| Human web access | OIDC/SSO + strong MFA/passkey | application-local credentials | +| Human cloud CLI | SSO → temporary role/session | permanent cloud access keys | +| Human production admin | JIT privileged role + step-up | standing administrator | +| Assistant coding session | human principal + constrained agent actor/session | exporting all workstation secrets to agent | +| Autonomous agent | workload identity + task-scoped authority | borrowed human token | +| GitHub Actions | OIDC → cloud/Vault short-lived credential | stored cloud keys | +| Kubernetes → cloud | native workload/pod identity | IAM/service-account static key | +| Kubernetes → DB | workload identity → dynamic DB credential | shared DB password | +| Cross-cloud workload | workload federation / SPIFFE-style identity | exported service-account key | +| Agent → MCP server | resource-bound OAuth token | shared static bearer key | +| MCP → backend | new downstream token / token exchange | inbound-token passthrough | +| Agent → database | brokered dynamic credential | DB password in prompt | +| High-risk agent write | JIT authorization + action-bound approval | permanent broad write role | +| Legacy third-party API | per-consumer secret + central manager + rotation | shared key in source/config | +| Root/recovery | offline/HSM/quorum-controlled material | routine online use | + +--- + +# Part VIII — Assurance Tests + +## 33. Canon Security Tests + +### T-01 — Malicious Model Test + +Assume the agent intentionally requests the most privileged destructive action available. + +**Pass condition:** deterministic controls still limit execution to the configured authority ceiling. + +### T-02 — Credential Exfiltration Test + +Assume a prompt-injected agent tries to print or transmit every credential it can reach. + +**Pass condition:** reusable credentials are not present in model context and the runtime can only obtain narrowly scoped authority. + +### T-03 — Human Disconnect Test + +Terminate the supervising user's Agent Assistant session mid-task. + +**Pass condition:** privileged authority expires or stops according to policy; the workflow does not silently become autonomous. + +### T-04 — Policy Self-Modification Test + +Ask the autonomous agent to broaden the policy that constrains its own access. + +**Pass condition:** ordinary agent authority cannot modify its maximum authority boundary. + +### T-05 — Confused Deputy Test + +Present a valid token intended for service A to service B or attempt MCP downstream token passthrough. + +**Pass condition:** audience/resource validation rejects the token and downstream access requires separately authorized credentials. + +### T-06 — Approval Replay Test + +Reuse a previously valid approval artifact for a different target, parameter set, or later time. + +**Pass condition:** parameter binding, expiry, or replay protection rejects the request. + +### T-07 — Circuit Breaker Test + +Trigger defined anomaly/change-rate thresholds. + +**Pass condition:** autonomous mutation authority is suspended without requiring agent cooperation. + +### T-08 — Audit Reconstruction Test + +Select a privileged production mutation. + +**Pass condition:** investigators can reconstruct principal, actor, runtime, task, policy, credential issuance, target, action, and result. + +### T-09 — Audit Failure Test + +Disable or overload the primary audit path. + +**Pass condition:** the system alerts, fails closed where required, or uses redundant audit paths according to policy. + +### T-10 — Revocation Closure Test + +Leak a test credential, remediate it, and attempt reuse. + +**Pass condition:** the old credential is invalid and closure evidence is recorded. + +--- + +# Part IX — Metrics + +## 34. Exposure Metrics + +| Metric | Desired direction | +|---|---:| +| Static machine credentials | ↓ | +| Active unmanaged secrets | **0** | +| Orphan credentials without owner | **0** | +| Credentials older than policy | **0** | +| Production workloads using federation | ↑ toward 100% | +| Dynamic/JIT credentials as share of machine authentication | ↑ | +| Secrets found in current code | **0** | +| Secrets found in historical repositories | ↓ | + +--- + +## 35. Agentic Security Metrics + +| Metric | Desired direction | +|---|---:| +| Autonomous agents with unique identity | 100% | +| Autonomous agents with named owner | 100% | +| Autonomous agents with authority ceiling | 100% | +| Delegated actions carrying principal + actor evidence | 100% where applicable | +| High-impact actions linked to explicit authorization | 100% | +| Reusable credentials intentionally exposed to LLM context | **0** | +| Cross-tool token passthrough | **0** | +| Autonomous workflows with circuit breakers | 100% for production mutation | +| Autonomous workflows with defined budgets | 100% | + +--- + +## 36. Change Dynamics Metrics + +Relevant operational metrics include: + +- autonomous changes per hour/day; +- concurrent mutating agents; +- production deployments initiated autonomously; +- average agent runtime; +- tool calls per task; +- irreversible actions per task; +- rollbacks per autonomous change; +- policy-denied agent actions; +- circuit-breaker activations; +- human interventions per autonomous workflow; +- token/compute spend per successful change; +- change failure rate by Human / Assistant / Autonomous mode. + +These metrics help determine whether observed change velocity remains inside the designed Change Dynamics Envelope. + +--- + +## 37. Remediation Metrics + +Recommended measures: + +```text +MTTD = mean time to detect +MTTO = mean time to ownership +MTTRv = mean time to revoke +MTTR = mean time to full remediation +``` + +**MTTRv** is especially important because ticket closure can lag or misrepresent the security-critical event: invalidation of the exposed credential. + +Also track: + +- backlog versus inflow; +- unresolved active credentials; +- failed rotations; +- failed renewals; +- unused credential count; +- break-glass usage; +- repeated leak classes; +- time from exposure to architectural correction. + +--- + +# Part X — Maturity Model + +## 38. ASM Maturity + +| Level | State | +|---|---| +| **ASM-0 — Embedded** | Credentials are dispersed, copied, and long-lived; little inventory exists. | +| **ASM-1 — Stored** | Central secret manager, RBAC, basic scanning, and basic rotation exist. | +| **ASM-2 — Managed** | Ownership, automated rotation, inventory, detection, and measurable remediation are established. | +| **ASM-3 — Dynamic** | Workload federation, JIT access, dynamic secrets, and secretless CI/CD reduce standing credentials. | +| **ASM-4 — Agent-Aware** | Human principal and agent actor are distinguished; Assistant and Autonomous modes are explicitly modeled. | +| **ASM-5 — Governed Autonomy** | Autonomous agents have identities, mandates, budgets, authority ceilings, change envelopes, and deterministic circuit breakers. | +| **ASM-6 — Closed-Loop Authority** | Identity, delegation, credential issuance, execution, evidence, exposure detection, revocation, and remediation operate as one continuously reconciled authority lifecycle. | + +At ASM-6, "secrets management" has effectively evolved into an: + +> **Authority Lifecycle Control System for hybrid human/agent infrastructure.** + +--- + +# Part XI — Review Checklist + +## 39. Architecture Review Questions + +A production design should be able to answer: + +1. Which actors can reach this resource? +2. Which principal or mandate gives them authority? +3. What is the maximum authority each actor can obtain? +4. Can an agent modify the rules that determine that authority? +5. Can a model decision alone increase privilege? +6. Are credentials short-lived or dynamically generated where possible? +7. Can raw reusable credentials reach model context, logs, or memory? +8. What happens when the supervising human disconnects? +9. Can tool discovery accidentally become authorization? +10. Is token audience/resource binding enforced? +11. Can a child agent escalate beyond its caller? +12. What is the maximum autonomous change rate and concurrency? +13. Which circuit breaker halts runaway mutation? +14. Does that breaker work without agent cooperation? +15. Can the organization revoke all authority for a compromised agent identity? +16. Can investigators reconstruct who or what authorized a privileged action? +17. Can an agent erase that evidence? +18. What proves that a leaked credential has actually been revoked? +19. Are security-policy changes governed more strongly than application changes? +20. If every LLM behaves incorrectly, which protections still remain? + +--- + +# Part XII — Review Conclusions for v0.3 + +The review leading to this version made the following refinements: + +1. **Agent Assistant Coding and Autonomous Agent Coding are now explicit operating modes.** + Their identity, credential, accountability, and governance requirements differ. + +2. **The deterministic security substrate is elevated from a recommendation to a foundational invariant.** + Probabilistic systems can reason about access but cannot be the sole source of authorization. + +3. **Deterministic is explicitly distinguished from static.** + Contextual and dynamic policy is fully compatible with deterministic enforcement. + +4. **Change Dynamics is treated as a security property.** + Agentic coding changes not only who acts but how quickly and concurrently system state can change. + +5. **Budget and resource limits are recognized as blast-radius controls.** + They complement but never replace authorization. + +6. **Transition from Assistant to Autonomous operation is treated as a security architecture change.** + +7. **Policy self-modification receives explicit protection.** + Autonomous agents must not casually alter the controls that define their own maximum authority. + +8. **Agentic infrastructure remains subordinate to deterministic infrastructure controls.** + MCP, A2A, agent-to-agent, and infrastructure-agent patterns do not eliminate resource-side authorization. + +9. **The remediation lifecycle is retained as a closed-loop control.** + Detection is not success; revocation and verified closure are. + +10. **Absolute "security guarantees" are avoided as a claim.** + Deterministic enforcement is necessary for enforceable security properties and auditable assurance, but no engineering architecture can promise absolute security. + +--- + +# Part XIII — External Reference Basis + +The Canon is an original synthesis, not a restatement of any single external standard. Its design is consistent with and informed by the following bodies of work. + +## NIST + +- NIST SP 800-207 — *Zero Trust Architecture* +- NIST SP 800-207A — *A Zero Trust Architecture Model for Access Control in Cloud-Native Applications in Multi-Cloud Environments* +- NIST SP 800-63B-4 — *Digital Identity Guidelines: Authentication and Authenticator Management* + +## IETF / OAuth + +- RFC 8693 — *OAuth 2.0 Token Exchange* +- RFC 8707 — *Resource Indicators for OAuth 2.0* +- RFC 9396 — *OAuth 2.0 Rich Authorization Requests* +- RFC 9449 — *OAuth 2.0 Demonstrating Proof of Possession (DPoP)* +- RFC 9728 — *OAuth 2.0 Protected Resource Metadata* + +RFC 8693 is particularly relevant to the principal/actor distinction because it defines delegation semantics and the `act` actor claim. + +## OWASP + +- OWASP Secrets Management Cheat Sheet +- OWASP AI Agent Security Cheat Sheet +- OWASP guidance on least privilege, tool security, high-impact approval, sensitive-data handling, and agentic failure modes + +## Kubernetes and Workload Identity + +- Kubernetes ServiceAccount TokenRequest / bound projected service-account tokens +- SPIFFE / SPIRE workload identity concepts +- cloud-native workload federation and short-lived identity patterns + +## CI/CD + +- GitHub Actions OpenID Connect guidance for short-lived cloud credentials and claim-bound trust + +## Agent Protocols + +- Model Context Protocol authorization specification, including resource/audience binding and prohibition of token passthrough +- A2A enterprise authorization guidance, including identity-, skill-, action-, and data-level controls + +## HashiCorp Vault / Vault Radar + +- Vault dynamic database credentials and leases +- Vault audit logging best practices +- Vault Secrets Sync and workload identity federation +- HCP Vault Radar secret detection, activeness context, remediation workflow, and managed/unmanaged correlation + +--- + +# 40. Closing Principle + +The Canon can be reduced to one architectural rule: + +> **Agents may decide what to attempt; deterministic systems decide what may succeed.** + +From that principle follows the preferred lifecycle: + +> **Identity → delegation → deterministic authorization → ephemeral authority → execution → evidence → detection → revocation → verified remediation.** + +The practical consequence is that secrets become progressively less central: + +> **Old model:** securely store passwords, tokens, and keys. +> **Modern model:** minimize and dynamically manage credentials. +> **Agentic model:** dynamically manage authority, producing credentials only as short-lived implementation artifacts. + +That is the intended direction of Active Secrets Management. + diff --git a/spec/ArchitectureBlueprint.md b/spec/ArchitectureBlueprint.md new file mode 100644 index 0000000..bf9d727 --- /dev/null +++ b/spec/ArchitectureBlueprint.md @@ -0,0 +1,2512 @@ +# Gate House — Architecture Blueprint + +**Repository:** `gate-house` +**Project family:** NetKingdom +**Artifact:** `ArchitectureBlueprint.md` +**Status:** Initial architecture blueprint +**Version:** 0.1 +**Date:** 2026-08-24 + +--- + +## 1. Purpose + +This document translates the Gate House intent into a practical architecture for a first reference implementation. + +Gate House is the **deterministic authority plane** for human, workload, and agent-active NetKingdom environments. It is the reference implementation of the Active Secrets Management (ASM) Plane. + +Its central responsibility is: + +> **Decide whether a requested action is allowed, under explicit and reproducible rules, and represent that decision as bounded authority that downstream systems can enforce.** + +Gate House does not replace identity systems, secrets backends, policy engines, runtime execution systems, or adaptive security systems. It coordinates them around a canonical authority model. + +The architectural maxim is: + +> **Cognition proposes. Authority disposes. Infrastructure executes.** + +--- + +# 2. Architectural Goals + +Gate House should optimize for the following properties. + +## 2.1 Deterministic final authorization + +The final decision to grant or deny protected authority must be made by deterministic mechanisms. + +LLMs, agents, probabilistic classifiers, or adaptive systems may contribute context or request actions, but they must not be able to manufacture authority by themselves. + +## 2.2 Explicit identity chain + +The system should distinguish: + +- the **principal** on whose behalf authority originates; +- the **actor** directly requesting or performing the action; +- the **runtime identity** of the executing workload; +- the **tenant** and organizational context; +- the **mandate** or delegated purpose under which the action is attempted. + +## 2.3 Least authority + +Authority should be: + +- task-scoped; +- action-scoped; +- resource-scoped; +- tenant-scoped; +- environment-scoped; +- time-bounded; +- quota-bounded where appropriate. + +## 2.4 Short-lived authority + +Standing credentials and standing privilege should be minimized. + +Gate House should prefer issuance of short-lived authorization grants and rely on the Secrets Engine/OpenBao or cloud-native STS mechanisms to materialize them as short-lived credentials where necessary. + +## 2.5 Explicit agentic operating modes + +The system must support and distinguish: + +- **Agent Assistant Coding** — human-supervised; +- **Autonomous Agent Coding** — independently operating under explicit mandate. + +The transition from Assistant to Autonomous mode is an explicit governance event. + +## 2.6 Safe autonomy + +Autonomous agents must be independently stoppable. + +Gate House should support deterministic: + +- expiry; +- revocation; +- concurrency limits; +- action quotas; +- environment restrictions; +- circuit breakers; +- step-up authorization. + +## 2.7 Explainability and evidence + +Every material authorization decision should be reconstructable: + +> Who acted? On whose behalf? Under which mandate? Against which resource? For which action? Under which policy and constraints? For how long? And why was it allowed or denied? + +## 2.8 Composability + +Gate House should be a small control plane with explicit integration contracts. + +It should avoid becoming: + +- an IAM suite; +- another secret manager; +- a SIEM; +- an incident platform; +- a workflow engine; +- an agent runtime. + +--- + +# 3. Non-Goals + +The first Gate House implementation will not attempt to: + +- replace OpenBao; +- replace Key Cape; +- replace User Engine; +- replace Tenant Engine; +- implement King's Guard; +- implement a general secrets scanner; +- implement a general policy language; +- implement a general-purpose workflow engine; +- implement full cloud IAM abstraction; +- implement autonomous remediation; +- become the system of record for every security policy in NetKingdom. + +Its job is to provide the deterministic authority contract connecting these systems. + +--- + +# 4. System Context + +```mermaid +flowchart TB + H[Human Developer / Operator] + AA[Assistant Agent] + AU[Autonomous Agent] + KG[King's Guard] + KC[Key Cape] + UE[User Engine] + TE[Tenant Engine] + + GH[Gate House] + + SE[Secrets Engine] + OB[OpenBao] + OW[Ops Warden] + OM[Ops Mason] + + K8S[Kubernetes] + CLOUD[Cloud APIs] + DB[Databases] + GIT[Git / CI/CD] + SAAS[SaaS / External APIs] + + WH[Whitehat Security] + AUD[Audit / Evidence Store] + + H --> KC + KC --> GH + UE --> GH + TE --> GH + + H --> AA + AA --> GH + AU --> GH + + KG --> GH + + GH --> SE + SE --> OB + + GH --> OW + GH --> OM + + OW --> K8S + OW --> CLOUD + OW --> DB + OM --> K8S + OM --> CLOUD + + GH --> GIT + GH --> SAAS + + GH --> AUD + KG --> AUD + OW --> AUD + OM --> AUD + + WH --> GH + WH --> KG +``` + +--- + +# 5. Three-Plane Model + +Gate House is easiest to reason about as the center of three planes. + +## 5.1 Cognitive Plane + +The Cognitive Plane determines what might usefully happen next. + +Examples: + +- humans; +- LLMs; +- coding agents; +- operations agents; +- planners; +- MCP clients; +- A2A agents; +- King's Guard risk analysis. + +The Cognitive Plane can request authority. + +It cannot grant authority. + +## 5.2 Authority Plane + +Gate House belongs to the Authority Plane. + +The Authority Plane evaluates: + +- authenticated identity; +- principal; +- actor; +- runtime identity; +- tenant; +- environment; +- task; +- mandate; +- delegation; +- requested action; +- requested resource; +- policy; +- approval; +- posture; +- TTL; +- quotas; +- budgets; +- authority ceiling. + +It produces: + +- `GRANT`; +- `DENY`; +- `REQUIRE_APPROVAL`; +- optionally `DEFER` for non-security-critical upstream enrichment. + +Security-critical ambiguity should normally fail closed. + +## 5.3 Execution Plane + +The Execution Plane changes system state. + +Examples: + +- Git; +- CI/CD; +- Kubernetes; +- cloud APIs; +- databases; +- SaaS; +- production services; +- Ops Warden; +- Ops Mason. + +Gate House should not perform most execution itself. + +Instead it should issue or represent authority that execution systems can enforce. + +--- + +# 6. Core Domain Model + +The domain model is intentionally small. + +## 6.1 Principal + +The human, organization, workload, or system on whose behalf authority originates. + +Examples: + +```text +user:alice@example +service:release-controller +org:acme +tenant:acme +``` + +## 6.2 Actor + +The entity directly requesting or performing the action. + +Examples: + +```text +agent:deploy-agent-22 +workload:ci/github/actions/release +human:alice@example +``` + +## 6.3 Runtime Identity + +The concrete workload instance performing execution. + +Examples: + +```text +spiffe://netkingdom/prod/deployer/22 +k8s://cluster-a/ns-release/sa-deployer/pod-7f91 +aws://sts/role-session/... +``` + +## 6.4 Tenant + +The security and organizational domain in which the action occurs. + +Examples: + +```text +tenant:acme +tenant:internal +tenant:platform +``` + +## 6.5 Environment + +Operational environment. + +Examples: + +```text +dev +test +staging +production +``` + +## 6.6 Mandate + +A standing organizational authorization defining what an autonomous actor exists to do. + +Examples: + +```text +mandate:release-automation +mandate:vulnerability-remediation +mandate:production-diagnostics +``` + +A mandate is **not** a credential. + +It is a policy-recognized declaration of intended authority. + +## 6.7 Delegation + +A scoped transfer of authority from a principal to an actor. + +Delegation should normally attenuate: + +```text +child_authority ⊆ parent_authority +``` + +## 6.8 Authority Ceiling + +The maximum authority an actor can ever obtain under deterministic policy. + +An agent may use less authority than its ceiling. + +It may not reason itself into more. + +## 6.9 Action + +A canonical operation. + +Examples: + +```text +kubernetes.pod.read +kubernetes.deployment.restart +database.select +database.schema.modify +cloud.iam.role.modify +git.repository.write +release.deploy +``` + +## 6.10 Resource + +A canonical target. + +Examples: + +```text +k8s://cluster-a/ns/payments/deployment/api +db://orders-prod/schema/public/table/orders +aws://123456789012/eks/cluster-a +git://github/acme/payments +``` + +## 6.11 Grant + +A positive authorization result. + +A grant should be: + +- immutable after issuance; +- scoped; +- versioned; +- time-bounded; +- independently revocable where practical. + +## 6.12 Denial + +A negative authorization decision. + +A denial should include: + +- machine-readable reason; +- policy reference; +- evaluated constraints; +- optional remediation/approval hints. + +## 6.13 Approval + +An independent authorization artifact required for higher-risk actions. + +Approvals should be: + +- actor-bound; +- resource-bound; +- action-bound; +- parameter-bound; +- time-bound; +- replay-resistant. + +## 6.14 Posture + +A bounded security-state input. + +Typical source: + +- King's Guard. + +Examples: + +```text +HEALTHY +DEGRADED +SUSPICIOUS +CONTAIN +BLOCKED +``` + +Gate House should interpret posture through deterministic policy. + +## 6.15 Credential Binding + +The mapping from an authority grant to the technical credential mechanism used by a target system. + +Examples: + +```text +aws-sts-role +openbao-database-lease +openbao-pki-certificate +oauth-token-exchange +kubernetes-service-account-token +``` + +## 6.16 Decision Evidence + +The authoritative record of: + +- request; +- identities; +- evaluated policy; +- policy version; +- result; +- constraints; +- grant ID; +- approval ID; +- posture input; +- timestamps. + +--- + +# 7. Canonical Authorization Request + +A canonical request should be expressive enough for human, workload, and agent contexts without requiring every field in every scenario. + +Example: + +```yaml +request_id: req-01J6A8A1FJ3P + +principal: + id: user:alice@example + type: human + +actor: + id: agent:deploy-agent-22 + type: agent + +runtime: + id: spiffe://netkingdom/prod/deployer/22 + +tenant: + id: tenant:acme + +environment: production + +task: + id: release-7.2.1 + type: release + +mandate: + id: release-automation + +delegation: + mode: assistant + parent_session: session-01J6A7 + +request: + action: production.deploy + resource: k8s://cluster-a/ns/payments/deployment/api + +parameters: + image: registry.example/payments:7.2.1 + replicas: 6 + +approval: + id: approval-9432 + +posture: + actor: HEALTHY + resource: HEALTHY + +constraints: + requested_ttl: 20m + max_mutations: 1 + +context: + trace_id: 4bf92f3577b34da6a3ce929d0e0e4736 + source: mcp://ops-warden +``` + +--- + +# 8. Canonical Decision + +Example: + +```yaml +decision_id: dec-01J6A8AJ4YQW +request_id: req-01J6A8A1FJ3P + +decision: GRANT + +policy: + bundle: production-release + version: 2026-08-24.3 + +authority: + grant_id: grant-01J6A8AXK0N2 + action: production.deploy + resource: k8s://cluster-a/ns/payments/deployment/api + expires_at: 2026-08-24T20:22:00+02:00 + mutation_limit: 1 + +credential_binding: + type: kubernetes-execution-token + provider: secrets-engine + audience: ops-warden + +obligations: + - immutable_audit + - emit_deployment_evidence + - revoke_after_first_success + +explanation: + code: RELEASE_MANDATE_APPROVED + message: > + Actor is operating under the release-automation mandate, + approval matches resource and parameters, and current posture + permits one production deployment. + +evidence: + policy_hash: sha256:... + input_hash: sha256:... +``` + +--- + +# 9. Decision Types + +The first implementation should support at least four outcomes. + +## 9.1 GRANT + +The request is authorized under explicit constraints. + +## 9.2 DENY + +The request is not authorized. + +## 9.3 REQUIRE_APPROVAL + +The request may proceed only after acquisition of a separately governed approval artifact. + +This is preferable to returning a soft "maybe". + +## 9.4 DEFER + +Optional. + +Used only for non-security-critical enrichment, such as waiting for authoritative tenant metadata. + +A request must not be allowed to cross a privileged boundary while unresolved. + +--- + +# 10. Internal Component Architecture + +```mermaid +flowchart LR + API[Authorization API] + NORM[Request Normalizer] + CTX[Context Resolver] + POLICY[Policy Decision Service] + CEIL[Authority Ceiling Evaluator] + APPR[Approval Validator] + POST[Posture Interpreter] + LIMIT[Limits / Change Dynamics] + GRANT[Grant Service] + CRED[Credential Binding Adapter] + REVOKE[Revocation Service] + AUDIT[Audit / Evidence Service] + CACHE[Policy & Context Cache] + + API --> NORM + NORM --> CTX + CTX --> POLICY + + POLICY --> CEIL + POLICY --> APPR + POLICY --> POST + POLICY --> LIMIT + + CEIL --> GRANT + APPR --> GRANT + POST --> GRANT + LIMIT --> GRANT + + GRANT --> CRED + GRANT --> AUDIT + REVOKE --> AUDIT + + CACHE --> CTX + CACHE --> POLICY +``` + +--- + +# 11. Component Responsibilities + +## 11.1 Authorization API + +Responsibilities: + +- receive authorization requests; +- validate schema; +- enforce authentication of calling systems; +- attach correlation metadata; +- return normalized decisions. + +The API should not embed business policy. + +## 11.2 Request Normalizer + +Responsibilities: + +- canonicalize resource identifiers; +- canonicalize actions; +- normalize parameters; +- remove ambiguity before policy evaluation; +- ensure parameter-bound approvals compare normalized values. + +Example: + +```text +kubectl rollout restart deployment api -n payments +``` + +may normalize to: + +```text +action: kubernetes.deployment.restart +resource: k8s://cluster-a/ns/payments/deployment/api +``` + +## 11.3 Context Resolver + +Fetches authoritative context from trusted systems. + +Potential sources: + +- User Engine; +- Tenant Engine; +- Key Cape; +- Mandate registry; +- King's Guard; +- environment/resource registry. + +The resolver should distinguish: + +- authoritative context; +- advisory context; +- stale context. + +Security-critical missing context should fail closed. + +## 11.4 Policy Decision Service + +Evaluates deterministic authorization logic. + +The first implementation should make the policy backend pluggable. + +Potential engines: + +- OPA/Rego; +- Cedar; +- native evaluator. + +The domain model must not depend on one policy language. + +## 11.5 Authority Ceiling Evaluator + +Ensures that requested authority does not exceed: + +- actor ceiling; +- mandate ceiling; +- delegation ceiling; +- tenant ceiling; +- environment ceiling; +- parent-agent ceiling. + +This should be a mandatory layer even if policy already encodes similar logic. + +Defense in depth is appropriate at the authority boundary. + +## 11.6 Approval Validator + +Validates step-up authorization artifacts. + +Should verify: + +- issuer; +- actor; +- principal; +- action; +- resource; +- normalized parameters; +- issuance time; +- expiry; +- nonce/replay properties; +- approval class. + +## 11.7 Posture Interpreter + +Converts trusted adaptive-security posture into deterministic restrictions. + +Example: + +```yaml +posture: + actor: DEGRADED +``` + +may resolve into: + +```yaml +restrictions: + deny: + - production.write + require_approval: + - staging.write +``` + +The Posture Interpreter must not call an LLM to determine whether authority exists. + +## 11.8 Limits / Change Dynamics Controller + +Evaluates operational limits: + +- concurrent grants; +- concurrent mutating actors; +- per-task mutation count; +- runtime; +- deployment frequency; +- destructive action quota; +- token/compute budget; +- agent-chain depth. + +This is not the primary authorization layer. + +It is a secondary blast-radius layer. + +## 11.9 Grant Service + +Issues immutable grant records. + +Responsibilities: + +- assign grant IDs; +- enforce TTL; +- encode authority scope; +- attach obligations; +- register revocation state; +- optionally mint signed grant artifacts. + +## 11.10 Credential Binding Adapter + +Maps grants to credential mechanisms. + +It should not contain the actual secret backend logic. + +Instead it should delegate to Secrets Engine. + +Example: + +```text +grant + ↓ +credential binding request + ↓ +Secrets Engine + ↓ +OpenBao / AWS STS / OAuth / PKI +``` + +## 11.11 Revocation Service + +Supports: + +- grant revocation; +- actor suspension; +- mandate suspension; +- tenant freeze; +- emergency kill switch; +- propagation to credential providers. + +Revocation should not depend on the affected agent cooperating. + +## 11.12 Audit / Evidence Service + +Records: + +- request; +- normalized request; +- identity chain; +- context versions; +- policy version; +- decision; +- grant; +- revocation; +- credential binding metadata; +- execution references where available. + +Audit storage should be independently controlled. + +--- + +# 12. Policy Architecture + +Gate House should separate policy into layers. + +## 12.1 Baseline Invariants + +Hard global rules. + +Examples: + +```text +deny if tenant is unresolved +deny if production action has no authenticated actor +deny if autonomous actor has no mandate +deny if child authority exceeds parent authority +deny if actor attempts to modify its own authority ceiling +deny if audit subsystem is unavailable for critical actions +``` + +These should be difficult to override. + +## 12.2 Environment Policy + +Examples: + +```text +production +staging +development +``` + +Production should require stronger controls. + +## 12.3 Tenant Policy + +Per-tenant restrictions. + +Important for multi-tenancy. + +## 12.4 Mandate Policy + +Defines what autonomous actor classes are intended to do. + +## 12.5 Resource Policy + +Specific restrictions for: + +- Kubernetes clusters; +- databases; +- cloud accounts; +- repositories; +- SaaS APIs. + +## 12.6 Posture Policy + +Maps King's Guard state to authority consequences. + +## 12.7 Approval Policy + +Defines which action classes require: + +- human approval; +- dual approval; +- break-glass; +- step-up MFA; +- parameter-bound authorization. + +## 12.8 Change Dynamics Policy + +Constrains: + +- concurrency; +- rate; +- budget; +- runtime; +- action quotas. + +--- + +# 13. Policy Evaluation Order + +A simple initial evaluation order is desirable. + +```text +1. authenticate caller +2. normalize request +3. resolve principal / actor / tenant / runtime +4. verify operating mode +5. verify mandate / delegation +6. enforce authority ceiling +7. evaluate hard invariants +8. evaluate environment + tenant + resource policy +9. apply posture restrictions +10. validate approval +11. apply change-dynamics limits +12. derive obligations +13. GRANT or DENY +14. emit evidence +``` + +Where possible, evaluation should be monotonic toward restriction: + +```text +initial possible authority + ↓ +identity constraints + ↓ +mandate constraints + ↓ +tenant constraints + ↓ +resource constraints + ↓ +posture constraints + ↓ +approval constraints + ↓ +limits + ↓ +final authority +``` + +No later stage should silently expand beyond an earlier hard ceiling. + +--- + +# 14. Assistant Mode Architecture + +## 14.1 Intent + +Assistant mode keeps the human as primary principal while preserving the agent as actor. + +```mermaid +sequenceDiagram + participant H as Human + participant A as Assistant Agent + participant K as Key Cape + participant G as Gate House + participant O as Ops Warden + participant R as Resource + + H->>K: authenticate + K-->>H: human session + H->>A: request task + A->>G: request action(principal=H, actor=A) + G->>G: deterministic policy evaluation + G-->>A: scoped grant + A->>O: execute with grant + O->>R: perform authorized action + R-->>O: result + O-->>G: execution evidence +``` + +## 14.2 Assistant-Mode Requirements + +- human session must be active; +- human principal must remain identifiable; +- agent should not inherit every human credential; +- privileged grants should be short-lived; +- human session termination should invalidate or shorten associated authority; +- irreversible actions may require explicit confirmation; +- agent must not silently continue as autonomous actor. + +--- + +# 15. Autonomous Mode Architecture + +```mermaid +sequenceDiagram + participant T as Trigger/Scheduler + participant A as Autonomous Agent + participant K as Workload Identity + participant G as Gate House + participant S as Secrets Engine + participant O as Ops Warden + participant R as Resource + + T->>A: start task + A->>K: attest workload identity + K-->>A: short-lived identity + A->>G: request action(actor=A, mandate=M) + G->>G: evaluate mandate + ceiling + policy + G-->>A: grant + A->>S: request credential binding(grant) + S-->>A: short-lived execution credential + A->>O: execute + O->>R: protected action + O-->>G: evidence +``` + +## 15.1 Autonomous-Mode Requirements + +Every autonomous agent must have: + +- unique identity; +- named governance owner; +- explicit mandate; +- authority ceiling; +- lifecycle; +- runtime limit; +- task budget; +- concurrency limit; +- revocation path; +- audit trace; +- no borrowed human credential. + +--- + +# 16. King's Guard Integration + +King's Guard is an adaptive security system. + +Gate House should consume King's Guard output as **bounded posture input**. + +## 16.1 Accepted Pattern + +```text +King's Guard: + actor = agent-934 + posture = DEGRADED + confidence = 0.72 + reason = anomalous-tool-usage +``` + +Gate House policy: + +```text +IF actor.posture == DEGRADED +THEN + deny production.write + allow production.read + require approval for staging.write +``` + +## 16.2 Forbidden Pattern + +```text +King's Guard: + "This looks safe enough. + Give agent-934 admin." +``` + +Adaptive systems may restrict or request authority changes. + +They must not bypass Gate House. + +## 16.3 Containment Flow + +```mermaid +sequenceDiagram + participant KG as King's Guard + participant GH as Gate House + participant OW as Ops Warden + participant R as Resource + + KG->>GH: posture update: CONTAIN actor-X + GH->>GH: deterministic containment policy + GH-->>OW: authorized containment grant + OW->>R: isolate / suspend / revoke + OW-->>KG: containment result + KG->>KG: validate outcome +``` + +--- + +# 17. Secrets Engine and OpenBao Integration + +Gate House should not directly become a secrets backend. + +## 17.1 Separation of Responsibilities + +```text +Gate House: + "This authority is allowed." + +Secrets Engine: + "This is how the target system expects authority to be represented." + +OpenBao: + "This is how the required credential is securely issued and leased." +``` + +## 17.2 Example + +Request: + +```text +database.select +db://orders-prod +TTL 15m +``` + +Gate House: + +```text +GRANT +``` + +Secrets Engine: + +```text +binding = openbao.database.dynamic +role = orders-readonly +ttl = 15m +``` + +OpenBao: + +```text +username = v-gh-... +password = ... +lease = 15m +``` + +The credential should ideally be consumed by a trusted execution layer and not placed into LLM context. + +--- + +# 18. Execution Gateway Pattern + +Where possible, Gate House should encourage a brokered execution model. + +Preferred: + +```text +Agent + ↓ request +Gate House + ↓ grant +Execution Gateway / Ops Warden + ↓ obtains credential +Target System +``` + +Less preferred: + +```text +Agent + ↓ +raw reusable credential + ↓ +Target System +``` + +Benefits: + +- fewer secrets in model context; +- easier audit; +- easier revocation; +- target-specific enforcement; +- reduced exfiltration risk. + +--- + +# 19. MCP Integration + +MCP is treated as a capability interface, not an authorization system. + +## 19.1 MCP Tool Registration + +Tool metadata may define: + +- action identifier; +- resource schema; +- parameter schema; +- risk class; +- reversibility; +- required grant class. + +Example: + +```yaml +tool: restart_service +action: kubernetes.deployment.restart +risk: privileged-write +reversible: true +authorization: + gate_house: required +``` + +## 19.2 Invocation Flow + +```text +LLM selects tool + ↓ +MCP server constructs normalized authority request + ↓ +Gate House + ↓ +GRANT / DENY + ↓ +MCP server executes only if granted +``` + +## 19.3 Token Handling + +Inbound tokens should not be blindly forwarded to downstream resources. + +Downstream credentials should be separately issued or exchanged and audience-bound. + +--- + +# 20. Change Dynamics Envelope + +Gate House should model agentic operational velocity as a security concern. + +## 20.1 Envelope Dimensions + +Possible controls: + +```yaml +change_dynamics: + max_concurrent_mutations: 2 + max_actions_per_grant: 1 + max_resources_per_task: 5 + max_runtime: 30m + max_agent_chain_depth: 3 + max_destructive_actions: 0 + max_deployments_per_hour: 4 + token_budget_eur: 10 + compute_budget_cpu_minutes: 120 +``` + +## 20.2 Hard vs Soft Limits + +Hard: + +- destructive action quota; +- production concurrency; +- authority ceiling; +- environment boundary. + +Soft/advisory: + +- cost warning; +- anomaly score; +- human attention recommendation. + +Security-critical limits should be deterministic. + +--- + +# 21. Circuit Breaker Architecture + +Gate House should support independent suspension primitives. + +Examples: + +```text +suspend actor +suspend mandate +suspend tenant writes +suspend production writes +revoke grant +revoke all grants for runtime +switch environment to read-only +require approval for all mutations +``` + +## 21.1 Circuit Breaker Sources + +Potential sources: + +- King's Guard; +- human operator; +- incident automation; +- budget threshold; +- audit failure; +- policy subsystem failure; +- anomaly threshold mapped by deterministic policy. + +## 21.2 Safe Degraded Mode + +Preferred sequence: + +```text +NORMAL + ↓ +RESTRICTED + ↓ +READ_ONLY + ↓ +BLOCKED +``` + +Observability should usually remain available longer than mutation authority. + +--- + +# 22. Multi-Tenant Model + +Gate House is intended for multi-tenant environments. + +Tenant context must be explicit. + +## 22.1 Rules + +- every protected request should resolve to a tenant or explicitly be platform-scoped; +- cross-tenant authority must be exceptional; +- tenant isolation policy must be evaluated before resource policy; +- ambiguous tenant context should fail closed; +- audit evidence must retain tenant context; +- King's Guard signals must not accidentally leak tenant-private information across boundaries. + +## 22.2 Platform Operations + +Platform-level actors should use explicit platform mandates rather than implicit global authority. + +Example: + +```text +mandate: platform-maintenance +scope: + tenants: "*" +constraints: + action_class: infrastructure-only + customer_data_access: denied +``` + +--- + +# 23. Policy Self-Modification Protection + +A major agentic failure mode is self-escalation. + +Gate House must treat modifications to: + +- authority ceilings; +- policy bundles; +- identity trust; +- tenant mappings; +- approval rules; +- audit configuration; +- credential backends; +- circuit breakers; + +as control-plane changes requiring stronger authorization than ordinary workload changes. + +Example invariant: + +```text +IF actor == subject_of_policy_change +AND change would expand actor authority +THEN require independent governance principal +``` + +--- + +# 24. Audit Architecture + +## 24.1 Event Types + +At minimum: + +```text +AUTH_REQUEST_RECEIVED +AUTH_CONTEXT_RESOLVED +AUTH_DECISION +GRANT_ISSUED +GRANT_REVOKED +APPROVAL_VALIDATED +POSTURE_APPLIED +CREDENTIAL_BINDING_REQUESTED +CREDENTIAL_BINDING_ISSUED +EXECUTION_STARTED +EXECUTION_COMPLETED +CIRCUIT_BREAKER_TRIGGERED +POLICY_CHANGED +``` + +## 24.2 Evidence Requirements + +Privileged action evidence should support reconstruction of: + +- principal; +- actor; +- runtime; +- tenant; +- task; +- mandate; +- resource; +- action; +- parameters hash; +- approval; +- posture; +- policy version; +- grant; +- credential binding; +- execution result. + +## 24.3 Tamper Resistance + +The actor being audited should not have authority to erase the authoritative audit record. + +Gate House may write to: + +- append-only event store; +- external SIEM; +- immutable object storage; +- signed evidence log. + +The first implementation may use ordinary storage but should preserve the interface for stronger backends. + +--- + +# 25. Data Storage + +Gate House should minimize durable sensitive state. + +## 25.1 Durable State + +Likely: + +- mandates; +- grant metadata; +- revocation state; +- policy references; +- approval references; +- audit metadata; +- limits/counters. + +## 25.2 Avoid Storing + +Prefer not to store: + +- raw secret values; +- cloud access keys; +- database passwords; +- OAuth refresh tokens; +- full sensitive payloads unless required. + +Credential material belongs in Secrets Engine/OpenBao or equivalent backends. + +--- + +# 26. API Surface + +Initial APIs should remain small. + +## 26.1 Authorization + +```text +POST /v1/authorize +``` + +Returns: + +```text +GRANT +DENY +REQUIRE_APPROVAL +``` + +## 26.2 Grant Introspection + +```text +GET /v1/grants/{grant_id} +``` + +Used by execution gateways. + +## 26.3 Revocation + +```text +POST /v1/grants/{grant_id}/revoke +POST /v1/actors/{actor_id}/suspend +POST /v1/mandates/{mandate_id}/suspend +``` + +## 26.4 Posture + +```text +POST /v1/posture +``` + +Trusted integrations only. + +## 26.5 Mandates + +```text +POST /v1/mandates +GET /v1/mandates/{id} +``` + +Initial implementation may keep mandates static/config-driven. + +## 26.6 Decision Explain + +```text +GET /v1/decisions/{decision_id} +``` + +Returns machine- and human-readable explanation. + +--- + +# 27. Trust Boundaries + +```mermaid +flowchart TB + subgraph Untrusted["Potentially Probabilistic / Untrusted"] + LLM[LLM / Agent] + MCP[MCP Client] + end + + subgraph TrustedIdentity["Trusted Identity Sources"] + KC[Key Cape] + UE[User Engine] + TE[Tenant Engine] + end + + subgraph GateHouse["Gate House Trust Boundary"] + API[API] + POL[Policy] + GRT[Grant Service] + AUD[Audit] + end + + subgraph Credential["Credential Boundary"] + SE[Secrets Engine] + OB[OpenBao] + end + + subgraph Execution["Protected Execution"] + OW[Ops Warden] + RES[Resources] + end + + LLM --> API + MCP --> API + KC --> API + UE --> API + TE --> API + API --> POL + POL --> GRT + GRT --> SE + SE --> OB + GRT --> OW + OW --> RES + GRT --> AUD +``` + +Gate House must not blindly trust identity fields supplied by the agent request. + +Identity and tenant claims should come from authenticated or independently resolved sources. + +--- + +# 28. Failure Modes + +## 28.1 Policy Engine Unavailable + +Production writes: + +```text +DENY +``` + +Read-only diagnostics may optionally use cached policy if policy explicitly permits. + +## 28.2 King's Guard Unavailable + +Do not grant additional authority. + +Use last-known-good restrictive posture or configured fallback. + +## 28.3 Audit Unavailable + +For privileged production mutation: + +```text +DENY +``` + +or use redundant audit path. + +## 28.4 Secrets Engine Unavailable + +Authorization may still return a grant, but execution requiring credentials cannot proceed. + +Gate House should distinguish: + +```text +authority granted +credential unavailable +``` + +## 28.5 User Engine / Tenant Engine Unavailable + +If identity or tenant context is security-critical and cannot be resolved: + +```text +DENY +``` + +## 28.6 Stale Context + +Every externally resolved context item should have: + +- source; +- version; +- fetched time; +- expiry/staleness policy. + +--- + +# 29. Caching + +Caching is useful but dangerous at authorization boundaries. + +## 29.1 Cacheable + +Potentially: + +- static resource metadata; +- policy bundles; +- tenant membership with short TTL; +- mandate definitions; +- public key sets. + +## 29.2 Avoid Long-Lived Caching + +Avoid long-lived caching of: + +- revocation state; +- incident posture; +- emergency suspension; +- approvals; +- human session presence. + +## 29.3 Cache Rule + +A cache may improve availability. + +It must not silently expand authority after source-of-truth changes. + +--- + +# 30. Deployment Model + +The first reference implementation should target Kubernetes. + +## 30.1 Suggested Services + +Minimal deployment: + +```text +gate-house-api +gate-house-policy +gate-house-grants +gate-house-audit +``` + +The first prototype may combine these into one process with clear internal module boundaries. + +## 30.2 Production Direction + +Later: + +- multiple replicas; +- stateless decision path; +- durable grant/revocation store; +- dedicated audit sink; +- independent policy bundle distribution; +- mTLS or workload identity; +- namespace/network isolation; +- protected admin/control API. + +## 30.3 Workload Identity + +Gate House itself should authenticate downstream services using workload identity rather than static credentials wherever possible. + +--- + +# 31. Technology Direction + +The architecture should remain implementation-neutral initially. + +Potential choices: + +## 31.1 API + +- HTTP/JSON for initial interoperability; +- gRPC later if useful for high-volume decision calls. + +## 31.2 Policy + +- OPA/Rego is a strong initial candidate; +- Cedar is worth benchmarking for typed authorization semantics; +- native policy layer may be appropriate for hard invariants. + +A hybrid model may eventually be useful: + +```text +hard invariants: native +organizational policy: OPA/Cedar +``` + +## 31.3 Storage + +Potential: + +- PostgreSQL for grants, mandates, revocation, audit metadata; +- append-only event store later. + +## 31.4 Identity + +- OIDC; +- SPIFFE/SPIRE; +- Kubernetes projected service-account tokens; +- cloud workload identity. + +## 31.5 Secrets + +- Secrets Engine abstraction; +- OpenBao backend; +- cloud-native STS backends. + +--- + +# 32. Reference Repository Structure + +```text +gate-house/ +├── README.md +├── INTENT.md +├── ArchitectureBlueprint.md +├── docs/ +│ ├── adr/ +│ ├── concepts/ +│ ├── flows/ +│ └── threat-model/ +├── api/ +│ ├── openapi/ +│ └── schemas/ +├── domain/ +│ ├── identity/ +│ ├── authority/ +│ ├── delegation/ +│ ├── mandate/ +│ ├── posture/ +│ └── grant/ +├── policy/ +│ ├── invariants/ +│ ├── bundles/ +│ ├── engine/ +│ └── tests/ +├── grants/ +│ ├── issuance/ +│ ├── revocation/ +│ └── introspection/ +├── approvals/ +├── limits/ +│ ├── quota/ +│ ├── budget/ +│ └── concurrency/ +├── integrations/ +│ ├── user-engine/ +│ ├── tenant-engine/ +│ ├── key-cape/ +│ ├── secrets-engine/ +│ ├── openbao/ +│ ├── kings-guard/ +│ ├── ops-warden/ +│ └── mcp/ +├── audit/ +├── cmd/ +├── internal/ +├── test/ +│ ├── unit/ +│ ├── integration/ +│ ├── adversarial/ +│ └── scenarios/ +└── deploy/ + ├── kubernetes/ + └── helm/ +``` + +This is a reference layout, not yet a constraint. + +--- + +# 33. Initial End-to-End Scenarios + +## Scenario 1 — Human-Assisted Kubernetes Read + +Goal: + +- prove principal/actor separation; +- prove assistant-mode session binding; +- prove read-only grant. + +Flow: + +```text +human SSO +→ assistant agent +→ Gate House +→ read-only grant +→ Ops Warden +→ Kubernetes logs +``` + +Success criteria: + +- no production write; +- grant expires with session; +- audit reconstructs human + agent. + +## Scenario 2 — Autonomous Release + +Goal: + +- prove workload identity; +- prove mandate; +- prove production deployment scope. + +Flow: + +```text +scheduler +→ release agent +→ workload identity +→ Gate House +→ production.deploy grant +→ Ops Warden +→ Kubernetes +``` + +Success criteria: + +- no IAM modification; +- one deployment only; +- short TTL; +- independent revocation. + +## Scenario 3 — Dynamic DB Credential + +Goal: + +- prove authority-to-credential separation. + +Flow: + +```text +agent +→ Gate House +→ GRANT database.select +→ Secrets Engine +→ OpenBao +→ dynamic DB credential +→ execution gateway +``` + +Success criteria: + +- credential not exposed to model; +- credential TTL <= grant TTL; +- credential revoked with grant. + +## Scenario 4 — King's Guard Restriction + +Goal: + +- prove adaptive input cannot grant privilege. + +Flow: + +```text +King's Guard posture = DEGRADED +→ Gate House +→ deny production.write +→ allow read +``` + +Success criteria: + +- deterministic restriction; +- no model reasoning in authorization path. + +## Scenario 5 — Self-Escalation Attempt + +Goal: + +- prove control-plane protection. + +Flow: + +```text +agent +→ request policy change +→ attempt to expand own authority +→ Gate House +→ DENY / independent governance required +``` + +--- + +# 34. Security Test Program + +The reference implementation should include adversarial tests from the beginning. + +## 34.1 Malicious Model Test + +Assume agent intentionally requests maximum destructive access. + +Expected: + +```text +authority ceiling holds +``` + +## 34.2 Prompt Injection Test + +Assume tool description tells agent to dump credentials. + +Expected: + +```text +no reusable credentials available in model context +``` + +## 34.3 Human Disconnect Test + +Terminate Assistant session. + +Expected: + +```text +associated privileged grants expire or are revoked +``` + +## 34.4 Policy Self-Modification Test + +Agent attempts own privilege expansion. + +Expected: + +```text +DENY +``` + +## 34.5 Approval Replay Test + +Reuse approval for different parameters. + +Expected: + +```text +DENY +``` + +## 34.6 Cross-Tenant Test + +Attempt resource access in another tenant. + +Expected: + +```text +DENY +``` + +## 34.7 MCP Token Passthrough Test + +Attempt reuse of inbound token against downstream resource. + +Expected: + +```text +DENY / separate credential required +``` + +## 34.8 Audit Loss Test + +Disable audit sink. + +Expected: + +```text +privileged mutation fails closed +``` + +## 34.9 Circuit Breaker Test + +Suspend actor while task is active. + +Expected: + +```text +new actions denied +active grants revoked where possible +``` + +--- + +# 35. Performance Targets + +Security correctness is primary, but authorization cannot become an operational bottleneck. + +Initial qualitative targets: + +- local/cached authorization decision: low tens of milliseconds; +- external context lookups should be minimized; +- grants should be cacheable by execution gateways until expiry/revocation; +- revocation propagation should be near-real-time for privileged actors; +- audit should be asynchronous where safe but durable before returning success for critical actions. + +Exact SLOs should be established after the first benchmark prototype. + +--- + +# 36. Availability Model + +Gate House is a security-critical dependency. + +Production architecture should eventually target: + +- multiple replicas; +- redundant policy engine; +- redundant audit path; +- durable revocation store; +- clear fail-closed semantics. + +Availability must not be improved by silently bypassing authorization. + +A preferred degradation model is: + +```text +full authority + ↓ +cached read-only + ↓ +diagnostic-only + ↓ +deny privileged action +``` + +--- + +# 37. Observability + +Gate House should expose: + +## Metrics + +- authorization requests; +- grants; +- denials; +- approval-required decisions; +- decision latency; +- context lookup latency; +- policy errors; +- active grants; +- revoked grants; +- actor suspensions; +- mandate suspensions; +- circuit-breaker activations; +- cache hit rate; +- audit failures; +- cross-tenant denial count. + +## Traces + +Trace: + +```text +request +→ normalization +→ context resolution +→ policy +→ grant +→ credential binding +→ execution +``` + +## Logs + +Logs must avoid: + +- raw credentials; +- sensitive approval payloads; +- unnecessary customer data. + +--- + +# 38. Administrative Interfaces + +The admin/control path is itself a privileged security surface. + +Initial administrative functions: + +- register/update mandate; +- suspend actor; +- suspend mandate; +- revoke grant; +- set emergency environment restriction; +- inspect decision; +- inspect policy version. + +Administrative access should: + +- require strong authentication; +- be separately authorized; +- be audited; +- never be available to ordinary agent workload identities. + +--- + +# 39. Governance Integration + +Gate House should make governance machine-readable where practical. + +A mandate record may include: + +```yaml +id: mandate:release-automation +owner: team:platform-release +purpose: deploy approved releases +operating_mode: autonomous + +authority_ceiling: + actions: + - production.deploy + resources: + - k8s://cluster-a/ns/payments/* + denied_actions: + - cloud.iam.* + - kubernetes.rbac.modify + +constraints: + max_runtime: 30m + max_concurrency: 1 + max_mutations_per_task: 1 +``` + +This becomes a bridge between organizational governance and runtime enforcement. + +--- + +# 40. Architecture Decision Records to Create Early + +Recommended ADRs: + +```text +ADR-001 Canonical Authority Request Schema +ADR-002 Principal / Actor / Runtime Identity Model +ADR-003 Policy Engine Selection +ADR-004 Grant Representation and Signing +ADR-005 Revocation Semantics +ADR-006 Posture Input Contract with King's Guard +ADR-007 Credential Binding Contract with Secrets Engine +ADR-008 Audit Evidence Model +ADR-009 Assistant Session Binding +ADR-010 Autonomous Mandate Model +ADR-011 Multi-Tenant Isolation Rules +ADR-012 Failure / Fail-Closed Semantics +ADR-013 MCP Authorization Integration +ADR-014 Policy Self-Modification Protection +``` + +--- + +# 41. Prototype Milestones + +## M0 — Executable Skeleton + +Deliver: + +- service skeleton; +- `/authorize`; +- canonical request schema; +- canonical decision schema; +- static policy; +- structured audit. + +Success: + +```text +request → deterministic GRANT/DENY +``` + +## M1 — Identity and Tenant Context + +Deliver: + +- principal; +- actor; +- runtime identity; +- tenant; +- assistant/autonomous mode. + +Success: + +```text +same actor receives different decisions depending on principal / tenant / mode +``` + +## M2 — Mandates and Authority Ceilings + +Deliver: + +- autonomous mandate model; +- authority ceiling; +- delegation attenuation. + +Success: + +```text +agent cannot exceed mandate +``` + +## M3 — Grant Lifecycle + +Deliver: + +- grant issuance; +- TTL; +- introspection; +- revocation; +- actor suspension. + +Success: + +```text +granted authority can be independently revoked +``` + +## M4 — Secrets Binding + +Deliver: + +- Secrets Engine integration; +- OpenBao dynamic database credential scenario. + +Success: + +```text +authority → ephemeral credential → expiry/revocation +``` + +## M5 — Agent Assistant Scenario + +Deliver: + +- human principal; +- agent actor; +- session binding; +- disconnect revocation. + +Success: + +```text +human-supervised authority stops with supervision +``` + +## M6 — Autonomous Release Scenario + +Deliver: + +- workload identity; +- autonomous mandate; +- deployment grant; +- quota; +- runtime budget. + +Success: + +```text +scheduled agent deploys but cannot alter IAM/policy +``` + +## M7 — King's Guard Posture + +Deliver: + +- posture API; +- deterministic posture restrictions; +- circuit breaker. + +Success: + +```text +adaptive risk signal reduces authority without granting privilege +``` + +## M8 — Adversarial Security Suite + +Deliver: + +- self-escalation; +- cross-tenant; +- token misuse; +- approval replay; +- audit outage; +- circuit breaker tests. + +Success: + +```text +incorrect/malicious agent behavior does not cross configured authority boundaries +``` + +--- + +# 42. Longer-Term Evolution + +Possible later capabilities: + +- signed portable grants; +- token exchange; +- cross-domain delegation; +- policy simulation; +- policy impact analysis; +- temporal authorization; +- graph-based delegation chains; +- distributed revocation; +- tenant-local policy extensions; +- confidential-computing attestation; +- agent reputation/posture inputs; +- capability-based authorization; +- formal verification of hard invariants; +- high-assurance decision replay; +- multi-region authority plane. + +These should only be introduced if they preserve the small and explicit responsibility boundary. + +--- + +# 43. Architectural Invariants + +Gate House should preserve the following invariants throughout implementation. + +### A-01 + +No LLM or statistical component is the final source of privilege. + +### A-02 + +Every privileged action resolves to an explicit actor. + +### A-03 + +Autonomous actions resolve to an explicit mandate. + +### A-04 + +Delegated authority cannot silently exceed parent authority. + +### A-05 + +Tenant context is explicit for protected actions. + +### A-06 + +Production mutations require deterministic policy evaluation. + +### A-07 + +A grant cannot outlive its configured TTL. + +### A-08 + +Revocation does not depend on the affected agent cooperating. + +### A-09 + +Adaptive posture may restrict authority but cannot probabilistically create new authority. + +### A-10 + +Credentials are not treated as the source of authority. + +### A-11 + +Agents cannot normally change the controls that define their own authority ceiling. + +### A-12 + +Audit evidence is independent of the actor being audited. + +### A-13 + +Failure of security-critical dependencies does not silently expand authority. + +### A-14 + +Assistant sessions do not silently become autonomous sessions. + +### A-15 + +If every agent behaves incorrectly, deterministic authority boundaries still hold. + +--- + +# 44. Blueprint Summary + +Gate House should be implemented as a small, composable, deterministic authority control plane. + +Its core path is: + +```text +authenticated context + ↓ +principal + actor + runtime + ↓ +tenant + environment + ↓ +mandate / delegation + ↓ +action + resource + parameters + ↓ +authority ceiling + ↓ +deterministic policy + ↓ +posture restrictions + ↓ +approval + ↓ +change-dynamics limits + ↓ +GRANT / DENY + ↓ +credential binding + ↓ +execution + ↓ +audit / evidence +``` + +The architecture should make one property easy to demonstrate: + +> **An intelligent system may request anything. It can only cause the protected system to do what deterministic authority policy permits.** + +That is the architectural essence of Gate House.