generated from coulomb/repo-seed
tegwick
d6088e4e16
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.
72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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 |