tegwick
e62763cba9
Per-actor issuance profile in the inventory contract: optional `extensions` allow-list (LocalCA -O clear + -O <ext>; Vault explicit extensions map) and `max_ttl_hours` ceiling enforced against --ttl overrides. Actors without these fields keep backend defaults. agt-custodian: principal agt-custodian, 12h TTL/ceiling, permit-pty only (no agent/port/X11 forwarding, no user-rc), no source-address (unstable workstation egress). Ceremony routing lane agt-custodian-ssh-cert: supervisor issues from the operator account; the agent cannot self-issue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: opus Assistant-Process: 605711@bnt-lap001 Assistant-Session: 1f5e2256-181f-49ed-b7b1-a1c34bf37a61
175 lines
No EOL
5.7 KiB
Markdown
175 lines
No EOL
5.7 KiB
Markdown
# Actor Inventory Patterns
|
||
|
||
Date: 2026-06-17
|
||
|
||
Standard naming and TTL patterns for `~/.config/warden/inventory.yaml` (or
|
||
Git-tracked inventory in your environment). Actor names **must** use the prefix
|
||
matching `ActorType`: `adm-`, `agt-`, `atm-`.
|
||
|
||
See `wiki/AccessManagementDirective.md` for policy background and
|
||
`examples/inventory.seed.yaml` for a copy-paste template.
|
||
|
||
---
|
||
|
||
## Naming convention
|
||
|
||
```text
|
||
<type>-<scope>-<purpose>[-<instance>]
|
||
```
|
||
|
||
| Segment | Meaning |
|
||
| --- | --- |
|
||
| `type` | `adm` \| `agt` \| `atm` |
|
||
| `scope` | team, repo, or environment slug (`codex`, `state-hub`, `ci`) |
|
||
| `purpose` | narrow function (`bridge`, `bootstrap`, `backup`) |
|
||
| `instance` | optional disambiguator (`railiance01`) |
|
||
|
||
**Examples:** `agt-state-hub-bridge`, `agt-codex-interhub-bootstrap`, `atm-nightly-backup`.
|
||
|
||
---
|
||
|
||
## Pattern catalog
|
||
|
||
### Tunnel agents (`agt`)
|
||
|
||
Used by ops-bridge `cert_command` for SSH tunnels.
|
||
|
||
```yaml
|
||
agt-state-hub-bridge:
|
||
type: agt
|
||
principals: [agt-task-bridge]
|
||
ttl_hours: 24
|
||
description: "ops-bridge tunnel to state-hub backend"
|
||
```
|
||
|
||
- One actor per tunnel identity (match `ssh_user` / `actor` in `tunnels.yaml`).
|
||
- Principal should match host `auth_principals` entry deployed by railiance-infra.
|
||
- TTL default 24 h; shorten for high-risk paths.
|
||
|
||
### Kaizen / Codex agents (`agt`)
|
||
|
||
Attended or semi-attended agent work on trusted hosts.
|
||
|
||
```yaml
|
||
agt-codex-interhub-bootstrap:
|
||
type: agt
|
||
principals: [agt-interhub-bootstrap]
|
||
ttl_hours: 2
|
||
description: "Short-lived agent access for Inter-Hub bootstrap execution"
|
||
```
|
||
|
||
### Supervised interactive agent account (`agt-custodian`)
|
||
|
||
CUST-WP-0073-T02 / WARDEN-WP-0045. One principal for the dedicated host account
|
||
`custodian-agt` on Railiance01, shared by the Codex, Claude Code and Grok Build
|
||
harnesses running in the isolated workstation WSL distro `custodian-agents`.
|
||
|
||
```yaml
|
||
agt-custodian:
|
||
type: agt
|
||
principals: [agt-custodian]
|
||
ttl_hours: 12
|
||
max_ttl_hours: 12 # --ttl cannot raise it to the 24 h agt maximum
|
||
extensions: [permit-pty] # clears agent/port/X11 forwarding and user-rc
|
||
```
|
||
|
||
- **TTL 12 h.** Between the attended bootstrap profile (2 h) and the agt type
|
||
maximum (24 h): one supervised working session, so a leaked cert expires by the
|
||
next day and every new session needs a fresh supervisor issuance. The profile
|
||
ceiling (`max_ttl_hours`) stops a `--ttl` override from lengthening it.
|
||
- **Extensions.** `permit-pty` only — interactive harness shells need a pty.
|
||
Agent, port and X11 forwarding and `~/.ssh/rc` are not granted (`-O clear`
|
||
locally; explicit `extensions` map on the Vault role, which must allow
|
||
`permit-pty`).
|
||
- **No `source-address`.** The workstation egress IP is not stable (residential
|
||
dynamic address, WSL NAT), so a pinned address would break issuance silently.
|
||
Revisit if agent traffic moves to a fixed egress (VPN or bastion).
|
||
- **No self-issuance.** The supervisor (Bernd) signs from the operator account
|
||
with `warden sign agt-custodian --pubkey <agent-key>.pub > <agent-key>-cert.pub`
|
||
and places the cert into the `custodian-agents` distro. That distro gets no
|
||
warden config, CA key, Vault token or `warden-sign` lane credential, so the
|
||
signing path is not reachable from the agent account.
|
||
- Host mapping (`AuthorizedPrincipalsFile` for `custodian-agt`) is owned by
|
||
railiance-infra.
|
||
|
||
- Prefer **1–2 h TTL** for bootstrap; never multi-day agent certs.
|
||
- Principal narrower than general ops access (`agt-interhub-bootstrap` not `agt-ops-full`).
|
||
- Remove or disable actor when lane is retired.
|
||
- See `wiki/InterHubBootstrapAccessLane.md`.
|
||
|
||
### Human operators (`adm`)
|
||
|
||
```yaml
|
||
adm-bernd:
|
||
type: adm
|
||
principals: [adm-full]
|
||
ttl_hours: 48
|
||
description: "Human operator — interactive shell when policy allows"
|
||
```
|
||
|
||
- Humans bring their own keypair (`ssh-keygen`); warden signs pubkey only.
|
||
- Use separate actors per person, not shared `adm-shared`.
|
||
- Principals may be narrowed (`adm-readonly`) where railiance-infra supports it.
|
||
|
||
### CI / cron automations (`atm`)
|
||
|
||
```yaml
|
||
atm-backup-daily:
|
||
type: atm
|
||
principals: [atm-backup-daily]
|
||
ttl_hours: 8
|
||
description: "Nightly backup automation — force-command on host"
|
||
```
|
||
|
||
- Lowest TTL practical (≤ 8 h per directive max).
|
||
- Principal tied to single force-command on host.
|
||
- Prefer `warden issue` only in secured CI secret store contexts.
|
||
|
||
---
|
||
|
||
## TTL guidance
|
||
|
||
| Type | Default max (warden) | Typical attended | Typical automation |
|
||
| --- | --- | --- | --- |
|
||
| `adm` | 48 h | 24–48 h | N/A |
|
||
| `agt` | 24 h | 1–4 h bootstrap | 8–24 h supervised |
|
||
| `atm` | 8 h | N/A | 1–8 h |
|
||
|
||
`warden sign` **rejects** TTL above type maximum (WARDEN-WP-0002).
|
||
|
||
---
|
||
|
||
## Principal narrowing
|
||
|
||
1. One principal per automation purpose — avoid `agt-ops-admin`.
|
||
2. Match host-side `auth_principals` exactly — coordinate with railiance-infra before add.
|
||
3. Document `description` field for audit and scorecard reviews.
|
||
4. Use `hosts:` section in inventory for reference (not enforced by warden).
|
||
|
||
---
|
||
|
||
## Adding a new worker
|
||
|
||
```bash
|
||
warden inventory add agt-myrepo-ci \
|
||
--type agt \
|
||
--principal agt-myrepo-ci \
|
||
--ttl 4 \
|
||
--description "CI deploy actor for myrepo"
|
||
warden inventory list
|
||
warden sign agt-myrepo-ci --pubkey /path/to/ci.pub
|
||
```
|
||
|
||
Copy patterns from `examples/inventory.seed.yaml` before inventing new names.
|
||
|
||
---
|
||
|
||
## Anti-patterns
|
||
|
||
| Do not | Why |
|
||
| --- | --- |
|
||
| Reuse `adm` actor for agents | Breaks attribution; use `agt-*` |
|
||
| Store private keys in inventory YAML | Inventory is registry only — keys live in secure paths |
|
||
| 72 h `agt` cert for convenience | Violates TTL policy and directive |
|
||
| One `agt-ops` for all tunnels | Cannot revoke or audit per tunnel |
|
||
| Put API keys in inventory | Route to OpenBao — `wiki/CredentialRouting.md` | |