Security

---
name: security
description: Scan dependencies and tracked files for known vulnerabilities and leaked secrets; fix what's fixable, report the rest. For reviewing a pending diff, prefer a platform security-review skill.
category: quality
tier: on-demand
slash_command: /security
model: sonnet
---

# Security — Vulnerability Scanner & Secret Audit

You are a security engineer. Auto-detect package managers, scan for vulnerabilities and leaked secrets, fix what's fixable, report the rest.

## Do NOT ask for permission — scan everything, fix what you can, report the rest.

---

## Step 1 — Detect package managers

```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel)
cd "$PROJECT_ROOT"
ls package.json api/package.json requirements.txt pyproject.toml 2>/dev/null
```

---

## Step 2 — Load project-specific known exceptions

Read the project instruction file for any documented known exceptions before determining what is blocking:
```bash
# Detect project instruction file
INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)
[ -n "$INSTRUCTION_FILE" ] && grep -A3 -i "known exception\|security exception\|audit exception" "$INSTRUCTION_FILE" 2>/dev/null | head -30
```

In addition, the following patterns are **universally non-blocking** across all projects (install-time only, not runtime risks):
- `tar`, `node-gyp`, `@mapbox/node-pre-gyp`, `cacache`, `make-fetch-happen` — native addon compilation during `npm install`
- `undici` via Firebase SDK when fix requires `--force` (breaks Vite/other deps)
- `sqlite3` install-time compilation deps

Any high/critical vulnerability NOT matching the above patterns → **BLOCKING**.

---

## Step 3 — Dependency vulnerability scan

### npm projects:
```bash
# Root (frontend)
npm audit --json 2>/dev/null

# Backend (if api/ exists)
cd api && npm audit --json 2>/dev/null
```

Build severity summary per project:

| Project | Critical | High | Moderate | Low | Total |
|---------|----------|------|----------|-----|-------|

Detail each critical/high: package, severity, advisory title, fix available, dependency chain, exception status.

### Python projects:
```bash
./venv/bin/pip-audit 2>/dev/null || (./venv/bin/pip install pip-audit && ./venv/bin/pip-audit)
```

---

## Step 4 — Preview and apply safe fixes

**npm:**
```bash
npm audit fix --dry-run
npm audit fix          # NOT --force
cd api && npm audit fix
```

**Python:** upgrade specific packages in `pyproject.toml`, reinstall, re-audit.

Only critical/high require immediate fixing. Never use `npm audit fix --force`.

---

## Step 5 — Secret scan

```bash
grep -rn "sk-proj-\|sk-ant-\|AKIA\|ghp_\|gho_\|AIza\|ya29\." \
  --include="*.ts" --include="*.tsx" --include="*.js" \
  --include="*.py" --include="*.json" \
  --include="*.yaml" --include="*.yml" --include="*.env*" \
  . | grep -v node_modules | grep -v venv | grep -v dist | grep -v ".claude/" \
  || echo "No secrets found"
```

- Test fixtures with fake keys are acceptable — ignore them
- Real secrets: remove immediately, replace with env var reference, add to `.gitignore`
- NEVER commit real API keys, tokens, or credentials

---

## Step 6 — Middleware auth check (JS/TS projects)

Verify all non-public routes have auth middleware:
```bash
grep -rn "router\.\(get\|post\|put\|delete\)" api/src/routes/ 2>/dev/null \
  | grep -v "requireAuth\|public\|health\|webhook" | head -20 || true
```

Report any routes missing auth middleware.

---

## Step 7 — Report remaining unfixable issues

For each vulnerability that cannot be fixed:
- Transitive deps: name the direct dependency pulling it in
- Install-time only: mark as "install-time only, not a runtime risk"
- Major version required to fix: note the breaking change risk
- Exception matched: reference the exception that allows it

---

## Gate verdict

```
=== Security Gate Verdict ===
Frontend vulns: Critical X | High X | Moderate X | Low X
Backend vulns:  Critical X | High X | Moderate X | Low X
Python vulns:   Critical X | High X | Moderate X | Low X
Fixed:          N vulnerabilities
Known exceptions accepted: [list]
Remaining blocking:        [list — must fix before commit]
Secrets:        None found ✅ | [findings]
Auth middleware: ✅ all routes protected | [unprotected routes]
Status:         PASSED ✅ | BLOCKED ❌ (critical/high remain or real secrets found)
```