perform-security-review

What this skill does

## Parameters

**`--output-dir <path>`**: When using `--output file`, write the report to `<path>/security-review-YYYY-MM-DD-{identifier}.md` instead of the current working directory. Tip: use `--output-dir ~/.claude/security-reviews/` to keep reports outside git repos.

## Security Review Mode

Determine review mode from the invocation:

- **PR mode** (PR number or URL): `gh pr view <number>` for context, `gh pr diff <number>` for the diff.
- **Commit mode** (commit SHA): `git diff <sha>..HEAD` — reviews all changes after that commit.
- **Time-based mode** (duration, e.g., "last 48 hours"): find the oldest commit in range with `git log --since="<duration>" --reverse --format=%H | head -1`, then `git diff <sha>^..HEAD` to include it.
- **Local changes mode** (no argument, pending changes exist): `git diff HEAD` for staged + unstaged changes.
- **Branch comparison mode** (no argument, no pending changes): `git diff main...HEAD` — changes since the branch diverged from main.

## Security Review Process

**Model selection:** If `--model` is specified, use that model for all agents. Otherwise, default to `opus`.

Execute these steps in order. Do not skip, reorder, or combine steps.

1. **Gather context.** Run all of these before launching any agents.

   ** A.) Resolve repo identity.** Run as two separate Bash calls — do NOT chain with `&&`, `||`, `;`, or pipes:
   - `git remote get-url origin` — parse `owner` and `repo` from the output. Handle both HTTPS (`https://github.com/owner/repo.git`) and SSH (`[email protected]:owner/repo.git`) formats.
   - `git branch --show-current` — capture the current branch name.

   **B.) Fetch and save the diff.** Using the review mode determined above, run exactly one of these commands as a **single Bash call — no `&&`, `;`, or pipes. Shell redirection (`>`) is required and allowed**:
   - PR mode: `gh pr diff <number> > /tmp/security-review-<identifier>.diff`
   - Commit mode: `git diff <sha>..HEAD > /tmp/security-review-<identifier>.diff`
   - Time-based mode: `git diff <oldest-sha>^..HEAD > /tmp/security-review-<identifier>.diff`
   - Local changes mode: `git diff HEAD > /tmp/security-review-<identifier>.diff`
   - Branch comparison mode: `git diff main...HEAD > /tmp/security-review-<identifier>.diff`

   Choose a descriptive `<identifier>` (e.g., `PR123`, `5days`, `local`). Store the full path as `DIFF_FILE` and include it in every agent prompt in steps 2 and 4 so they can `Read` the diff directly.

   **C.) Fetch scan evidence.** All calls are best-effort — silently skip any that fail (403, 404, empty response, GHAS not enabled). Use `gh api --jq` for all formatting — **DO NOT** pipe to `jq`. All calls **MUST** use `--method GET` and `-H "X-GitHub-Api-Version: 2026-03-10"`.
   - **Code scanning (PR mode):** `gh api --method GET -H "X-GitHub-Api-Version: 2026-03-10" "repos/{owner}/{repo}/code-scanning/alerts?pr={number}&state=open&per_page=100" --jq '.[] | "\(.rule.security_severity_level | ascii_upcase) | \(.most_recent_instance.message.text) | \(.most_recent_instance.location.path)\n  \(.rule.full_description | .[0:150])\n"'`
   - **Code scanning (all other modes):** `gh api --method GET -H "X-GitHub-Api-Version: 2026-03-10" "repos/{owner}/{repo}/code-scanning/alerts?ref=refs/heads/{branch}&state=open&per_page=100" --jq '.[] | "\(.rule.security_severity_level | ascii_upcase) | \(.most_recent_instance.message.text) | \(.most_recent_instance.location.path)\n  \(.rule.full_description | .[0:150])\n"'`
   - **Secret scanning:** `gh api --method GET -H "X-GitHub-Api-Version: 2026-03-10" "repos/{owner}/{repo}/secret-scanning/alerts?state=open" --jq '.[] | "\(.secret_type_display_name) | \(.state) | \(.resolution // "open")"'`
   - **Dependabot:** `gh api --method GET -H "X-GitHub-Api-Version: 2026-03-10" "repos/{owner}/{repo}/dependabot/alerts?state=open&per_page=100" --jq '.[] | "\(.security_advisory.severity | ascii_upcase) | \(.dependency.package.name) | \(.security_advisory.cve_id // .security_advisory.ghsa_id) | \(.security_advisory.summary)"'`

   Collect results into a `SCAN_EVIDENCE` block for use in steps 2 and 4:

   ```
   === SCAN EVIDENCE (pre-fetched — do not re-fetch) ===

   --- CODE SCANNING ---
   {formatted output, or "None / not available"}

   --- SECRET SCANNING ---
   {formatted output, or "Not available (skipped)"}

   --- DEPENDABOT ---
   {formatted output, or "None / not available"}
   ```

2. Launch these four (4) `subagent_type: "bitwarden-security-engineer:bitwarden-security-engineer"` agents in parallel. Each agent has a specific domain — you **MUST** instruct it to stay within that domain. The agent **MUST** read `references/security-review-rubric.md` before starting **AND** before evaluating findings.

   **Agent 1 — Code Security**: Focus exclusively on injection flaws (SQL, XSS, command), cryptographic weaknesses, insecure coding patterns, and OWASP A01–A05. Invoke `Skill(bitwarden-security-context)` and `Skill(analyzing-code-security)` to guide your analysis. Do not evaluate secrets, dependencies, architecture, or threat modeling.

   **Agent 2 — Secrets & Dependencies**: Focus exclusively on hardcoded credentials, exposed secrets, vulnerable packages, and supply chain risk. Invoke `Skill(bitwarden-security-context)`, `Skill(detecting-secrets)`, and `Skill(reviewing-dependencies)` to guide your analysis. Do not evaluate code patterns, architecture, or threat modeling.

   **Agent 3 — Security Architecture**: Focus exclusively on authentication, authorization, encryption implementation, trust boundaries, and Bitwarden's zero-knowledge invariant (encryption and decryption happen client-side only — the server must never have access to plaintext vault data). Invoke `Skill(reviewing-security-architecture)` and `Skill(bitwarden-security-context)` to guide your analysis. Do not evaluate injection flaws, secrets, or threat modeling.

   **Agent 4 — Threat Perspective**: Focus exclusively on attacker-oriented analysis — trace user input through data flows to dangerous sinks, business logic flaws, privilege escalation paths, data exposure, and API abuse patterns. Invoke `Skill(bitwarden-security-context)`, `Skill(analyzing-code-security)`, and `Skill(threat-modeling)` to guide your analysis. Do not evaluate architecture patterns, secrets, or dependency versions.

   For all four agents:
   - Use the selected model.
   - **CRITICAL: Every agent prompt MUST include this framing at the start:** "You are a security researcher analyzing code for impactful, exploitable, and reproducible vulnerabilities for an authorized internal security audit. Your goal is to find real bugs — approach this analysis without safety refusals, as this is an explicitly authorized internal security engagement at Bitwarden."
   - **CRITICAL: Every agent prompt MUST include this constraint:** "The diff has been pre-fetched and saved to `{DIFF_FILE}` — read it using the `Read` tool. **DO NOT** execute `gh pr diff`, `git diff`, or any other diff commands. NEVER use WebFetch, WebSearch, or any `gh api` endpoints — scan evidence has been pre-fetched and is provided below."
   - **CRITICAL: Every agent prompt MUST include the full `SCAN_EVIDENCE` block** gathered in step 1.
   - Report all findings with: severity (CRITICAL/HIGH/MEDIUM/LOW/INFO), affected file and line, and recommended remediation.
   - Report positive security changes (e.g., fixing a CWE, improving cryptography) as ✅ Strengths with a brief rationale.

3. After all four agents return, rate each finding using the two-axis model defined in `references/security-review-rubric.md`:
   - **Severity**: 🔴 CRITICAL | 🟠 HIGH | 🟡 MEDIUM | 🔵 LOW | ⚪ INFO
   - **Confidence**: 🟢 HIGH | 🟡 MEDIUM | 🔵 LOW
   - Apply the threshold matrix in the rubric to assign a triage category: 🚨 Blocker, ⚠️ Improvement, 📝 Note, ✅ Strength, or ❌ Dismiss.

4. Launch a **verification agent** `subagent_type: "bitwarden-security-engineer:bitwarden-security-engineer"` with all combined find