trustivan is the one binary you run outside a TRUSTIVAN deployment. It is a
pure HTTP client for the API — it holds no state, opens no ports, and does
nothing you could not do with curl.
It exists because the curl version is four requests with a polling loop
between them, and every pipeline that writes it writes one of the same three
bugs:
- it treats
202as “the scan finished” —202is work accepted, not work done; - it polls without a deadline, so a stuck scan holds the runner until the CI platform kills the job and reports it as an infrastructure failure;
- it reads the verdict’s HTTP status instead of its body, and so cannot tell “the build should stop” from “TRUSTIVAN is down”. Those demand opposite reactions.
Install
Download the release artefact for your platform:linux-amd64, linux-arm64, darwin-amd64 and
darwin-arm64, with a SHA256SUMS file beside them.
It also ships inside the backend image at /app/trustivan, which is the route
for a runner with no access to GitHub releases:
Environment
Nothing else is required. The key is read from the environment rather than a
flag deliberately: a secret on a command line is readable by every other
process on the runner.
trustivan scan
Queue a scan.
trustivan gate
Scan, wait, evaluate a policy, and exit accordingly. This is the command a
pipeline runs.
scan, plus:
A scan that failed is never evaluated. Running a policy against a scan that
produced no evidence answers “no findings above the threshold”, which is true
and the most dangerous possible answer.
Output:
! when it fired — it reached its threshold — not merely
because it matched something. A rule needing 5 that matched 2 did not fire, and
marking it would report a passing build as nearly failing.
Exit codes
1 and 2 are distinct deliberately. A pipeline that cannot tell them apart
either ships on an outage or blocks on one, and both are wrong. Treat 2 as an
infrastructure alert, not as a finding.