convez.ai
Skill
velimattiv

claude-security-audit

velimattiv/claude-security-audit

Ver no GitHub
BomPluginScore · de 0 a 100

A thorough, polyglot, multi-phase security audit skill for Claude Code. Discovers attack surfaces across 60+ frameworks, runs a SARIF scanner bundle, executes 9 parallel deep-dive categories, and produces an OWASP-methodology-tagged report.

Instalação

$npx convez-ai velimattiv/claude-security-audit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 semanas
Versão
v2.6.1
Issues abertas
5
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

/security-audit — Claude Code Skill

ci codeql license: MIT

A thorough, multi-phase security audit skill for Claude Code. Goes beyond generic vulnerability scanning by enumerating every attack surface (HTTP, gRPC, GraphQL, WebSocket, queue consumers, serverless handlers, mobile/desktop IPC — polyglot across 60+ frameworks), running an OWASP-methodology-tagged scanner bundle, and executing 11 parallel deep-dive categories (Auth/Authz, IDOR/BOLA, Token Scope, MITM, Crypto, Secrets, Deployment, Injection/SSRF, LLM-specific, Supply Chain & CI/CD, MCP/Agentic).

Supported runtime: Claude Code only. Other harnesses are not supported.

Version

  • v2.3.0 (current) — kept Semgrep (evaluated and declined Opengrep: its only free ruleset is archived/frozen at Dec-2024, and free-OSS invoke-only use of Semgrep is unrestricted); added an AUDIT_SAST_RULES offline / BYO-rules override. See CHANGELOG.
  • v2.2.0 — CyberGym-E2E-derived quality round: sub-agent repo-navigation discipline + explicit source→sink taint tracing, semantic-correctness scorecard check (--semantic-floor), patched-commit decoy method, and a CWE↔OWASP tag-pair validator. See CHANGELOG + docs/EPIC-v2.2-cybergym.md.
  • v2.1.0 — capability refresh: supply-chain (cat-10) + MCP/agentic (cat-11) deep-dives, methodology spine (OWASP Top 10:2025, CWE Top 25, Agentic 2026), unified configurable output dir (de-BMAD), grype EPSS/KEV, precision/recall scorecard. See CHANGELOG + docs/EPIC-v2.1-refresh.md.
  • v2.0.6 — DinD probe :ro,z SELinux fix in the Path B smoke test (probe was misclassifying SELinux confinement as DinD blockage, pushing every Fedora / RHEL / CentOS contributor to a misleading PASS-WITH-LIMITATIONS exit).
  • v2.0.5 — Phase 4 ↔ Path B wrapper integration. The skill now actually uses the container wrapper when host scanners aren't on PATH (or when $AUDIT_FORCE_PATH_B=1). Closes the gap that made Path B half-implemented in v2.0.2-2.0.4. Plus wrapper hardening ($AUDIT_CONTAINER_RUNTIME override, docker build --load, --build exits after build) and run-e2e-test.sh --path-b flag.
  • v2.0.4 — case-insensitive checksum match in install-scanners.sh (fixes silent hadolint install failure caused by the hadolint vendor publishing its .sha256 file body in lowercase while the asset URL uses capital-L Linux).
  • v2.0.3 — Path B Containerfile fix (PEP 668) + regression gate (tests/e2e/test-path-b-build.sh).
  • v2.0.2 — in-skill artifact mandate (no external --append-system-prompt); E2E PASS against juice-shop@v19.2.1 with 12/12 fixtures matched, 474 findings, 60 unique CWEs. See docs/test-runs/e2e-full-run-v2.0.2-2026-04-25T0250Z.md.
  • v2.0.0 — full polyglot audit, 9 deep-dive categories, 6 required + 6 conditional scanners, SARIF + SBOM + delta-mode baseline. See docs/V2-SCOPE.md for the design spec.
  • v2.1 candidates — listed in docs/ROADMAP.md.

What it does

  1. Discover — builds a Project Map: languages, frameworks, monorepo topology, ORM schemas, PII columns, LLM SDK usage, trust zones (Phase 0).
  2. Partition — splits the repo into audit partitions and risk-ranks them so deep-dive budget goes where it matters (Phase 1).
  3. Inventory the attack surface — not just HTTP routes: queues, schedulers, webhooks, file uploads, serverless, mobile/desktop IPC, admin/debug endpoints (Phase 2).
  4. Keystone index — the files whose change cascades invalidation (Phase 3).
  5. Run the scanner bundle in parallel — semgrep, osv-scanner, gitleaks, trufflehog, trivy, hadolint; optional brakeman, checkov, kube-linter, govulncheck, psalm, zizmor by detected context. All SARIF (Phase 4).
  6. Deep-dive 11 categories — each as a Claude Opus sub-agent, fanned out per partition × category, 8 in flight (Phase 5).
  7. Config audit + methodology spine — CORS/CSP/cookies/headers plus ASVS L2 / API Top 10 / LLM Top 10 / LINDDUN / STRIDE (Phase 6).
  8. Synthesize — dedupe, cross-reference, rank, tag with OWASP / CWE methodology IDs. Emit human Markdown report, SARIF 2.1.0, and CycloneDX SBOM (Phase 7).
  9. Baseline — persist for sub-minute delta-mode re-audits on PRs (Phase 8).

Typical run: 15–60 minutes (full mode) or 2–5 minutes (delta mode after baseline exists).

Install

User-level (available in every project), pinned to a tagged release:

git clone --depth 1 --branch v2.3.0 \
  https://github.com/velimattiv/claude-security-audit.git ~/Code/claude-security-audit
cp -R ~/Code/claude-security-audit/skills/security-audit ~/.claude/skills/security-audit
cat ~/.claude/skills/security-audit/VERSION   # → 2.3.0

Project-level (just this repo):

git clone --depth 1 --branch v2.3.0 \
  https://github.com/velimattiv/claude-security-audit.git /tmp/csa
mkdir -p .claude/skills
cp -R /tmp/csa/skills/security-audit .claude/skills/security-audit

For a step-by-step install (with backup of any existing security-audit skill, smoke-test, full-E2E validation, troubleshooting, and uninstall), see docs/INSTALL.md.

Scanner prerequisites

The skill brings six security tools (semgrep, osv-scanner, gitleaks, trufflehog, trivy, hadolint) plus their rule databases. The recommended deployment shape is to run the entire audit — Claude Code, the skill, the scanners, and the project clone — inside an isolated container. That keeps your daily-driver host clean and matches CI/production isolation.

Recommended — isolated container (everything inside)

Use any container shape that gives you a clean working environment with git, Node 20+, Python 3.10+, plus a way to run claude. Common patterns:

  • VS Code Dev Container / GitHub Codespaces — declare git/claude/python3 in .devcontainer/devcontainer.json, open the project, run the scanner installer + audit inside.
  • cw launcher / similar tmux-based container launchers — boot a fresh container per audit, install everything inside, throw the container away after.
  • Plain Docker / Podman — docker run --rm -it a base image, install dependencies, mount the project read-only.

Inside the isolated container:

# Clone the audit target inside the container
git clone <your-target-repo> /workspace/target

# Install Claude Code (https://docs.anthropic.com/claude-code/install)
# and authenticate in this container instance only
claude login

# Install the skill at user-level inside the container
git clone --depth 1 --branch v2.3.0 \
  https://github.com/velimattiv/claude-security-audit.git ~/Code/csa
cp -R ~/Code/csa/skills/security-audit ~/.claude/skills/security-audit

# Install the scanner bundle (Path A — direct install). This is the
# right install model for an isolated container: scanners are part
# of the container's purpose, host pollution is a non-concern.
bash ~/Code/csa/scripts/install-scanners.sh

# Run the audit
cd /workspace/target
claude --dangerously-skip-permissions
> /security-audit

When the audit's done, the entire container is disposable — including the auth, the scanner binaries, and any cached rule databases. Nothing leaks to your host.

Acceptable — Path B (scanners-only-in-container, Claude on host)

If you really want Claude running on your daily-driver host (e.g. you already have Claude Code installed and authenticated there, and the audit is one-off), Path B isolates only the scanner bundle:

scripts/run-audit-in-container.sh --build      # one-time
scripts/run-audit-in-container.sh preflight    # verify
scripts/run-audit-in-container.sh scan semgrep # per-scanner runs

The wrapper uses Podman (preferred, rootless) or Docker. Container hardening: --cap-drop=ALL, --security-opt=no-new-privileges, --read-only rootfs, non-root audit user. Target repo bind-mounted read-only; only .claude-audit/ is writable.

This still leaves Claude Code on your host. The skill orchestrator runs there and is the larger trust boundary.

Strongly discouraged — Path A on your daily-driver host

scripts/install-scanners.sh    # only if you really mean it

Six security tools on your laptop is invasive host state for a tool that may run once a week. The scanners auto-update their detection databases — that's continuous host churn from a security tool you installed to look at security. Use the isolated-container pattern above unless you genuinely have no option.

If you do go this route: don't half-install. A partial host install (some scanners present, some missing) is worse than no install — the audit report won't tell you which scanner-corroborated categories silently skipped. Run scripts/install-scanners.sh --check to verify all six landed; if any failed, fully fix the failure and re-run.

Supported hosts: macOS (Homebrew), Debian/Ubuntu (apt), Fedora (dnf), Arch (pacman). Windows is not supported — use WSL or the isolated container pattern.

What Path B does NOT isolate. The skill's orchestrator (workflow.md), deep-dive sub-agents (Phase 5), built-in-review sub-agents (Phase 4's /security-review, adversarial-review), and synthesis (Phase 7) all run in whatever runtime Claude Code uses. Treat Path B as "sandboxed scanners," not "sandboxed audit."

Required scanner bundle (six, all SARIF-emitting, free / open-source)

  • semgrep — polyglot SAST, community ruleset.
  • osv-scanner — SCA across all manifest ecosystems.
  • gitleaks — secrets in working tree + git history.
  • trufflehog — verified-secret sweep.
  • trivy — IaC + Dockerfile + vulns + SBOM.
  • hadolint — Dockerfile lint.

Conditional adds (installed on demand by context): brakeman (Rails), checkov (Terraform-heavy), kube-linter (Kubernetes), govulncheck (Go reachability), psalm (PHP taint), zizmor (GitHub Actions).

If any scanner is missing, the skill prints a degraded-mode warning and continues with whatever is installed. Never hard-fails for a missing scanner.

Use

In Claude Code, invoke with:

/security-audit                                   # full audit
/security-audit mode: delta                       # requires baseline
/security-audit scope: "services/api"             # narrow to a path
/security-audit categories: "crypto,mitm,secrets" # run only named deep-dives
/security-audit mode: report                      # re-emit from artifacts
/security-audit top_n: 12                         # override partition cap

Deliverables land in the output directory (default docs/security-audit-output/): the human security-audit-report.md, findings.sarif, findings.cyclonedx.json, and the pruned security-audit-baseline.json. On first run the skill asks where to write them (or pass output: <dir>); the choice is remembered for mode: delta / mode: report. See skills/security-audit/lib/output-routing.md.

CI integration

See docs/ci-examples/github-actions/security-audit.yml for a working example: runs on push / PR / nightly, uploads SARIF to the Security tab, and fails the PR on CRITICAL findings. Adaptations to GitLab / Buildkite / CircleCI are mechanically similar; PRs welcome.

Runtime state

The skill writes its working state under .claude-audit/ at the project root. Add .claude-audit/ to the project's .gitignore (the skill will offer to do this on first run). The baseline for delta mode is stored in two places: the pruned docs/security-audit-output/security-audit-baseline.json (checked in) and the full .claude-audit/baseline.json (gitignored).

Troubleshooting

See docs/TROUBLESHOOTING.md for common issues (scanner install, network-blocked vuln DB, semgrep auto-vs-explicit rulesets, delta-mode staleness, SARIF upload rejection).

Licensing & attribution

  • This skill: MIT (see LICENSE).
  • The adversarial review prompt under skills/security-audit/vendored/adversarial-review/ is vendored unmodified from bmad-method by BMad Code, LLC, under MIT.
  • skills/security-audit/lib/cwe-map.json reproduces CWE IDs and names from MITRE's Common Weakness Enumeration under CC BY 4.0.
  • skills/security-audit/lib/asvs-l2.md references OWASP ASVS 5.0 category topics (canonical text at https://github.com/OWASP/ASVS).
  • See NOTICE.md for full per-file attribution and scanner bundle license transparency.
  • CodeQL is excluded by default because its CLI is license-restricted to OSI-approved OSS repositories. Users on eligible repos can enable it manually; see NOTICE.md and the conditional-scanner docs.
Ver o original no GitHub

Bom para

Relacionados