generated from coulomb/repo-seed
tegwick
1865e0744e
Add credential routing, actor patterns, security map, OpenBao SSH checklist, and policy-gated signing design. Update registry and SCOPE; record INTENT↔SCOPE reassessment (C3 completeness).
141 lines
3.9 KiB
Markdown
141 lines
3.9 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"
|
||
```
|
||
|
||
- 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` | |