Verifica in modo incrociato le viste della tua superficie di attacco e individua gli endpoint che non possono corroborarsi a vicenda.

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. È corretto per uno strumento di discovery — è un 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 la sua directory swagger/ da sola 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.

Installazione

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.

Uso

Ogni percorso è una sorgente, scansionata una volta per vista. Puntalo su ciò che hai — un albero di sorgenti, una directory di specifiche, un singolo file di cattura — e le viste che mancano disattivano le loro regole anziché inondare il report.

I gruppi si fermano a dodici — l'ordinamento è dal peggiore al migliore, quindi la coda è la parte meno informativa, e -f json ha tutto.

In CI

Vedere cosa conteneva ciascuna vista

Il report dice che le viste non concordano; --endpoints dice cosa ciascuna di esse conteneva.

Ogni vista ottiene una lista: la chiave, quali viste l'hanno confermata, le tecnologie dietro di essa, i file, e la scrittura prima della normalizzazione — che è dove si trova sempre la differenza quando due righe avrebbero dovuto corrispondere e non l'hanno fatto. È da tre a quattro volte il resto del payload, quindi è un flag anziché il default.

Oppure applica direttamente un gate: alibi scan . ./contracts --fail-on high esce con codice diverso da zero quando un risultato raggiunge quella severità. Una scansione che noir non è riuscito a leggere completamente riporta executionSuccessful: false, quindi un'esecuzione degradata non passa come pulita.

Come vengono confrontati gli endpoint

Noir mantiene la sintassi di route propria di ciascun framework anziché inventarne una comune, quindi lo stesso endpoint arriva scritto in diversi modi:

La regola che li rende 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 sono conservati come evidenza e riportati, ma non raggiungono mai la chiave.

I risultati dicono come è stata fatta la corrispondenza:

Cosa lo mantiene onesto

Uno strumento come questo muore riportando centinaia di risultati alla sua prima esecuzione, o riportando progressi che nessuno ha fatto. Sei cose spingono in senso contrario:

Le regole non scattano senza entrambe le viste. Scansiona una codebase senza contratti da nessuna parte e ogni endpoint tecnicamente si qualifica come una 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 nella scansione. Il report nomina le regole che sono rimaste fuori.

I quasi-match sono riportati come dubbio, non come risultati. "Nel codice, non nella documentazione" è indistinguibile da "in entrambi, ma alibi non è riuscito ad allinearli." Quindi un endpoint che finisce in una vista viene controllato rispetto alle altre per un quasi match — stesso percorso con un verbo diverso, o a un segmento di distanza dove un lato ha un parametro e l'altro un letterale. I risultati che portano un quasi-match sono declassati e segnalati per revisione. Quel conteggio sta accanto ai totali, perché ogni risultato è affidabile solo nella misura in cui è piccolo.

Viste che non si sono mai incontrate sono una diagnostica, non centinaia di risultati. Argo CD registra /api in Go e documenta 198 path sotto di esso, quindi il suo codice e la sua specifica non condividono un solo endpoint. Letto alla lettera sono 58 shadow API e 198 contratti fantasma, nessuno dei quali reale. Zero corroborazione tra due viste popolate significa che il confronto non ha funzionato — un punto di mount che sta al posto delle route sottostanti, o uno stack che noir non è riuscito a leggere — quindi le regole sono trattenute e la ragione viene stampata. I percorsi che risultano avere molti endpoint da altre viste sotto di essi sono etichettati come probabili mount.

Quando le due viste si allineano una volta rimosso un prefisso costante da una di esse, la diagnostica lo dice e nomina il prefisso. La specifica generata di Gitea dichiara basePath: /GITEA-API-APP-SUBURL/api/v1 mentre il suo router Go monta /api/v1; le viste non condividono nulla, ma 154 dei 535 path documentati corrispondono a un percorso di codice una volta rimossi quei tre segmenti. Quello è un basePath di specifica, un servers[].url, o un mount che il lettore di codice ha perso — ed è riportato, mai applicato, perché riallineare i percorsi nasconderebbe il bug che ha trovato.

Un diluvio che in realtà è un singolo sottoalbero mancante viene nominato come uno solo: 207 dei 354 contratti fantasma di NodeBB stanno sotto /api/v3, dove la vista del codice non contiene nulla affatto.

Una vista mancante e una vuota significano cose opposte. Noir riporta ciò che non è riuscito a leggere, e alibi lo stampa sopra i risultati. NetBox distribuisce un documento OpenAPI da 12,35MB con 308 path; noir lo salta per aver superato il suo limite di dimensione file, e senza quel report alibi afferma che il progetto non documenta nulla — non semplicemente incompleto, ma la risposta sbagliata affermata con sicurezza.

Una regola che ha smesso di essere eseguita non ha risolto nulla. Registrare le scansioni e confrontarle reintroduce lo stesso errore a distanza: dimentica la directory dei contratti in un'esecuzione e SHADOW non valuta nulla, il che a una differenza ingenua appare esattamente come se ogni shadow API fosse stata chiusa. Sul fixture a cinque viste, eliminare un argomento ha trasformato sette risultati permanenti in "risolti". Gli snapshot registrano quali regole sono state valutate, le differenze considerano solo le regole che sono state eseguite in entrambe le scansioni, e le altre sono nominate sotto NOT COMPARED.

Un'assenza è evidenza solo quando il segnale esiste. I tagger di autenticazione di Noir coprono i framework che conoscono. In uno stack che non coprono, nulla porta un tag di autenticazione, e trattarlo come "non autenticato" promuoverebbe ogni risultato e svuoterebbe di significato la colonna della severità. Gli aggiustamenti che scattano su un tag mancante richiedono che quel tag appaia prima da qualche parte nella scansione.

Regole

La severità poi cambia in base a ciò che hanno trovato i tagger di noir: dati personali, upload di file, nessun segno di autenticazione, o un metodo che cambia stato.

Sia la mappa delle viste (views.yml) che le regole (rules.yml) sono dati, non codice.

I gateway non sono liste di endpoint

Un location /api/ sta per tutto ciò che c'è sotto, quindi le regole di gateway e infrastruttura rispondono a questo raggiunge quell'endpoint anziché questo lo contiene. Confrontate come insiemi, ogni regola di prefisso appare come una route che nessuno ha implementato e ogni route implementata appare irraggiungibile.

La copertura è deliberatamente generosa. Noir riporta il percorso che una regola corrisponde ma non se corrisponde come prefisso o esattamente (location = /x, un Ingress pathType: Exact), quindi l'esattezza non può essere recuperata — e trattare ogni regola come prefisso sopprime i risultati anziché inventarli.

Il report dice quanta parte del codice raggiunge ciascuna vista di routing, perché se "34 endpoint che nessun gateway raggiunge" è reale dipende da se quella config è quella che fronta il servizio. Nessuna soglia separa onestamente questi casi: il fixture di test e2e di Argo CD raggiunge il 39% del suo codice e la config reale di NetBox raggiunge il 100%.

Un catch-all — location /, un Ingress a /, un RewriteRule ^(.*)$ — non è evidenza in nessuna delle due direzioni. Instrada tutto o nulla, lo stesso per ogni endpoint, quindi conta come non raggiungerne nessuno. Una vista di gateway che non contiene nient'altro non ha alcun segnale da offrire, e UNEXPOSED resta fuori e lo dice anziché riportare ogni endpoint come irraggiungibile. Il chart Helm di Casdoor è esattamente questo: una regola Ingress a /, che letta come evidenza ha prodotto 365 risultati.

Il traffico deve essere stato osservato

Una cattura HAR registra richieste che sono avvenute. Una collezione Postman registra richieste che qualcuno intendeva fare. ORPHAN, LIVE_UNDOC e COLD ragionano tutti su ciò che è stato eseguito, quindi richiedono una vista che qualcuno ha effettivamente osservato e lo dicono quando restano fuori.

La superficie non-web resta fuori

Noir riporta argomenti CLI, topic Kafka e deep link mobile nella stessa lista. cli://gitops-engine/agent appiattito in HTTP diventa /agent — collide con qualsiasi route web di quel nome e gli viene chiesto se un gateway vi instrada. Il protocollo appartiene all'identità dell'endpoint; http e https sono uno spazio unico e tutto il resto mantiene il proprio.

Soppressione

Alcune lacune sono lo stato intenzionale. Metti un .alibi.yml accanto alla sorgente:

Oppure passa --ignore REGEX per un caso isolato. I risultati soppressi sono contati e il conteggio viene stampato — uno strumento che scarta silenziosamente i risultati è peggiore di uno che ne stampa troppi, perché non c'è più alcun modo di sapere cosa ha trattenuto.

Stato

In fase iniziale, ma tutte e cinque le viste sono confrontate.

Misurato su cinque repository:

Casdoor è il caso più pulito: 230 dei suoi 235 endpoint documentati corrispondono al codice, senza alcun fallimento di normalizzazione dei percorsi. Tutti i 19 quasi-match erano lo stesso percorso sotto un verbo diverso — noir che registra ogni metodo su un handler catch-all Go, non un problema di corrispondenza.

NetBox è quello istruttivo. Contiene due superfici in un unico repository: una web UI renderizzata dal server e una REST API con DRF-router di cui solo la seconda è documentata. Scansionato interamente riporta 746 risultati, la maggior parte dei quali la vera ma inutile osservazione che una web UI non è in una specifica API. Limitato alla superficie che il contratto descrive, collassa a ciò che valeva davvero la pena dire:

→ 3 shadow API: /api/plugins, /api/schema/redoc, /api/schema/swagger-ui, tutte e tre genuinamente servite e genuinamente assenti dallo schema. I 397 fantasmi che rimangono sono le operazioni bulk che la sottoclasse di router di NetBox stessa aggiunge a ogni endpoint di lista, che nessuna percorrenza di urlconf può vedere.

Gli altri tre sono trattenuti, ciascuno per una ragione che vale la pena conoscere:

• Argo CD registra /api in Go e documenta 198 path sotto di esso — la stessa superficie a due granularità.
• authentik assembla il suo URLconf a runtime importando il modulo urls di ogni app installata, cosa che nessun lettore statico può seguire.
• flipt monta un gateway gRPC; la sua sorgente Go contiene una route. La sua superficie HTTP è implementata nelle annotazioni .proto, motivo per cui grpc parla per la vista del codice: archiviato lì, 36 dei suoi 36 path documentati si corroborano.

Che è il tetto di questo strumento, detto chiaramente: confronta ciò che noir riesce a leggere, e una vista letta alla granularità sbagliata è peggiore di una non letta affatto. La maggior parte del meccanismo sopra esiste per distinguere questi casi anziché riportarli come difetti.

Licenza

MIT