godaudits

Audit everything after anything. godaudits is an evidence-first codebase audit system that combines a 431-check Agent Skill with a zero-dependency runtime. It produces validated machine state, computed scores and coverage, a standalone remediation report, and optional SARIF annotations.

Version 2.12 adds attributed paired accuracy runs, append-only adjudication, and the first public OSS retrospective to the validated version 2 engine. The model still performs the work that requires judgment: tracing code paths, testing competing explanations, clustering root causes, calibrating impact, and prescribing a specific fix. The runtime performs work that should never depend on model mood: catalog compilation, repository fingerprinting, secret-safe signal collection, check completeness, score arithmetic, cross-reference validation, dependency cycle detection, rendering, re-audit diffs, and benchmark metrics.

What makes it different

• 18 domains and 431 versioned checks, each with inspection and failure guidance.
• Six project forms, secondary-form composition, all 37 arc-ready profiles, and conservative product, industry, and regulatory candidates.
• Pillars 1.1 structural validation and deterministic nested-scope routing with present, stub, excluded, absent, and unknown states.
• Arc-ready 1.1 table-ledger validation, artifact hashes, dependency-order drift, Git-history freshness with an explicit non-Git fallback, and launch prepublication checks bound to a content hash or Git revision.
• Explicit OWASP Web Top 10:2025 coverage without duplicate score weight.
• Every applicable check records pass, fail, unknown, or not-applicable. Uninspected never means pass.
• Every check is labeled screening or deep-trace. Medium-budget audits keep deep-trace checks in the ledger as unknown, so skipped work lowers coverage.
• Security and build completeness are deep-capable. The other domains are explicitly screening-grade and carry specialist escalation criteria.
• Quality score and audit coverage are separate. Low coverage caps the verdict.
• Evidence supports source, absence, tool, runtime, and human records.
• Source evidence carries a content hash. Secret evidence is masked and fingerprinted.
• Scores are computed from catalog weights and outcomes, with Critical, weak-domain, and coverage caps.
• Findings and remediation tasks are reciprocal and validator-enforced.
• Accepted risks require an owner, acceptance date, expiry, and review command.
• Re-audits preserve ids and produce structured added, resolved, reopened, changed, removed-id, score, and coverage deltas.
• MDX and SARIF are generated views. JSON is the source of truth.
• SARIF, Semgrep, ast-grep, Gitleaks, and OSV-Scanner results can be imported as versioned redacted evidence without promoting their conclusions into findings.
• An eight-repository fixture corpus, deterministic product evaluations, and live-harness cases test the auditor itself.
• JSON Schema 2020-12 validation tests real emitted evidence and rejects malformed nested project-context and Pillars contracts.

Quickstart

Install the Agent Skill:

npx skills add hannsxpeter/godaudits

Or clone and install it for detected tools:

git clone https://github.com/hannsxpeter/godaudits
cd godaudits
sh install.sh

The installer marks managed copies and refuses to replace or uninstall an unowned godaudits directory. Move a pre-existing custom directory aside explicitly before installation.

Then invoke it inside an existing project:

/godaudits

The runtime is bundled inside the skill. Agents use the installed godaudits command when available, or run runtime/godaudits.js beside SKILL.md with Node 22 or newer.

Outputs

All audit writes stay under .godaudits/:

Artifact	Role
EVIDENCE.json	Deterministic file inventory, hashes, signals, forms, overlays, arc artifacts, Pillars state, absences, and limitations
AUDIT.json	Canonical schema-versioned check, standards, evidence, finding, task, risk, freshness, and computed state
AUDIT.mdx	Generated standalone report and remediation handoff
AUDIT.sarif	Optional SARIF 2.1.0 output for code-host annotations
TOOL-EVIDENCE.json	Optional secret-safe evidence imported from SARIF, Semgrep, ast-grep, Gitleaks, or OSV-Scanner
archive/	Paired prior JSON and MDX versions for re-audit history

AUDIT.json is authoritative. MDX and SARIF are disposable derived views.

The audit workflow

flowchart TD
  A[Repository] --> B[Static evidence fingerprint]
  B --> C[Applicability and risk profile]
  C --> D[Complete 431-check ledger]
  D --> E[18 domain evaluators]
  E --> F[Independent refutation and clustering]
  F --> G[Validated audit JSON]
  G --> H[Computed scores and coverage]
  H --> I[MDX report]
  H --> J[SARIF output]
  I --> K[Agent-executable remediation]
  K --> L[Re-audit and structured delta]

Loading

The normal command sequence is:

godaudits doctor
godaudits evidence . --output .godaudits/EVIDENCE.json
godaudits pillars . --task "audit request routing" --target src/router.js
godaudits init --name my-project --scale funded-product --profile security-critical --applicable security,build,repo --budget medium --evidence .godaudits/EVIDENCE.json --output .godaudits/AUDIT.json
godaudits validate .godaudits/AUDIT.json --repo . --require-fresh-evidence --write
godaudits render .godaudits/AUDIT.json --output .godaudits/AUDIT.mdx
godaudits sarif .godaudits/AUDIT.json --output .godaudits/AUDIT.sarif

Focused medium-budget audits are the default. Request --applicable all --budget full only when the larger context and deep-trace work are explicitly warranted.

Import external scanner results as evidence leads, never automatic findings. The generalized importer requires the scanner command and a version when the report does not embed one:

godaudits import-sarif scanner.sarif --start 1000 --output .godaudits/TOOL-EVIDENCE.json
godaudits import-tool semgrep.json --tool semgrep --command "semgrep scan --json ." --start 1000 --output .godaudits/TOOL-EVIDENCE.json
godaudits import-tool ast-grep.json --tool ast-grep --tool-version VERSION --command "ast-grep scan --json=pretty" --start 2000 --output .godaudits/TOOL-EVIDENCE.json
godaudits import-tool gitleaks.json --tool gitleaks --tool-version VERSION --command "gitleaks dir --report-format json" --start 3000 --output .godaudits/TOOL-EVIDENCE.json
godaudits import-tool osv.json --tool osv-scanner --tool-version VERSION --command "osv-scanner scan --format json ." --start 4000 --output .godaudits/TOOL-EVIDENCE.json

The Agent Skill orchestrates these commands and performs the domain judgment between initialization and validation.

Capability modes

Static mode is the default:

• Reads repository source and git metadata.
• Writes only under .godaudits/.
• Does not run the application, tests, migrations, live systems, product network requests, or product model calls.

Two stronger evidence modes are available only with explicit authority:

• Sandbox: commands run in a disposable environment with outbound network disabled and no production credentials.
• Connected: explicitly authorized read-only evidence from CI, observability, database metadata, or trackers, with query and provenance recorded.

Static inference is never presented as runtime fact. Claims requiring stronger evidence stay Tentative or unknown.

Check catalog and scoring

The generated catalog at skills/godaudits/catalog/checks.json contains all checks, source modules, source lines, inspection guidance, failure guidance, scoring dimensions, routing behavior, cost tiers, depth labels, specialist escalation criteria, and default weights.

Risk profiles live in skills/godaudits/catalog/profiles.json:

• balanced: default general product risk.
• security-critical: identity, money, regulated data, privileged actions, and multi-tenant workloads.
• growth: public products dominated by activation, visibility, conversion, and launch execution.
• library: libraries and developer tools dominated by compatibility, API quality, maintainability, and repository discipline.

The chosen profile is recorded in the audit and cannot be switched to improve a score without changing the machine state and audit trail. Every profile's domain weights total 100 and are validated with the generated catalog.

Validation

godaudits validate rejects:

• Missing domains or checks, unknown ids, stale pack versions, or modified catalog weights.
• Pass, fail, and not-applicable outcomes without evidence.
• Failed checks without findings or open findings attached to passing checks.
• Missing, duplicate, malformed, or unredacted sensitive evidence.
• Certain Critical or High findings without two independent evidence paths.
• One-way finding-task links, missing Critical or High closure, dependency cycles, unsafe parallel file overlap, and incomplete final re-audit dependencies.
• Invalid, expired, or ownerless risk and open-question records.
• Unknown compliance results without an owned question, or injected compliance results without a finding and task.
• Hand-authored scores or counters that disagree with derived state.
• Stale repository evidence, incomplete OWASP category ledgers, or unsupported form and overlay metadata.

Coverage caps prevent a polished subset from masquerading as a full audit.

Evaluation and benchmarks

The built-in corpus covers Node API, Python worker, Go CLI, clean Rust library, web application, mobile or desktop, data or ML, and infrastructure or IaC fixtures. It tests deterministic evidence collection, compatibility archetype classification, all six project forms, absence evidence, clean controls, and secret redaction:

npm run benchmark
npm run eval:suites

When an expected-finding manifest exists, evaluate an actual audit:

godaudits evaluate .godaudits/AUDIT.json expected.json

Metrics include recall, precision, severity accuracy, citation validity, remediation closure, clean-control rate, misses, and false positives. The built-in corpus is a runtime regression net, not proof that an unseen model audit is accurate. Behavioral cases and the result template live under evals/; they are never reported as passed without retained harness evidence. The versioned standing result, including misses and false positives, is in ACCURACY.md. npm run accuracy:check validates one highest-weight target per domain and refuses unattributed or unpaired new runs. The first complete suite measured no skill lift: both arms saturated the small A-SEC-6 fixtures, while the installed-skill arm cost more. The first public OSS retrospective recorded one miss against CVE-2015-9235. These null and negative results are published because benchmark credibility depends on retaining misses, not only wins.

Re-audits

Re-audit mode preserves historical ids and compares compiled states:

godaudits diff .godaudits/archive/AUDIT-v1.json .godaudits/AUDIT.json

The delta reports added, resolved, reopened, changed, and improperly removed findings plus task, score, and coverage movement. It exits nonzero on project mismatch, invalid re-audit metadata, or removed finding and task history. Evidence hashes identify changed or moved source.

Portable prompts

• PROMPT.md is compact. It contains the orchestrator and core contracts. It is only suitable for focused audits when the requested domain modules are separately available.
• PROMPT.full.md contains all 18 modules and the report contract. Use it for a standalone full audit when the client context window permits it.

The compact prompt explicitly requires unavailable checks to remain unknown. It cannot silently claim a full audit.

Tool support

Tool	Skill path	Invoke
Claude Code	~/.claude/skills/godaudits	/godaudits
Codex, Cursor, Zed, Gemini CLI, OpenCode, Amp	~/.agents/skills/godaudits	tool-native or auto
Factory Droid	~/.factory/skills/godaudits	/godaudits
Cline	~/.cline/skills/godaudits	auto
Windsurf	~/.codeium/windsurf/skills/godaudits	@godaudits
VS Code or Copilot project install	.github/skills/godaudits	/godaudits
Aider or plain chat	PROMPT.full.md	attach or read

The runtime is inside the canonical skill directory, so skill-only installs do not lose validation or rendering support.

The godplans loop

godaudits mirrors godplans:

• godplans requirement R-SEC-3 demands ownership predicates.
• godaudits check A-SEC-3 evaluates them in built code.
• Plan-aware findings carry both ids.
• Remediation tasks preserve that traceability.
• The final task is always a compiled re-audit.

Either tool works alone. Together they close plan, build, audit, remediate, and verify into one id system.

Repository map

Path	Role
skills/godaudits/SKILL.md	Canonical orchestrator
skills/godaudits/references/	Core contracts and 18 domain modules
skills/godaudits/catalog/	Generated checks, risk profiles, project context, and standards mappings
skills/godaudits/schemas/	Audit, evidence, and benchmark schemas
skills/godaudits/runtime/	Self-contained zero-dependency engine
skills/godaudits/policies/	Versioned compliance policy packs
benchmarks/	Multi-language deterministic corpus
ACCURACY.md	Versioned model-run results, gaps, misses, and false positives
evals/	Live-harness behavioral cases and result contract
test/	Compiler, evidence, renderer, evaluator, init, diff, and SARIF tests
scripts/lint.sh	Repository, runtime, catalog, schema, benchmark, and prompt gates
scripts/validate-evidence-schema.py	Pinned JSON Schema 2020-12 evidence validation
docs/ENGINE.md	Runtime architecture and invariants
docs/EVALUATION.md	Benchmark and accuracy methodology
docs/RELEASE-POLICY.md	Stable release cadence and external OSS dogfood publication contract
dogfood/	Indexed versioned external OSS audit artifacts; an empty index makes no track-record claim
docs/MIGRATION-2.0.md	Version 1 to version 2 migration
docs/MIGRATION-2.1.md	Version 2.0 to version 2.1 migration
docs/THREAT-MODEL.md	Auditor safety and evidence threat model

Development

npm test
npm run benchmark
npm run accuracy:check
npm run eval:suites
npm run catalog
npm run build:prompt
npm run check
npm run release:check

Generated catalog and prompts have non-mutating freshness checks in CI. See CONTRIBUTING.md.

License

MIT