snitch

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; `
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:

# 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