zairo

Git-diff-aware security scanning. zairo scans what actually changed in a commit or PR, not the whole codebase — so LLM-based vulnerability scanning stays fast and cheap enough to run on every diff.

Why

Pointing an LLM at an entire repository on every commit doesn't scale: it's slow, expensive, and buries the two lines that actually changed under thousands that didn't. zairo instead:

1. Diffs the repo to find exactly which lines changed.
2. Builds a small dependency graph around those lines — the changed functions plus their direct callers/callees — using Trailmark (supports Python, TypeScript/JavaScript, Java, Go, Rust, C/C++, C#, Ruby, PHP, Swift, Kotlin, and more, auto-detected).
3. Scans each changed function/method individually: the model sees that code plus real caller/callee snippets — and, when the change is at the whole-file level rather than inside one function, an outline of the file's other definitions too. All of it pulled from the subgraph only; nothing outside it is ever sent.
4. Writes the result as a browsable report, and optionally as SARIF for your existing security tooling.

Contents

• Why
• Install
• Quickstart
• zairo analyze — scan a single repo
• zairo fleet — scan multiple repos at once
• Output files
• CI / PR gating
• Caching
• Development

Install

pip install zairo

Requires Python 3.12+ (a core dependency, Trailmark, requires it). LLM scanning (--llm) goes through LiteLLM, so you'll also need an API key for whatever --model you use — set via the environment variable your provider expects (e.g. GEMINI_API_KEY for the default gemini/gemini-2.5-pro, ANTHROPIC_API_KEY for Claude models, OPENAI_API_KEY for GPT models). See LiteLLM's provider docs for the full list.

Quickstart

# Analyze uncommitted changes in a repo
zairo analyze /path/to/repo

# Diff two refs, and run an LLM scan on what changed
zairo analyze /path/to/repo --base main --target HEAD --llm

No repo handy? Generate a few small ones with known, distinct vulnerabilities to try it on:

python examples/generate_sample_repos.py
zairo analyze examples/sample-repos/cmd-injection-app --base HEAD~1 --target HEAD --llm

This creates examples/sample-repos/{cmd-injection-app,sql-injection-app,path-traversal-app} — each a 2-commit repo with one commit introducing a specific, LLM-findable vulnerability. (Not committed to this repo: a usable git history can't live nested inside another repo's .git, so the generator creates them locally on demand.)

zairo analyze

Scans a single repo. repo_path is the only required argument.

What to diff:

LLM scanning:

Output & gating:

Run zairo analyze --help for this same list from the CLI.

zairo fleet

For a security team that owns many repos, not just one: scans several repos with the same settings and rolls the results up into one fleet.json/fleet.html/fleet.sarif, alongside each repo's own reports under <output>/<repo-slug>/.

# From positional paths
zairo fleet /path/to/repo-a /path/to/repo-b --base main --target HEAD --llm

# Or from a file, one repo path per line ('#' comments allowed)
zairo fleet --repos-file repos.txt --base main --target HEAD --llm --fail-on high

It accepts almost all the same options as analyze (see the tables above — --depth, --language, --llm, --model, --concurrency, --cache, --max-tokens, --tokens, --fail-on, --verbose), applied identically to every repo. That means --base/--target need to mean the same thing across all of them — this fits best when your repos share a diffing convention (e.g. all diffing against main). Repos with different conventions need separate fleet invocations.

--tokens reports one combined total across every repo scanned, not a per-repo breakdown.

A few things unique to fleet:

Note --concurrency (shared with analyze) and --repo-concurrency control different things: --concurrency is LLM requests in parallel within one repo's scan; --repo-concurrency is how many repos run at once. Combined, total in-flight LLM requests can reach their product — mind your provider's rate limits.

Run zairo fleet --help for the full list.

Output files

fleet produces the same three files per repo, plus fleet.json / fleet.html / fleet.sarif (a rollup: per-repo status and severity counts, a dashboard table linking into each repo's reports, and every repo's SARIF results merged into one multi-run log).

CI / PR gating

--fail-on <low|medium|high|critical> (on both analyze and fleet) exits non-zero if any finding at or above that severity is found, so a CI step can block a merge on it. It requires --llm, and doesn't suppress the SARIF output — it's still written even on a failed gate, so a scanning UI reflects the current state either way.

zairo analyze . --base "$BASE_REF" --target HEAD --llm --fail-on high -o zairo_out

See examples/github-actions/zairo-pr-scan.yml for a full PR-scan workflow: it runs zairo on the PR diff, uploads report.sarif to GitHub's code scanning, and fails the job if the gate fails.

Caching

LLM findings are cached by a hash of the exact prompt content (the code sent, plus its neighbor context) — not by commit or file path. So re-running zairo after an unrelated change elsewhere in the repo, or after reverting a change back to something previously scanned, skips the LLM call entirely for anything unchanged. The cache lives at <output>/.llm_cache.json; delete it (or pass --no-cache) to force a fresh scan.

Development

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest

The package uses a src/ layout (src/zairo/), so pip install -e . is required for import zairo to resolve correctly during development — the package isn't importable by just being on PYTHONPATH from the repo root.

License

MIT — see LICENSE.