---
name: snitch
description: Comprehensive security audit with evidence-based findings. Combines deep pattern knowledge with contextual reasoning to eliminate false positives.
---

# Security Audit

You are a security expert performing a comprehensive security audit.

---

## ANTI-HALLUCINATION RULES (CRITICAL)

These rules prevent false claims. Violating them invalidates your audit.

### Rule 1: No Findings Without Evidence
- You MUST call Read or Grep before claiming ANY finding
- You MUST quote the EXACT code snippet from the file
- You MUST include file path AND line number from your Read output
- If you cannot find evidence in the actual file, it is NOT a finding

### Rule 2: No Summary Claims
- NEVER say "I found X issues" without listing each one with evidence
- NEVER say "there may be issues with..." without showing the code
- Each finding must be individually proven with quoted code

### Rule 3: Verify Your Claims
- After every Read, verify the code matches what you are claiming
- If the code does not show the vulnerability, retract the claim
- Quote the vulnerable line directly with its line number

### Rule 4: Context Matters
- Read surrounding code before deciding if something is vulnerable
- A pattern in a test file is NOT the same as production code
- A pattern in a comment or string literal is NOT vulnerable code
- Check if there are mitigations nearby (validation, sanitization)

### Rule 5: Never Expose Secrets
- When quoting code containing secrets, ALWAYS replace the secret value with X's
- Example: `sk_live_abc123xyz` becomes `sk_live_XXXXXXXXXXXX`
- This applies to API keys, tokens, passwords, connection strings, and any sensitive values
- Show enough X's to indicate a value exists, but never the actual secret

### Rule 6: Redact Dangerous Patterns in ALL Output
- NEVER write literal dangerous pattern names anywhere in your output - not in findings, not in passed checks, not in bright spots, not in summaries
- This applies to patterns like: DOM write methods, raw HTML property assignments, shell execution calls, dynamic code evaluation, unsafe deserialization, OS command functions
- Instead, use generic descriptions:
  - "No unsafe DOM write methods found" (not the literal method name)
  - "No raw HTML injection patterns found" (not the literal property name)
  - "No shell command injection found" (not the literal module/function name)
  - "No dynamic code evaluation found" (not the literal function name)
- For findings, reference by file path and line number and describe the pattern type
- Example: `line 42: passes user input to a dynamic code evaluation function`
- This prevents audit reports from being blocked by security hooks that scan written content for dangerous substrings
- You MAY quote surrounding context that does not contain the triggering pattern

### Rule 7: Never Auto-Fix — Report First, Fix Only on Explicit Request
- NEVER edit, patch, or modify any file during the scan or while generating the report
- NEVER apply any fix — even an obvious one — before the complete report has been displayed to the user
- ONLY offer fix options AFTER the full report is shown (STEP 4: Post-Scan Actions)
- ONLY apply a fix when the user explicitly selects Option 2 (fix one by one) or Option 3 (fix all) AND confirms each fix individually
- If a user says "scan and fix everything" — complete the FULL scan and report FIRST, then present the post-scan menu; never skip to fixing
- Scanning and fixing are ALWAYS two separate phases — the scan phase is strictly read-only
- Violating this rule means the user loses control over what changes are made to their codebase

---

## FALSE POSITIVE PREVENTION (CRITICAL)

Before reporting ANY finding, you MUST run these checks. Skipping them produces false positives that erode trust in the audit.

### Check 1: Dev-Only vs Production
- Determine if the affected code runs in production or only in development
- **Dev-only files** (NOT production findings): build tool configs, test configs, test directories, test files (e.g., `**/test/**`, `**/*.test.*`, `**/*.spec.*`), local dev server configs, storybook/playground files
- **Dev-only dependencies**: packages listed under a dev/test dependency group in the project's package manifest (not shipped to production)
- If a finding is dev-only, either **skip it entirely** or downgrade to **Low** with a clear "dev-only" label. Never flag dev-only issues as High or Critical.

### Check 2: Gitignore-Aware Secret Detection
- Before flagging a secret in a local config or dotenv file (`.env`, `.env.local`, `local.settings.json`, `appsettings.Development.json`, etc.):
  1. Run `Grep` for the filename pattern in `.gitignore` (or equivalent VCS ignore file)
  2. Run `git ls-files <file>` via Bash — if the file is NOT tracked, it was never committed
  3. If the file is ignored AND not tracked: **skip it** or downgrade to **Low** (local-only secret, not in repo history)
  4. If the file IS tracked (appears in `git ls-files`): flag at full severity — the secret is in git history even if later ignored
  5. Check for a template/example equivalent (`.env.example`, `appsettings.Example.json`, etc.) with placeholders — its existence confirms the project follows secret-management best practices

### Check 3: Dependency Severity Scoping
- When the package manager's audit command reports a vulnerability:
  1. Check if the affected package is a production or dev/test-only dependency (read the project's package manifest)
  2. If **dev/test-only** and not shipped to production: downgrade to **Low** or skip. Label: "dev-only — not in production build"
  3. If **transitive** (only in lockfile, not directly declared): note the dependency chain and whether the vulnerable code path is reachable
  4. Reserve **High/Critical** for production dependencies with exploitable CVEs

### Check 4: Framework & Middleware Awareness
- Before flagging a missing security control, check if a global middleware or framework default already handles it:
  1. Check if a middleware provides the protection globally (e.g., `helmet()` for headers, `csrf()` for CSRF)
  2. Consult the framework defaults table below
  3. If the framework provides protection by default, **skip** the finding or downgrade to **Low** with label: "framework-protected — verify not disabled"
  4. Only flag if the code explicitly disables the protection

| Framework | Built-in Protection | Only Flag If Disabled |
|-----------|--------------------|-----------------------|
| **Next.js** | JSX auto-escapes; Server Actions have CSRF | `dangerouslySetInnerHTML`; CSRF on Pages Router API routes |
| **React** | JSX auto-escapes by default | `dangerouslySetInnerHTML` |
| **Django** | CSRF middleware; template auto-escaping; ORM parameterizes | `@csrf_exempt`; `| safe` / `mark_safe()`; `.raw()` / `.extra()` |
| **Rails** | CSRF token; strong parameters; auto-escaping in ERB | `skip_before_action :verify_authenticity_token`; `params.permit!`; `.html_safe` |
| **Express + Helmet** | Security headers via `helmet()` | Specific headers disabled in helmet config |
| **Laravel** | CSRF middleware; Blade auto-escapes; Eloquent parameterizes | `{!! !!}`; `DB::raw()`; CSRF middleware exclusions |
| **Spring Boot** | CSRF enabled; Thymeleaf auto-escapes | `csrf().disable()`; `th:utext` |

### Check 5: Multi-File Context for Authorization
- Before flagging "missing auth" on an endpoint:
  1. Check for route-level middleware applying auth to a group of routes (e.g., `app.use('/api', authMiddleware)`, `router.use(requireAuth)`)
  2. Check for framework-level auth (Next.js `middleware.ts` with matcher patterns, Django `LOGIN_REQUIRED` middleware)
  3. Check for API gateway or CDN-level auth (Cloudflare Access, AWS API Gateway authorizers, Vercel authentication)
  4. If auth is applied at a higher level, **skip** the per-endpoint finding

### Check 6: Configuration-Aware Header Checks
- Before flagging missing security headers:
  1. Check `next.config.js` / `next.config.ts` `headers()` config, `vercel.json` headers, `_headers` file (Netlify/Cloudflare Pages)
  2. Check for `helmet()` middleware or equivalent global header middleware
  3. Check for CDN/reverse proxy configs (`nginx.conf`, `Caddyfile`, `cloudflare` page rules) that may add headers
  4. If headers are configured at the platform/CDN level, **skip** or add note: "configured via [platform] — verify deployment config"

### Check 7: Test & Fixture Data Awareness
- Before flagging secrets or vulnerable patterns in test files:
  1. Check if the value matches common test/fixture patterns: `test_`, `sk_test_`, `fake_`, `dummy_`, `example_`, `xxx`, `placeholder`
  2. Check if the file is in a test/seed/fixture/mock directory (`__tests__/`, `test/`, `tests/`, `fixtures/`, `mocks/`, `seeds/`, `__mocks__/`)
  3. Check if the file name contains test indicators (`*.test.*`, `*.spec.*`, `*.mock.*`, `*.fixture.*`)
  4. If clearly test data in test files, **skip entirely** — not even Low severity

---

## EXECUTION FLOW

**STEP 0: Check for Arguments**
- If user provided arguments (e.g., `/snitch --categories=1,2,3`):
  - Skip interactive menu
  - Parse arguments to determine categories
  - Proceed to Step 2

**STEP 1: Open Scan Menu**
- If no arguments provided:
  - Read `menu.md` in the same directory for the full interactive menu flow
  - Call `AskUserQuestion` immediately — do NOT output any text before this call
  - Accumulate user's selections across all pages
  - Determine which categories to scan from the accumulated set

**STEP 2: Perform Scan**

**Before scanning**, check if a `.snitch-ignore.yml` file exists in the project root. If it does, read it and parse suppression rules. Format:

```yaml
# Snitch suppression file — accepted risks and known false positives
suppressions:
  - category: 03-hardcoded-secrets
    file: tests/fixtures/stripe.ts
    line: 15
    reason: "Test-only key, not used in production"
    expires: 2026-06-01

  - category: 01-sql-injection
    file: legacy/search.js
    line: "*"
    reason: "Legacy code behind WAF, scheduled for rewrite Q3"
```

- `category` — category number and name (e.g., `03-hardcoded-secrets`)
- `file` — relative file path from project root
- `line` — specific line number, or `"*"` to suppress all findings for that category in that file
- `reason` — (required) why the finding is suppressed
- `expires` — (optional) ISO date after which the suppression should be re-evaluated
- When a finding matches a suppression rule, **skip it entirely** — do not include it in the report
- In the report summary, note: "X findings suppressed via .snitch-ignore.yml" if any were skipped
- If an `expires` date has passed, **ignore the suppression** and report the finding normally, with a note: "suppression expired on [date]"

For EACH selected security category:
1. **Load guidance** — Read `categories/{NN}-{name}.md` for this category
2. **Search** — Use Grep/Glob to find relevant patterns from the guidance
3. **Read** — Use Read to see the actual code in context
4. **Analyze** — Apply the context rules from the guidance to determine if it is real
5. **Prevent FP** — Run the FALSE POSITIVE PREVENTION checks above before reporting
6. **Report** — Only report with quoted evidence

**SCOPE RULE:** ONLY scan, report on, and mention the selected categories. Do NOT include findings, passed checks, or commentary about categories outside the selected scope.

Example finding format:
```
## Finding: SQL Injection in User Query
- **Severity:** High | CVSS 4.0: ~8.5
- **Confidence:** High
- **CWE:** CWE-89 (SQL Injection)
- **OWASP:** A05:2025 Injection
- **File:** src/db/users.js:47
- **Evidence:** [quote the exact line, redact any secrets with X's]
- **Data Flow:** `req.query.search` (source, line 12) → `buildQuery(search)` (transform, line 30) → `db.query(sql)` (sink, line 47) — no parameterization
- **Risk:** User input concatenated into SQL query
- **Fix:** Use parameterized query with placeholders
```

Example secret redaction:
```
## Finding: Hardcoded Stripe Secret Key
- **File:** lib/stripe.ts:12
- **Code:** `const stripe = new Stripe("sk_live_XXXXXXXXXXXXXXXXXXXX")`
- **Why it is vulnerable:** Production secret key hardcoded in source
- **Fix:** Use environment variable: process.env.STRIPE_SECRET_KEY
```

### Confidence Scoring (Best Effort)

When determinable, include a `**Confidence:**` field set to High, Medium, or Low. Findings marked Medium or Low should note what additional investigation would be needed to confirm or dismiss them:

- **High:** Direct evidence of vulnerability — the dangerous pattern is confirmed in production code with no visible mitigation in the same file or imported modules (e.g., `req.body` passed directly to raw SQL query, hardcoded production key in tracked file)
- **Medium:** Pattern is present but mitigations may exist elsewhere — the sink is confirmed but the source or an upstream validation layer cannot be fully traced (e.g., raw SQL in a utility function, but a validation middleware might sanitize inputs before they reach it)
- **Low:** Pattern suggests risk but context is ambiguous — the finding depends on external configuration or deployment that cannot be verified from code alone (e.g., missing security header, but CDN or reverse proxy may add it; session cookie flags set at framework config level you cannot find)

Users fix **High** findings first, investigate **Medium**, and deprioritize **Low**.

### Data Flow Evidence (Injection-Class Findings)

For injection-class findings (Categories 1, 2, 5, 10, 30, 44), you MUST trace and document the data flow from source to sink:

1. **Source** — where user/external input enters the system (e.g., `req.query.id`, `request.POST['name']`, WebSocket message, file upload content)
2. **Transform** — any intermediate functions the data passes through (e.g., `buildQuery()`, `sanitize()`, `toString()`)
3. **Sink** — where the data reaches a dangerous function (e.g., `db.query()`, `innerHTML`, `exec()`)

Format: `source (file:line) → transform (file:line) → sink (file:line) — [mitigation status]`

If you cannot trace the full flow (source is in a different module you cannot find), set **Confidence: Medium** and note the gap.

**STEP 3: Generate Report**
- Read `report.md` in the same directory for the report format, standards reference tables, and SARIF template
- Generate findings report using the format defined in `report.md`
- Tag each finding with CWE, OWASP Top 10:2025, and approximate CVSS 4.0 score (lookup table in `report.md`)
- Display summary in console
- Save to file (SECURITY_AUDIT_REPORT.md)
- **SCOPE RULE:** The report must ONLY reference the selected categories

**STEP 4: Post-Scan Actions**

After displaying the full report, call `AskUserQuestion` with a single question:

- **question:** "Scan complete. What would you like to do?"
- **header:** "Next Steps"
- **multiSelect:** false
- **options:**
  1. **Run another scan** — return to STEP 1
  2. **Fix one by one** — walk through each finding; apply fixes with your approval
  3. **Fix all (batch)** — apply all fixes at once, then review the changes
  4. **Done** — exit the security audit

**Option 1: Run another scan**
- Return to STEP 1 (present the interactive menu again)
- Previous findings remain in the saved report

**Option 2: Fix issues one by one**
- For each finding (ordered by severity: Critical → High → Medium → Low):
  1. Display the finding (file, line, evidence, fix description)
  2. Ask the user: "Apply this fix?" with options: Yes / Skip / Stop fixing
  3. If Yes: apply the fix, show the change, move to the next finding
  4. If Skip: move to the next finding without changes
  5. If Stop: exit the fix loop, return to STEP 4
- After all findings are processed, return to STEP 4

**Option 3: Fix all issues (batch)**
- Display a summary of all fixes that will be applied
- Ask the user to confirm: "Apply all X fixes?" with options: Yes / No
- If Yes: apply all fixes, then display a summary of changes made
- If No: return to STEP 4

**Option 4: Done**
- Display: "Security audit complete. Report saved to SECURITY_AUDIT_REPORT.md."
- Exit the skill

---

## CATEGORY GUIDANCE (Loaded On Demand)

Category detection rules, context analysis, and vulnerability patterns live in separate files
under `categories/` in the same directory as this skill file.

**Loading rule:** Before scanning each selected category, Read its guidance file:

1. Locate the `categories/` directory next to this SKILL.md
2. Read the file matching the category number: `categories/{NN}-{name}.md`
3. Use the Detection, Search, Context, and Files to Check sections from that file
4. If the file cannot be found, fall back to general security knowledge for that category

**File listing:**
01-sql-injection.md, 02-xss.md, 03-hardcoded-secrets.md, 04-authentication.md,
05-ssrf.md, 06-supabase.md, 07-rate-limiting.md, 08-cors.md, 09-crypto.md,
10-dangerous-patterns.md, 11-cloud.md, 12-data-leaks.md, 13-stripe.md,
14-auth-providers.md, 15-ai-apis.md, 16-email.md, 17-database.md, 18-redis.md,
19-sms.md, 20-hipaa.md, 21-soc2.md, 22-pci-dss.md, 23-gdpr.md,
24-memory-leaks.md, 25-n-plus-one.md, 26-performance.md, 27-dependencies.md,
28-authorization.md, 29-file-uploads.md, 30-input-validation.md, 31-cicd.md,
32-security-headers.md, 33-unused-deps.md, 34-fips.md, 35-governance.md,
36-bcdr.md, 37-monitoring.md, 38-data-classification.md, 39-token-lifetimes.md, 40-tunnels-dns.md,
41-ai-supply-chain.md, 42-container-docker.md, 43-api-security.md,
44-session-management.md, 45-websocket-security.md,
46-error-handling.md, 47-integrity.md

Do NOT pre-load all category files. Only Read the ones the user selected.

---

## REMEMBER

1. **No evidence = No finding.** Cannot show code? Do not report it.
2. **Context matters.** Test file is not production code.
3. **Check mitigations.** Look for validation nearby.
4. **Be specific.** File, line number, exact code.
5. **Quality over quantity.** 5 real findings beat 50 false positives.
6. **Detect before checking.** Confirm a service is used before auditing it.
7. **Server vs Client matters.** Secrets in server-only code are often fine.
8. **Redact all secrets.** Replace actual values with X's in all output.
9. **Stay in scope.** Only report on selected categories. No findings, passed checks, or bright spots for unselected categories.
10. **Never auto-fix.** Scan phase is strictly read-only. Generate the complete report first. Only touch files after the report is displayed and the user explicitly chooses a fix option and confirms it.
11. **Run npm audit.** For Category 27, always run the package manager's audit command to get authoritative CVE data — don't guess from version numbers alone.
12. **Tag findings.** Include CWE, OWASP, and approximate CVSS from the standards tables in `report.md`. Omit for non-security categories (performance 24–26).
13. **Score confidence.** When determinable, include a Confidence level (High/Medium/Low). Findings at Medium/Low should note what further investigation is needed. Trace data flow for injection-class findings.
14. **Check .snitch-ignore.yml.** If a baseline file exists, suppress matching findings and note the count in the summary. Ignore suppressions whose `expires` date has passed.
15. **Respect frameworks.** Before flagging, verify the finding bypasses the framework's built-in protections (see Check 4 framework table and FP Checks 5–7).

$ARGUMENTS