verdis 0.1.1

Reports are claims. Verdis runs them.

Every verdict traceable to a run · every rule written down and tested · no model decides an outcome

Quickstart · How it works · The verdicts · The benchmark · Threat model

Triage starts with its most expensive question

Verdis is an open-source tool that reproduces a security report before a human reads it. It builds your project at the claimed version, runs the proof of concept in a rootless sandbox with no network, and returns a verdict together with a hashed evidence bundle. It ships as a Python CLI and a GitHub Action.

A maintainer who opens a report needs five answers before anything can be decided. The first, does this reproduce?, takes the longest, and every answer that comes before it is a guess. Verdis answers all five in one pass, starting with that one.

_{A real run. The report and target are in examples/demo.}

Start here

Install

pipx install verdis
verdis doctor

To try what is on main before it is released:

pipx install "verdis @ git+https://github.com/usualdork/verdis"

Or from a checkout:

git clone https://github.com/usualdork/verdis.git
cd verdis && pip install .
verdis doctor

doctor checks the sandbox backend, the images and the permissions.

Verdis needs Python 3.12+ and Podman or Docker. A proof of concept is attacker-controlled code, so when no container runtime is available Verdis stops instead of running it on the host. The host-process backend (--sandbox local) exists for development, is not a security boundary, and has to be requested by name.

Pull the sandbox image once. It is built for linux/amd64; on Apple Silicon, make sandbox builds it for your machine instead:

docker pull ghcr.io/usualdork/verdis/base:latest   # or: podman pull

Images are never pulled at run time: the bits that run are the ones you pinned. If your runtime is a VM or a remote daemon, point it at a directory it can mount:

export VERDIS_WORK_DIR=~/.cache/verdis

One triage

verdis triage report.md --repo ./libfoo --ref v2.3.1

Verdis verdict: REPRODUCED (Tier 1)   report VDS-0042   target libfoo@v2.3.1

Why: the sanitizer oracle fired and matched the claim; the claimed impact
     (memory corruption) was demonstrated
Evidence:
  1. run 1: AddressSanitizer reported a diagnostic
  2. run 1: sanitizer class heap-buffer-overflow
  3. run 1: frame #1 parse_header (src/hdr.c:212)
Policy:
- SECURITY.md Supported versions: version 2.3.1 matches supported pattern 2.x
Duplicates: none above threshold.
Suggested next action: confirm the severity and decide on a fix
Bundle: ~/.local/share/verdis/evidence/reports/VDS-0042/bundle  (run ./rerun.sh to reproduce)
Not established: exploitability beyond what the evidence shows; behaviour on
configurations other than the one tested.

The card states what was shown and what was not. A reproduction is evidence about one claim at one ref in one configuration; severity, exploitability and the reply to the reporter stay with you.

Useful flags: --compare <ref> checks whether a fix removes the behaviour, --output json|sarif feeds scripts and code scanning, --bundle-out <path> writes the evidence bundle where you want it, and --model-provider none|openai|anthropic|ollama selects the model, or none.

How it works

The seven verdicts

The rules run in a fixed order and the first one that applies decides. They are written in src/verdis/judge/rules.py and explained in the verdicts page.

What you get

The evidence bundle

Every verdict ships with a bundle: the report as it arrived, the claim, the plan, the policy matches, the build and run logs, the oracle results, the environment, the verdict in JSON and Markdown, a draft reply, and a script that reproduces the run on another machine.

bundle/
├── manifest.json          versions, hashes, the environment
├── original/report.md     the report as it arrived, unmodified
├── claim.json             what was understood, with source spans
├── plan.json · plan.txt   the plan, in full and in readable form
├── policy_matches.json    the clauses that matched, with citations
├── build.json · build.log
├── run.json · run.log     every run, with exit codes and timings
├── oracles.json           what each oracle saw, and whether it matched
├── fs_changes.json        files the run created or changed
├── blocked_network.json   outbound attempts the sandbox refused
├── environment.json       image digests, kernel, tool versions
├── verdict.json · verdict.md
├── draft_reply.md         a reply you can approve, edit or discard
└── rerun.sh               reproduces the run elsewhere

verdis bundle verify bundles/VDS-0042/   # re-hash every file against the manifest
cd bundles/VDS-0042 && ./rerun.sh        # run it again, next to the original

A bundle holds no secrets, because the orchestrator's tokens never enter a sandbox, and no exploit material beyond the reporter's own proof of concept.

What the benchmark shows

VerdisBench is a corpus of 673 cases from 25 independent target programs written in C, Python, Node and Go. Each case is a report, a target and a statement of what the verdict should be, and each program is checked in a real container before a case is written from it. The corpus includes 41 adversarial reports that try to steer the tool, 40 of them compared against a clean twin, and three upstream CVEs (libxml2 and libarchive) taken at the vulnerable commit with the proof of concept the fix brought.

Because the 539 negatives share 25 programs, the cases are not independent draws, and the upper 95% bound on the false-REPRODUCED rate is 12% when each program counts once. It is 0.71% if every case were independent. Both figures, with the reasoning, are in the benchmark reference. The corpus found nine real defects while it was being built, and each one is now a regression test.

make corpus && make corpus-check   # build the cases, prove each program behaves as claimed
make benchmark-sandbox             # run the whole corpus inside a container

Validate the repository

git clone https://github.com/usualdork/verdis.git
cd verdis
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e ".[dev]"
pytest

CI holds the core to 100% line coverage. The suite includes a sandbox conformance run that asserts the isolation is really there: no network, no writes outside the work directory, no privilege gain, and resource overruns stopped. It runs against a real container runtime in CI on every push.

The security model

Everything in a report is treated as hostile input, including the text a model reads and the commands a plan proposes.

No sandbox is perfect. Run Verdis on a dedicated, ephemeral runner that holds no other secrets, and start in shadow mode. The full model, including what is out of scope, is in the threat model.

Scope

Verdis is built for maintainers triaging reports about their own projects. It reproduces the report it is given. It does not find vulnerabilities, audit a codebase, or create, improve or weaponise a proof of concept, and it does not score or detect the authorship of reporters: it judges evidence, not people. A REPRODUCED verdict is evidence about one claim, at one ref, in one configuration, and it is not a statement about a project's security as a whole.

Status

The Reproducible Report Spec

A small YAML block a reporter can add to a report. Reports that carry one are triaged without a model and deduplicate reliably. verdis preflight checks a proof of concept in a clean environment and writes the block for you.

rrs: 0.1
target:
  repo: https://github.com/example/libfoo
  ref: v2.3.1
claim:
  class: CWE-122
  component: src/hdr.c:parse_header
  impact: memory corruption leading to crash
steps:
  - build: default
  - run: ./build/parse_demo poc.bin
inputs:
  - path: poc.bin
    sha256: <hash>
expect:
  oracle: sanitizer
  signature: heap-buffer-overflow in parse_header
config:
  default: true

The specification is in the concepts page.

The GitHub Action

- uses: usualdork/verdis@v1
  with:
    mode: shadow
    sandbox: default
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

It runs as a composite action, so the proof of concept runs in the runner's own container runtime. It asks for the minimum permissions and passes the token only to the step that posts a comment or applies a label, after the verdict exists. Run it in shadow mode for a month before you let it comment.

Documentation

Project leadership

Contributing

Read CONTRIBUTING.md, the Code of Conduct and the security policy before opening an issue.

Issues, corrections, recipes, oracles and adapters are welcome. Verdis gets better when people who maintain software tell us what their reports look like, and the benchmark gets better when they send the cases that break it.

Use synthetic, consented, anonymised or non-sensitive public examples. Do not submit personal data, live-case material, victim information, target lists, credentials or harmful operational detail.

License

Copyright © 2026 the Verdis contributors.

Licensed under the Apache License 2.0. Contributions are accepted under the same licence.