Implement KG-WP-0002 posture pilot scaffold
This commit is contained in:
codex
parent
6cee3503da
commit
3c549d9b78
22 changed files with 1418 additions and 25 deletions
276
specs/ImmuneContracts.md
Normal file
276
specs/ImmuneContracts.md
Normal file
|
|
@ -0,0 +1,276 @@
|
|||
---
|
||||
title: Kings Guard Immune Contracts
|
||||
document_id: KG-CONTRACTS-IMMUNE
|
||||
version: 0.1.0
|
||||
status: Draft
|
||||
date: 2026-07-23
|
||||
repo: kings-guard
|
||||
classification: Public
|
||||
---
|
||||
|
||||
# Kings Guard Immune Contracts
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the first canonical contract layer for `kings-guard`.
|
||||
The goal is to stabilize the shared vocabulary that adjacent systems can target
|
||||
before a larger decision plane or runtime exists.
|
||||
|
||||
The contracts are deliberately:
|
||||
|
||||
- implementation-neutral;
|
||||
- small enough to map from existing services and audit streams;
|
||||
- explicit about producer and consumer responsibility;
|
||||
- safe to adopt without granting `kings-guard` identity, authorization, or
|
||||
secret-custody authority.
|
||||
|
||||
The current reference implementation for these contracts lives in
|
||||
`src/kings_guard/contracts.py`.
|
||||
|
||||
## 2. Contract Principles
|
||||
|
||||
### 2.1 Observation is not interpretation
|
||||
|
||||
An `immune_observation` is a normalized statement about a security-relevant
|
||||
event or state. It should stay as close as possible to what a source system
|
||||
knows directly.
|
||||
|
||||
Interpretation happens later through `security_phenotype`,
|
||||
`posture_assessment`, and `immune_signal`.
|
||||
|
||||
### 2.2 Intent is explicit
|
||||
|
||||
Posture must be evaluated against a declared `security_genome`, not only
|
||||
against statistical surprise.
|
||||
|
||||
### 2.3 Response stays bounded
|
||||
|
||||
`immune_signal` and `effector_request` may recommend or request response, but
|
||||
they do not silently acquire authority owned by adjacent systems.
|
||||
|
||||
### 2.4 Memory is governed
|
||||
|
||||
`immune_memory_entry` records reusable learning without becoming a raw secret
|
||||
store or a place to centralize tenant-confidential payloads.
|
||||
|
||||
## 3. Contract Map
|
||||
|
||||
| Contract | Meaning | Typical producers | Typical consumers |
|
||||
| --- | --- | --- | --- |
|
||||
| `security_genome` | Canonical healthy intent for a subject or compartment | workload/service owners, platform architects | posture evaluators, admission/review tooling |
|
||||
| `immune_observation` | Normalized evidence record | services, audit streams, workload sensors, policy kernels | phenotype derivation, posture evaluators, memory pipelines |
|
||||
| `security_phenotype` | Derived observable state at one moment | `kings-guard` adapters/evaluators, local sentinels | posture evaluators, signal emitters |
|
||||
| `posture_assessment` | Risk/confidence judgment over current state | `kings-guard` evaluators | signal emitters, human reviewers, future responders |
|
||||
| `immune_signal` | Typed coordination message about posture or response | `kings-guard` evaluators, local sentinels | local fast loops, owning services, State Hub, future coordinators |
|
||||
| `effector_request` | Bounded action hint or request | signal emitters | owning services, policy gates, human operators |
|
||||
| `tolerance` | Explicitly permitted deviation | workload/service owners, governance owners | posture evaluators |
|
||||
| `inflammation` | Elevated defensive posture mode | posture evaluators, local loops | owning services, operators |
|
||||
| `immune_memory_entry` | Durable, governed learning artifact | post-incident review, evaluators, future analytics | future evaluators, policy authors |
|
||||
|
||||
## 4. Contract Definitions
|
||||
|
||||
### 4.1 `security_genome`
|
||||
|
||||
The `security_genome` describes intended healthy operation for a subject or
|
||||
compartment.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- identity of the subject (`subject_id`, `tenant_id`);
|
||||
- declared purpose;
|
||||
- permitted capability scope;
|
||||
- permitted protocols and egress destinations;
|
||||
- data classifications;
|
||||
- declared tolerances.
|
||||
|
||||
Produced by:
|
||||
|
||||
- workload/service owners;
|
||||
- platform architects;
|
||||
- future admission or deployment tooling.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- `kings-guard` posture evaluators;
|
||||
- future review, admission, or governance tooling.
|
||||
|
||||
### 4.2 `immune_observation`
|
||||
|
||||
The `immune_observation` is the normalized input record for posture work.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- source system;
|
||||
- timestamp;
|
||||
- subject and actor identifiers;
|
||||
- tenant context;
|
||||
- capability or resource scope;
|
||||
- protocol;
|
||||
- decision/outcome;
|
||||
- optional deny reason, identity-binding mode, egress destination, and policy
|
||||
version.
|
||||
|
||||
Produced by:
|
||||
|
||||
- service audit streams;
|
||||
- workload sensors;
|
||||
- local policy kernels;
|
||||
- future platform/runtime sensors.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- phenotype derivation;
|
||||
- posture evaluation;
|
||||
- future memory pipelines.
|
||||
|
||||
### 4.3 `security_phenotype`
|
||||
|
||||
The `security_phenotype` is the derived observable state of a subject at a
|
||||
point in time.
|
||||
|
||||
In v0.1 it is intentionally small:
|
||||
|
||||
- observed capability;
|
||||
- protocol and decision;
|
||||
- active findings;
|
||||
- tolerated findings.
|
||||
|
||||
Produced by:
|
||||
|
||||
- `kings-guard` evaluators or adapters.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- posture assessment;
|
||||
- signal emission;
|
||||
- future visualization and debugging surfaces.
|
||||
|
||||
### 4.4 `posture_assessment`
|
||||
|
||||
The `posture_assessment` is the evaluator's judgment.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- posture level (`healthy`, `elevated`, `inflamed`, `compromised`);
|
||||
- risk score;
|
||||
- confidence score;
|
||||
- findings and tolerated findings;
|
||||
- human-readable rationale.
|
||||
|
||||
Produced by:
|
||||
|
||||
- `kings-guard` evaluators.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- signal emitters;
|
||||
- future human review or approval surfaces.
|
||||
|
||||
### 4.5 `immune_signal`
|
||||
|
||||
The `immune_signal` is a typed coordination message emitted after assessment.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- signal id;
|
||||
- signal kind;
|
||||
- posture;
|
||||
- summary;
|
||||
- target system;
|
||||
- findings;
|
||||
- optional effector requests and metadata.
|
||||
|
||||
Produced by:
|
||||
|
||||
- `kings-guard` evaluators;
|
||||
- future local sentinels.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- owning services with local fast loops;
|
||||
- State Hub for metadata-only evidence;
|
||||
- future response coordinators.
|
||||
|
||||
### 4.6 `effector_request`
|
||||
|
||||
The `effector_request` is a bounded action request or hint attached to a
|
||||
signal.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- target system;
|
||||
- action name;
|
||||
- authority boundary;
|
||||
- reason;
|
||||
- whether human approval is required.
|
||||
|
||||
Produced by:
|
||||
|
||||
- `immune_signal` emitters.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- the system that already owns the action;
|
||||
- human operators when approval is required.
|
||||
|
||||
### 4.7 `tolerance`
|
||||
|
||||
A `tolerance` is an explicitly declared deviation that should not trigger an
|
||||
inappropriate response on its own.
|
||||
|
||||
In v0.1 it is represented as a simple match rule:
|
||||
|
||||
- `match_field`;
|
||||
- `match_value`;
|
||||
- description;
|
||||
- effect (`monitor` or `ignore`).
|
||||
|
||||
### 4.8 `inflammation`
|
||||
|
||||
`Inflammation` is not a standalone object in v0.1. It is represented as the
|
||||
`inflamed` posture level plus one or more `immune_signal` / `effector_request`
|
||||
records.
|
||||
|
||||
This keeps the first scaffold small while preserving the operating concept.
|
||||
|
||||
### 4.9 `immune_memory_entry`
|
||||
|
||||
An `immune_memory_entry` is the durable, governed output of defensive learning.
|
||||
|
||||
Minimum fields in v0.1:
|
||||
|
||||
- memory id;
|
||||
- subject scope;
|
||||
- summary;
|
||||
- records it was derived from;
|
||||
- recommended countermeasures;
|
||||
- confidentiality class.
|
||||
|
||||
Produced by:
|
||||
|
||||
- post-incident review;
|
||||
- future evaluator pipelines.
|
||||
|
||||
Consumed by:
|
||||
|
||||
- future contract revisions;
|
||||
- policy authors;
|
||||
- future cross-run learning surfaces.
|
||||
|
||||
## 5. Current Reference Slice
|
||||
|
||||
`kings-guard`'s first executable slice demonstrates these contracts with one
|
||||
real pilot:
|
||||
|
||||
- service: `qonto-assistant`
|
||||
- source evidence: audit event shaped from its current `AuditEvent`
|
||||
- intent source: normalized genome derived from its existing security-genome
|
||||
record
|
||||
- output: posture assessment and advisory-only signal with bounded effector
|
||||
requests
|
||||
|
||||
See:
|
||||
|
||||
- `docs/AdjacentSystemBoundary.md`
|
||||
- `docs/pilots/QontoAssistantPosturePilot.md`
|
||||
- `src/kings_guard/`
|
||||
Loading…
Add table
Add a link
Reference in a new issue