/perform-security-review

name: perform-security-review
description: Performs a security-focused code review by launching multiple specialized agents and a verification agent to ensure comprehensive coverage and accurate findings. Use this skill when the user asks for a "perform-security-review", "bitwarden-security-review", "execute a security review", "run a comprehensive security audit", "perform an end-to-end security assessment", or needs to coordinate multiple security checks across code, dependencies, secrets, and configurations. The skill manages the workflow, delegates tasks to specialized agents, and presents final findings to the user.
argument-hint: "[--output <chat|file|github>] [--output-dir <path>] [--model <model>] [--base-ref <ref>] [pr-number-or-url|commit-sha|duration]"
allowed-tools: Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh repo view --json defaultBranchRef:*), Bash(git branch --show-current:*), Bash(git diff:*), Bash(git log:*), Bash(git merge-base:*), Bash(git remote get-url:*), Bash(git rev-parse:*), Bash(printenv GITHUB_ACTIONS), Read, Skill, Task, Write, mcp__plugin_aikido_aikido-mcp__aikido_issues_list

Parameters

**`--base-ref <ref>`**: Branch comparison mode only. Use this ref as the diff base instead of probing for one. It still passes all three checks in step 1-A2, so an unresolvable or disconnected ref is rejected rather than trusted. Supply this when the probes in step 1-A2 would resolve the wrong base — a non-default trunk such as `rc`, or a repository where `gh` is unauthenticated so candidate 2 is unavailable. It does not rescue a default `actions/checkout`; `references/base-ref-resolution.md` says why and what does.

**`--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. A PR number, commit SHA, or duration argument selects its own mode, and `--base-ref` selects branch comparison mode when no positional argument is given.

**If a positional argument and `--base-ref` are both present, stop and report the conflict**, naming both and asking for one. Launch no agents. Write the report to the resolved output destination, as the step 1-A2 abort does.

• **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 PR, commit, or duration argument, no `--base-ref`, and pending changes exist): `git diff HEAD` for staged + unstaged changes.
• **Branch comparison mode** (no positional argument, and either `--base-ref <ref>` is given or the tree has no pending changes): `git diff <base-ref>...HEAD` — changes since the branch diverged from the base, resolved in sub-step A2 rather than assumed to be `main`. `--base-ref` selects this mode outright, so it works in a dirty tree, but a three-dot diff compares commits and leaves pending changes unreviewed. Run `git diff --quiet HEAD` here too and add the step 5 header's `Pending changes:` line when it reports dirty; without `--base-ref`, pending changes route to local changes mode instead.

Two of those modes turn on whether the tree is dirty. Test it with `git diff --quiet HEAD`, which exits 1 when pending changes exist.

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 them. Three places stop the run early, and taking them is following this rule: the mode-conflict stop above, the step 1-A2 abort, and the step 1B stops.

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

**A.) Resolve repo identity.** Run each of these as its own Bash call — 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 (`git@github.com:owner/repo.git`) formats.
• `git branch --show-current` — capture the current branch name.

**A2.) Resolve the base ref.** Branch comparison mode only; skip for every other mode. Run each command as its own Bash call. `references/base-ref-resolution.md` explains why each check below exists.

A caller may supply `--base-ref <ref>`. When present it is the only candidate: do not probe for others, and if it fails any of the three checks below, go straight to the abort. Falling through to `origin/HEAD` would review a base the caller did not ask for. Use the ref exactly as given — never rewrite it — but a bare `main` resolves to the local branch rather than `origin/main`, so name the ref you used in the step 5 header, where a stale local base is at least visible.

Otherwise, candidates in order: 1. `git rev-parse --abbrev-ref origin/HEAD` — its output, when the command exits 0. Key on the exit status, never the output. 2. `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`, giving `origin/<default_branch>`. Not `gh api`; see `references/tool-grants.md`. Build it whenever candidate 1 does not yield a base ref — either its command exited non-zero, so there is no candidate 1 at all, or its output failed one of the three checks. If the API call itself fails, candidate 2 does not exist.

**Every candidate passes all three checks, in this order, whatever its source.** A probe candidate that fails any check is discarded and resolution falls through to the next probe. A caller-supplied `--base-ref` has no next candidate, so it goes straight to the abort. 1. It matches