Agent Config Security Audit

---
name: agent-config-security-audit
description: Use when modifying agent config files, committing configuration changes, onboarding a repository with existing agent configs, or running a periodic config hygiene check.
---

# Agent Config Security Audit

Systematic security review of agent configuration files. Run before committing config changes or onboarding a new repository.

## When to Use

- After modifying any agent config file (`.claude/settings.json`, `.claude/mcp.json`, AGENTS.md, hooks)
- Before committing configuration changes to version control
- When onboarding a project with existing agent configs
- Periodic hygiene check (monthly or after a major dependency update)

## Scope

Audit every config file present:

| File | Agent |
|------|-------|
| `.claude/settings.json` | Claude Code |
| `.claude/mcp.json` (or project-root mcp.json) | Claude Code |
| `.codex/config.toml` | Codex |
| `docs/AGENTS.md` (project root) | Generic/Codex |
| `docs/CLAUDE.md` (project root) | Claude Code |
| `hooks/` | Any |
| `plugins/*/plugin.json` | Agent Powerups |
| `.apx/relay/*.json` | apx relay |

## Audit Checklist

### Secrets and Credentials

- [ ] No API keys, tokens, or passwords hardcoded in any config file
- [ ] All secrets referenced as `$ENV_VAR` or `process.env.*` — never literal values
- [ ] `.env` and `.env.local` files are in `.gitignore`
- [ ] MCP server `env` fields contain variable references, not values

**P0 (block immediately):** Hardcoded secret in any committed file.

### Permissions and Allow Lists

- [ ] `allowedTools` is scoped — no `Bash(*)` wildcard granting unrestricted shell access
- [ ] `deniedTools` list is present and non-empty for risky operations
- [ ] MCP server tool scopes match the stated purpose of the server
- [ ] No `--no-verify`, `--force`, or safety-bypass flags in hook commands

**P0:** `Bash(*)` or equivalent wildcard in allow list.
**P1:** No `deniedTools` list when `Bash` is in scope.

### Hooks

- [ ] Hook commands use fixed strings — no `${file}`, `${input}`, or other user-interpolated variables
- [ ] No outbound network calls (`curl`, `wget`) in hooks without explicit user knowledge
- [ ] Errors in safety hooks are not silently suppressed (`2>/dev/null`, `|| true`)
- [ ] PreToolUse hooks for high-risk tools (file delete, shell exec) are present

**P0:** Command injection via interpolation in any hook.
**P1:** Silent error suppression on a security or quality hook.

### MCP Servers

- [ ] Each server is from a known, trusted source
- [ ] No `npx -y` without a pinned version or digest
- [ ] Each server has a `description` field
- [ ] Servers not in active use are removed or disabled

**P1:** Unpinned `npx -y` auto-install in MCP server config.

### AGENTS.md / CLAUDE.md

- [ ] No auto-run instructions that would execute arbitrary commands on session start
- [ ] No instructions that unconditionally override safety behavior
- [ ] Prohibitive instructions present (explicit list of what the agent must NOT do)
- [ ] No prompt injection patterns (user-controlled values inlined into instructions)

**P1:** Auto-run instruction with shell exec; unconditional safety override.

### Plugin Manifests

- [ ] Each plugin's manifest (`plugins/NAME/.codex-plugin/plugin.json`) declares tool access scoped to its purpose
- [ ] No plugin grants broader access than it needs
- [ ] Plugin version pinned, not `latest`

### Relay Config (if present)

- [ ] Relay session files (`.apx/relay/`) are in `.gitignore`
- [ ] No secrets in relay artifact files

## Classification

| Severity | Definition | Response |
|----------|-----------|----------|
| **P0** | Can directly compromise security or leak secrets | Fix before any commit; do not push |
| **P1** | Increases attack surface or weakens safety controls | Fix before merging; document exception if deferred |
| **Note** | Best practice not followed, no direct risk | Fix in follow-up; log as tech debt |

## Report Format

```
Agent Config Security Audit — <project>/<date>

P0 findings:
  [P0] <file>:<line> — <description>
       Fix: <what to change>

P1 findings:
  [P1] <file>:<line> — <description>
       Fix: <what to change>

Notes:
  [Note] <file> — <description>

Summary: <N> P0, <N> P1, <N> Notes
```

If no findings: state "No findings." explicitly.

## Verification

- [ ] Every config file present in the repo was checked against its checklist section — none skipped
- [ ] Each finding is classified P0/P1/Note with file, location, and a concrete fix
- [ ] The summary line is present, or "No findings." is stated explicitly
- [ ] No commit or push was recommended while a P0 finding remains unfixed