tegwick
2278cefbb3
Add secrets-engine secret-use snapshot: catalog plus local evidence only, contracted non-secret fields, declared 1d heartbeat cadence. Never contacts OpenBao. Completeness is not claimed. owner_status stays proposed until kings-guard admits the snapshot as an observation input. Assistant: grok Assistant-Session: 01a05f07-ae72-7781-9fcb-19efd61add00
99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# Secret-use evidence engine contract
|
|
|
|
Status: **shipped** as `secrets-engine secret-use snapshot`. Observation-input
|
|
admission remains **proposed** until kings-guard consumes it. `layer.yaml`
|
|
`owner_status` stays `proposed` until that admission. Completeness is not
|
|
claimed.
|
|
|
|
Standard: NetKingdom Security Layer Model v0.7 §9.6. Companion:
|
|
`net-kingdom/SECURITY-COMPANION.md` §6.
|
|
|
|
## What this is
|
|
|
|
A read-only Lifecycle engine surface of **non-secret** lease, revocation,
|
|
mount, rotation, and delivery-session metadata, so kings-guard can evaluate
|
|
secret-abuse posture without a vault client.
|
|
|
|
`secrets-engine route` and `secrets-engine audit` are operator summaries over
|
|
local JSONL. They are not this surface. The shipped command is
|
|
`secrets-engine secret-use snapshot [--catalog-id ID] [--json]`. It reads the
|
|
catalog and local evidence only. It never contacts OpenBao.
|
|
|
|
## Bound (normative)
|
|
|
|
The archive proves the records it holds were not altered or truncated after
|
|
arrival. It does **not** prove a record was sent. Absence of a record is **not**
|
|
evidence of non-occurrence. Completeness is not claimed.
|
|
|
|
This surface cannot close adversarial omission at a compromised source. Cadence
|
|
for load-bearing classes is a heartbeat (`secrets-engine evidence heartbeat`),
|
|
not rate monitoring.
|
|
|
|
## Fields (non-secret)
|
|
|
|
| Field | Meaning | Freshness |
|
|
| --- | --- | --- |
|
|
| `as_of` | UTC timestamp of the snapshot | Snapshot time |
|
|
| `catalog_id` | Lane id | Catalog load |
|
|
| `stage` | `build` \| `test` \| `prod` | Catalog load |
|
|
| `kind` | `kv` \| `auth-capability` | Catalog load |
|
|
| `mount` | OpenBao mount name | Catalog load |
|
|
| `path` | KV path or allowlisted auth path, never a value | Catalog load |
|
|
| `field_names` | Declared field names, never values | Catalog load |
|
|
| `ready` | All declared fields present (boolean) | Last route/verify |
|
|
| `session_handle` | Accessor fingerprint only | Last exec/verify |
|
|
| `revocation_attempted` | Boolean | Last session |
|
|
| `revocation_succeeded` | Boolean | Last session |
|
|
| `lifecycle_operation` | `suspend` \| `deactivate` \| `destroy` \| `revoke` if one ran | Last lifecycle |
|
|
| `decision_id` | Present only where a decision was rendered | Last privileged action |
|
|
| `stance_stage` / `stance_failure_mode` | Named PEP residue | Last privileged action |
|
|
| `evidence_kind` | `load-bearing` \| `attributive` \| `heartbeat` | Per record |
|
|
|
|
Forbidden in this surface: secret values, tokens, passwords, AppRole
|
|
`secret_id`, raw accessors, certificate private keys, subprocess argv, and
|
|
exception prose.
|
|
|
|
## Freshness
|
|
|
|
Every row carries `as_of`. There is no cached authorization verdict. A consumer
|
|
must not treat a stale snapshot as a standing allow. Cadence for load-bearing
|
|
classes is the heartbeat declared in `evidence-classification.yaml`:
|
|
|
|
```text
|
|
form: heartbeat
|
|
interval: 1d
|
|
command: secrets-engine evidence heartbeat
|
|
```
|
|
|
|
The snapshot envelope repeats that cadence. Evidence-derived fields (`ready`,
|
|
session, stance, decision id) appear only when a local record exists. Omission
|
|
is not non-occurrence.
|
|
|
|
## Destination
|
|
|
|
Intended owner of custody is `audit-core`. Today the engine queues load-bearing
|
|
records in `evidence_dir/outbox/` and writes attributive records to local
|
|
JSONL. Drain to `audit-core` is best-effort and is never on the mutation path.
|
|
|
|
kings-guard reads this engine surface, not OpenBao.
|
|
|
|
## Non-responsibilities
|
|
|
|
This surface does not decide whether an action is permitted, does not expose an
|
|
approval-validity query, does not prove omission at source, and does not
|
|
observe production events kings-guard has not received. Companion §10 still
|
|
holds: nothing is observed in production until kings-guard reports otherwise.
|
|
|
|
## Assent
|
|
|
|
A coordination message to kings-guard records this contract. Assent or contest
|
|
belongs in kings-guard's own voice.
|
|
|
|
**2026-09-01:** kings-guard assented, in its own voice (State Hub message
|
|
`75ebd2cc-a166-4676-94aa-deef2791c0c9`), to this document as a proposed
|
|
Engine / Lifecycle read-only non-secret surface. Assent covers: no secret
|
|
values; destination audit-core; completeness not claimed; heartbeat rather
|
|
than rate monitoring for load-bearing classes; kings-guard reads this engine
|
|
surface, never OpenBao. kings-guard will not consume it as an observation
|
|
input until the surface ships and publishes its cadence declaration.
|
|
`layer.yaml` `owner_status` remains `proposed` until that surface exists.
|