alibi

Cross-check the views of your attack surface and find the endpoints that cannot corroborate each other.

An endpoint should be able to account for itself. It is in the code, so a contract should describe it. It is in the contract, so something should implement it. It takes real traffic, so it had better exist somewhere. When one view knows about an endpoint and the others do not, that gap is the finding.

alibi runs OWASP noir, reads its JSON, and compares the views against each other.

Why this is a separate tool

Noir already reads five independent views of the same surface:

View	Read from
code	200-plus analyzers across 33 languages
doc	OpenAPI, RAML, WSDL, GraphQL SDL, AsyncAPI, gRPC, Smithy, TypeSpec, OData, OpenRPC
traffic	HAR, mitmproxy, Burp, Caido, ZAP, Postman, Insomnia, Bruno, .http
gateway	nginx, Apache, Envoy, Kong, Traefik, APISIX, Caddy, Istio, Kubernetes Ingress and Gateway API
infra	Terraform, CloudFormation, CDK, Serverless, Vercel, Netlify, Wrangler, Azure Functions, Kamal

What it does not do is compare them. That is the whole job here, and it needs no change to noir — alibi runs it once per view and joins the results.

The per-view part matters. Noir deduplicates by (method, url) across every analyzer, so a Flask route and an OpenAPI path spelled identically collapse into one endpoint carrying one technology. That is right for a discovery tool — it is one endpoint — but it erases the corroboration this tool is built to measure, and it erases it in the worst possible direction: the better two views agree, the more of them vanish. Casdoor scans as 372 code endpoints and 9 documented ones; scan its swagger/ directory alone and the specification has 235.

--only-techs restricts the detector pool, so one scan per view keeps each one whole. Which technology speaks for which view is views.yml; which technologies exist is whatever noir list techs reports.

alibi parses no API formats of its own. Its only input is noir's JSON.

Install

Requires noir 1.0.0 or newer on PATH -- that is the release where noir list techs became a subcommand, and that catalog is what assigns every technology to a view. Development tracks the current noir release. An older binary is refused by name rather than left to fail on its first catalog read.

$ uv tool install noir-alibi     # or: pipx install noir-alibi
$ alibi scan ./my-service

Use

$ alibi scan                                      # the working directory
$ alibi scan ./service ./contracts ./prod.har     # or wherever the views live

Every path is a source, scanned once per view. Point it at whatever you have — a source tree, a spec directory, a single capture file — and the views you are missing switch their rules off rather than flooding the report.

alibi  ·  1 source  ·  377 endpoints

  code 372   doc 235

  230 corroborated -- vouched for by more than one view

  19 endpoints nearly matched another view -- these may be matching failures, not real gaps

SHADOW  Shadow API -- Implemented, but no contract describes it
  134 findings  ·  4 critical, 57 high, 62 medium, 11 low

  critical POST    /api/upload-groups        router.go:87
           upload paths carry more consequence than reads
  critical POST    /api/upload-permissions   router.go:208
  ...
  ... and 122 more (SHADOW in full: -f json)

TWO SURFACES?
  The doc view is 97% under /api, and 37 of these findings are outside it.
  If that is a separate surface the contract never covered, narrow the scan:
    alibi scan <paths> --ignore '^/(?!api(/|$))'
  If it is the same surface left undocumented, they are the findings that matter most.

Groups stop at twelve — the ordering is worst-first, so the tail is the least informative part, and -f json has all of it.

Flags for noir go after a bare -- or through --noir-arg. Filters such as --exclude-path are fine; flags that would replace the JSON contract or collapse alibi's per-view scans (--format, --diff-*, --only-techs, …) are refused with exit status 2.

In CI

- run: alibi scan . ./contracts -f sarif > alibi.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: alibi.sarif }

Seeing what each view held

The report says the views disagree; --endpoints says what each of them contained.

$ alibi scan ./repo -f json --endpoints

Every view gets a list: the key, which views vouched for it, the technologies behind it, the files, and the spelling before normalization — which is where the difference always is when two rows should have matched and did not. It is three to four times the rest of the payload, so it is a flag rather than the default.

Or gate directly: alibi scan . ./contracts --fail-on high exits non-zero when a finding reaches that severity. A scan noir could not read in full reports executionSuccessful: false, so a degraded run does not pass as a clean one.

How endpoints are matched

Noir keeps each framework's own route syntax rather than inventing a common one, so the same endpoint arrives spelled several ways:

python_flask   /api/users/<int:user_id>
aiohttp        /users/{id}
java_spring    /api/catalog/{id}
oas3           /v1/pets/{petId}
rails          /posts/:id
nginx          /admin/.*

The rule that makes these comparable: a path parameter's name is not part of its identity. {petId} and <int:user_id> describe the same slot; only its position and whether it spans a / matter. Names are kept as evidence and reported, but never reach the key.

Findings say how the match was made:

Grade	Meaning
G1	the spellings already agreed
G2	they agree once parameter syntax is normalized
G0	only one view has it — nothing was matched

What keeps it honest

A tool like this dies by reporting hundreds of findings on its first run, or by reporting progress nobody made. Six things push back:

Rules do not fire without both views. Scan a codebase with no contracts anywhere and every endpoint technically qualifies as an undocumented shadow API. Those findings say nothing except that you did not supply any documentation, so a rule only runs when every view it reasons about was actually in the scan. The report names the rules that sat out.

Near misses are reported as doubt, not as findings. "In code, not in the docs" is indistinguishable from "in both, but alibi failed to line them up." So an endpoint that lands in one view is checked against the others for a near miss — same path with a different verb, or one segment apart where one side has a parameter and the other a literal. Findings carrying a near miss are demoted and flagged for review. That count sits next to the totals, because every finding is only as trustworthy as it is small.

Views that never met are one diagnostic, not hundreds of findings. Argo CD registers /api in Go and documents 198 paths beneath it, so its code and its specification share not one endpoint. Read literally that is 58 shadow APIs and 198 phantom contracts, none of them real. Zero corroboration between two populated views means the comparison did not work — a mount point standing in for the routes beneath it, or a stack noir could not read — so the rules are held back and the reason is printed instead. Paths that turn out to have many endpoints from other views beneath them are labelled as probable mounts.