---
name: security-audit
description: Subsystem-scoped security audit. Use on "audit the gateway", "review trust boundaries of X", "check personality isolation", "audit the skill loader" or any named subsystem. Not per-PR review, not whole-repo. Writes plan/audits/ report; read-only.
---

# Security Audit Workflow — Ethos Codebase

A workflow for posture/subsystem security audits of the Ethos codebase. **Not** a per-PR diff review — that's a different motion. This is for *"audit the gateway dedup path"*, *"review the tool capability model"*, *"audit personality isolation"*, *"check the channel-adapter trust boundary"*, *"audit the skill loader"*.

The thing that makes audits work is discipline about scope and evidence. Everything below is in service of that.

## 1. Frame the audit

Before reading any code, write down four things. **If any is unclear, stop and ask the user.**

- **Scope** — one subsystem, one question. *"Audit the gateway"* is scope. *"Audit Ethos"* is not — split it. Examples: gateway dedup, supervisor lifecycle, AgentLoop's tool-execution path, universal skill scanner, plugin loader, channel adapter X, MCP integration, storage abstraction.
- **Threat model** — one paragraph. Common Ethos threats: malicious skill author, prompt injection from untrusted tool output, compromised MCP server, malicious personality definition, adversarial channel input, capability escalation across personality boundaries, secret exfiltration through tool args/results/audit logs, plugin abuse of registered hooks. Findings only make sense relative to this.
- **Asset criticality** — what's on the line if this subsystem fails. User's filesystem? API keys? Team's shared memory? Conversation history? Drives severity; CVSS does not.
- **Prior audits** — check `plan/audits/` for prior findings. Read them first. Re-auditing blind duplicates work and misses regressions.

## 2. Ground in the constitution

Security findings are only valid if they reflect what the codebase is *supposed* to be. Before reading code, read the documents that say so:

- [ARCHITECTURE.md](../../../ARCHITECTURE.md) — layer model, dependency direction, frozen schemas, safety rules. Findings that contradict ARCHITECTURE.md are findings; findings that contradict your *intuition* of how things should work are not.
- [SOUL.md](../../../SOUL.md) — product identity invariants. Useful when evaluating whether a feature *should exist*, not just whether it's safe.
- [CLAUDE.md](../../../CLAUDE.md) — project rules.
- The subsystem's local docs and the relevant `safety-*` / `injection*` modules.

Do not assume a tool is sandboxed because its name sounds safe. Do not assume a capability boundary exists because it would be a good idea. Verify in code.

## 3. Map trust boundaries

Most LLM-framework vulnerabilities cross a trust boundary. Map the ones in scope before reading code:

- Adversary → channel adapter (Telegram/Discord/Slack/Email/WhatsApp message content)
- Untrusted tool output → prompt (`web_extract`, `browse_url`, `read_file` with attacker-controlled content)
- Skill author → personality (skill content, declared permissions, tool list)
- MCP server → AgentLoop (tool definitions, tool results)
- Plugin author → AgentLoop (hooks, tools, injectors registered)
- Personality A → Personality B (cross-personality memory / fs / state)
- Member agent → coordinator → other members (multi-agent prompt injection)

For each in scope: what wraps the data, what classifies it as untrusted, what downgrades capability after crossing.

## 4. Execute the checks

Work from a checklist filtered to the trust boundaries in scope. Per check:

1. **Run the canonical command or read the canonical file.** Static: `rg`, `pnpm typecheck`, `pnpm lint`, `pnpm test`. Dynamic: write a vitest that exercises the trust-boundary crossing. Don't invent fuzzers; reach for what the project already supports.
2. **Capture verbatim evidence.** `file:line:literal-code`. Paraphrased code isn't evidence.
3. **Verdict per check:** pass / fail / n-a / needs-followup. *Needs-followup* is legitimate when threat-model fit is ambiguous — don't force a call.

**Read-only by default. No `Edit` / `Write` / `MultiEdit` on the codebase during the audit.** Reproducer tests stay local — cite them in the report; do not commit. Don't "fix while you're there." Don't delete dead code you happened to notice. The audit surfaces; fixes are separate.

The audit report itself IS allowed to be written — that's the deliverable. Everything else in the codebase is off-limits during this motion.

## 5. Score findings

- **Severity = impact under *your* threat model**, not CVSS. A prompt-injection vector with no path to escalation is medium; a `network → exec` escalation via a skill is critical regardless of where it lands.
- **One root cause = one finding** with N instances. Three tools missing redaction is one finding (*"redaction not enforced at tool boundary"*), not three.
- **Every finding cites evidence.** `file:line:exact-code`, command run, verbatim output. No evidence, no finding.
- **Every finding has a concrete remediation.** "Add a sanitizer" is not remediation. *"In `packages/core/src/agent-loop.ts:265`, wrap the tool result with `wrapUntrusted()` from `safety-trust-boundary.ts` before adding to message history"* is.
- **Cite project rules when they apply.** ARCHITECTURE.md principle violated? Name it. SOUL.md test failed? Name it. Project rules are stronger evidence than auditor judgement.

### Severity rubric

| Severity | Definition (under Ethos threat model) |
|---|---|
| **Critical** | Bypasses a fundamental architectural safety claim AND is reachable via realistic adversary (prompt injection, npm install, or plain config). Full compromise of the boundary. |
| **High** | Meaningful capability escalation OR cross-personality / cross-team leakage. Plausible exploit path; may require an additional step but not exotic. |
| **Medium** | Real isolation gap or trust-model mismatch. Limited or indirect exploit, but the documented contract is not what the code does. |
| **Low** | Informational, documented-but-poorly behaviour, marginal exploit, or defense-in-depth recommendation. |

## 6. Write the report

Default path: `plan/audits/<subsystem>-audit-YYYY-MM-DD.md` (Markdown) or `.html` if the user asked for HTML. Match the tone of existing plan docs (terse, structured, evidence-led). Required sections:

1. **Scope & threat model** — the four things from step 1, crisply.
2. **Methodology** — what code was read, what commands were run, what trust boundaries were probed. A future auditor must be able to replay from this section alone.
3. **Summary** — finding counts by severity, top three risks, overall posture in one paragraph. Read first; make it carry weight.
4. **Findings** — one per finding: ID (`<PREFIX>-NNN`, e.g. `PI-001` for personality-isolation), title, severity, affected files/symbols, evidence (verbatim), impact, remediation, references (architecture principle, SOUL test, CWE, OWASP-LLM).
5. **What was checked and passed** — positive coverage, grouped by trust boundary. Without this the report reads as "everything is broken" when most things are fine.
6. **Out of scope / deferred** — what this audit did NOT cover, one-line reason each. Prevents the report being mistaken for a full-stack review.
7. **Appendix: raw output** — long dumps, test cases, configs. Keep findings section readable.

If HTML: single-file, embedded CSS, semantic HTML (`<article>` per finding), color-coded severity badges, anchor IDs per finding, print-friendly. No JS, no external deps. Use the existing audit at `plan/audits/personality-isolation-audit-2026-05-14.html` as the reference template — match its structure and styling.

## 7. Wrap

The audit ends when the report is written to `plan/audits/`. Each finding carries its ID, severity, and concrete remediation — the report **IS** the follow-up record. No separate tracking file. No git commit. No PR. The user decides what to do with the findings.

**Do not fix findings inside the audit.** The audit surfaces and prioritizes; fixes go through the normal review path. Mixing the two corrupts both — the report becomes *"here's what I changed"* instead of *"here's what's wrong,"* and the fix loses the rigor of a focused PR.

## Invariants

- **Never audit from memory.** ARCHITECTURE.md, SOUL.md, CLAUDE.md, and the subsystem's code are the source of truth; recall is not.
- **Read-only.** No `Edit`, `Write`, `MultiEdit` on the codebase. Reproducer tests stay local. The audit report in `plan/audits/` is the only write permitted. No `git commit`, no `git push`.
- **Never print secrets.** Redact (`REDACTED`) and reference the secret's storage location.
- **One root cause = one finding. One finding = one concrete remediation.**
- **Project rules win over auditor opinion.** If ARCHITECTURE.md or SOUL.md explicitly permits something, it is not a finding even if you'd design it differently.
- **Cite, don't summarise.** `file:line:literal-code` or it didn't happen.
- **If scope is unclear, stop and ask.** Audit sprawl is the failure mode.
