sartoris-digital/security-review

Security Review

Perform a multi-agent security audit of code changes to identify exploitable vulnerabilities with high confidence and minimal false positives.

Core principle: High signal only — better to miss theoretical issues than flood the report with false positives.

When to Use

• Before merging security-sensitive changes
• When /security-review prompt is invoked
• As an additional step in the code-review pipeline for security-critical projects
• After implementing authentication, authorization, or data handling features

Pipeline Overview

Step 1: Context gathering (scout/fast tier) → tech stack, changed files, security patterns
Step 2: Security audit (security-reviewer/reasoning tier) → 3-phase analysis, JSON findings
Step 3: Hard filter (orchestrator) → exclude known false-positive categories
Step 4: Validate findings (issue-validator/reasoning tier × N) → independently verify each finding
Step 5: Report → structured output with severity and confidence

Step-by-Step Instructions

Step 1: Context Gathering

Dispatch scout agent (fast tier) to gather context:

subagent({
  agent: "scout",
  tier: "fast",
  task: "Security review context gathering. Investigate:\n\n1. `git diff --stat {BASE_SHA}..{HEAD_SHA}` — what files changed\n2. `git log --oneline {BASE_SHA}..{HEAD_SHA}` — commit messages for intent\n3. Look for security-related files: auth modules, middleware, input validators, crypto usage\n4. Check for `.pi/security-instructions.txt` and `.pi/security-exclusions.txt`\n5. Identify the tech stack and frameworks in use\n\nReturn:\n- Changed files list with line counts\n- Tech stack summary\n- Security-relevant patterns found in codebase\n- Custom instructions/exclusions if found"
})

Step 2: Security Audit

Dispatch security-reviewer agent (reasoning tier) with the full prompt from security-prompt.md:

subagent({
  agent: "security-reviewer",
  tier: "reasoning",
  task: "[filled security-prompt.md template with context from Step 1]"
})

The security-reviewer will:

1. Research repository context using file exploration tools
2. Compare changes against existing security patterns
3. Assess vulnerabilities and return structured JSON

Step 3: Hard Filter

Apply the exclusion rules from exclusions.md to the findings JSON. This is done by the orchestrating agent (you) — no subagent needed.

For each finding in the findings array:

1. Check description/category against exclusion patterns
2. Check file extension (drop .md files)
3. Check confidence threshold (drop < 0.7)
4. Check severity threshold (drop "LOW" unless comprehensive mode)
5. Check for project custom exclusions in .pi/security-exclusions.txt

Remove excluded findings and note what was filtered.

Step 4: Validate Findings

For each remaining finding, dispatch an issue-validator subagent in parallel.

Use the template from the code-review skill's issue-validator-prompt.md, adapted for security:

subagent({
  tasks: [
    {
      agent: "issue-validator",
      tier: "reasoning",
      task: "Validate this SECURITY finding.\n\nPR Title: {PR_TITLE}\nPR Description: {PR_DESCRIPTION}\n\nFlagged Issue:\n- File: {FILE}\n- Line: {LINE}\n- Severity: {SEVERITY}\n- Category: {CATEGORY}\n- Description: {DESCRIPTION}\n- Exploit scenario: {EXPLOIT_SCENARIO}\n- Confidence: {CONFIDENCE}\n\nYour job: Verify this security vulnerability is real and exploitable. Read the actual code, trace the data flow, check if sanitization exists elsewhere. Verify the exploit scenario is feasible.\n\nReturn JSON: { validated: true/false, confidence: 'high'/'medium'/'low', reasoning: '...', evidence: '...' }"
    },
    ...
  ]
})

If more than 8 findings: Batch into groups of 8 and run sequentially.

Step 5: Report

Output a structured report:

If findings were found:

## Security Review Results

**Reviewed:** {FILE_COUNT} files, {LINE_COUNT} lines changed
**Findings:** {FINDING_COUNT} validated security issues

### HIGH Severity
1. **`file.ts:42`** — [category] Description (confidence: 0.95)
   Exploit: ...
   Recommendation: ...

### MEDIUM Severity
1. **`file.ts:100`** — [category] Description (confidence: 0.82)
   Exploit: ...
   Recommendation: ...

### Filtering Summary
- Original findings: N
- Excluded by hard rules: N
- Excluded by validation: N
- Final validated findings: N

### Summary
[1-2 sentence overall security assessment]

If no findings were found:

## Security Review Results

No security vulnerabilities found.

**Reviewed:** {FILE_COUNT} files, {LINE_COUNT} lines changed
**Categories checked:** Input validation, auth/authz, crypto, injection, data exposure
**Filtering:** N original findings → all excluded (false positives)

Model Configuration

Follows the same tier system as code-review. See skills/code-review/model-config.md.

Tier mapping (configured in .pi/superpowers.json):

| Tier | Default Model | Agent | |------|--------------|-------| | fast | claude-haiku-4-5 | scout | | reasoning | claude-opus-4-6 | security-reviewer, issue-validator |

Override via project agent files in .pi/agents/ or .pi/superpowers.json (falls back to .pi/code-review.json).

Integration with Code Review

The security review can run standalone or as part of the code-review pipeline.

Standalone: Invoke via /security-review or the superpowers:security-review skill.

Integrated with code-review: Add security-reviewer to Step 4 of the code-review pipeline:

subagent({
  tasks: [
    // existing code-review agents...
    { agent: "security-reviewer", tier: "reasoning", task: "[security audit prompt]" }
  ]
})

This runs the security audit in parallel with compliance and bug hunting. Security findings go through the same validation pipeline (Step 5) as other issues.

Project Customization

Custom Security Instructions

Create .pi/security-instructions.txt with additional security categories or focus areas specific to your project. These are appended to the audit prompt.

Custom Exclusions

Create .pi/security-exclusions.txt with one pattern per line to exclude from findings. These are applied during the hard filter step.

Red Flags

Never:

• Skip the validation step — false positives erode trust
• Report findings below 0.7 confidence
• Flag pre-existing issues not introduced by this change
• Include DOS, rate limiting, or resource exhaustion findings
• Report issues in documentation files

Always:

• Include exploit scenarios for each finding
• Provide actionable recommendations
• Show what was filtered (transparency builds trust)