Verifica in modo incrociato le viste della tua superficie di attacco e individua gli endpoint che non possono corroborarsi a vicenda.
Verifica in modo incrociato le viste della tua superficie di attacco e individua gli endpoint che non riescono a corroborarsi a vicenda.
Un endpoint dovrebbe essere in grado di rendere conto di sé stesso. È nel codice, quindi un contratto dovrebbe descriverlo. È nel contratto, quindi qualcosa dovrebbe implementarlo. Riceve traffico reale, quindi farebbe meglio a esistere da qualche parte. Quando una vista conosce un endpoint e le altre no, quel divario è il risultato.
alibi esegue OWASP noir, legge il suo JSON e confronta le viste tra loro.
Noir legge già cinque viste indipendenti della stessa superficie:
| Vista | Letta da |
|---|---|
| code | oltre 200 analizzatori su 33 linguaggi |
| 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 e Gateway API |
| infra | Terraform, CloudFormation, CDK, Serverless, Vercel, Netlify, Wrangler, Azure Functions, Kamal |
Ciò che non fa è confrontarle. Questo è l'intero compito qui, e non richiede alcuna modifica a noir — alibi lo esegue una volta per vista e unisce i risultati.
La parte per-vista è importante. Noir deduplica per (method, url) su ogni analizzatore, quindi una route Flask e un path OpenAPI scritti in modo identico collassano in un unico endpoint che porta una sola tecnologia. Questo è corretto per uno strumento di discovery — è un solo endpoint — ma cancella la corroborazione che questo strumento è costruito per misurare, e la cancella nella peggiore direzione possibile: più due viste concordano, più di esse svaniscono. Casdoor viene scansionato come 372 endpoint di codice e 9 documentati; scansiona solo la sua directory swagger/ e la specifica ne ha 235.
--only-techs limita il pool di rilevatori, quindi una scansione per vista mantiene ciascuna integra. Quale tecnologia parla per quale vista è views.yml; quali tecnologie esistono è ciò che riporta noir list techs.
alibi non analizza alcun formato API per conto proprio. Il suo unico input è il JSON di noir.
Richiede noir 1.0.0 o superiore nel PATH -- è la release in cui noir list techs è diventato un sottocomando, e quel catalogo è ciò che assegna ogni tecnologia a una vista. Lo sviluppo segue la release corrente di noir. Un binario più vecchio viene rifiutato per nome anziché essere lasciato fallire alla sua prima lettura del catalogo.
$ uv tool install noir-alibi # or: pipx install noir-alibi
$ alibi scan ./my-service
$ alibi scan # the working directory
$ alibi scan ./service ./contracts ./prod.har # or wherever the views live
Ogni percorso è una sorgente, analizzata una volta per vista. Puntalo su qualunque cosa tu abbia — un albero dei sorgenti, una directory di specifiche, un singolo file di cattura — e le viste che ti mancano disattivano le loro regole invece di inondare il 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.
I gruppi si fermano a dodici — l'ordinamento è dal peggiore al migliore, quindi la coda è la parte meno informativa, e -f json contiene tutto.
I flag per noir vanno dopo un -- nudo o tramite --noir-arg. Filtri come --exclude-path vanno bene; i flag che sostituirebbero il contratto JSON o collasserebbero le scansioni per vista di alibi (--format, --diff-*, --only-techs, …) vengono rifiutati con stato di uscita 2.
- run: alibi scan . ./contracts -f sarif > alibi.sarif
- uses: github/codeql-action/upload-sarif@v3
with: { sarif_file: alibi.sarif }
Il report indica che le viste non concordano; --endpoints dice cosa conteneva ciascuna di esse.
$ alibi scan ./repo -f json --endpoints
Ogni vista riceve una lista: la chiave, quali viste l'hanno confermata, le tecnologie alla base, i file e la grafia prima della normalizzazione — che è dove si trova sempre la differenza quando due righe avrebbero dovuto corrispondere e non l'hanno fatto. È tre o quattro volte il resto del payload, quindi è un flag anziché il valore predefinito.
Oppure applica il gate direttamente: alibi scan . ./contracts --fail-on high esce con codice diverso da zero quando un finding raggiunge quella gravità. Una scansione che noir non è riuscito a leggere completamente riporta
executionSuccessful: false, quindi un'esecuzione degradata non passa come una pulita.
Un symlink, un binario o un'immagine che noir ha tralasciato di proposito non vengono conteggiati.
Noir mantiene la sintassi delle route propria di ciascun framework anziché inventarne una comune, così lo stesso endpoint arriva scritto in diversi modi:
python_flask /api/users/<int:user_id>
aiohttp /users/{id}
java_spring /api/catalog/{id}
oas3 /v1/pets/{petId}
rails /posts/:id
nginx /admin/.*
La regola che rende questi confrontabili: il nome di un parametro di percorso non fa parte della sua identità. {petId} e <int:user_id> descrivono lo stesso slot; contano solo la sua posizione e se attraversa un /. I nomi vengono conservati come evidenza e riportati, ma non entrano mai nella chiave.
I risultati indicano come è stato effettuato il confronto:
| Grado | Significato |
|---|---|
G1 | le grafie coincidevano già |
G2 | coincidono una volta normalizzata la sintassi dei parametri |
G0 | solo una vista lo contiene — nulla è stato confrontato |
Uno strumento come questo muore riportando centinaia di risultati alla prima esecuzione, oppure riportando progressi che nessuno ha fatto. Sei cose spingono nella direzione opposta:
Le regole non scattano senza entrambe le viste. Analizza un codebase senza contratti da nessuna parte e ogni endpoint tecnicamente si qualifica come shadow API non documentata. Quei risultati non dicono nulla se non che non hai fornito alcuna documentazione, quindi una regola viene eseguita solo quando ogni vista su cui ragiona era effettivamente presente nella scansione. Il report elenca le regole che sono rimaste escluse.
I quasi-incroci vengono riportati come dubbio, non come risultati. "Nel codice, non nella documentazione" è indistinguibile da "in entrambe, ma alibi non è riuscito ad allinearle". Quindi un endpoint che finisce in una vista viene confrontato con le altre per un quasi-incrocio — stesso percorso con un verbo diverso, oppure a un segmento di distanza dove un lato ha un parametro e l'altro un valore letterale. I risultati che presentano un quasi-incrocio vengono declassati e segnalati per la revisione. Quel conteggio sta accanto ai totali, perché ogni risultato è affidabile solo nella misura in cui è esiguo.