Gegenprüfen Sie die Ansichten Ihrer Angriffsfläche und finden Sie die Endpunkte, die sich nicht gegenseitig bestätigen können.

Was es nicht tut, ist sie zu vergleichen. Genau das ist hier die Aufgabe, und sie erfordert keine Änderung an noir — alibi führt es einmal pro Ansicht aus und verknüpft die Ergebnisse.

Der Teil pro Ansicht ist wichtig. Noir dedupliziert nach (method, url) über alle Analyzer hinweg, sodass eine Flask-Route und ein identisch geschriebener OpenAPI-Pfad zu einem Endpunkt mit einer Technologie zusammenfallen. Das ist richtig für ein Discovery-Tool — es ist ein Endpunkt —, aber es löscht die Bestätigung aus, die dieses Tool messen soll, und es löscht sie in der denkbar schlechtesten Richtung: Je besser zwei Ansichten übereinstimmen, desto mehr von ihnen verschwinden. Casdoor wird als 372 Code-Endpunkte und 9 dokumentierte gescannt; scannt man nur sein swagger/-Verzeichnis, hat die Spezifikation 235.

--only-techs schränkt den Detektor-Pool ein, sodass ein Scan pro Ansicht jede einzelne ganz hält. Welche Technologie für welche Ansicht spricht, steht in views.yml; welche Technologien existieren, ist das, was noir list techs meldet.

alibi parst keine API-Formate selbst. Seine einzige Eingabe ist noirs JSON.

Installation

Erfordert noir 1.0.0 oder neuer im PATH -- das ist die Version, in der noir list techs ein Unterbefehl wurde, und dieser Katalog ist es, der jede Technologie einer Ansicht zuordnet. Die Entwicklung folgt der aktuellen noir-Version. Eine ältere Binary wird namentlich abgelehnt, statt beim ersten Kataloglesen zu scheitern.

Verwendung

Jeder Pfad ist eine Quelle, einmal pro Ansicht gescannt. Richten Sie es auf das, was Sie haben — einen Quellbaum, ein Spezifikationsverzeichnis, eine einzelne Capture-Datei —, und die fehlenden Ansichten schalten ihre Regeln ab, statt den Bericht zu fluten.

Gruppen enden bei zwölf — die Reihenfolge ist schlimmste zuerst, sodass der Schwanz der am wenigsten informative Teil ist, und -f json hat alles.

In CI

Sehen, was jede Ansicht enthielt

Der Bericht sagt, dass die Ansichten nicht übereinstimmen; --endpoints sagt, was jede von ihnen enthielt.

Jede Ansicht bekommt eine Liste: den Schlüssel, welche Ansichten für ihn bürgten, die dahinterstehenden Technologien, die Dateien und die Schreibweise vor der Normalisierung — wo der Unterschied immer liegt, wenn zwei Zeilen hätten übereinstimmen sollen und es nicht taten. Es ist das Drei- bis Vierfache der restlichen Nutzlast, also ist es ein Flag und nicht die Voreinstellung.

Oder direkt gaten: alibi scan . ./contracts --fail-on high beendet sich mit einem Nicht-Null-Code, wenn ein Befund diesen Schweregrad erreicht. Ein Scan, den noir nicht vollständig lesen konnte, meldet executionSuccessful: false, sodass ein beeinträchtigter Lauf nicht als sauberer durchgeht.

Wie Endpunkte abgeglichen werden

Noir behält die eigene Routensyntax jedes Frameworks bei, statt eine gemeinsame zu erfinden, sodass derselbe Endpunkt in mehreren Schreibweisen ankommt:

Die Regel, die diese vergleichbar macht: Der Name eines Pfadparameters ist nicht Teil seiner Identität. {petId} und <int:user_id> beschreiben denselben Platz; nur seine Position und ob er ein / überspannt, zählen. Namen werden als Beleg behalten und berichtet, erreichen aber nie den Schlüssel.

Befunde sagen, wie der Abgleich erfolgte:

Was es ehrlich hält

Ein Tool wie dieses stirbt daran, beim ersten Lauf Hunderte von Befunden zu melden, oder daran, Fortschritt zu melden, den niemand gemacht hat. Sechs Dinge wirken dem entgegen:

Regeln feuern nicht ohne beide Ansichten. Scannen Sie eine Codebasis ohne irgendwo Verträge, und jeder Endpunkt qualifiziert sich technisch als undokumentierte Shadow-API. Diese Befunde sagen nichts außer, dass Sie keine Dokumentation geliefert haben, also läuft eine Regel nur, wenn jede Ansicht, über die sie schlussfolgert, tatsächlich im Scan war. Der Bericht nennt die Regeln, die ausgesetzt haben.

Beinahe-Treffer werden als Zweifel gemeldet, nicht als Befunde. "Im Code, nicht in den Docs" ist nicht von "in beiden, aber alibi konnte sie nicht zur Deckung bringen" zu unterscheiden. Also wird ein Endpunkt, der in einer Ansicht landet, gegen die anderen auf einen Beinahe-Treffer geprüft — derselbe Pfad mit einem anderen Verb, oder ein Segment entfernt, wo eine Seite einen Parameter und die andere ein Literal hat. Befunde mit einem Beinahe-Treffer werden herabgestuft und zur Überprüfung markiert. Diese Zahl steht neben den Summen, denn jeder Befund ist nur so vertrauenswürdig, wie er klein ist.

Ansichten, die sich nie trafen, sind eine Diagnose, nicht Hunderte von Befunden. Argo CD registriert /api in Go und dokumentiert 198 Pfade darunter, sodass sein Code und seine Spezifikation keinen einzigen Endpunkt teilen. Wörtlich gelesen sind das 58 Shadow-APIs und 198 Phantom-Verträge, von denen keiner real ist. Null Bestätigung zwischen zwei befüllten Ansichten bedeutet, dass der Vergleich nicht funktioniert hat — ein Mount-Point, der für die Routen darunter steht, oder ein Stack, den noir nicht lesen konnte —, also werden die Regeln zurückgehalten und stattdessen der Grund ausgegeben. Pfade, die sich als solche herausstellen, unter denen viele Endpunkte aus anderen Ansichten liegen, werden als wahrscheinliche Mounts gekennzeichnet.

Wenn die beiden Ansichten übereinstimmen, sobald ein konstanter Präfix von einer von ihnen abfällt, sagt die Diagnose das und nennt den Präfix. Giteas generierte Spezifikation deklariert basePath: /GITEA-API-APP-SUBURL/api/v1, während sein Go-Router /api/v1 mountet; die Ansichten teilen nichts, aber 154 der 535 dokumentierten Pfade stimmen mit einem Codepfad überein, sobald diese drei Segmente entfernt werden. Das ist ein Spec-basePath, eine servers[].url oder ein Mount, den der Code-Reader fallen ließ — und es wird berichtet, nie angewendet, weil das Neuausrichten der Pfade den Bug verbergen würde, den es gefunden hat.

Eine Flut, die in Wahrheit ein fehlender Teilbaum ist, wird als eine benannt: 207 von NodeBBs 354 Phantom-Verträgen liegen unter /api/v3, wo die Code-Ansicht gar nichts enthält.

Eine fehlende Ansicht und eine leere bedeuten Gegenteiliges. Noir meldet, was es nicht lesen konnte, und alibi gibt das über den Befunden aus. NetBox liefert ein 12,35 MB großes OpenAPI-Dokument mit 308 Pfaden; noir überspringt es, weil es sein Dateigrößenlimit überschreitet, und ohne diesen Bericht behauptet alibi, das Projekt dokumentiere nichts — nicht bloß unvollständig, sondern die falsche Antwort selbstsicher vorgetragen.

Eine Regel, die nicht mehr lief, hat nichts aufgelöst. Scans aufzuzeichnen und zu vergleichen führt denselben Fehler aus der Distanz wieder ein: Vergessen Sie das Vertragsverzeichnis in einem Lauf, und SHADOW wertet nichts aus, was für eine naive Differenz genau so aussieht, als wären alle Shadow-APIs geschlossen worden. Beim Fünf-Ansichten-Fixture verwandelte das Weglassen eines Arguments sieben bestehende Befunde in "aufgelöst". Snapshots zeichnen auf, welche Regeln ausgewertet wurden, Differenzen berücksichtigen nur Regeln, die in beiden Scans liefen, und der Rest wird unter NOT COMPARED genannt.

Eine Abwesenheit ist nur dann ein Beleg, wenn das Signal existiert. Noirs Auth-Tagger decken die Frameworks ab, die sie kennen. In einem Stack, den sie nicht abdecken, trägt nichts ein Auth-Tag, und das als "unauthentifiziert" zu behandeln würde jeden Befund hochstufen und die Schweregrad-Spalte ihrer Bedeutung berauben. Anpassungen, die bei einem fehlenden Tag feuern, erfordern, dass dieses Tag zuerst irgendwo im Scan auftaucht.

Regeln

Der Schweregrad verschiebt sich dann je nach dem, was noirs Tagger fanden: personenbezogene Daten, Datei-Uploads, kein Anzeichen von Authentifizierung oder eine Methode, die den Zustand ändert.

Sowohl die Ansichtszuordnung (views.yml) als auch die Regeln (rules.yml) sind Daten, kein Code.

Gateways sind keine Endpunktlisten

Ein location /api/ steht für alles darunter, also beantworten Gateway- und Infrastrukturregeln die Frage erreicht dies jenen Endpunkt statt enthält dies ihn. Als Mengen verglichen sieht jede Präfixregel wie eine Route aus, die niemand implementiert hat, und jede implementierte Route wie unerreichbar.

Die Abdeckung ist bewusst großzügig. Noir meldet den Pfad, den eine Regel trifft, aber nicht, ob sie als Präfix oder exakt trifft (location = /x, ein Ingress pathType: Exact), sodass Exaktheit nicht wiederhergestellt werden kann — und jede Regel als Präfix zu behandeln unterdrückt Befunde, statt sie zu erfinden.

Der Bericht sagt, wie viel des Codes jede Routing-Ansicht erreicht, denn ob "34 Endpunkte, die kein Gateway erreicht" real ist, hängt davon ab, ob diese Konfiguration die ist, die dem Dienst vorgelagert ist. Kein Schwellenwert trennt das ehrlich: Argo CDs e2e-Test-Fixture erreicht 39 % seines Codes und NetBox' echte Konfiguration erreicht 100 %.

Ein Catch-all — location /, ein Ingress auf /, ein RewriteRule ^(.*)$ — ist in keine Richtung ein Beleg. Es routet alles oder nichts, dasselbe für jeden Endpunkt, also zählt es als keinen von ihnen erreichend. Eine Gateway-Ansicht, die nichts anderes enthält, hat kein Signal anzubieten, und UNEXPOSED setzt aus und sagt das, statt jeden Endpunkt als unerreichbar zu melden. Casdoors Helm-Chart ist genau das: eine Ingress-Regel auf /, die als Beleg gelesen 365 Befunde produzierte.

Traffic muss beobachtet worden sein

Eine HAR-Aufzeichnung zeichnet Anfragen auf, die stattgefunden haben. Eine Postman-Collection zeichnet Anfragen auf, die jemand zu stellen beabsichtigte. ORPHAN, LIVE_UNDOC und COLD schlussfolgern alle über das, was lief, also erfordern sie eine Ansicht, die jemand tatsächlich beobachtet hat, und sagen das, wenn sie aussetzen.

Nicht-Web-Oberfläche bleibt draußen

Noir meldet CLI-Argumente, Kafka-Topics und mobile Deep Links in derselben Liste. cli://gitops-engine/agent zu HTTP flachgeklopft wird /agent — es kollidiert mit jeder Web-Route dieses Namens und wird gefragt, ob ein Gateway dorthin routet. Das Protokoll gehört zur Identität des Endpunkts; http und https sind ein Raum und alles andere behält seinen eigenen.

Unterdrückung

Manche Lücken sind der beabsichtigte Zustand. Legen Sie eine .alibi.yml neben die Quelle:

Oder übergeben Sie --ignore REGEX für einen Einzelfall. Unterdrückte Befunde werden gezählt und die Zahl wird ausgegeben — ein Tool, das Befunde stillschweigend fallen lässt, ist schlimmer als eines, das zu viele ausgibt, weil es dann keine Möglichkeit mehr gibt zu erkennen, was es zurückgehalten hat.

Status

Früh, aber alle fünf Ansichten werden verglichen.

Gemessen an fünf Repositories:

Casdoor ist der sauberste Fall: 230 seiner 235 dokumentierten Endpunkte stimmten mit dem Code überein, ganz ohne Pfadnormalisierungsfehler. Alle 19 Beinahe-Treffer waren derselbe Pfad unter einem anderen Verb — noir registrierte jede Methode auf einem Go-Catch-all-Handler, kein Abgleichproblem.

NetBox ist der lehrreiche Fall. Es hält zwei Oberflächen in einem Repository: eine servergerenderte Web-UI und eine DRF-Router-REST-API, von denen nur die zweite dokumentiert ist. Ganz gescannt meldet es 746 Befunde, die meisten davon die wahre, aber nutzlose Beobachtung, dass eine Web-UI nicht in einer API-Spezifikation steht. Auf die Oberfläche begrenzt, die der Vertrag beschreibt, kollabiert es auf das, was tatsächlich zu sagen war:

→ 3 Shadow-APIs: /api/plugins, /api/schema/redoc, /api/schema/swagger-ui, alle drei echt bedient und echt im Schema fehlend. Die 397 Phantome, die bleiben, sind die Bulk-Operationen, die NetBox' eigene Router-Unterklasse jedem Listen-Endpunkt hinzufügt, welche kein urlconf-Durchlauf sehen kann.

Die anderen drei werden zurückgehalten, jede aus einem Grund, den es sich zu kennen lohnt:

• Argo CD registriert /api in Go und dokumentiert 198 Pfade darunter — dieselbe Oberfläche in zwei Granularitäten.
• authentik setzt seine URLconf zur Laufzeit zusammen, indem es das urls-Modul jeder installierten App importiert, was kein statischer Reader verfolgen kann.
• flipt mountet ein gRPC-Gateway; sein Go-Quellcode enthält eine Route. Seine HTTP-Oberfläche ist in .proto-Annotationen implementiert, weshalb grpc für die Code-Ansicht spricht: dort abgelegt, bestätigen sich 36 seiner 36 dokumentierten Pfade.

Was die Obergrenze dieses Tools ist, klar ausgedrückt: Es vergleicht, was noir lesen kann, und eine in der falschen Granularität gelesene Ansicht ist schlimmer als eine gar nicht gelesene. Der größte Teil der obigen Maschinerie existiert, um diese auseinanderzuhalten, statt sie als Defekte zu melden.

Lizenz

MIT