Void-Homelab/docs/yerin-security-agent.md

# Yerin — the Void 2.0 Security Agent

> Cradle note: Yerin is the sword artist — fast, vigilant, the one who *notices the
> threat first and calls it*. In Void 1.x she already owns the 5-minute alert
> cron. In Void 2.0 she becomes a first-class **read-only security/observability
> agent**: she watches, reports, and proposes — she never silently acts.

## Design principles

1. **Read-only by capability.** Yerin's agent record gets `{ read: true }` and
   **no** `write`/`suggest`. Anything she wants changed she raises to you; she
   cannot mutate state. (If you later want her to be able to *propose* a
   remediation, add `suggest: true` and the existing pending-change flow gives
   you an approval gate for free.)
2. **Own toolset, own registry.** Security tools live in
   `lib/ai/agent/tools/security/` behind `securityRegistry` — separate from
   Dross's `companionRegistry`, so she gets investigative tools, not
   `propose_change`.
3. **No secret material, ever.** Tools project explicit columns and rely on the
   audit layer's write-time redaction. `agent_inventory` deliberately never does
   `SELECT *`.

## Built this pass (TDD, on `main`, not deployed)

`lib/ai/agent/tools/security/` + `securityRegistry`, tests in
`tests/ai/security_tools.test.js`:

| Tool | What it answers |
|------|-----------------|
| `audit_log` | "Who did what, newest first?" Filter by `actor_kind` / `actor_id`. Reads the redacted audit trail. Capped at 200. |
| `agent_inventory` | "Which agents exist and what is each allowed to do?" Returns id/slug/name/kind/model + capabilities + scopes. Never returns token material. |

## Roadmap — tools to add next (designed, not yet built)

Each is read-only and maps to an existing repo, so each is a small TDD task:

- **`pending_review`** — list `pending_changes` awaiting approval (the queue of
  agent-proposed mutations). Wraps `pendingChanges.listPending`. Security-relevant
  because it's exactly where a prompt-injected agent's intent surfaces.
- **`resource_exposure`** — inventory of resources with `url`/`host`/`status`
  (attack surface / what's reachable). Wraps `resources.listBySpace` across spaces.
- **`token_audit`** — agent tokens with `label`, `last_used`, `revoked_at`
  (NOT the hash) to spot stale/unused credentials. Needs a small repo read.
- **`recent_captures`** — newly ingested refs/source_docs (untrusted external
  content entering the system), so Yerin can flag suspicious inbound material.

Stretch (needs new plumbing, your call):
- **`tls_expiry` / `service_health`** — port Void 1.x's `lib/security.js` cert
  checks + the Yerin alert cron into a tool she can call on demand.
- **Active probes** (e.g. "is this CT's admin port exposed?") would require
  network egress — must go through `safeFetch` and be owner-gated. Defer.

## Wiring Yerin up (the remaining integration steps — left for you)

These touch live agent seeding / MCP config, so they're documented rather than
done unsupervised:

1. **Seed the agent.** A migration (010) inserting a `yerin` agent row with
   `capabilities = {"read": true}`, `kind: 'claude'` (or `'ollama'` if you want
   her cheap/local), and a persona prompt. Mirror migration 007's companion seed.
2. **Expose `securityRegistry` over MCP.** `lib/mcp/companion-stdio.js` currently
   hardcodes `companionRegistry`. Parameterise it (env `VOID_TOOL_REGISTRY=security`
   selects the registry) so a Yerin session spawns with her tools. ~10 lines.
3. **A Yerin entry point.** Either a route (`POST /api/security/ask`) reusing the
   `claude_cli` driver with Yerin's persona + `securityRegistry`, or a scheduled
   cron that runs a standing "anything suspicious in the last 24h?" pass and files
   the result as a Sacred Valley card (ties into Plan 6).

## Adjacent agent roles (so the roster stays coherent)

- **Dross** — companion/chat (Lindon's own spirit-AI; the right-rail assistant).
  Read + suggest. Already live.
- **Yerin** — security/vigilance (this doc). Read-only.
- **Orthos** — see the role proposal below.

### Proposed role: Orthos — the local-model Advisor / Council

Orthos in Cradle is the ancient dragon-turtle: a **powerful ally with long
experience and a deep spiritual (Path of Black Flame) connection** — exactly your
framing. That maps cleanly onto a specific, useful Void 2.0 role:

**Orthos = the reflective Advisor, running on the local Ollama model (free,
always-on), not Claude.** He plays to a local model's strengths (summarisation &
synthesis, not precise tool-use):

- **The long view / "council briefing."** A scheduled pass that fuses recent
  captures, open tasks, and audit highlights into a short reflective digest —
  the Void 1.x "Orthos council briefing" reborn as a Sacred Valley widget.
- **"Spiritual connection" = the knowledge graph.** Let Orthos traverse the
  embedding/RRF links to surface *non-obvious connections* across Spaces
  ("these three captures in two different Spaces are converging on X"). That's
  the literal mechanisation of his deep-sight: semantic connection-finding over
  the vector store.
- **Why local:** it's high-frequency, low-stakes, cost-sensitive reflection —
  perfect for `llama3.1:8b` on `192.168.1.185`, keeping Claude budget for Dross.
  Capability: `{ read: true }`, `kind: 'ollama'`, `model: 'llama3.1:8b'`.

So the trio reads naturally: **Dross** converses, **Yerin** guards, **Orthos**
reflects — and two of the three (Yerin alerts, Orthos council) become Plan 6
Sacred Valley widgets. See `docs/plan-6-brainstorm-brief.md`.