coulomb/kings-guard
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Register kings-guard with State Hub

Browse source
This commit is contained in:
codex 2026-07-23 22:55:42 +02:00
parent 1075f18a1a
commit 42dfd27886
10 changed files with 3714 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
# state-hub: track .claude/rules
# Claude Code local state (track shared rules; ignore machine-specific files)
.claude/*
!.claude/rules/
!.claude/rules/*.md

29
.repo-classification.yaml Normal file
View file

@ -0,0 +1,29 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-07-23'
classified_by: codex
category: product
domain: infotech
secondary_domains:
- government
capability_tags:
- access-control
- policy
- governance
- risk
- platform
- operations
business_stake:
- technology
- operations
- legal
- product
business_mechanics:
- control
- coordination
- adaptation
notes: Adaptive security assessment and bounded-response control plane for
multi-tenant cloud environments; consumes evidence from identity,
authorization, secret, and runtime systems without replacing their primary
authority.

222
AGENTS.md Normal file
View file

@ -0,0 +1,222 @@
# kings-guard — Agent Instructions
## Repo Identity
**Purpose:** Adaptive immune security control plane for complex multi-tenant cloud environments.
**Domain:** infotech
**Repo slug:** kings-guard
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `KG-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
| Optional local edge relay | http://127.0.0.1:18080 |
When an operator has enabled the edge relay, set API_BASE to the relay URL.
Queueable writes return an explicit queued receipt if the central hub is
unreachable. Treat that as pending local evidence, then ask the operator to run
statehub outbox status/replay after connectivity returns.
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workplans for this domain
curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=kings-guard&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workplan_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workplan_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
2. Check inbox: `GET /messages/?to_agent=kings-guard&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. If finishing a workplan: hand off **residuals** as live work records first
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
4. After workplan file changes, run:
```bash
statehub fix-consistency
```
Coding agents should run this directly; ask the operator only if the CLI or
State Hub API is unavailable. This syncs task status from files into the hub DB.
---
{CREDENTIAL_ROUTING}
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
## Repo-Specific Notes
This repo is currently **docs-first**. There is no application runtime, package
manifest, or test suite yet. Do not invent build/test commands that do not
exist; add them only when the corresponding implementation lands.
## Working Set
Start with these files:
```bash
cat INTENT.md
cat SCOPE.md
sed -n '1,260p' specs/NetKingdomImmuneArchitecture.md
sed -n '1,220p' history/InitialExploration.md
ls workplans/
```
## Verification
Current verification is structural, not runtime:
```bash
# Check markdown/frontmatter edits and workplan formatting
git diff --check
# Sync workplan/task state into State Hub after workplan changes
cd /home/worsch/state-hub && ./.venv/bin/statehub fix-consistency --repo kings-guard
```
When this repo gains executable code, extend this section with the real
install/test/lint/run commands in the same change.
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/KG-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-KG-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: KG-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: kings-guard
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: KG-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
**Residuals when finishing:** actionable leftovers become live work records
before `status: finished` — usually an intake (`origin: residual`,
`origin_ref: KG-WP-NNNN`) or a spawned workplan. Residual is a *role*,
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
State Hub API is unavailable.

202
INTENT.md Normal file
View file

@ -0,0 +1,202 @@
# INTENT
> This file captures **why this repository exists**, the **direction it is
> moving toward**, and the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of
> current implementation.
---
## One-liner
**Recursive adaptive security control plane for complex cloud environments: it
declares healthy intent, detects harmful deviation, contains damage locally,
restores known-good operation, and retains governed defensive memory.**
---
## Why This Exists
Modern cloud environments are too dynamic to protect through identity, policy,
and perimeter rules alone.
Even when authentication, authorization, and secret custody are well designed,
the environment still changes continuously:
- workloads are rebuilt and redeployed;
- dependencies shift;
- operators, agents, and automations act with real authority;
- tenants share substrates while requiring strong isolation;
- legitimate identities can become compromised;
- harmful behavior can emerge from software that still looks formally allowed.
Security therefore needs a layer that does more than authenticate and allow.
It must continuously compare **declared healthy operation** against **observed
behavior**, decide whether the current state is acceptable, and coordinate
bounded response when it is not.
This repository exists to provide that adaptive layer.
---
## The Mission
> *Where we are going.*
Kings Guard aims to become a **recursive adaptive security system** for
multi-tenant, multi-operator, and agent-active environments.
It should make security an ongoing control loop:
```text
declare healthy intent
-> establish and attest identity
-> observe actual behavior
-> compare behavior with policy and intended scope
-> assess risk and confidence
-> respond within bounded authority
-> restore known-good operation
-> validate the outcome
-> retain governed security memory
```
The mature system should:
- model intended healthy operation explicitly;
- evaluate trust as temporary, scoped, and continuously reassessed;
- detect and contain disturbances near their origin;
- coordinate local and global defensive signals without collapsing tenant
boundaries;
- drive reconstitution and recovery, not only alerting;
- learn from incidents without normalizing compromise or leaking sensitive
tenant data.
---
## Responsibility Boundary
Kings Guard owns the **adaptive security assessment and response layer**.
### Kings Guard owns
- the model of healthy intent, tolerated variation, and harmful deviation;
- security phenotype assessment from observed state and behavior;
- normalized immune observations and signal contracts;
- posture assessment across compartments, subjects, and resources;
- bounded response policy for containment, inflammation, quarantine, and
reconstitution;
- recovery validation and governed immune memory;
- coordination between local autonomous defense and broader federated defense.
### Kings Guard does not own
- primary human, workload, or device identity issuance;
- login, MFA, token minting, or directory lifecycle;
- resource authorization policy administration;
- long-lived secret custody, lease issuance, or secret value delivery;
- infrastructure provisioning, workload deployment, or platform operations;
- general work coordination, task management, or live project state.
### System boundary
| Concern | Primary owner | Kings Guard responsibility |
| --- | --- | --- |
| Identity, authentication, MFA, and verified claims | `key-cape` and related IAM systems | Consume identity and attestation as security inputs; do not replace identity. |
| Resource authorization and decision logs | `flex-auth` | Contribute posture and risk context; do not become the authorization control plane. |
| Secret custody, delivery, leases, and rotation | `railiance-platform` and `secrets-engine` | Consume secret-access evidence and drive defensive posture; do not hold raw secret authority. |
| Operational SSH certificate issuance and access routing | `ops-warden` | Supply posture, evidence, or future response hooks; do not become the SSH issuing lane. |
| Infrastructure, runtime, and platform execution | Railiance repos and workload operators | Signal constraints, isolation, and reconstitution needs; do not own deployment mechanics. |
| Workstream and task coordination | `state-hub` | Emit non-secret evidence and integration events where appropriate; do not become a work tracker. |
---
## Design Principles
### 1. Intent before anomaly
Security should first ask whether behavior is compatible with declared healthy
operation, not merely whether it is statistically unusual.
### 2. Trust is temporary
Trust is not a permanent property of an identity, network location, or workload.
It is a time-bound judgment derived from identity, provenance, integrity,
context, and observed behavior.
### 3. Local containment first
Defensive action should happen as close as possible to the disturbed
compartment, with wider coordination only when impact crosses boundaries.
### 4. Bounded response over uncontrolled automation
Automated response must be explicitly scoped, reversible where possible, and
governed so defense does not become its own source of harm.
### 5. Recovery is part of security
Detection without reconstitution is incomplete. The system should restore
known-good operation and verify that restoration succeeded.
### 6. Memory must be governed
The system should learn from incidents, but memory must preserve tenant
confidentiality, prevent evidence poisoning, and avoid turning compromise into
"normal" behavior.
### 7. Replaceable implementations, stable contracts
Sensors, policy engines, response effectors, and deployment substrates may
change. Kings Guard should depend on stable capability contracts rather than one
mandatory product stack.
---
## What This Is
Kings Guard is:
- an adaptive security control-plane concept and implementation home;
- a contract layer for healthy intent, observations, signals, posture, and
effectors;
- a coordination system for detection, containment, recovery, and memory;
- a reference architecture for recursive, compartment-aware cloud defense.
---
## What This Is Not
Kings Guard is not:
- an identity provider;
- an authorization registry;
- a secret store;
- a SIEM-only alerting surface;
- a generic deployment/orchestration repository;
- a justification to weaken tenant isolation in the name of global defense.
---
## Direction of Evolution
The repository should evolve through clear layers:
1. **Canonical model:** define the stable vocabulary for security genome,
phenotype, observation, signal, effector, tolerance, inflammation, and
immune memory.
2. **Assessment loop:** provide a minimal service that ingests observations,
evaluates posture against declared intent, and produces typed signals.
3. **Bounded response:** integrate with selected effectors for isolation,
throttling, revocation, or reconstitution under explicit policy.
4. **Recovery and validation:** prove that known-good restoration can be
coordinated and verified, not merely requested.
5. **Federated memory:** retain reusable defensive knowledge without exposing
tenant-confidential operational detail.
---
## Guiding Question
> **How can a cloud environment continuously distinguish healthy from harmful
> behavior, contain damage near its origin, and learn from incidents without
> centralizing too much trust or harming legitimate operation?**

66
SCOPE.md Normal file
View file

@ -0,0 +1,66 @@
# SCOPE
> Lightweight boundary for agents and contributors.
---
## One-liner
Adaptive security assessment and bounded-response layer for multi-tenant cloud
platforms.
---
## Core Idea
`kings-guard` turns declared healthy intent plus observed runtime behavior into
posture judgments, typed security signals, and bounded response requests. It
consumes evidence from identity, authorization, secret, and runtime systems
without replacing those systems' primary authority.
---
## In Scope
- Canonical terminology and contracts for security genome, phenotype,
observation, signal, effector, tolerance, inflammation, and immune memory.
- Reference architecture and boundary documents for adaptive defense in
multi-tenant and agent-active environments.
- Minimal posture-evaluation loop design: ingest observations, compare against
intended healthy state, and emit typed posture/signal results.
- Integration seams to adjacent security systems such as `key-cape`,
`flex-auth`, `secrets-engine`, `ops-warden`, and the Railiance runtime
layers.
- Non-secret evidence, workplans, and repo-operational metadata.
---
## Out of Scope
- Identity issuance, login, MFA, or token minting.
- Authorization policy administration or final resource allow/deny decisions.
- Secret custody, lease issuance, or raw secret-value delivery.
- Infrastructure provisioning, workload deployment, or cluster/platform
operations.
- Generic SIEM ownership, ticket tracking, or live work coordination beyond
this repo's own workplans.
---
## Current State
- Markdown-first exploration repo. Current canon is `INTENT.md`,
`specs/NetKingdomImmuneArchitecture.md`, and `history/InitialExploration.md`.
- No executable service, schemas, or integration adapters exist yet.
- The first implementation strand should establish canonical contracts and a
minimal posture pilot before broader integrations.
---
## Getting Oriented
- Start with: `INTENT.md`
- Architecture draft: `specs/NetKingdomImmuneArchitecture.md`
- Exploration notes: `history/InitialExploration.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`

19
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,19 @@
# Work Records — kings-guard
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | KG-WP-0001 | finished | — | workplans/KG-WP-0001-statehub-bootstrap.md |
| workplan | KG-WP-0002 | ready | — | workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md |
| task | KG-WP-0001-T01 | done | — | workplans/KG-WP-0001-statehub-bootstrap.md |
| task | KG-WP-0001-T02 | done | — | workplans/KG-WP-0001-statehub-bootstrap.md |
| task | KG-WP-0001-T03 | done | — | workplans/KG-WP-0001-statehub-bootstrap.md |
| task | KG-WP-0002-T01 | todo | — | workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md |
| task | KG-WP-0002-T02 | todo | — | workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md |
| task | KG-WP-0002-T03 | todo | — | workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md |
| task | KG-WP-0002-T04 | todo | — | workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md |

687
history/InitialExploration.md Normal file
View file

@ -0,0 +1,687 @@
# Adaptive Immune Security Architecture
Kings Guard Security is an exploration about how to establish robust security in a continuously changing complex IT environment.
How would the architecture of an it security system for a multitenant multipurpose it cloud platfrom look like that is inspired by analogy to a biological immune system?
A recursive, identity-centred security system that continuously distinguishes intended from harmful behaviour, contains disturbances locally, restores healthy operation, and learns from every incident without weakening tenant isolation.
The objective is not an impossible state in which nothing malicious ever enters. It is to preserve the platform’s **viability** by enabling it to:
1. anticipate threats,
2. withstand compromise,
3. contain damage,
4. recover healthy operation,
5. adapt its future defences.
This closely matches the NIST cyber-resiliency formulation of anticipating, withstanding, recovering from and adapting to adverse conditions. ([NIST Computer Security Resource Center][1])
Biologically, the architecture draws on barriers, innate immunity, adaptive immunity, signalling, memory, regulation and tissue repair. Innate immunity provides fast, general responses, while adaptive immunity develops specific responses and memory; both depend on regulation to avoid damaging the organism itself. ([NCBI][2])
## 1. The crucial interpretation of “self”
A simplistic security analogy would classify everything as either:
* self and trusted, or
* foreign and hostile.
That would be dangerous. A legitimate workload can be compromised, an administrator account can be hijacked, and a previously permitted behaviour can become harmful.
Therefore, **self must not mean “inside the network.”**
In this architecture, self means:
> A subject whose identity, provenance, integrity, current state, requested action and behavioural context remain consistent with explicitly declared intent.
This follows the zero-trust shift away from trusting network locations toward protecting identified users, workloads, resources and actions. NIST explicitly rejects implicit trust based solely on location or ownership and, for cloud-native systems, recommends policies based on application and service identities. ([NIST Computer Security Resource Center][3])
A workload should therefore continuously be able to answer:
* Who am I?
* Which tenant do I belong to?
* Which software and configuration am I running?
* Who authorized this deployment?
* Which capabilities may I exercise?
* Which data may I access?
* With whom may I communicate?
* What behaviour is expected from me?
* Is my current state consistent with that declaration?
This could be called the workload’s **security phenotype**.
---
# 2. Biological concepts and architectural counterparts
| Biological concept | Security counterpart | Architectural capability |
| ----------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
| Genome | Canonical intended state | Signed architecture, configuration, policies, SBOMs, identities and capability declarations |
| Skin and mucosa | External barriers | Edge gateway, DDoS protection, ingress validation, protocol filtering |
| Organ boundaries | Tenant compartments | Tenant-specific identity, network, compute, data, key and policy boundaries |
| Cell membrane | Workload boundary | Workload identity, sandbox, runtime policy, least privilege |
| Self markers | Attested identity and provenance | Cryptographic workload identity, signatures, deployment provenance |
| Innate immunity | Immediate general defence | Deny-by-default, validation, rate limits, runtime rules, isolation |
| Pattern-recognition receptors | Security sensors | Kernel, network, identity, API, data and application telemetry |
| Antigen presentation | Normalized security evidence | Contextual observation records presented to decision services |
| Cytokines | Security signalling | Typed event fabric carrying alerts, state changes and response requests |
| Lymph nodes | Local correlation centres | Tenant-local detection, evidence aggregation and response coordination |
| Adaptive immunity | Incident-specific defence | New detections, policies, playbooks and countermeasures |
| Antibodies | Targeted countermeasures | Signatures, deny rules, revocations, filters and compensating controls |
| Complement system | Automated response primitives | Block, throttle, quarantine, terminate, revoke and rotate |
| Memory cells | Security memory | Threat knowledge, attack paths, successful countermeasures and lessons |
| Regulatory T cells | Safety and governance | Response limits, approval rules, suppression, rollback and exception control |
| Inflammation | Elevated defensive posture | Temporary restriction, increased telemetry and reduced trust |
| Tissue repair | Reconciliation and recovery | Immutable redeployment, restoration, secret rotation and validation |
The point is not to reproduce biology literally. The analogy provides a useful decomposition of **distributed protection, signalling, regulation, learning and repair**.
---
# 3. Top-level architecture
```mermaid
flowchart TB
EXT["Users, Agents, Services, Devices and External Systems"]
subgraph GOV["Security Genome and Governance"]
INTENT["Intent and Capability Registry"]
CANON["Security Canon and Policy Sources"]
SUPPLY["Software and Configuration Provenance"]
RISK["Risk Appetite and Tenant Profiles"]
end
subgraph ICP["Platform Immune Control Plane"]
ID["Identity and Attestation Authority"]
MEMORY["Immune Memory and Countermeasure Graph"]
DECIDE["Policy and Response Decision Engine"]
REGULATE["Tolerance, Safety and Escalation Controller"]
AUDIT["Independent Audit and Validation"]
BUS["Security Signal Fabric"]
end
subgraph TENANT["Tenant Immune Compartment — repeated per tenant"]
MEMBRANE["Tenant Membrane"]
THYMUS["Admission and Deployment Education"]
APPS["Applications, Data and Workloads"]
SENTINELS["Local Sentinels"]
NODE["Tenant Immune Node"]
EFFECTORS["Local Response Effectors"]
HEAL["Recovery and Reconstitution"]
end
subgraph PLATFORM["Shared Platform Compartments"]
SHARED["Brokered Shared Services"]
INFRA["Cluster, Network, Storage and Runtime"]
PLATFORM_SENTINELS["Platform Sentinels"]
end
EXT --> MEMBRANE
GOV --> ID
GOV --> DECIDE
GOV --> THYMUS
MEMBRANE --> APPS
THYMUS --> APPS
ID --> APPS
APPS --> SENTINELS
INFRA --> PLATFORM_SENTINELS
SENTINELS --> NODE
NODE --> BUS
PLATFORM_SENTINELS --> BUS
BUS --> DECIDE
MEMORY --> DECIDE
RISK --> REGULATE
DECIDE --> REGULATE
REGULATE --> EFFECTORS
EFFECTORS --> APPS
EFFECTORS --> MEMBRANE
EFFECTORS --> HEAL
HEAL --> APPS
BUS --> MEMORY
AUDIT --> MEMORY
AUDIT --> DECIDE
APPS <--> SHARED
```
The most important topological feature is that the architecture is **recursive**:
* every workload has a local protective boundary;
* every application has a security context;
* every tenant has an immune compartment;
* every cluster has a platform immune system;
* the complete cloud estate has a federated security system.
Local systems act autonomously within bounded authority, while higher levels coordinate events whose impact crosses compartments.
---
# 4. Seven orthogonal security planes
## 4.1 Security Genome Plane
The genome describes what healthy operation is supposed to look like.
For each workload or capability, it should contain:
* tenant and ownership;
* intended purpose;
* software and configuration provenance;
* permitted interfaces;
* dependencies;
* permitted callers and destinations;
* data classifications;
* expected resource consumption;
* expected execution behaviour;
* availability and recovery requirements;
* applicable policies;
* known exceptions.
This connects naturally with your distinction between **stable INTENT and actual SCOPE**.
The immune system does not merely ask whether behaviour is statistically unusual. It asks:
> Is actual behaviour compatible with the declared intent and authorized scope?
This prevents the system from gradually learning that a persistent compromise is “normal.”
## 4.2 Identity and Attestation Plane
This plane establishes identity for:
* humans;
* agents;
* devices;
* workloads;
* services;
* deployment pipelines;
* infrastructure components;
* external organizations.
Human identity could remain within the **KeyCape IAM profile**, while workload identity is handled through a replaceable attestation contract.
SPIFFE/SPIRE is a strong implementation model because it provides cryptographically verifiable workload identities based on node and workload attestation rather than relying solely on long-lived secrets. Its trust-domain model also lends itself to tenant and platform compartmentation. ([spiffe.io][4])
An identity is not permanently trusted. It acquires a current **trust posture** derived from:
* strength of attestation;
* software integrity;
* configuration integrity;
* device or node state;
* recent behaviour;
* credential age;
* active incident context;
* requested resource sensitivity.
## 4.3 Membrane and Compartment Plane
There should be several nested membranes:
1. **platform membrane** between the cloud and the outside world;
2. **tenant membrane** between tenants;
3. **application membrane** around an application domain;
4. **workload membrane** around each execution unit;
5. **data membrane** around sensitive data sets;
6. **management membrane** around control-plane operations.
Each tenant should have its own:
* identity namespace;
* policy bundle;
* encryption context;
* secrets domain;
* network policy;
* data partition;
* telemetry partition;
* security memory scope;
* response authority.
Kubernetes supports multiple tenancy patterns, but its documentation explicitly distinguishes softer and harder isolation and notes trade-offs among security, complexity and cost. A biological architecture should therefore support several **isolation phenotypes**, rather than assuming namespaces alone are sufficient. ([Kubernetes][5])
A practical classification would be:
| Isolation class | Typical realization |
| --------------- | ---------------------------------------------------------------------- |
| Shared | Namespace and policy isolation |
| Reinforced | Virtual control plane, dedicated nodes or sandboxed runtimes |
| Strong | Dedicated cluster and tenant trust domain |
| Sovereign | Dedicated cloud account, keys, control plane and operational authority |
The risk profile of a tenant or workload determines the required isolation class.
## 4.4 Sentinel and Evidence Plane
Sentinels are distributed throughout the system:
* edge sentinels;
* API sentinels;
* identity sentinels;
* workload sentinels;
* kernel sentinels;
* network sentinels;
* data-access sentinels;
* control-plane sentinels;
* application-domain sentinels.
They produce normalized **security observations**, not immediately final conclusions.
A useful observation envelope would include:
```yaml
security_observation:
observation_id: uuid
timestamp: datetime
tenant_id: tenant-reference
compartment_id: compartment-reference
subject_id: attested-subject-reference
resource_id: resource-reference
operation: requested-or-observed-action
evidence:
- evidence-reference
intent_relation:
expected: true
deviation_type: none | unknown | prohibited | anomalous
assessment:
confidence: 0.0-1.0
severity: informational | low | medium | high | critical
novelty: known | variant | unknown
blast_radius: local | application | tenant | platform
proposed_response:
action: observe | challenge | restrict | isolate | revoke | rebuild
ttl: duration
```
The evidence remains distinguishable from its interpretation. That allows later reassessment when new information becomes available.
## 4.5 Signal and Coordination Plane
Biological cytokines coordinate immune activity. The platform equivalent is a typed, authenticated **security signal fabric**.
It transports:
* observations;
* identity posture changes;
* integrity failures;
* policy violations;
* suspected attack chains;
* response requests;
* response outcomes;
* recovery state;
* escalation messages.
Signals require:
* tenant and compartment scope;
* origin identity;
* evidence references;
* confidence;
* severity;
* expiry time;
* deduplication identity;
* confidentiality classification;
* permitted consumers.
Raw tenant evidence should not automatically enter a global platform data lake. The architecture should distinguish:
* **tenant-private evidence**;
* **platform-operational evidence**;
* **shareable threat characteristics**;
* **global countermeasure knowledge**.
This allows collective learning without creating a cross-tenant surveillance or leakage mechanism.
## 4.6 Response and Recovery Plane
The response system should use a graduated ladder:
1. **observe** — collect more evidence;
2. **challenge** — require stronger authentication or attestation;
3. **constrain** — reduce permissions, destinations or rate;
4. **degrade** — disable nonessential capabilities;
5. **isolate** — quarantine workload, identity, node or tenant segment;
6. **revoke** — invalidate credentials, sessions or deployment authority;
7. **terminate** — stop malicious execution;
8. **reconstitute** — rebuild from known-good state;
9. **restore** — recover validated data and service;
10. **immunize** — distribute a tested countermeasure.
Responses should be local by default. A workload sentinel may stop its workload, but it should not be able to shut down unrelated tenants.
Every automated response should carry:
* authority source;
* reason and evidence;
* scope;
* duration or lease;
* rollback procedure;
* expected outcome;
* validation condition;
* escalation threshold.
Runtime detection and enforcement can be realized by different interchangeable effectors. Current cloud-native examples include Falco for runtime detection and Tetragon for Kubernetes-aware eBPF observation and inline enforcement. ([Falco][6])
## 4.7 Memory and Adaptation Plane
Immune memory should not be just a SIEM archive. It should be an active knowledge graph connecting:
```text
Observation
→ Evidence
→ Subject
→ Asset
→ Vulnerability
→ Attack technique
→ Intended capability
→ Countermeasure
→ Response action
→ Outcome
→ Residual risk
```
MITRE D3FEND is particularly suitable as an external vocabulary because it models defensive countermeasures and their relationships to offensive techniques as a knowledge graph. ([d3fend.mitre.org][7])
Memory objects need:
* provenance;
* confidence;
* applicability conditions;
* tenant visibility;
* creation and expiry dates;
* successful and unsuccessful outcomes;
* counter-evidence;
* versioning;
* revocation.
Security memory must be allowed to **decay**. A rule that was useful two years ago may now be ineffective or actively harmful.
---
# 5. Tenant-local and platform-wide immunity
The system should distinguish three kinds of security knowledge.
## Tenant-local immunity
Contains:
* tenant-specific behaviour;
* tenant-specific risks;
* local incidents;
* business-process expectations;
* local countermeasures;
* confidential evidence.
The tenant immune node owns this information and can act rapidly inside its compartment.
## Platform immunity
Contains:
* infrastructure attacks;
* shared service compromise;
* cluster and control-plane conditions;
* supply-chain risks;
* cross-tenant attack patterns;
* platform countermeasures.
The platform immune system may contain or disconnect a tenant compartment, but it should not inspect tenant-private data without an explicit legal and policy basis.
## Federated immune memory
Contains only information approved for broader use, such as:
* attack fingerprints;
* affected component versions;
* defensive techniques;
* anonymized behavioural patterns;
* successful containment strategies;
* externally sourced threat intelligence.
Cross-tenant learning should distribute **countermeasures and abstract characteristics**, not raw customer evidence.
---
# 6. Preventing digital autoimmune disease
A biological analogy becomes truly valuable when it includes immune failure modes.
## Autoimmunity
The security system attacks legitimate activity.
Countermeasures:
* policy simulation;
* shadow mode;
* canary enforcement;
* independent evidence requirements;
* bounded response authority;
* automatic expiry;
* rollback;
* tenant-specific tolerance profiles.
## Immunodeficiency
The system lacks sensors, policies or response capabilities.
Countermeasures:
* coverage measurement;
* mandatory baseline controls;
* sentinel health monitoring;
* capability maturity assessment;
* periodic attack simulation.
## Chronic inflammation
The platform remains permanently in a high-alert state.
Consequences include:
* alert fatigue;
* excessive logging;
* degraded performance;
* blocked delivery;
* permanently elevated privileges for security tooling.
Controls should include response budgets, signal suppression, incident closure criteria and automatic return to baseline.
## Immune evasion
An attacker appears legitimate or disables sensors.
Countermeasures:
* independent telemetry paths;
* remote attestation;
* immutable evidence;
* separation of control and observation;
* detection of missing signals;
* periodic re-attestation.
## Malignant growth
A legitimate component expands beyond its intended role.
This includes:
* privilege accumulation;
* uncontrolled agent autonomy;
* data hoarding;
* hidden dependencies;
* excessive resource consumption.
The response is not signature detection, but comparison of actual growth against declared purpose, resource limits and capability boundaries.
---
# 7. Cybernetic control loops
The architecture should operate at three timescales.
## Fast local loop — innate immunity
```text
Sense → match local rule → constrain → report
```
Examples:
* reject an invalid request;
* block an unauthorized syscall;
* rate-limit abnormal traffic;
* quarantine a workload.
## Tenant loop — adaptive response
```text
Correlate → assess tenant context → select response
→ observe outcome → update tenant memory
```
Examples:
* revoke a tenant user session;
* restrict an application;
* rotate tenant credentials;
* deploy a tenant-specific rule.
## Platform learning loop
```text
Aggregate abstract findings → analyze attack pattern
→ validate countermeasure → publish policy update
→ measure effectiveness
```
Examples:
* revise a platform baseline;
* block a vulnerable artifact;
* introduce a new supply-chain requirement;
* change default isolation for a workload class.
---
# 8. VSM mapping
The architecture maps neatly onto the Viable System Model.
| VSM system | Immune-security responsibility |
| --------------------------- | ------------------------------------------------------------------------------- |
| **System 1 – Operation** | Workload, application and tenant-local sentinels and effectors |
| **System 2 – Coordination** | Security signal fabric, deduplication, suppression and incident coordination |
| **System 3 – Control** | Tenant and platform response controllers |
| **System 3* – Audit** | Independent validation, red teaming, forensic evidence and control verification |
| **System 4 – Intelligence** | Threat research, attack simulation, adaptive policies and immune memory |
| **System 5 – Policy** | Security identity, risk appetite, legal constraints and response authority |
This supports recursion: each tenant is a viable security system while remaining part of the larger platform security system.
---
# 9. Suggested NetKingdom capability structure
For NetKingdom, I would organize the architecture into these stable capabilities rather than tightly coupling it to individual products:
```text
netkingdom
├── security-genome
│ ├── intent-registry
│ ├── capability-registry
│ ├── policy-canon
│ └── provenance-registry
│
├── identity-immunity
│ ├── human-identity
│ ├── workload-identity
│ ├── attestation
│ └── trust-posture
│
├── compartment-control
│ ├── tenant-isolation
│ ├── workload-boundaries
│ ├── data-boundaries
│ └── shared-service-brokers
│
├── sentinel-mesh
│ ├── edge-sentinel
│ ├── identity-sentinel
│ ├── runtime-sentinel
│ ├── network-sentinel
│ └── data-sentinel
│
├── immune-coordination
│ ├── observation-model
│ ├── signal-fabric
│ ├── tenant-immune-node
│ └── platform-immune-node
│
├── immune-response
│ ├── decision-engine
│ ├── response-orchestrator
│ ├── effectors
│ └── escalation
│
├── immune-memory
│ ├── evidence-store
│ ├── countermeasure-graph
│ ├── outcome-learning
│ └── memory-federation
│
└── immune-regulation
├── tolerance-control
├── simulation
├── response-budgets
├── audit
└── recovery-validation
```
The stable core would consist of the contracts between these capabilities. KeyCape, SPIRE, OPA, Tetragon, Falco, network-policy engines, evidence stores and other implementations would remain replaceable components behind those contracts. OPA/Gatekeeper, for example, can serve as one admission-policy implementation rather than becoming the architecture itself. ([openpolicyagent.org][8])
# Central architectural proposition
The resulting NetKingdom system would not primarily be a collection of scanners, dashboards and blocking products. It would be a **recursive security control system** that:
```text
declares healthy intent
→ establishes cryptographic identity
→ observes actual behaviour
→ detects meaningful divergence
→ responds within bounded authority
→ restores known-good operation
→ validates the outcome
→ retains governed memory
```
Its most distinctive property would be the combination of:
* **zero-trust identity**,
* **tenant compartmentation**,
* **distributed innate protection**,
* **adaptive countermeasure generation**,
* **cybernetic response loops**,
* **regulated autonomy**,
* **continuous repair**.
A logical next artifact is an OAS-formatted `NetKingdomImmuneArchitecture.md` with context, capability, control-loop, deployment, data, trust-boundary and failure-mode views.
[1]: https://csrc.nist.gov/pubs/sp/800/160/v2/r1/final "SP 800-160 Vol. 2 Rev. 1, Developing Cyber-Resilient Systems: A Systems Security Engineering Approach | CSRC"
[2]: https://www.ncbi.nlm.nih.gov/books/NBK539801/?utm_source=chatgpt.com "Physiology, Immune Response - StatPearls - NCBI Bookshelf"
[3]: https://csrc.nist.gov/pubs/sp/800/207/final "SP 800-207, Zero Trust Architecture | CSRC"
[4]: https://spiffe.io/docs/latest/spire-about/spire-concepts/ "SPIRE Concepts | SPIFFE"
[5]: https://kubernetes.io/docs/concepts/security/multi-tenancy/ "Multi-tenancy | Kubernetes"
[6]: https://falco.org/docs/?utm_source=chatgpt.com "The Falco Project"
[7]: https://d3fend.mitre.org/about/ "About | MITRE D3FEND™"
[8]: https://openpolicyagent.org/docs/kubernetes?utm_source=chatgpt.com "OPA for Kubernetes Admission Control"

2292
specs/NetKingdomImmuneArchitecture.md Executable file
View file

File diff suppressed because it is too large Load diff

77
workplans/KG-WP-0001-statehub-bootstrap.md Normal file
View file

@ -0,0 +1,77 @@
---
id: KG-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: kings-guard
status: finished
owner: codex
topic_slug: netkingdom
created: "2026-07-23"
updated: "2026-07-23"
state_hub_workstream_id: "b7ff79b9-ae27-4a46-a782-49482392eb83"
---
# Bootstrap State Hub integration
Adaptive immune security control plane for complex multi-tenant cloud environments.
## Review Generated Integration Files
```task
id: KG-WP-0001-T01
status: done
priority: high
state_hub_task_id: "add34171-9f18-48b9-a88e-07ea34cb6382"
```
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
**Done 2026-07-23:** Added a repo-specific `INTENT.md`, rewrote `SCOPE.md`
from the generated placeholder into an explicit boundary for adaptive security
assessment/response, extended `AGENTS.md` with the repo's actual docs-first
workflow, and confirmed `.custodian-brief.md` is adequate as generated.
Corrected the generated `topic_slug` from `custodian` to `netkingdom` so the
repo's first workplans align with the broader security ecosystem.
## Verify Local Developer Workflow
```task
id: KG-WP-0001-T02
status: done
priority: high
state_hub_task_id: "17fb3a0c-91c5-4b45-967e-962ef6c89ac5"
```
Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
**Done 2026-07-23:** Documented the current repo reality in `AGENTS.md`:
there is no runtime yet, so verification is `git diff --check` plus focused
document review and `statehub fix-consistency` after workplan edits. Explicitly
noted that install/test/lint/run commands should be added only when executable
code lands.
## Seed First Real Workplan
```task
id: KG-WP-0001-T03
status: done
priority: medium
state_hub_task_id: "5b5f56d9-7e89-43b6-94c3-db4461e9eed4"
```
Create the first implementation workplan for the repository's most important
next change. After workplan file updates, run the sync locally from this repo
checkout:
```bash
statehub fix-consistency
```
**Done 2026-07-23:** Created `KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md`
to define the first substantive strand: canonical immune contracts, adjacent
security boundaries, a minimal posture loop, and a first pilot integration
lane. Sync to State Hub follows this bootstrap closeout.

115
workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md Normal file
View file

@ -0,0 +1,115 @@
---
id: KG-WP-0002
type: workplan
title: "Canonical immune contracts and first posture pilot"
domain: infotech
repo: kings-guard
status: ready
owner: codex
topic_slug: netkingdom
created: "2026-07-23"
updated: "2026-07-23"
quality_dor: DoR-Ok
quality_dor_at: "2026-07-23"
quality_dor_by: "codex"
state_hub_workstream_id: "5c5c5a26-dfca-4d42-86a7-b87877677207"
---
# Canonical immune contracts and first posture pilot
Establish `kings-guard` as the adaptive security layer that sits beside the
existing NetKingdom security lanes instead of competing with them. The first
strand should produce stable contracts and one narrow posture pilot before any
broader implementation or automation claims.
This workplan deliberately keeps authority boundaries clear:
- `key-cape` remains identity and attestation input.
- `flex-auth` remains authorization policy and final allow/deny owner.
- `railiance-platform` and `secrets-engine` remain secret-custody and delivery
owners.
- `ops-warden` remains the operational SSH certificate lane.
- `kings-guard` evaluates health/posture, emits signals, and requests bounded
response.
## Task: Define canonical immune contracts
```task
id: KG-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "9982a3b4-1e65-493a-9b61-322f23d4fd2d"
```
Write the first repo-owned canonical contract for the core vocabulary:
`security_genome`, `security_phenotype`, `immune_observation`,
`immune_signal`, `effector_request`, `tolerance`, `inflammation`, and
`immune_memory`.
Done when:
- each term has a concise, non-overlapping definition;
- producer/consumer expectations are named for each contract;
- the contracts are usable without requiring one particular product stack.
## Task: Write adjacent-system boundary contract
```task
id: KG-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "0c44035e-b1b8-4f5d-8a6c-e6514b4bc897"
```
Author a boundary document that shows how `kings-guard` consumes evidence from
`key-cape`, `flex-auth`, `secrets-engine`, `ops-warden`, and Railiance runtime
layers without taking over their responsibilities.
Done when:
- each adjacent system's primary authority is stated explicitly;
- `kings-guard` inputs, outputs, and non-goals are named per system;
- tenant-isolation and non-secret evidence rules are captured.
## Task: Scaffold a minimal posture loop
```task
id: KG-WP-0002-T03
status: todo
priority: high
state_hub_task_id: "c88a7da6-a9ff-4bd9-ba47-7c199321666b"
```
Create the initial repository structure for a minimal posture engine or schema
package that can ingest normalized observations, compare them against declared
intent, and emit typed posture/signal results.
Done when:
- the repo has a clear implementation layout rather than only prose;
- one sample input/output path exists end-to-end for observation -> posture ->
signal;
- tests or fixture-driven validation prove the contract shape is stable.
## Task: Choose and specify the first pilot lane
```task
id: KG-WP-0002-T04
status: todo
priority: medium
state_hub_task_id: "77e1dc69-9902-4381-8028-ce1cfac7e9d5"
```
Pick one narrow pilot integration lane and specify it precisely. Preferred
pilot order:
1. `ops-warden` sign-request posture hinting
2. `secrets-engine` exec-delivery posture hinting
3. Railiance workload reconstitution signal generation
Done when:
- the chosen lane has a concrete request/response flow;
- the pilot can run without granting `kings-guard` secret, identity, or final
authorization authority;
- bounded-response and rollback expectations are documented.