valvur

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.

[valvur scans a project whose lockfile pins a package published as malicious, and lists the findings]

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 valvurvalvur scan                 # offline by default; --profile full adds the registries' answersvalvur 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

Air-gapped? The database, the Name Index and its malicious list, KEV, EPSS and OSV's databases all live outside the image, and each has a mirror setting. See docs/AIR-GAPPED.md.

Privacy

valvur collects nothing: no account, no API key, no telemetry, and no part of it reports on you or your code. The results stay in .security-scan/, which ignores itself in git. What the host fetches is public data, each fetch recorded in run.json. python3 scripts/verify-offline.py checks it, and on Linux unshare -rn valvur scan proves it (how).

Documentation

Community and support

• Questions and ideas: Discussions.
• Bugs, and findings valvur missed: https://github.com/MaverickHQ/valvur/issues, with the tarball valvur doctor --bundle writes: versions and the last run.json, never your source, raw output or findings.
• Security: a suspected vulnerability in valvur, a false clean included, goes privately by SECURITY.md.
• Contributing: CONTRIBUTING.md has the setup and the short list of what is refused on principle. MAINTAINERS.md says who maintains valvur, one person today, and what you can rely on. There is no paid tier and no support contract.

Licence

Apache-2.0, see LICENSE; chosen over MIT for the explicit patent grant. Bundled Scanners keep their own licences, listed above and in NOTICE. valvur adds no GPL or AGPL component; the Alpine base carries GPL userland as every Linux container does, and the published SBOM discloses all of it (ADR-0005).