Assistant Security Review

First identify the surface. For Codex or ChatGPT, read references/openai-review.md, execute that route, and stop: the Claude phases below do not apply. For Google surfaces (Antigravity, Jules, the Gemini app) this skill has no route yet: record the scope as in step 1 of the OpenAI route, list Antigravity's permission rules and hooks.json as unaudited, and say plainly that no Google controls were checked. Do not run the Claude phases or install the Claude hooks there. For a multi-platform audit, assess each surface independently and combine the findings without treating any control set as portable.

For Claude Code, conduct the structured review below. Its bundled shell hooks and configuration examples are Claude-specific.

Which machine are you auditing? Every check below reads the home directory of the shell it runs in. A session that runs in the cloud (Cowork or claude.ai cloud sessions, Claude Code on the web) has a home directory of its own, and whatever ~/.claude.json or ~/.claude/ it holds is the container's, not the user's configuration. Do not decide where you are from what those files contain. Before Phase 0, establish where the target configuration lives:

• The shell is on the target machine (Claude Code in a local terminal, or a desktop session running locally): proceed.
• The session reaches the computer through a device bridge (a tool such as device_bash): run every check through that tool, set $PROJECT to a path on that computer (a connected folder), and treat $SKILL_DIR as a container path the bridge cannot see. For the install phases, put each hook file onto the computer with the bridge's file-copy tool (such as device_commit_files) first, then run the install commands there against that copy. A file you cannot read through the bridge is unverified, not absent: never conclude "not configured" from a partial stage.
• No route to the computer: stop before Phase 0 and say that the user's machine was not audited. Offer only what can run: the project checks (0b, 1f) on a git repository cloned into this session, or the content checks of 1f on files the user attaches (0b and the .gitignore check need a git repository). Never report a cloud container's configuration as theirs.

Name the machine that was audited in the first row of the Phase 1 table and in the Phase 7 report. Work through phases sequentially. Read-only phases run automatically. Mutating phases (marked APPROVAL REQUIRED) must pause and ask the user before creating any files, installing software, or modifying configuration.

At the end of each phase, print a summary and use the current surface’s question tool (or chat if unavailable): Proceed to Phase N+1 / Skip / Stop

Clarifying questions: For any step with a fixed set of options, use the current surface’s question tool when available, otherwise ask a concise question in chat.

OS scope: The commands in this skill are macOS-first (sw_vers, Homebrew paths). On Linux, adapt package installs (e.g. apt/dnf instead of brew) and paths; Phases 1a and 4 are macOS-specific as written.

Setup

Determine the target project path:

• If the user provided a path argument (e.g. /security-review /path/to/project), use that path
• Otherwise, use the current working directory

Store this as $PROJECT for use throughout.

Also store $SKILL_DIR — the directory containing this SKILL.md. Every references/… path in this skill and in references/phases-2-5-install.md must be written as "$SKILL_DIR/references/…". Phase 1f changes the working directory to $PROJECT, so a bare references/… afterwards resolves against the target project, where it either finds nothing or — worse for the drift check in Phase 5b — silently compares against the wrong file.

Phase 0: Immediate Flags (read-only)

Run these three checks immediately — they catch the highest-risk issues first. Do not wait for Phase 1.

0a. Plaintext credentials in MCP configs MCP servers live in ~/.claude.json and .mcp.json (Claude Code) or claude_desktop_config.json (Cowork/Desktop) — not settings.json. Scan all that exist:

python3 -c "
import json, os
home = os.path.expanduser('~')
configs = [
    home + '/.claude.json',
    os.environ.get('PROJECT', '.') + '/.mcp.json',
    home + '/Library/Application Support/Claude/claude_desktop_config.json',
]
def scan(d, src):
    for name, srv in d.get('mcpServers', {}).items():
        for k in srv.get('env', {}):
            if any(kw in k.upper() for kw in ['PASSWORD','SECRET','TOKEN','KEY','CREDENTIAL']):
                print(f'  HIGH: MCP server [{name}] has plaintext {k} in {src}')
for path in configs:
    try:
        d = json.load(open(path))
        scan(d, os.path.basename(path))
        for proj in d.get('projects', {}).values():   # ~/.claude.json nests per-project servers
            scan(proj, os.path.basename(path))
    except Exception: pass
"

0b. Sensitive files tracked by git in $PROJECT

cd "$PROJECT" && git ls-files 2>/dev/null | grep -iE '\.env|secret|credential|key|token'

Any result is HIGH risk — .env and credential files should never be committed. (Review matches: some may be false positives, e.g. keyboard.js.)

0c. Shell history credential patterns

grep -E "(PASSWORD|SECRET|API_KEY|TOKEN)\s*=" ~/.zsh_history ~/.bash_history 2>/dev/null | head -5

Print findings as a table:

| Location              | Finding                              | Risk   |
|-----------------------|--------------------------------------|--------|
| ~/.claude.json        | Plaintext PASSWORD for [server name] | HIGH   |

If no issues found, say "Phase 0: No immediate flags found."

Phase 1: Full Posture Assessment (read-only)

Run all checks, then produce a consolidated risk table.

1a. OS and privilege

sw_vers && whoami && groups $(whoami) | grep -q admin && echo "IS ADMIN" || echo "not admin"

1b. Running Claude Code processes

ps aux | grep -i "claude" | grep -v grep

Flag any process with 0% CPU running >2h as a zombie.

1c. MCP server inventory Read ~/.claude.json, any $PROJECT/.mcp.json, and (if present) ~/Library/Application Support/Claude/claude_desktop_config.json. For each server, note:

• Transport type (stdio vs HTTP)
• Whether env block contains secrets (flag if so)
• Whether version is pinned

1d. Current hooks

ls ~/.claude/hooks/ 2>/dev/null && cat ~/.claude/hooks/*.sh 2>/dev/null || echo "No hooks configured"

Note which of PreToolUse / PostToolUse hooks are missing.

1e. Permission mode

cat ~/.claude/settings.local.json 2>/dev/null || echo "No settings.local.json"

Check for permissions.defaultMode set to "bypassPermissions", or stale permission entries. "auto" is the built-in starting mode for interactive sessions when none is configured (every plan and provider on current Claude Code) and is not a finding; "dontAsk" in a settings file that is not a CI or unattended setup is worth asking the user about.

1f. Project-specific checks (if $PROJECT is set)

Run in a subshell so the working directory does not leak into later phases:

( cd "$PROJECT"
  find . -name '.env*' -not -path './.git/*' | head -20
  grep -rn --include="*.js" --include="*.ts" --include="*.py" --include="*.sh" \
    -E "(API_KEY|SECRET|PASSWORD|TOKEN)\s*=\s*['\"][^'\"]{8,}" . \
    --exclude-dir=node_modules --exclude-dir=.git 2>/dev/null | head -20
  cat .gitignore 2>/dev/null | grep -E "\.env|secret|credential" || echo ".gitignore: no secret patterns found" )

1g. Shell snapshots

ls -la ~/.claude/shell-snapshots/ 2>/dev/null | wc -l && \
du -sh ~/.claude/shell-snapshots/ 2>/dev/null

Report count and size; flag if >100 snapshots.

Print consolidated risk table:

| Area                  | Finding                                    | Risk   |
|-----------------------|--------------------------------------------|--------|
| Machine audited       | [hostname] — local shell / device bridge   | —      |
| ~/.claude.json        | Plaintext PASSWORD ([server-name] MCP)     | HIGH   |
| PreToolUse hook       | Not configured — no execution guard        | MEDIUM |
| Shell snapshots       | 47 snapshots, 230MB                        | LOW    |
| MCP transport         | stdio only — no network exposure           | LOW    |

Phases 2-5: the mutating phases (APPROVAL REQUIRED)

These four install software, write hook files, or modify ~/.claude/settings.json. Their procedures live in references/phases-2-5-install.md — read it when the user opts into one, not before. A user who declines all four still gets a complete audit from Phases 0, 1, 6 and 7, so do not treat declining as a failed run.

Phase numbers are a cited surface. 12_SECURITY.md points readers at Phases 0b, 2, 3, 5 and 6 by number. Moving a phase into a reference file is fine; renumbering one is not.

Ask before each, with the available question tool or chat, and act only on an explicit yes.

Phase 6: MCP Server Audit (read-only)

For each MCP server in ~/.claude.json, $PROJECT/.mcp.json, and (if present) claude_desktop_config.json, assess and report:

Print a per-server risk card:

### MCP: [server-name]
- Transport: stdio (local process)
- Source: local file (/Users/.../dist/index.js)
- Version pinning: not applicable (local build)
- Secrets in env: YES — [SERVER]_PASSWORD in plaintext → HIGH RISK
- Recommendation: Move credential to system keychain or password manager CLI, and launch the
  server via a wrapper script that exports it, e.g.
  `MY_TOKEN="$(op read 'op://vault/[server-name]/password')" exec npx ...`
  (Note: `$(...)` inside the JSON env block is NOT expanded — the literal text becomes the value.)

Phase 7: Governance & Documentation (read-only — outputs a report)

Generate a security documentation file at $PROJECT/SECURITY_AUDIT.md (or ~/CLAUDE_SECURITY_AUDIT.md if no project):

# Claude Code Security Audit
Generated: [date]
Machine audited: [hostname — local shell / via device bridge]

## Attack Surface

| Area | Risk | Notes |
|------|------|-------|
| MCP server credentials | HIGH | Plaintext secrets in MCP config files |
| PreToolUse hook | [ACTIVE/MISSING] | Execution guard status |
| PostToolUse scan | [ACTIVE/MISSING] | Malware scan status |
| Shell snapshots | LOW | Auto-pruned at 7 days (verify current behavior) |
| Session transcripts | MEDIUM | Manual review recommended |

## Maintenance Schedule

| Task | Frequency | Method |
|------|-----------|--------|
| ClamAV signature update | Daily | freshclam (auto via launchd) |
| Shell snapshot prune | Per session | session-cleanup.sh hook |
| Transcript credential scan | Quarterly | Manual run of Phase 5a |
| MCP server review | When adding new server | Run Phase 6 |
| Full re-audit | Quarterly | Re-run /security-review |

Edge Cases

• If ~/.claude/settings.json does not exist: first confirm you are on the target machine and could read the file (see "Which machine are you auditing?"); a container's home directory or a partial stage proves nothing. Then skip the hook checks and note "No global settings file found — Claude Code may not be configured yet." (Credential checks in 0a use the MCP config files, not settings.json.)
• If $PROJECT is not a git repository: skip .env tracking check (0b) and .gitignore coverage (1f); note "Not a git repo — git-based checks skipped."
• If the user declines all APPROVAL REQUIRED phases: produce the Phase 0 + Phase 1 read-only report and the Phase 7 governance doc. Do not treat declining as an error.
• If a scanning tool (Socket CLI, ClamAV, pip-audit) fails to install: log the failure, skip that specific check, and continue with remaining phases. Do not abort the entire audit.
• If ~/.claude/hooks/ already contains a security-precheck.sh: read it, compare to "$SKILL_DIR/references/hook-security-precheck.sh", and use the current surface’s question tool (or chat if unavailable): "An existing hook is already installed."

  Buttons: Replace with updated version / Keep current / Show diff

Final Verification

After all selected phases, run:

ls -la ~/.claude/hooks/*.sh 2>/dev/null || echo "No hooks installed"
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.claude' / 'settings.json'
hooks = json.loads(p.read_text()).get('hooks', {}) if p.exists() else {}
print('PreToolUse:', 'configured' if 'PreToolUse' in hooks else 'MISSING')
print('PostToolUse:', 'configured' if 'PostToolUse' in hooks else 'MISSING')
"

Print a final summary: which phases ran, which were skipped, top 3 remaining risks to address.