valvur

Offline security scanning for AI-generated code.

Seven open-source scanners and AI-specific checks, in one command and one ranked report.

Scorecard's Code-Review, Branch-Protection and Contributors checks need a second maintainer; valvur has one (MAINTAINERS.md).

Status: `1.6.1`, the version this tree declares; the PyPI badge above shows what pip install valvur serves, and the CHANGELOG what each version changed.

In Claude Code: /plugin marketplace add MaverickHQ/valvur, then /plugin install valvur@valvur, and ask it to scan the project.

From a terminal, with Docker or Podman running: uvx valvur scan.

Why valvur

• Seven scanners, one report. Gitleaks, Trivy, OSV-Scanner, Opengrep, Checkov, zizmor and Syft, pinned, installed and run for you in one container, beside valvur's own checks for AI-written code. A vulnerability two of them report is one finding, not two, and everything is ranked together.
• Nothing leaves your machine, provably. No account, no API key, no telemetry. The Scanners run in one container with no network interface, and your source is copied in, never mounted. Every fetch of public data is recorded in run.json, beside what left the machine: nothing. One command checks it.
• Built for how AI-generated code breaks. Models invent package names that attackers then register; agent instruction files carry injected directives and hidden Unicode; agent settings leak tokens. valvur checks for each, offline, beside the classic secrets, vulnerable dependencies and misconfigurations.
• Ten findings that matter, not four hundred. Findings are ranked by whether attackers are exploiting them, from CISA KEV and FIRST EPSS rather than CVSS alone, grouped by rule and directory, with development-only dependencies demoted.
• You stay in charge. valvur proposes fixes and never applies them. An agent told to reach zero findings can delete code or write suppressions instead, and *the finding disappeared* is not *the vulnerability is fixed*.

What it finds

What it checks, rule by rule, and what it cannot see: how valvur works.

How it works

1. A small host shim decides what a scan reads (the files git would publish, plus .env* files and agent configuration), fetches the public data it needs, and records each fetch.
2. One Scan Container, with no network interface, runs every Scanner over a copy of those files fed on stdin. Nothing in it can change your source.
3. One findings model normalises and ranks what they report, and the shim writes the Results Folder into your project:

.security-scan/          ← ignores itself in git, so it is never committed

├── SUMMARY.md ← start here: the verdict, anything that failed, the top groups ├── REMEDIATION.md ← a ranked proposal: you choose what to apply ├── findings.json ← every finding, normalised, secrets redacted ├── results.sarif ← SARIF 2.1.0, for code scanning and IDEs └── run.json ← what ran, what was fetched, and what left the machine: nothing

A scan ends findings, clean or inconclusive. It never says clean when stale data, an uninspected ecosystem or a Scanner that did not finish cannot support it, and it says why.

Measured, not claimed

How much of what valvur claims it finds is measured as the Score: nine tracks scored by the OWASP Benchmark's formula, with a ratchet that no change may fall more than two points under. It is 74.1 out of 100, the same on Linux and on macOS.

Track 8 is precision on maintained code, where almost nothing is a vulnerability: 3 of its 171 findings are real. Track 9 measures the rules for model output reaching a sink: they catch 30 of 34 generated flows with no false alarm, and none of five published advisories in LangChain, LlamaIndex and Vanna, whose flows each cross a function. Each rule's precision is in docs/RULES.md, and the method, the gates and what valvur does not claim are in docs/EVALUATING.md. Read that one sceptically.

Use it

In an AI coding agent

The Claude Code plugin brings the MCP server, a skill that runs the workflow, and a hook that asks you before the agent installs a package valvur flags. Kiro takes it as a power. Any MCP client runs the server with uvx --from valvur valvur-mcp. The agents' guide has the configuration for eleven clients, the seven tools, and the permissions a *don't ask* mode needs.

From the command line

The Scanners run in a container, so the machine needs Docker or Podman; valvur doctor says what is missing.

pip install valvur          # or: uv tool install valvur

valvur scan # offline by default; --profile full adds the registries' answers valvur check npm left-pad # before an install: real, a near-miss, or malicious? valvur gate . --fail-on high --no-inconclusive

The command-line guide has every command, what a first scan fetches, the Results Folder, and the settings files.

In CI

- uses: MaverickHQ/valvur-action@16b19e275f843419887873ed536a71f872607e24 # v0.2

with: { fail-on: high, no-inconclusive: "true" }

The action scans, uploads results.sarif to code scanning and gates the job. The CI guide covers the gate, the image as a step of its own, and GitLab.

Built on open-source scanners

valvur builds no detection engine. Seven open-source Scanners do that and deserve the credit; valvur adds one File Set, one findings model, exploit-aware ranking, and three Checks of its own. All of them run in one container, fed a copy of the files. run.json records the version of each that ran, and raw/ keeps what each said.

Exploit intelligence comes from CISA KEV and FIRST EPSS: public primary sources, auditable and mirrorable. No proprietary database, and nothing to lock you in.

What it does not do

• No reachability analysis. We do not prove a vulnerable function is called.
• No autonomous fixing. You choose the fixes.
• No penetration testing. No DAST, no exploitation, no scanning of deployed systems.
• No code-quality analysis. Security only.
• We will not out-detect commercial SAST. We win on trust, breadth in one artifact, and prioritisation, not on engine depth.

Platforms

| macOS, Docker Desktop or Podman | Supported, and tested by hand on