review-security-issue

Review Security Issue

Review an issue that outlines a security, vulnerability, or privacy concern.

Prerequisites

• The gh CLI must be authenticated (gh auth status)
• You must be in a git repository with a GitHub remote
• The issue must have topic:security. In unattended queue mode it must also have agent:plan-requested; for a direct user request, warn if that workflow label is missing and continue without changing it.

Agent Comment Marker

All comments posted by this skill must begin with the following marker line so that prior reviews can be detected and human comments can be distinguished from agent comments:

> **🔒 security-review-agent**

This marker is used in Step 2 to detect prior reviews and in Step 5 to distinguish agent comments from human comments.

Step 1: Fetch the Issue

The user will provide an issue ID (e.g., #42 or 42). Strip any leading # and fetch the issue contents.

gh issue view <id>

To also retrieve the full issue body as JSON (useful for parsing):

gh issue view <id> --json title,body,state,labels,author

Step 2: Check if Review is Needed

First, check the issue's labels from the metadata fetched in Step 1.

• If the issue has agent:implementation-requested, the issue has already been reviewed and a human authorized remediation. There is no review to perform. Suggest using fix-security-issue and stop.
• If topic:security is missing, report that this specialized skill only reviews security issues and stop.
• If this is queue mode and agent:plan-requested is missing, report that the issue is not ready for unattended pickup and stop.
• If the user directly requested review of this issue, warn that agent:plan-requested is missing, then proceed without it. Never add or offer to add the human-only request label.

Next, fetch existing comments on the issue:

gh issue view <id> --json comments --jq '.comments[].body'

Search the comments for the agent marker (> **🔒 security-review-agent**).

• If the marker is found and no subsequent human comments exist that ask follow-up questions or challenge the review, you are done. Report to the user that a review already exists.
• If the marker is found but there are newer human comments with questions or objections, proceed to Step 5 to address them.
• If the marker is not found, proceed to Step 3.

Step 3: Analyze the Issue

Pass the issue title, description, and any relevant code references to the principal-engineer-reviewer sub-agent for analysis. Use the Task tool:

Task tool with subagent_type="principal-engineer-reviewer"

In the prompt, instruct the reviewer to approach the issue with a security-focused lens, specifically evaluating:

• Validity: Is this a real security, vulnerability, or privacy concern?
• Severity: What is the potential impact (data exposure, privilege escalation, denial of service, etc.)?
• Exploitability: How easy is it to exploit? Does it require authentication, specific conditions, or access?
• Attack scenario: What are the concrete steps an attacker would take to exploit this, from their perspective?
• Affected surface: Which components, endpoints, or code paths are affected?
• Recommendation: Should this be fixed, mitigated, accepted as risk, or closed as not actionable?

Step 4: Post the Review

Based on the analysis from Step 3, post a comment on the issue.

If the concern is legitimate

Post a comment with a remediation plan:

gh issue comment <id> --body "$(cat <<'EOF'
> **🔒 security-review-agent**

## Security Review

**Determination:** Legitimate concern

### Summary
<1-3 sentences describing the security issue and its impact>

### Severity Assessment
- **Impact:** <high / medium / low>
- **Exploitability:** <description of attack vector and prerequisites>
- **Affected components:** <list of affected code paths or services>

### Attack Scenario
Step-by-step from the attacker's perspective:
1. <attacker's first action — e.g., crafts a malicious payload>
2. <attacker's second action — e.g., sends request to endpoint>
3. <resulting impact — e.g., gains access to sensitive data>

### Remediation Plan
1. <step 1 with file/component references>
2. <step 2>
3. ...

### Additional Notes
<any caveats, trade-offs, or related concerns>
EOF
)"

If the concern is not actionable

Post a comment with a rationale:

gh issue comment <id> --body "$(cat <<'EOF'
> **🔒 security-review-agent**

## Security Review

**Determination:** Not actionable

### Rationale
<clear explanation of why this is not a security concern, including any mitigating factors already in place>

### References
<links to documentation, code, or standards that support the determination>
EOF
)"

Step 5: Mark the Security Plan Ready

After posting a legitimate-concern review with a remediation plan, replace agent:plan-requested with agent:plan-ready only when the request label was present:

gh issue edit <id> --remove-label "agent:plan-requested" --add-label "agent:plan-ready"

This signals that an unattended agent produced a remediation plan that awaits human review. For an unlabeled direct invocation, leave the agent:* labels unchanged. A later direct request can authorize remediation without agent:implementation-requested; warn that the expected label is missing and continue, while unattended remediation still requires that label. For a not-actionable determination, remove agent:plan-requested if present, do not add another agent:* label, and report that a human should close the issue or record the risk decision.

Step 6: Address Follow-up Comments

After posting (or if a prior review exists with new human comments), review all comments that do not contain the > **🔒 security-review-agent** marker. These are human comments.

For each unanswered human comment:

1. Read the question or objection.
2. Formulate a response based on the codebase and the prior security analysis.
3. Post a reply that begins with the agent marker.

Important: The authenticated user posting these comments may be a real person's account. Humans may reply to your comments directly. Always use the agent marker to distinguish your comments from theirs.

Useful Commands Reference

Example Usage

Review a security issue

User says: "Review security issue #42"

1. Fetch issue #42 via gh issue view 42
2. Fetch comments and check for the security-review-agent marker
3. No prior review found -- pass issue to principal-engineer-reviewer with security lens
4. Reviewer determines it's a legitimate XSS vulnerability in the API response handler
5. Post a comment with severity assessment and remediation plan
6. If agent:plan-requested was present, replace it with agent:plan-ready; otherwise leave the direct invocation unlabeled
7. Report the finding and posted comment to the user

Re-review with new comments

User says: "Check on security issue #42 again"

1. Fetch issue #42 and its comments
2. Find existing security-review-agent review from a prior run
3. Detect two new human comments asking about scope of the vulnerability
4. Post responses to each, prefixed with the agent marker
5. Report to the user what was addressed