code-audit-suite

Code Audit Suite

Purpose

One orchestrator that runs the entire local quality/security tool chain in a single pass and reports a unified verdict — the umbrella over all the individual skills. It runs them first-to-last, never aborts on the first finding, detects what is applicable, and prints one aggregated summary table that Claude reads directly (no dashboards).

The chain (in order): SonarQube → Trivy → Opengrep → secrets (Gitleaks + TruffleHog) → Bearer → MegaLinter → Architecture (dependency-cruiser) → Build-Verify (tsc/compile/build) → Kubescape → DAST (ZAP + Nuclei) → ScanCode.

The bar is functioning code, not cosmetics. "Clean" here means the code is correct, secure, well-licensed and actually compiles/builds — never the "looks nice but doesn't work" trap (a green quality gate on code that fails to build). The static scanners do not run the compiler; build-verify does, so a refactoring or generated change that breaks the build is caught, not shipped.

Core Workflow (drive everything to zero)

1. Run the full suite from / against the project directory:

   ~/.claude/skills/code-audit-suite/scripts/run-all.sh [TARGET_DIR]
   

   To include runtime/DAST, start the app and pass its URL:

   SUITE_URL=http://localhost:3000 ~/.claude/skills/code-audit-suite/scripts/run-all.sh [TARGET_DIR]
   

   Authorization: setting SUITE_URL runs OWASP ZAP + Nuclei, which actively probe a live application. Only set it for apps you own or are explicitly authorized to test (ZAP_FULL=1 escalates to an active attack; the default is a passive baseline).

2. Read the aggregated summary at the end. Each tool is PASS, ❌ FINDINGS, ⚠ ERROR (a Docker/pull/build/timeout failure — NOT a finding), or SKIPPED (reason). The overall exit code is 0 = CLEAN, 1 = FINDINGS, 2 = INCOMPLETE (a tool errored, or nothing ran). Treat INCOMPLETE as "fix the environment and re-run", not as a security result.
3. Triage and fix following the Fixing policy below — fix only what you own, disposition the rest. Group fixes by tool (upgrade deps for Trivy, rotate secrets, fix taint paths for Opengrep, …).
4. Re-run — the whole suite or just the affected single skill — until every tool is either PASS or its remaining items are dispositioned per the policy.

Fixing policy — read BEFORE changing anything (autonomous-safe)

When driving findings down — especially under a /goal that fixes autonomously — follow these rules so the suite cleans the codebase without causing damage:

1. Fix every finding in the source the repo maintains — no matter who wrote it or when. Code you copied, forked, pulled from GitHub, or that pre-dates your work is YOURS the moment it lives in the tree and you build on it → fix its findings too, pre-existing ones included. "Zero errors" means the whole maintained codebase, not just newly written lines.

   The ONLY exception is code an external mechanism regenerates or overwrites, where a hand-edit would not survive — there, fix upstream of the artifact:

   • Package-manager dependencies (node_modules/, .venv/, site-packages/, a vendor/ restored from a lockfile, git submodules): don't hand-edit — bump the version/pin in your manifest/lockfile (the next install reverts any edit anyway). A Trivy CVE here = a version bump.
   • Generated artifacts (dist/, build/, out/, *.pb.*, *_pb2.py, minified assets): fix the generator/source, not the artifact.
   • Quick test: would a routine git pull / submodule update, a package-manager (re)install, or the build REGENERATE this file from a source you don't control? If yes → fix upstream of it. If no → it's owned, fix it in place — including copied/adopted code that nothing restores. (Your own uncommitted edits to a tracked file do NOT count as "regenerated".)

2. Secrets in git history (Gitleaks/TruffleHog): rotate/revoke first (TruffleHog --results=verified shows if it is still live). A still-live secret is cleared ONLY by real rotation — .gitleaksignore silences Gitleaks, but TruffleHog re-verifies every run and keeps failing until the credential is actually revoked. Once rotated, you may allowlist the historical fingerprint. Do NOT rewrite git history (git filter-repo, force-push) autonomously — that is destructive and breaks shared history; only on explicit human request.

3. False positives — only with an objective reason, never to go green. A finding may be suppressed only when you can state why the tool is wrong in concrete, checkable terms — e.g. "the value is a compile-time constant", "this sink is unreachable", "the match is test-fixture data", "this license is allowed by our policy". "Looks fine" / "probably safe" is not a verification and is forbidden. Never delete or contort real code, and never mark something safe just to turn the verdict green. If you find yourself suppressing many findings from one tool, that is a signal you are green-washing — stop and re-examine.

   Suppression mechanism per tool (use the tool's own, with the reason inline):

   • Trivy .trivyignore (CVE/ID) · Opengrep # nosemgrep: <rule> · secrets .gitleaksignore (fingerprint, but see clause 2 re TruffleHog) · SonarQube hotspot → "safe" with a comment · Bearer bearer.yml (disable_rule) · dependency-cruiser encode the allowed edge as an explicit rule (or lower its severity) in .dependency-cruiser.cjs.
   • Kubescape, ZAP, Nuclei: these skills expose no suppression hook, so a verified false positive from them cannot be silenced through the skill — surface it to a human rather than bending the code.
   • ScanCode / MegaLinter: excluding a file or disabling a linter to hide a real finding is forbidden — exclusions are only for generated/vendored paths (see clause 1).
   • No clean suppression path? Then a genuine-but-unfixable false positive must stay as a finding and be surfaced to a human — do not bend the code.

4. Real issues: fix the root cause (upgrade the dependency, sanitize the input, add the missing header, correct the logic), then re-run the affected tool to confirm.

5. What "clean" means here: every issue in the maintained source is fixed — pre-existing and copied-in code included — and the project actually compiles/builds. A green quality scan on code that does not build is NOT clean; that is the "looks nice but doesn't work" failure (build-verify exists to catch it). Only items that are externally regenerated (fix upstream instead), historical secrets (rotated + allowlisted), or verified false positives are dispositioned — never silently dropped.

6. Never reach CLEAN by loosening configuration. The general rule: any change that reduces what a tool scans, or what it fails on, is a deviation that needs a human, finding-specific decision — never an autonomous shortcut to green. The env vars below are non-exhaustive examples of that rule, not the whole list:

   • Severity/scope gates: don't lower TRIVY_SEVERITY, KUBESCAPE_SEVERITY or BEARER_SEVERITY, and don't empty SCANCODE_DENY.
   • Which tools run: don't add SUITE_SKIP, or a narrow SUITE_ONLY, to drop a tool whose findings you don't want to face.
   • What a tool scans (just as effective at hiding findings): don't narrow the scanner set — TRIVY_SCANNERS (e.g. dropping license), MEGALINTER_DISABLE / MEGALINTER_DISABLE_LINTERS, a weaker OPENGREP_CONFIG pack, or SCANCODE_IGNORE over real (non-vendored) paths.

   If a finding is genuinely wrong, disposition it per clauses 1–5 (the tool's own suppression, with a checkable reason) — do not turn a configuration knob to make it vanish.

What runs, and what is skipped (no silent gaps)

Applicability is detected and logged, never silently dropped:

Tool	Runs when
sonarqube	the SonarQube server at localhost:9000 is UP
trivy, opengrep, secrets, bearer	always (source present)
megalinter	always (heavy image — skip with SUITE_SKIP if not wanted)
architecture	JS/TS sources or package.json are present
build-verify	always (auto-detects TS/Python/Go/Rust/PHP/Ruby/JVM/.NET, AND builds every Dockerfile by default; "nothing to verify" if none)
kubescape	Kubernetes manifests are detected
dast	SUITE_URL is provided
scancode	always (slow — license/copyright pass)

Tuning

• Skip heavy/irrelevant tools: SUITE_SKIP=megalinter,scancode,sonarqube run-all.sh
• Run only specific tools: SUITE_ONLY=trivy,secrets,opengrep run-all.sh
• Tool names: sonarqube trivy opengrep secrets bearer megalinter architecture buildverify kubescape dast scancode.
• Severity baselines differ per axis (by design): Trivy gates from LOW (any vulnerability fails — strict), while Bearer and Kubescape gate from high. Adjust per run with TRIVY_SEVERITY / BEARER_SEVERITY / KUBESCAPE_SEVERITY — but per Fixing-policy clause 6, never loosen them just to reach CLEAN.

Performance notes

• First runs pull/prepare per-tool data (Trivy DB, Nuclei templates, Kubescape frameworks, MegaLinter image ~18 GB, ScanCode under amd64 emulation). A full first pass is slow; subsequent runs are much faster (caches in Docker volumes).
• For a tight refactoring loop, prefer SUITE_ONLY=trivy,opengrep,secrets or run the relevant single skill, and reserve the full suite for milestone audits.
• build-verify Tier 2 (heavy): by default build-verify runs docker build on every Dockerfile found — the faithful release build, but a real image build per Dockerfile (pulls base images, runs every layer). For the fast loop set BUILD_VERIFY_NO_DOCKER=1 (skips it) or SUITE_SKIP=buildverify.
• Beyond Docker: the SonarQube stage builds JVM/.NET projects with host mvn/gradle/dotnet (only the generic/JS/TS/Python path is fully containerized) — so for those project types those tools must be installed. (build-verify, by contrast, compiles JVM/.NET inside Docker SDK images.) Install timeout/gtimeout (coreutils) for clean per-tool hang protection; without it the suite uses a bash-watchdog fallback that kills the tool's whole process tree (including the docker client, so the container is torn down) — coreutils is still preferred for its --kill-after escalation.

Relationship to the individual skills

This skill only orchestrates; it adds no new scanning logic. Some scanners overlap on purpose (e.g. Trivy's secret/license/misconfig scanners run alongside the dedicated secrets/ScanCode/Kubescape tools — a broad fast net plus deep verification); these overlaps are intentional and documented per-skill, not accidental duplication. Each tool's behavior, fix guidance and overlap rationale live in its own skill (trivy-security, opengrep-sast, secrets-scan, bearer-privacy, megalinter-quality, architecture-analysis, kubescape-k8s, dast-runtime, license-compliance, sonarqube-quality). Invoke those directly for focused work.

Resources

• scripts/run-all.sh — sequential orchestrator with applicability detection, per-tool sections, aggregated summary, and a verdict exit code (0 = CLEAN, 1 = FINDINGS, 2 = INCOMPLETE/nothing-ran). It validates the target dir and SUITE_ONLY/SUITE_SKIP names (a typo aborts rather than green-washes), prechecks the Docker daemon, distinguishes tool ERRORS from FINDINGS, wraps each tool in a timeout (via timeout/gtimeout if present, else a bash watchdog), and cleans scanner artifacts on exit. Env: SUITE_URL, SUITE_OPENAPI_SPEC, SUITE_SKIP, SUITE_ONLY, SUITE_TOOL_TIMEOUT (default 1800s).