dianyike/claude-code-insights/security-review

/security:review — Read-Only Security Audit

Run the security-reviewer subagent to produce a dual-verification security report. This command is always read-only — it will never modify source code files.

Command Syntax

/security:review [options] [path...]
  --base <branch>              # Diff against a base branch (merge-base)
  --scope staged|working-tree  # Explicit change scope
  --background                 # Run in background, return job ID
  --wait                       # Run in foreground (default)

Target Resolution

Determine the review scope before invoking the subagent:

Priority Order

1. If --base <branch> is specified → branch diff mode

• Run: git merge-base HEAD <branch> → git diff --name-only <merge-base>..HEAD

1. If --scope is specified → explicit scope mode

• staged: git diff --staged --name-only
• working-tree: git diff --name-only + git ls-files --others --exclude-standard

1. If neither specified and working tree is dirty → auto: working-tree
2. If neither specified and working tree is clean → auto: branch diff against default branch

Path Filtering

If [path...] arguments are provided, filter the resolved file list to only include files whose paths start with any of the given prefixes.

Handoff to Subagent

Pass the resolved scope to the security-reviewer subagent:

Review scope:
- Mode: <branch-diff|staged|working-tree>
- Base: <branch> (if applicable)
- Files: <resolved file list>
- Path filters: <prefixes> (if applicable)

Background Execution

When --background is specified:

1. Launch the security-reviewer subagent with run_in_background: true
2. Return immediately with: "Security review started. Use /security:status to check progress."
3. When the subagent completes, the notification will include the verdict and report path.

When --wait (default):

1. Launch the security-reviewer subagent in foreground
2. Display the verdict and report path when complete

Related Commands

• /security:fix <report> — Opt-in remediation based on a review report (requires explicit user action)

Job Management (Phase 1 — not yet implemented)

The following commands are planned but not yet available as separate skills. Until implemented, use natural language (e.g., "check the security scan status") and the main agent will handle it via the Agent tool's built-in background notification.

• /security:status [job-id] — Check background job progress. Without ID, list all active jobs
• /security:result <job-id> — Retrieve completed job verdict and report path
• /security:cancel <job-id> — Mark a running job as CANCELLED (subagent may still complete in background)

Expected behavior (for future implementation):

• Job state is persisted at .agents-output/security/jobs/<job-id>.json
• States: QUEUED → RUNNING → COMPLETED / FAILED / CANCELLED
• On session restart, any RUNNING job is marked STALE (detected by checking status == RUNNING with created_at older than the current session start)

Completion Criteria

• [ ] Target resolution produced a concrete file list (or "no changes found" if empty)
• [ ] security-reviewer subagent invoked with resolved scope
• [ ] Verdict and report path displayed to user
• [ ] If --background: job ID returned immediately, no blocking
• [ ] No source code files modified

Gotchas

• --base and --scope are mutually exclusive in practice — if both specified, --base wins (priority order). Don't warn the user; just follow priority
• When working tree is clean AND no default branch is detectable (e.g., fresh repo with only one commit), auto mode falls through to an empty file list. Surface this clearly instead of running Semgrep on zero files
• --background relies on Claude Code's run_in_background for the Agent tool — the subagent cannot be cancelled mid-execution; /security:cancel only marks the job as CANCELLED and stops waiting for results
• Path filters are prefix-matched, not glob-matched. src/auth matches src/auth/login.ts and src/auth-utils/helper.ts. If users expect glob semantics, clarify
• Iterate this section: After each real usage, append new gotchas here

What This Command Does NOT Do

• Does not modify source code (read-only)
• Does not enter the Fix-Verify Loop (Section 4 of the protocol)
• Does not auto-remediate findings
• Does not require Write or Edit tool permissions