trusty-audit

What it is

An auditor has been engaged to assess your codebase and how your team works in it. Rather than ship your source to them, they send you this: a client-side collector that runs on your machine, inside your network, against repositories you name. It installs the exact audit tooling the engagement pins, runs it, and writes one zip file. You look inside that file, then send it back.

Nothing here is a background service. It runs when you run it, writes everything under a single working directory, and stops. rm -rf on that directory removes everything it wrote.

Before you start

• A Mac with Apple Silicon. The installer refuses an Intel Mac and refuses a non-macOS host, rather than downloading a binary that cannot execute. There is no Windows or Linux build.
• The engagement.toml your auditor sent you. It pins the tool versions this engagement runs and carries its instructions. Put it in the directory you will run from, or point at it with --config <FILE>. Without it there is nothing to install and the run refuses.
• GitHub, through gh. Repository access uses your own GitHub login: run gh auth login first. Every repository read goes through gh, so whatever your credential can see is what the audit can see, and nothing more.
• Board tokens, if boards are in scope. JIRA needs a site URL, an account email, and an API token; Linear needs a personal API key. Both live in engagement.toml under [boards.jira] and [boards.linear]. Skip this if the engagement covers code only.
• Outbound access to github.com. Both the installer and the pinned tools download release assets from there. A proxy that blocks binary downloads fails in the first thirty seconds, naming the URL it could not reach.
• An instructions.md, if this engagement has a brief. Optional. A free-form markdown file sitting beside manifest.toml naming the focus areas and concerns this review has to address. trusty-audit render finds it there on its own — no flag, no manifest key — and records it verbatim in the report as its Analyst Instructions section. Leave it out and the run is unchanged; put one there that cannot be read and the run stops rather than quietly ignoring it. Guide and template.

1 · Install

One command. It detects your platform, resolves the latest release, downloads the tarball and its published SHA-256 sidecar, refuses to continue if the two disagree, checks the binary actually runs, installs it with an atomic rename, and then launches it.

curl -fsSL https://raw.githubusercontent.com/bobmatnyc/trusty-tools/main/crates/trusty-audit/install.sh | sh

It installs into ${CARGO_HOME:-$HOME/.cargo}/bin and never uses sudo. If that directory is not on your PATH, the installer says so and prints the line to add. Re-running the command upgrades in place.

Three environment variables change what it does: TRUSTY_AUDIT_VERSION pins an exact version instead of taking the latest, TRUSTY_AUDIT_INSTALL_DIR chooses a different destination, and TRUSTY_AUDIT_NO_LAUNCH=1 installs without starting the binary.

2 · First run

Whether the installer launched it for you or you type trusty-audit by itself, a bare invocation is a status check, not a sweep. It reports the working directory it will use, that no audit has run there yet, that none of the four pinned tools are installed, and reminds you to register what to audit. It asks for nothing and downloads nothing yet — that starts with the next two steps.

It does not need engagement.toml to show you this — only installing tools and running the audit do. Its reminder to register targets does not go away once you have registered some; check trusty-audit targets for the registry itself, not this status line.

3 · Register what to audit

Name each target once. Registration is additive, so you build the set up over several commands, and registering the same thing twice changes nothing.

trusty-audit add repo acme/api
trusty-audit add board jira:ACME
trusty-audit add board linear:ENG
trusty-audit targets

Each add reaches the target with the same credential the audit will use — your gh login for a repository, the configured board token for a board — and refuses one it cannot read. That is deliberate: a target recorded without ever being reached becomes a gap discovered an hour into an unattended run.

trusty-audit discover lists every repository your GitHub credential can see, marking private and archived ones, if you would rather look before you choose. trusty-audit remove <target> takes one back out.

4 · Run the audit

trusty-audit audit

This is the first command that needs your OpenRouter key — installing tools and registering targets never touch it. The audit renders its report through a language model, so before the sweep can start it resolves a key: an OPENROUTER_API_KEY already exported in your shell wins; otherwise a key already in engagement.toml — your auditor may have put theirs there — is used; otherwise trusty-audit asks at the terminal, with the typing hidden, and asks twice so a mistyped key is caught immediately. Either way the run prints which of the three it used. What you type at the prompt is written back into engagement.toml, readable only by your account, and is not asked for again. The key never reaches a log line, an error message, or the package you send back.

If there is no terminal to ask on — a script, a CI job — it refuses and names both ways to supply a key, rather than hanging or reading whatever happened to be on standard input.

One command chains four phases. It downloads and version-checks the four tools the engagement pins — tga, trusty-search, trusty-analyze and trusty-review — clones the repositories you registered, sweeps each one, and assembles the return package. Progress prints as it goes, phase by phase and repository by repository.

Expect it to take hours on a large set. You can interrupt it and run the same command again: installed tools, completed clones, and audited repositories are all carried over rather than redone, and each carried-over repository is printed as resumed so a fast re-run does not read as a run that did nothing. --fresh discards that record and audits everything again, which is the expensive direction and has to be asked for by name.

One repository failing does not stop the rest. The run continues, names every repository it did not cover, and exits non-zero — so a partial engagement can never be mistaken for a whole one, by you or by a shell command chained after it. A repository that produces nothing for four hours is stopped and recorded as a timeout, so a hang costs one repository instead of the whole run.

Everything lands under one directory — ./trusty-audit-work by default, or wherever --work-dir points. Clones go in repos/, the pinned binaries in tools/, tool output in logs/, and the deliverable in out/. Clones are shallow and stop starting new ones past 20 GB on disk, so an org-wide audit does not fill the machine.

What you send back

The last line of a finished run is the path to one file: audit-return-package.zip, inside the working directory unless --out named somewhere else. Send that file to your auditor by whatever channel you agreed. Nothing is uploaded for you.

It is unencrypted and has no password, on purpose: open it and read exactly what you are about to send. Inside are the report directory for each audited repository, the analysis database those reports were computed from, a README describing the contents, and a metadata file naming which repositories were covered and at which tool versions.

Two guarantees hold while the zip is written. The OpenRouter key is scanned for across every member, and a match refuses the whole package rather than quietly dropping one file. A symlink or a hardlink under the collected directories is refused for the same reason — either could pull a file from outside the working directory into an archive that leaves your network.

The analysis database holds no file contents, no diffs and no patches. It does hold free text — commit messages, pull-request and work-item titles, classification notes — so a snippet someone pasted into one of those is in the file.

When something refuses

Every refusal below leaves nothing installed and nothing half-written. The installer's messages name what failed, why, and what to do; these are the ones you are most likely to see.

• Unsupported operating system. You are not on macOS. There is no asset to download; run it on a Mac.
• Unsupported macOS architecture. An Intel Mac. No x86_64 macOS asset is published for any crate in this workspace, and handing you the arm64 one would give you a file that cannot execute.
• Checksum mismatch. The download does not match its published digest. Retry once; if it mismatches again, do not use the file — report it against the repository.
• Could not reach the releases API. Network or proxy. If you are rate limited, set GITHUB_TOKEN and re-run, or pin a version with TRUSTY_AUDIT_VERSION to skip the lookup.
• Install directory is not writable. The installer never uses sudo. Point TRUSTY_AUDIT_INSTALL_DIR at a directory you own.
• Installed, but not launched. There was no terminal to attach, so it printed the command to run yourself rather than starting something that could not prompt you for the key.
• A pinned tool will not install. Usually an egress proxy blocking binary downloads. The error names the URL. Allow the GitHub release-asset host, or ask your auditor for a package built for your network — all four tools install or none do, so there is never a half-pinned set.