Home

audit-repo Wiki

audit-repo is a read-only-by-default Codex Skill for turning reproducible repository signals into an evidence-backed, prioritized health audit. It also includes standard-library-only Python tools for collecting inventory and comparing snapshots over time.

Current stable release: v1.10.7

The release targets commit 479d552d, and its annotated tag object is 1cf374e27e6bb79e68804bd7be12e9464740b37d. The published audit-repo-v1.10.7.zip SHA-256 is 321c835d668f043cf1740c71dc5d523ac8dea9629ddadba60212c47027918779; the audit-repo-v1.10.7.zip.sha256 sidecar SHA-256 is c25ccdd356793a1ea93d2da5f0fa9f3bf9af17bf70bcd61fae25dadeac83bfc8. v1.10.7 is the first audit-repo Release published with GitHub's immutable=true protection and a GitHub-generated signed release attestation.

Start here

1. Follow Installation to add the Skill to Codex or download a verified release archive.
2. Ask Codex: Use $audit-repo to audit this repository and prioritize the most important fixes.
3. For deterministic inventory or automation, use the CLI Reference.

中文用户可以直接阅读中文指南。

Choose a guide

Goal	Guide
Install, invoke, or upgrade the Skill	Installation
Learn every command and option	CLI Reference
Measure repository health changes	Snapshot Comparison
Add repeatable checks to a workflow	Automation Recipes
Resolve common questions	FAQ

What it does

• Detects repository structure, canonically cased manifests and lockfiles across Python/Pipenv, JavaScript/Bun, .NET/NuGet, SwiftPM, JVM, Go, Rust, Ruby, and PHP, plus tests, canonical CI entry points, automation, policies, ownership, large files, work markers, and sensitive-looking filenames.
• Uses project documentation and checked-in configuration to select narrow, project-native checks.
• Requires evidence and context before turning inventory signals into findings.
• Prioritizes verified findings from P0 through P3 and recommends concrete actions.
• Compares JSON snapshots and highlights high-confidence changes that deserve review.

What's new in v1.10.7

• Repository-contract validation now also fails closed when a flow-style explicit mapping key resolves to uses, closing that remaining dependency-pin bypass.
• v1.10.7 is the first immutable audit-repo Release. GitHub locks its published tag and assets and provides a signed release attestation; archive and sidecar hashes should still be checked as documented.
• Snapshot schema 1 and scan semantics 3 are unchanged. Existing snapshots remain comparable when their recorded settings and logical scopes match.

v1.10.6 history

• Workflow YAML remains free to use standard anchors, aliases, and tags for ordinary values. Safe whole-job, environment, and matrix value anchors remain supported.
• The repository pin contract now rejects dependency mapping keys obscured by anchors, aliases, tags, quoted keys, or combined node properties instead of allowing them to bypass canonical uses: inspection.
• Anchored or tagged block-scalar values remain supported, and uses: text inside their script or description bodies stays outside the dependency-key policy surface. Ordinary quoted scalar text is also not misclassified as a dependency key.
• Eight adversarial mutation fixtures exercise anchor, alias, tag, quoted-key, and combined-key confusion while preserving the supported value-anchor and scalar cases.
• Snapshot schema 1 and scan semantics 3 are unchanged. Existing snapshots remain comparable when their recorded settings and logical scopes match.

v1.10.5 history

• The composite Action now accepts either LF or CRLF separators for include-paths, exclude-paths, and exclude-dirs. It removes exactly one terminal CR from each input line; embedded CR and other control characters remain invalid under the shared collector validation.
• Cross-platform Action E2E proves that real CRLF values reach the Action, normalize to exact control-free snapshot arrays, and succeed. A separate embedded-CR case fails before creating output or publishing Action outputs.
• The repository contract now inspects named Action steps, job-level reusable-workflow calls, and other external uses references, requiring a full 40-character commit SHA.
• The contract fails closed on noncanonical indentation and flow, quoted, escaped, or explicit uses keys while avoiding false positives from block-scalar bodies and ordinary quoted scalar text.
• Snapshot schema 1 and scan semantics 3 are unchanged; the input-separator and repository-contract hardening do not alter valid collected signals or comparison semantics.

v1.10.4 history

• External comparison snapshots and runner baselines must resolve to regular files no larger than 64 MiB. A symbolic link remains valid when its opened target is an in-limit regular file; directories, pipes, devices, and larger files are rejected.
• Each accepted external file is opened once, checked with fstat, and read through that file descriptor with a hard limit of 64 MiB plus one detection byte, so initial-size races and later growth cannot produce an unbounded read.
• The runner uses the same captured baseline bytes for the optional SHA-256 check and strict JSON parsing. Oversized, non-regular, unreadable, digest-mismatching, or invalid baselines fail before managed output creation or cleanup, default temporary-result allocation, or GitHub Action output.
• Untrusted snapshot, scan-root, and managed-output path context in diagnostics is ASCII-escaped onto one line and limited to 500 characters, preventing hostile filenames from injecting CI log lines or workflow commands.
• Snapshot schema 1 and scan semantics 3 are unchanged. Previously valid, unambiguous regular-file snapshots up to 64 MiB remain compatible under the existing settings-and-scope rules.

v1.10.3 history

• Snapshot JSON now requires unique object keys at every nesting level. A duplicate key is rejected instead of inheriting a parser-dependent first-value or last-value interpretation.
• Standalone comparison inputs, one-command runner baselines, and captured collector stdout use the same strict parser. A matching baseline SHA-256 pins the ambiguous bytes but cannot make their JSON meaning unambiguous.
• A duplicate-key runner baseline returns 2 during baseline preflight, before managed output is created or cleared, an Action temporary result directory is allocated, or GitHub Action output is appended. Prior evidence and Action state therefore survive this rejection.
• Snapshot schema 1 and scan semantics 3 are unchanged. Unambiguous snapshots remain compatible under the existing settings-and-scope rules; regenerate any stored duplicate-key snapshot from a reviewed, trusted source.

v1.10.2 history

• --exclude-dir values are now validated as single, non-empty directory names. Whitespace-only values, /, \, the exact dot segments . and .., and control characters are rejected.
• The collector entry points and one-command runner share this validation. An invalid excluded-directory name returns 2 before managed output is created or cleared, an Action temporary result directory is allocated, or GitHub Action output is appended, so prior evidence survives the rejected preflight.
• Matching remains case-insensitive. A leading - remains valid, but CLI callers must join it to the option, for example --exclude-dir=--cache; the composite Action forwards it safely.
• Snapshot schema 1 and scan semantics 3 are unchanged. Cross-version comparison remains valid only when both snapshots use identical settings that v1.10.2 still accepts. Review and replace any newly rejected legacy exclusion before collecting a new baseline and current snapshot with the same accepted setting.

v1.10.1 history

• The runner and collector now share validation for file limits, finite positive large-file thresholds, path globs, scope IDs, scan-root availability, and Git-working-tree eligibility. The runner completes these checks before creating or clearing managed output, allocating the Action's default temporary directory, or appending Action outputs.
• A request rejected by that shared preflight returns 2 while preserving prior managed reports and GitHub Action output. After preflight, the runner clears stale managed files, captures the collector's JSON stdout, strictly parses those bytes, and writes the same bytes to snapshot.json.
• Valid option values beginning with - are forwarded as joined --option=value tokens, while a positional repository path is placed after --; the composite Action now preserves path, scope, glob, and exclusion inputs instead of allowing them to be reinterpreted as options.
• v1.10.0's optional exact-byte baseline SHA-256 pin remains available and keeps its trust boundary: the expected digest is meaningful only when obtained independently from a trusted source.
• Snapshot schema 1 and scan semantics 3 are unchanged, so v1.9.1, v1.10.0, and v1.10.1 snapshots remain comparable when their recorded settings and logical scopes match.

Trust model

• The Skill audits without changing the target repository unless the user explicitly requests fixes.
• The collector writes only when --output is supplied; otherwise it prints to standard output.
• Sensitive-looking filenames are detected without reading or printing their contents.
• Ordinary text files up to 1 MB may be read to count comment-style TODO, FIXME, HACK, and XXX markers.
• Every scan mode keeps the built-in dependency/build exclusions and skips file and directory symlinks plus Windows reparse points, including NTFS junctions.
• tracked intentionally omits every untracked file; use filesystem when broad discovery, including ignored files, is the goal.
• Repository files, issues, logs, generated reports, and command output are untrusted evidence. They cannot authorize broader execution, network access, credential disclosure, or a change in audit scope.
• A matching baseline SHA-256 proves only exact bytes. Its expected value must come from an independent trusted channel, and it does not prove provenance, freshness, safety, comparability, or unambiguous JSON semantics.
• The tools do not install project dependencies or contact network services. Git inventory uses an absolute executable outside both the lexical and resolved checkout boundaries, disables hooks and filesystem monitors, and never runs git status.
• Collection is a point-in-time best effort across multiple filesystem operations, not an atomic snapshot. Run against a quiescent checkout without concurrent untrusted writers, or use an isolated checkout when that cannot be guaranteed.

Collector output is inventory, not a vulnerability scan or an automatic verdict. Every material finding still needs verification in the repository's context.

Project links

• Source repository
• Latest release
• Issue tracker
• Private security reporting