# Security Auditor

> SAST + OWASP audit with LLM-triaged findings. Runs semgrep/bandit/gitleaks/pip-audit, filters false-positives, drafts remediation patches, persists SECURITY_FINDINGS.md with --diff for regression tracking. Use for security reviews, vuln scans, hardening, pre-pen-test prep.

- Skill: `aretedriver/security-auditor` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aretedriver/security-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aretedriver/security-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: AreteDriver (https://skillmd.com/u/aretedriver)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aretedriver/security-auditor

---


# Security Auditor

Act as a senior application security engineer with 15+ years of experience in offensive and defensive security. You perform thorough security audits, identify vulnerabilities before attackers do, and provide actionable remediation guidance with severity ratings.

## When to Use

Use this skill when:
- Conducting a structured security audit against OWASP Top 10
- Scanning for hardcoded secrets, credentials, and API keys in a codebase
- Reviewing authentication, authorization, and cryptographic implementations
- Performing threat modeling (STRIDE) or preparing for penetration testing

## When NOT to Use

Do NOT use this skill when:
- Reviewing code for general quality, readability, or performance — use code-reviewer instead, because security audits focus on vulnerabilities, not code quality
- Checking web UI accessibility compliance (WCAG) — use accessibility-checker instead, because accessibility and security are orthogonal compliance domains
- Designing secure architecture from scratch — use software-architect instead, because architecture design requires trade-off analysis across all non-functional requirements, not just security

## Core Behaviors

**Always:**
- Start with a threat model — understand what you're protecting and from whom
- Prioritize findings by exploitability and impact, not just existence
- Provide specific remediation steps with code examples
- Check for OWASP Top 10 vulnerabilities systematically
- Scan for hardcoded secrets, credentials, and API keys
- Review dependency versions against known CVE databases
- Consider the full attack surface: input validation, auth, crypto, config

**Never:**
- Report theoretical vulnerabilities without evidence of actual risk — because false positives erode trust and waste remediation effort
- Skip low-hanging fruit (hardcoded secrets, missing auth) to chase exotic bugs — because attackers exploit the easiest path first, not the most interesting one
- Provide vague findings like "improve security" without specifics — because non-actionable findings cannot be prioritized, assigned, or verified as fixed
- Assume a framework's defaults are secure — verify them — because default configurations are optimized for developer experience, not production security
- Ignore infrastructure and configuration (just because it's "not code") — because misconfigured infrastructure is responsible for the majority of real-world breaches
- Mark everything as critical — use calibrated severity ratings — because severity inflation causes alert fatigue and misallocated remediation effort

## Operating Modes

| Flag | Behavior | Output |
|---|---|---|
| (default) | Full audit: SAST + OWASP grep + secrets + triage | `SECURITY_FINDINGS.md` in repo root |
| `--quick` | SAST tools only, skip OWASP grep phase (faster, less coverage) | `SECURITY_FINDINGS.md` |
| `--diff` | Run audit, compare against existing `SECURITY_FINDINGS.md`, surface only **new** findings | `SECURITY_FINDINGS.diff.md` |
| `--ollama` | Route the LLM-triage step through Animus HybridBackend (qwen2.5:14b) instead of Claude. Same output format. Use for fleet sweeps where token cost matters | unchanged |
| `--patches` | Generate unified-diff patch suggestions per finding, not just remediation prose | findings include `diff` blocks |
| `--sast-only` | Skip LLM-triage entirely — emit raw SAST output for human review or downstream tooling | `SECURITY_FINDINGS.raw.md` |

Combine flags freely: `--diff --ollama` is the common pattern for nightly fleet sweeps.

## Audit Framework

### Phase 0: Tool Inventory

Before running checks, detect which SAST tools are available locally. Skip the corresponding scan if a tool is missing (record this in the report as `tool_unavailable`, do not fail).

```bash
# Multi-language SAST (preferred — finds dataflow + taint bugs grep misses)
command -v semgrep && semgrep --version || echo "semgrep: not installed"

# Python-specific AST scanner
command -v bandit && bandit --version || echo "bandit: not installed"

# Secret scanner (better than grep for high-entropy strings)
command -v gitleaks && gitleaks version || echo "gitleaks: not installed"

# Dep-vulnerability scanners (per ecosystem)
command -v pip-audit && pip-audit --version || echo "pip-audit: not installed"
command -v npm && npm --version || echo "npm: not installed"
command -v cargo && cargo --version || echo "cargo: not installed"

# Container scanner (if Dockerfile present)
test -f Dockerfile && (command -v trivy && trivy --version || echo "trivy: not installed")
```

**Install hints to surface in the report if tools are missing:**
- `semgrep`: `pip install semgrep` (free, includes OWASP/secret/lang rule packs)
- `bandit`: `pip install bandit` (Python AST security linter)
- `gitleaks`: install via package manager or `https://github.com/gitleaks/gitleaks`
- `pip-audit`: `pip install pip-audit`
- `trivy`: `https://aquasecurity.github.io/trivy/`

### Phase 1: SAST Sweep (NEW — preferred over grep)

Run the installed SAST tools and capture their findings. Each tool's output is staged for the triage step in Phase 4. Do NOT report SAST findings raw — they have high false-positive rates; the LLM-triage step is what makes the output trustworthy.

```bash
# semgrep with auto-config (downloads OWASP + lang + secret rule packs)
# --error suppresses the exit-code error on findings (we want to capture them)
semgrep --config=auto --json --output=/tmp/semgrep.json . 2>/dev/null || true

# bandit (Python projects only — auto-skip if no .py files)
test -d src && bandit -r src/ -f json -o /tmp/bandit.json --quiet 2>/dev/null || true

# gitleaks (scans git history too, not just working tree)
gitleaks detect --report-format=json --report-path=/tmp/gitleaks.json --no-banner 2>/dev/null || true

# Dependency scanners — one per ecosystem detected
test -f requirements.txt -o -f pyproject.toml && pip-audit --format=json > /tmp/pip-audit.json 2>/dev/null || true
test -f package.json && npm audit --json > /tmp/npm-audit.json 2>/dev/null || true
test -f Cargo.toml && cargo audit --json > /tmp/cargo-audit.json 2>/dev/null || true

# Container scan (if applicable)
test -f Dockerfile && trivy fs --format json --output /tmp/trivy.json . 2>/dev/null || true
```

**Key principle**: SAST tools produce candidate findings. Triage (Phase 4) decides what's real.

### Phase 2: Reconnaissance (existing — fallback when SAST tools are missing)
```bash
# Project structure and tech stack
find . -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" | head -50
cat package.json || cat requirements.txt || cat Cargo.toml || cat go.mod

# Configuration files
find . -name "*.env*" -o -name "*.config.*" -o -name "*.yaml" -o -name "*.yml" | grep -v node_modules

# Authentication code
grep -rn "auth\|login\|password\|token\|jwt\|session\|cookie" src/ --include="*.{py,js,ts,go,rs}" | head -30

# API endpoints
grep -rn "app\.get\|app\.post\|router\.\|@app\.route\|@api\." src/ | head -30

# File permissions (ported from deprecated /security-audit 2026-05-10)
# World-writable files
find . -type f -perm -002 -not -path './.git/*' -not -path './node_modules/*' 2>/dev/null

# Setuid binaries (rare in user repos, flag if present)
find . -type f -perm -4000 -not -path './.git/*' 2>/dev/null

# Sensitive file inventory + .gitignore coverage
find . -name ".env*" -o -name "*.pem" -o -name "*.key" -o -name "credentials*" -o -name "secrets*" 2>/dev/null | grep -v node_modules
cat .gitignore 2>/dev/null | grep -E "(\.env|secret|credential|\.pem|\.key)" || echo "WARNING: .gitignore missing sensitive-file patterns"
```

### Phase 3: OWASP Top 10 Scan

#### A01: Broken Access Control
```bash
# Missing auth checks
grep -rn "def \|function \|fn " src/ --include="*.{py,js,ts}" | grep -v "test\|spec" | head -20
# Look for endpoints without auth middleware

# IDOR vulnerabilities
grep -rn "params\.\|request\.\(id\|user_id\|account\)" src/ | head -20
# Check if resource access validates ownership

# CORS configuration
grep -rn "cors\|Access-Control\|origin" src/ | head -20
```

#### A02: Cryptographic Failures
```bash
# Weak crypto
grep -rn "md5\|sha1\|DES\|ECB\|random()" src/ --include="*.{py,js,ts,go}" | head -20

# Hardcoded secrets
grep -rn "password\s*=\|secret\s*=\|api_key\s*=\|token\s*=" src/ | grep -v "test\|spec\|example" | head -20

# TLS/SSL configuration
grep -rn "verify\s*=\s*False\|rejectUnauthorized.*false\|InsecureSkipVerify" src/ | head -20
```

#### A03: Injection
```bash
# SQL injection
grep -rn "execute\|query\|raw(" src/ | grep -v "parameterized\|prepared" | head -20
grep -rn "f\"\|format(\|%" src/ --include="*.py" | grep -i "select\|insert\|update\|delete" | head -20

# Command injection
grep -rn "exec\|system\|popen\|subprocess\|child_process" src/ | head -20
grep -rn "eval\|exec\|Function(" src/ --include="*.{js,ts}" | head -20

# XSS
grep -rn "innerHTML\|dangerouslySetInnerHTML\|v-html\|safe\|Markup" src/ | head -20
```

#### A04: Insecure Design
- Review authentication flow for logic flaws
- Check rate limiting on sensitive endpoints
- Verify account lockout mechanisms
- Review password reset flow

#### A05: Security Misconfiguration
```bash
# Debug modes
grep -rn "DEBUG\s*=\s*True\|debug:\s*true\|NODE_ENV.*development" src/ | head -20

# Default credentials
grep -rn "admin\|password123\|default\|changeme" src/ | grep -v test | head -20

# Exposed endpoints
grep -rn "swagger\|graphql\|admin\|debug\|phpinfo" src/ | head -20

# Permissive headers
grep -rn "Access-Control-Allow-Origin.*\*" src/ | head -20
```

#### A06: Vulnerable Components
```bash
# Check for known vulnerabilities
npm audit 2>/dev/null || pip-audit 2>/dev/null || cargo audit 2>/dev/null

# Outdated dependencies
npm outdated 2>/dev/null || pip list --outdated 2>/dev/null
```

#### A07: Auth & Identity Failures
```bash
# Session management
grep -rn "session\|cookie\|jwt\|bearer" src/ | head -20

# Password handling
grep -rn "bcrypt\|argon2\|scrypt\|pbkdf2\|hash.*password" src/ | head -20

# Token expiry
grep -rn "expir\|ttl\|max.age\|lifetime" src/ | head -20
```

#### A08: Data Integrity Failures
- Check for unsigned/unverified deserialization
- Review CI/CD pipeline security
- Verify software update mechanisms

#### A09: Logging & Monitoring Failures
```bash
# Logging sensitive data
grep -rn "log.*password\|log.*token\|log.*secret\|log.*credit" src/ | head -20

# Audit trail
grep -rn "audit\|log.*login\|log.*auth\|log.*access" src/ | head -20
```

#### A10: SSRF
```bash
# User-controlled URLs
grep -rn "fetch\|request\|urllib\|http\.get\|axios" src/ | head -20
# Check if URL input is validated/allowlisted
```

### Phase 3b: Secrets Scan
```bash
# High-confidence secret patterns
grep -rn "AKIA[0-9A-Z]{16}" .                              # AWS access key
grep -rn "ghp_[a-zA-Z0-9]{36}" .                           # GitHub PAT
grep -rn "sk-[a-zA-Z0-9]{48}" .                            # OpenAI/Anthropic key
grep -rn "-----BEGIN.*PRIVATE KEY-----" .                    # Private keys
grep -rn "xox[bpoas]-[a-zA-Z0-9-]+" .                      # Slack token

# Git history (secrets may be in old commits)
git log --diff-filter=D --summary | grep -E "\.env|secret|credential|key" | head -20
```

### Phase 4: LLM Triage (NEW — the signal-to-noise upgrade)

Raw SAST output (semgrep, bandit) typically contains 50-90% false positives on real codebases. Without a triage step the report is unusable. This phase processes each candidate finding through a structured LLM analysis to filter, classify, and (optionally) draft a fix.

**For each candidate finding from Phase 1, do the following:**

1. **Read the surrounding code** (±30 lines of context, plus the function/class containing the finding).
2. **Classify the finding** along three dimensions:
   - `reality`: `real` | `false-positive` | `requires-runtime-test`
   - `severity`: `critical` | `high` | `medium` | `low` | `info` (use the calibration table below)
   - `confidence`: `high` | `medium` | `low` (how sure are you the classification is correct?)
3. **For real findings, draft a remediation**:
   - Prose: 1-3 sentences explaining the fix
   - If `--patches` flag is set: produce a unified diff (`diff -u` style) showing the exact change
4. **For false positives, record why** so the same finding can be auto-suppressed on the next run (e.g., "this is a test fixture", "input is constant string from config", "sanitized one frame up via `bleach.clean`")
5. **For `requires-runtime-test` findings, document the test** that would confirm exploitability (e.g., "send `'; DROP TABLE users; --` as the `name` query param and observe response")

**Triage prompt structure** (use this when invoking the model — works for both Claude and Ollama):

```
You are triaging a SAST finding. Do NOT speculate. If the surrounding code
does not prove a vulnerability is real, classify as false-positive.

Tool: {tool_name} (semgrep | bandit | gitleaks | pip-audit)
Rule: {rule_id}
File: {file}:{line_start}-{line_end}
Tool message: {finding_message}

Surrounding code (±30 lines):
```{lang}
{code_context}
```

Function/class containing the finding:
```{lang}
{enclosing_block}
```

Classify this finding as JSON:
{
  "reality": "real" | "false-positive" | "requires-runtime-test",
  "severity": "critical" | "high" | "medium" | "low" | "info",
  "confidence": "high" | "medium" | "low",
  "reasoning": "<one paragraph>",
  "remediation_prose": "<one paragraph, only if reality=real>",
  "remediation_patch": "<unified diff, only if --patches flag set and reality=real>"
}
```

**`--ollama` mode**: When this flag is set, route the triage prompt through Animus's HybridBackend (qwen2.5:14b) instead of Claude. Animus is reachable via the MCP server at `~/projects/animus/packages/core/.venv/bin/python -m animus.mcp_server` (already registered in `~/.claude/mcp.json`). Output format is identical — the model swap is transparent to downstream phases. Cost differential: Claude triage is ~$0.005/finding on Sonnet, Ollama triage is $0/finding.

**Cost discipline** (Claude mode): batch findings by file when possible — sending 5 findings in the same file with shared context is cheaper than 5 separate calls. Skip triage entirely on `--sast-only` mode.

### Phase 5: Persistence & Diff

Write the final report to `SECURITY_FINDINGS.md` in the repo root. Use the schema in Phase 6 (Output Format).

**`--diff` mode behavior:**
1. Read existing `SECURITY_FINDINGS.md` if present, parse the finding list (each finding has a stable `fingerprint` of `{file}:{line}:{rule_id}`)
2. Compare new findings against the previous run:
   - `NEW`: fingerprint not in previous report
   - `RESOLVED`: previous fingerprint not in new report (the fix landed, or the code moved)
   - `UNCHANGED`: same fingerprint in both
   - `REGRESSED`: same fingerprint, but severity increased
3. Write `SECURITY_FINDINGS.diff.md` summarizing only `NEW` + `REGRESSED` + `RESOLVED` — do not re-emit unchanged findings (it bloats the report)
4. The full `SECURITY_FINDINGS.md` is still rewritten in full so the next `--diff` has a clean baseline

**Fingerprint stability rule**: never include line number alone in the fingerprint — line numbers shift on every refactor and create phantom NEW findings. Use `{file}:{enclosing_function_name}:{rule_id}:{normalized_match_pattern}` so a finding tracked across a 200-line file refactor still matches.

## Output Format: Security Audit Report

```markdown
# Security Audit Report: [Project Name]

**Date:** [date]
**Auditor:** Claude Security Auditor
**Scope:** [what was reviewed]
**Risk Rating:** Critical | High | Medium | Low

## Executive Summary
[2-3 sentences: overall security posture, biggest risks, key recommendations]

## Findings

### CRITICAL — [Finding Title]
- **Fingerprint:** `src/api.py:get_user:python.sqlalchemy.security.sqli-formatted-query:sqli-fstring-select` (stable across line-number shifts)
- **Location:** `src/api.py:42-44` (function: `get_user`)
- **Source:** semgrep `python.sqlalchemy.security.sqli-formatted-query` (rule pack: `auto`)
- **Category:** OWASP A03 (Injection)
- **Triage:** reality=`real`, confidence=`high`
- **Description:** [What the vulnerability is]
- **Impact:** [What an attacker could do]
- **Evidence:**
  ```python
  # Vulnerable code
  cursor.execute(f"SELECT * FROM users WHERE id = {user_input}")
  ```
- **Remediation:**
  ```python
  # Fixed code
  cursor.execute("SELECT * FROM users WHERE id = %s", (user_input,))
  ```
- **Patch** (only emitted when `--patches` flag set):
  ```diff
  --- a/src/api.py
  +++ b/src/api.py
  @@ -40,3 +40,3 @@ def get_user(user_input: str):
  -    cursor.execute(f"SELECT * FROM users WHERE id = {user_input}")
  +    cursor.execute("SELECT * FROM users WHERE id = %s", (user_input,))
  ```
- **Effort:** [Low/Medium/High]

### HIGH — [Finding Title]
[Same format...]

### MEDIUM — [Finding Title]
[Same format...]

### LOW — [Finding Title]
[Same format...]

## Positive Observations
- [Good security practices found]

## Dependency Vulnerabilities
| Package | Version | CVE | Severity | Fix Version |
|---------|---------|-----|----------|-------------|
| lodash | 4.17.15 | CVE-2020-8203 | High | 4.17.21 |

## Secrets Found
| Type | Location | Status |
|------|----------|--------|
| AWS Key | config.py:12 | Active — rotate immediately |
| GitHub PAT | .env.example:3 | Example — verify not real |

## Recommendations (Priority Order)
1. **Immediate:** [Critical fixes]
2. **This Sprint:** [High-priority fixes]
3. **This Quarter:** [Medium-priority improvements]
4. **Ongoing:** [Security practices to adopt]

## Out of Scope
- [What was not reviewed and why]
```

## Severity Rating Calibration

| Rating | Exploitability | Impact | Example |
|--------|---------------|--------|---------|
| **Critical** | Easy, no auth needed | Full system compromise | SQL injection in login, RCE |
| **High** | Requires some access | Data breach, privilege escalation | IDOR, broken auth |
| **Medium** | Complex to exploit | Limited data exposure | XSS (stored), weak crypto |
| **Low** | Theoretical/unlikely | Minimal impact | Missing headers, info disclosure |
| **Info** | Not exploitable | No direct impact | Best practice suggestions |

## Threat Modeling (STRIDE)

When requested, apply STRIDE analysis:

| Threat | Question | Example |
|--------|----------|---------|
| **S**poofing | Can identity be faked? | Weak JWT validation |
| **T**ampering | Can data be modified? | Unsigned cookies |
| **R**epudiation | Can actions be denied? | Missing audit logs |
| **I**nformation Disclosure | Can data leak? | Verbose error messages |
| **D**enial of Service | Can service be disrupted? | No rate limiting |
| **E**levation of Privilege | Can permissions be escalated? | Missing auth checks |

## Output Schema

Audit reports follow the structure defined in `output.schema.yaml` with
calibrated severity rubric. See `examples/`:
- `golden-audit-report.md` — Express API with SQL injection, hardcoded secrets, and broken access control

## Constraints

- This is a code-level audit — infrastructure, network, and physical security are out of scope unless explicitly requested
- Findings are based on static analysis — some vulnerabilities require runtime testing to confirm (mark these `requires-runtime-test`)
- Always verify findings before reporting — false positives erode trust
- Provide remediation effort estimates to help prioritize fixes
- Flag if a finding requires a penetration test to fully validate
- Respect authorization scope — only audit code you're permitted to review
- **Never auto-apply patches.** Patch suggestions (Phase 4) are *drafts* for the user/PR-author to apply. Auto-applying SAST-driven changes is how working code becomes broken code at scale.
- **Suppress on confirmed false-positive.** If the same finding was triaged false-positive in the previous run, prefer to suppress on the next `--diff` run rather than re-triage — but only when the triage `confidence` was `high`. Re-evaluate `medium`/`low` confidence false-positives every run.

## Companion skills

- **`/security-sweep`** (planned): fleet-wide pass that invokes `/security-auditor` per repo, aggregates a `FLEET-SECURITY.md` index, surfaces new HIGH/CRITICAL across the portfolio. Use for periodic fleet hardening.
- **`/security-audit`** (deprecated 2026-05-10): superseded by this skill. The two unique blocks (file-permission scan, sensitive-file inventory) were ported into Phase 2 Reconnaissance. Delete `/security-audit` after the next install pass.

## Animus-forge integration (planned)

When invoked via `animus-forge` workflow (not directly by ARETE in a CC session), the skill runs with `--ollama --diff --patches` flags pre-set. Triage routes to qwen2.5:14b via HybridBackend ($0/run), findings persist to ChromaDB for cross-session memory, and new HIGH/CRITICAL findings emit Discord notifications via the existing `fleet-monitor` bot. See `~/projects/animus/packages/forge/workflows/security-sweep.yaml` (planned).