Skip to content

Veridor

Veridor is a CI-first authorization regression runner. You declare what each identity is allowed to do; Veridor issues the same request as every declared identity, compares what happened against what you declared, and fails the build when the answer changes. It cannot tell you whether your declaration is right — only whether your target still agrees with it.

The runtime is the Python standard library only.

Status: early pre-release (alpha)

Nothing is released: no tag, no PyPI package, no container image, no chart. The source repository, github.com/Veridor-authz/veridor, is private. The plan is to publish the source, then a first tagged release. The configuration format, commands, flags and report formats may still change between commits.

Veridor is an independent personal project. It is not affiliated with or endorsed by any employer.

  • Install

    From a checkout, a wheel, a container image or a single-file zipapp you build yourself. Nothing is published yet. No runtime dependencies to audit.

    Install Veridor

  • Your first finding

    Sixty seconds from a checkout to a real confirmed finding against the demo target. The demo needs the source, which is not public yet.

    Quickstart

  • The three verbs

    map discovers, run gates, mutate checks the gate. Only run fails a build on a finding.

    Overview

  • Configuration

    Every key, the JSON Schema your editor can validate against, and cookie sessions with CSRF.

    Reference

  • Run it in CI

    GitHub Actions, GitLab CI, Jenkins, Azure, CodeBuild, Argo CD and Argo Rollouts; exit codes; SARIF, JUnit and GitLab reports.

    GitHub Action

  • What a finding means

    Coverage is asserted, never enforced. Read the bounds before you read a report.

    Claims and limits

The three verbs

Everything Veridor does is one of three questions, asked in this order.

Verb The question What you get
map What don't I cover, and what would a compromise reach? An access matrix, a blast radius per identity, boundary coverage, ranked anomaly candidates, and a diff against last week's matrix
run Does the boundary hold, and did it change? Findings, evidence grades, a baseline diff, SARIF, and the CI exit code
mutate Would my suite actually catch a regression? A mutation score and every mutant your checks failed to kill

Discover, declare, gate, then verify the gate. map proposes; you decide what to declare; run holds you to it; mutate tells you whether holding you to it means anything.

Only run gates on what it discovered. Nothing map finds moves its exit code — an inconsistency it noticed is a hypothesis, not a finding, and discovery must never fail somebody's build. map still exits 3 when its grid measured nothing, or, with --require-complete, when part of it went unmeasured. The one opt-in gate is not about a finding at all: --fail-on-drift fails when this run's matrix differs from a baseline you recorded earlier, which is a fact about two runs rather than a judgement about one. mutate has its own exit code that is never a run's; a surviving mutant says your declaration is weak, not that your target is broken.

init, coverage, new-marker, report, capsule and serve are utilities you reach for while using the three verbs, not headline commands. See the verbs overview.

Who it is for

  • You have a multi-tenant or role-separated API and a staging environment you are authorized to test. Veridor issues real requests with real credentials.
  • You already know which boundary you want held, or you are willing to write it down. The configuration is the policy; an unstated boundary is an untested one.
  • You want the check in CI, next to your tests, failing the build on a change rather than surfacing in a report somebody reads later.

If you have nothing written down yet, drift is the on-ramp: it records what your API does today and reports what moved, with no expectations declared. It is blind to anything that did not change.

Two identities is the floor that does not move. A single principal cannot express a boundary at all.

What Veridor is not

None of these are on a roadmap.

  • Not a scanner and not a pentest. It sends the requests you wrote, plus the controls below.
  • No API discovery. It never crawls, spiders, or guesses routes. The optional route inventory comes from an OpenAPI file you point it at.
  • No policy invention. Veridor has no independent notion of who should be allowed to see what.
  • No fuzzing and no payloads. One request per check per identity, with Accept-Encoding, Cache-Control and Pragma forced, plus each marker_probe and the liveness controls. No mutation, no injection, no traversal strings.
  • No injection classes. SQL injection, command injection, SSRF, XSS and path traversal are somebody else's tool.
  • No authentication-strength testing. It does not crack tokens, analyse JWTs, test session fixation, or evaluate password policy. It presents the credentials you give it. A 401 for an anonymous caller is an authentication result and is never counted as authorization coverage.
  • No audit of your declaration. A wrong declaration and a real vulnerability produce the same finding, and Veridor cannot tell them apart.
  • No proof of security. A passing run means nothing the gate fails on was found on this run; an expectation that held is evidence, not a guarantee.

What a finding means

A finding means exactly one thing:

Observed behaviour differed from the expectation you declared.

It does not mean the declaration was correct. The strongest evidence Veridor produces — a confirmed grade, where another identity's planted marker turned up in this response — is proof of data flow, never proof of policy. Triage a confirmed finding by checking your declaration first; it is the cheaper of the two hypotheses to eliminate.

Read claims and limits and verdicts and evidence grades before you read a report. Each of the three measurements has its own bound: boundary coverage says a denial is asserted, never that it is enforced; a mutation score says your check would catch a regression, never that the boundary holds; blast radius counts operations, not objects, and is a lower bound.

Getting started

Install Veridor, then see a real confirmed finding against the demo target in the Veridor source, which is private until it is published. To encode your own API's rules, read Write your access policy.