Finds the security holes in your app and tells you, in plain English, what to fix first. It runs 11 free security scanners, checks whether a recent attack like the npm worm already got you, and reads your code for the mistakes scanners miss. Then it fixes the safe ones for you.
Drop the folder into your agent's skills directory — e.g. ~/.claude/skills/security-audit/ for Claude Code. Works with any agent that reads SKILL.md.
---
name: security-audit
description: "Find the security holes in your own repos and apps. Runs real scanners (gitleaks and trufflehog for leaked and still-live secrets across git history, semgrep and CodeQL for code vulnerabilities, osv-scanner and pip-audit for vulnerable or known-malicious dependencies, trivy and checkov for Docker/Terraform/k8s misconfig, zizmor for GitHub Actions supply-chain holes, nuclei and OWASP ZAP for a running app). It also checks whether a recent attack already got you: malicious packages anywhere in the last 90 days of lockfiles, and fingerprints that supply-chain worms leave in the repo, on the machine, and on GitHub. Then it reviews by hand what scanners miss (broken authorization, IDOR, auth flows, rate limits, webhooks) and checks that the security and privacy promises in your legal pages, marketing copy, and UI are true in code. Triages everything into one short report of confirmed findings. Use when the user says security audit, security review, security scan, find vulnerabilities, harden this app, scan my repos, check for leaked secrets or live keys, are my dependencies safe, was I hit by the npm worm / Shai-Hulud / a supply chain attack, check my GitHub Actions, scan my site, DAST, pentest my app, do we do what our privacy policy says, or names any of these tools or basics (password hashing, security headers, cookie flags, CORS, CSRF, rate limiting, CVEs)."
compatibility: "Needs bash, git, perl, and python3. Scanners install through Homebrew (macOS or Linux; the CodeQL cask is macOS only). Docker is optional and only adds the ZAP live scan. The gh CLI is optional (repo visibility, zizmor online checks). Works in any agent host that can run shell commands."
metadata:
version: 2.0.0
---
# Security audit
Scanners are cheap. Their output is not. On one small Rails app, the first test run of these scanners produced 319 raw findings, and most were duplicates, noise, or false positives. Scanners also miss the bugs behind most real app breaches, like user A reading user B's invoice by changing an ID. So the audit has three phases and one report:
1. **Scan**: run every scanner that fits the repo.
2. **Review**: read the code for what scanners can't see, using `references/checklist.md`.
3. **Promises**: check the product's security and privacy claims against the code, using `references/promises.md`.
Then **triage** all of it. Every finding you report has been read in context and is real. The bar is "would this be embarrassing if a journalist found it?", not a SOC 2 audit. Match the bar to the project: a 500-line side project doesn't need a CSP. A B2B app with customer data does.
## Who this is for
Assume the person running this has never heard of any of these tools and doesn't know what a CVE, a CSRF token, or a GitHub Action is. They want to know one thing: is my app safe, and if not, what do I do? So:
- **Make the technical calls yourself.** Pick the scanners, the languages, and the flags. Don't ask the user anything they'd need security knowledge to answer.
- **Ask only plain yes/no questions**, and only for things that touch their machine or their live site: "Can I install some free security tools?" and "Can I test your live site at https://example.com? It sends a few thousand harmless test requests."
- **Every tool here is free.** Never mention, suggest, or ask about paid tools, pro editions, or licenses.
- **Write the report for them**, not for a security engineer. See step 6.
Scripts live in `scripts/` next to this file. Call them by full path, since you will be working from inside the target repo.
## Rules
- **Only the user's own code and apps.** Live scans send attack traffic. Before any live scan, state the exact URL and get a yes. Never scan a host the user hasn't said they own.
- **Never run an active live scan (`--active`) against a real site.** It submits forms and writes junk data. Only use it on a localhost server you started.
- **Never print a secret value.** Name the detector, file, line, and commit. `summarize.py` never prints values, but `trufflehog.jsonl` holds them raw, so never cat it. When you open a file to judge a hit, describe the value ("looks like a real `sk_live_` key", "obvious placeholder"). Do not quote it.
- **Results stay out of the repo.** Write them to `~/.security-scans/<repo>/<YYYY-MM-DD>/`. The reports are a map to the secrets.
- **Functionality is sacred.** Every finding carries a `Breakage risk:` line. Prefer additive fixes (add a header, set a cookie flag) over ones that can lock users out (forced 2FA, tighter CORS, rotated sessions).
- **No pushes, no history rewrites, no key rotation.** You fix code and bump versions locally. The user rotates keys and decides on history rewrites.
## 0. Scope
- **Repo**: the path given, else the current repo. If `$ARGUMENTS` is a subpath, the review and promise phases cover only that path, but the scanners still run on the whole repo (secrets and lockfiles live at the root).
- **Several repos**: run the whole audit once per repo. With three or more repos, give each repo its own subagent if the host has them, have each return its triaged findings with evidence, and spot-check that evidence before you accept it.
- **Stack**: read the manifests (`package.json`, `Gemfile`, `pyproject.toml`/`requirements.txt`, `go.mod`, `Cargo.toml`, `composer.json`). The stack decides which review items matter and which CodeQL languages to run.
- **Live site**: only if the user gave a URL or asked you to test their site. If the repo has a dev server, you can start it and scan it on localhost without asking, since that touches nothing real.
- **CodeQL**: it's free only for open-source code. Read the repo's LICENSE. For MIT, Apache, BSD, GPL, AGPL, or MPL, turn it on. For anything else (FSL, BUSL, Elastic, "all rights reserved", no license), skip it without asking. Semgrep still checks the code. Pick the languages from the manifests: `javascript-typescript`, `python`, `ruby`, `go`, `java-kotlin`, `csharp`, `swift`, `c-cpp`.
Tell the user in one plain sentence what you're about to check, then go.
## 1. Setup
```bash
scripts/setup.sh [--codeql] [--live] # lists what's installed; exits 2 if something is missing
scripts/setup.sh --install [--codeql] [--live] # brew-installs the missing pieces
```
If something is missing or out of date (`setup.sh` exits 2), ask once in plain words: "To check your code I need to install or update a few free, open-source security tools with Homebrew. It takes a few minutes. OK?" Updating matters: several tools carry their detection rules inside the program, so an old version misses newer attacks. Don't list tool names unless they ask. If they say no, run what exists and list the rest under "Not checked".
If Homebrew itself is missing, it's a free installer for Mac and Linux. Its install command asks for the computer's password, so the user has to run it themselves. Give them the one line from https://brew.sh and tell them to paste it into Terminal, then come back.
## 2. Scan
```bash
OUT=~/.security-scans/<repo>/$(date +%F)
scripts/scan.sh <repo> "$OUT" [--codeql python,javascript-typescript]
scripts/live.sh <url> "$OUT" [--active] # only when a live URL is in scope
python3 scripts/summarize.py "$OUT" # add --allFolder contents · 9 files
Members get the full folder as a single ZIP download.
Members read the full skill.
Club members get the full text and download of every skill, plus each new one as it ships.