torb audit

audit asks the registries about what a project already pins. torb yank and torb deprecate tell a project about a release only when it resolves again; a lock that pins a yanked version keeps installing it. audit is the check that reads the lock as it stands, so a build can fail on a yanked pin before anyone runs torb update.

Synopsis#

torb audit                   Report the locked versions the registry yanked and the packages it deprecated
  --project <directory>      The project whose lock to audit, instead of the one around the working directory
  --advisories <directory>   Also report the advisories of this directory that cover a pinned version
  --offline                  Ask no network: only the indexes the cache already holds

What it does#

1. It reads project.lock.trb of the workspace root and takes every package of the graph that is not a path: package - the direct dependencies and the ones only another package needs. A path: package has no registry and is skipped.

2. It fetches the index of each, from the registry the lock names (the one the project binds the owner to, where the lock names none), through the mirrors and the cache of config.trb, and checks it against the keys of the registry exactly as torb add does.

3. It prints what the index says against the pinned version, ordered by package:

   • a yanked version - acme/http 1.2.4 is yanked: sends a password, with the reason of the yank;
   • a deprecated package - acme/json is deprecated: it moved, and a line use acme/json-next instead where the notice names a package. The notice counts whatever version is pinned, since it is about the package.

4. With --advisories <directory>, it reads the advisories of each of those packages from <directory>/<owner>/<name>/ and prints every one whose affected versions include the pinned version, after what the index says of that package and ordered by advisory id:

   • an advisory - acme/http 1.2.4 is affected by TORB-2026-0001 (high): sends the proxy password in clear text.

It ends with one line: no findings in 3 registry packages, or 2 findings in 3 registry packages, the advisories counted with the rest.

$ torb audit
acme/http 1.2.4 is yanked: sends a password
acme/json is deprecated: it moved
  use acme/json-next instead
2 findings in 3 registry packages

audit writes nothing: not the lock, not the project, not the archives of the cache.

The advisory files#

A directory of advisories holds one file for each, at <directory>/<owner>/<name>/<id>.trb, where <id> is TORB-<year>-<number>: the year has four digits and the number four or more. It is the layout of a clone of the public advisory repository. The file is a list of lines in TorbScript, read without running anything:

advisory "TORB-2026-0001"
package "acme/http"
summary "sends the proxy password in clear text"
severity "high"
affected ">=1.0.0 <1.2.5", ">=2.0.0 <2.1.1"
published 1760000000
aliases "CVE-2026-12345"
references "https://example.test/advisory"

A line may be written once. A file with any other word, a missing required line, a package or advisory line that does not match its path, an unknown severity, a range that is none, or a directory entry that is not an <id>.trb file is refused, and so is the whole audit: a typo must not turn into "no findings". Only the directories of the packages the lock pins are opened. There is no signature to check; the directory is as trustworthy as the repository it was cloned from.

Exit codes#

1 and 2 differ so that a gate can tell a project with a yanked pin from a project that could not be checked. An advisory directory that cannot be read is a 2 and never a clean lock.

Pitfalls#

A fetched index is as new as the last fetch. With --offline, or where a mirror has an older copy, audit reads what the cache or the mirror holds; a yank after that is not in it. Run torb audit without --offline where the answer has to be current.

A finding stays until the pin or the registry changes. audit remembers nothing of an earlier run: a yanked pin is a finding on every run until torb update moves the pin or torb yank --undo takes the yank back.

A deprecation is no withdrawal. The package keeps installing and a finding of it does not mean the version is bad, only that its owner points elsewhere. The exit code 1 is the same for both, so a gate that wants to ignore deprecations reads the lines.

Examples#

Fail a continuous integration job where the lock pins a yanked version:

$ torb audit
acme/http 1.2.4 is yanked: sends a password
1 finding in 3 registry packages
$ echo $?
1

Check the lock against a clone of an advisory repository:

$ torb audit --advisories ../advisories
acme/http 1.2.4 is affected by TORB-2026-0001 (high): sends the proxy password in clear text
1 finding in 3 registry packages
$ echo $?
1

A file that does not read stops the audit, and the message names it:

$ torb audit --advisories ../advisories
error: ../advisories/acme/http/TORB-2026-0002.trb: `severe` is not a severity: low, moderate, high or critical
$ echo $?
2

A lock with only path: packages has nothing to ask a registry:

$ torb audit
no findings in 0 registry packages

Related#

• torb yank - withdraws a version, and what audit reports for a lock that pins it.
• torb deprecate - flags a package, the other finding of audit.
• torb update - moves a pin off a yanked version.
• torb install - the other command that only reads the lock.
• project.lock.trb - the file audit reads.
• config.trb - the mirrors an index may come from.