generated from coulomb/repo-seed
Implement WP-0022 audit trail and WP-0023 INTENT–SCOPE closeout
Add unified metadata-only audit.jsonl with secret-material guard, instrument sign/access/worker paths, and expose warden activity CLI. Surface broker hint when VAULT_TOKEN is unset, refresh INTENT/SCOPE docs, and add production integration checklists plus catalog lane promotion playbook.
This commit is contained in:
72
wiki/AuditTrail.md
Normal file
72
wiki/AuditTrail.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Audit Trail — Unified ops-warden Activity
|
||||
|
||||
Date: 2026-07-01
|
||||
Workplan: WARDEN-WP-0022
|
||||
|
||||
ops-warden records **metadata only** for every action it performs. No token, key,
|
||||
cert body, or other secret value ever lands in the audit log.
|
||||
|
||||
---
|
||||
|
||||
## What is recorded
|
||||
|
||||
| Kind | Source actions | Typical fields |
|
||||
| --- | --- | --- |
|
||||
| `sign` | `warden sign`, `warden issue`, `cert_command` | actor, backend, TTL, `policy_decision_id` |
|
||||
| `access` | `warden access --fetch` / `--exec` | need id, owner repo, subject, decision id, outcome |
|
||||
| `worker` | `warden worker` tick, approve, full-auto execute | triage counts, draft id, outcome |
|
||||
| `hub` | State Hub progress notes (`--hub`) | summary, author, event type |
|
||||
|
||||
### Storage
|
||||
|
||||
- **Primary:** `{state_dir}/audit.jsonl` — append-only JSONL (default
|
||||
`~/.local/state/warden/audit.jsonl`)
|
||||
- **Legacy (merged for back-compat):** `signatures.log`, `access-audit.log`
|
||||
|
||||
Rotation: when `audit.jsonl` exceeds 5 MiB it is renamed to `audit.jsonl.1` and a
|
||||
fresh file starts.
|
||||
|
||||
### Secret-material guard
|
||||
|
||||
`record_event()` rejects fields that look like secret values (known token prefixes,
|
||||
high-entropy runs). Signing and proxy paths swallow audit failures so gatekeeping
|
||||
never blocks the primary action — but tests prove values cannot be written.
|
||||
|
||||
---
|
||||
|
||||
## Query
|
||||
|
||||
```bash
|
||||
# Human table — last 7 days
|
||||
warden activity
|
||||
|
||||
# Filter and JSON for agents
|
||||
warden activity --days 3 --kind sign --json
|
||||
warden activity --days 7 --hub --json
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
| --- | --- |
|
||||
| `--days N` | Look back N days (default 7) |
|
||||
| `--kind sign\|access\|worker\|hub` | Filter by event kind |
|
||||
| `--json` | Stable JSON array for automation |
|
||||
| `--hub` | Include recent State Hub progress notes mentioning ops-warden |
|
||||
|
||||
---
|
||||
|
||||
## Linger and login independence
|
||||
|
||||
The coordination worker can run under a `systemd --user` timer with linger enabled
|
||||
(WARDEN-WP-0021). Audit events from worker ticks appear with `kind: worker`.
|
||||
|
||||
Full **logged-out** operational value still depends on State Hub and tunnels being
|
||||
reachable without an interactive login (State Hub on railiance01, `cust-wp-0011`).
|
||||
The audit trail is local-first; `--hub` adds narrative context when the hub is up.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- `wiki/OperatorAccessAssist.md` — metadata-only principle for access proxy
|
||||
- `wiki/PolicyGatedSigning.md` — `policy_decision_id` on sign events
|
||||
- `wiki/playbooks/scheduled-worker.md` — worker timer and review loop
|
||||
Reference in New Issue
Block a user