Methodik
Wie Erkennungsgenauigkeit gemessen wird
Geschrieben und gepflegt von Hendrik Schneider · Zuletzt geprüft · Wie wir das prüfen
Ein Scanner, der behauptet, False Positives zu reduzieren, ohne eine Zahl zu veröffentlichen, macht dieselbe unwiderlegbare Aussage wie jeder andere Scanner. Korthex bringt eine Accuracy Engine mit, die die Erkennung gegen ein Ground-Truth-Korpus misst - und es ist dieselbe Engine, die die eigenen Releases absichert. Diese Seite ist die Methode. Die Zahlen stehen unten, auch die unerfreulichen.
Was wird gemessen?
Drei Verhältnisse aus drei Zählwerten. Ein True Positive ist ein Befund, den der Scanner gemeldet hat und den die Ground Truth ebenfalls führt. Ein False Positive ist einer, den er gemeldet hat und den die Ground Truth nicht führt. Ein False Negative ist einer, den die Ground Truth führt und den der Scanner nicht gemeldet hat.
| Kennzahl | Formel | Was ein hoher Wert bedeutet | Was er verdeckt |
|---|---|---|---|
| Precision | tp / (tp + fp) | Was Sie sehen, ist echt | Ein Scanner, der fast nichts meldet, schneidet gut ab |
| Recall | tp / (tp + fn) | Echte Befunde werden nicht übersehen | Ein Scanner, der alles meldet, schneidet gut ab |
| F1 | harmonisches Mittel beider | Keines wird für das andere geopfert | Eine Zahl verdeckt, welches von beiden sich bewegt hat |
Was bedeutet Ground Truth hier?
Eine Ground-Truth-Datei ist ein handgeprüftes Inventar der Kryptografie in einem Korpus: pro Vorkommen der Algorithmus, die Datei und die Zeile. Sie ist JSON, sie liegt im Repository, und sie ist das, wogegen der Scanner benotet wird - was sie zum schwächsten Glied der ganzen Methode macht, denn eine falsche Ground Truth benotet einen korrekten Scanner als kaputt.
Deshalb wird bei jeder veröffentlichten Zahl das Korpus genannt. Eine Precision-Zahl ohne benanntes Korpus ist keine Messung eines Scanners, sondern die Messung eines Korpus, das niemand einsehen kann.
Die vier Modi
- Scanner: der Standard. Scan-Ausgabe gegen die Ground Truth, ein Korpus, ein Lauf.
- Migration: derselbe Vergleich über eine Migration hinweg - der Zustand vorher auf der erwarteten Seite, der Zustand nachher auf der tatsächlichen. Gemessen wird, ob der Plan funktioniert hat, nicht ob der Scan richtig lag.
- False Positives: Lauf gegen ein Korpus, das nachweislich sauber ist. Jeder Befund ist per Definition ein False Positive, dieser Modus isoliert die Rate also, ohne dass eine Ground Truth die echten aufzählen müsste.
- Korpus: eine Aggregation über ein ganzes Korpus statt über einen einzelnen Scan, mit weiterem Zeilenfenster.
Die Toleranzen, und die eine, die bewusst fehlt
Quellcode bewegt sich. Ein Refactoring, das einen Aufruf zwei Zeilen nach unten schiebt, ist keine Erkennungsregression, deshalb erlaubt der Abgleich eine konfigurierbare Zeilentoleranz. Auch Algorithmennamen werden normalisiert: MD5Sum, md5 und MD-5 fallen auf einen kanonischen Treffer zusammen, denn ein Scanner liegt nicht falsch, weil er anders schreibt als der Autor der Ground Truth.
Ein Zusammenfallen wird bewusst verweigert: zwei Befunde, die beide mit Unknown beschriftet sind, treffen einander nie. Es wäre trivial, das zuzulassen, und es würde jede Precision-Zahl auf dieser Seite aufblähen. Ein unidentifizierter Algorithmus auf beiden Seiten sind zwei offene Fragen, keine Antwort.
Was zeigen diese Zahlen nicht?
- Sie lassen sich nicht auf Ihre Codebasis übertragen. Ein an einem benannten Korpus gemessenes Verhältnis beschreibt dieses Korpus. Eine Codebasis mit anderen Sprachen, anderen Bibliotheken oder ungewöhnlichen Krypto-Wrappern schneidet anders ab, möglicherweise schlechter.
- Sie messen keine Schwere. Ein übersehener hartkodierter privater Schlüssel und eine übersehene MD5-Prüfsumme zählen im Recall gleich, und sie sind nicht derselbe Befund.
- Sie messen nicht die Compliance-Zuordnung. Ob ein Befund gegen die richtige BSI- oder NIST-Regel bewertet wird, ist eine eigene Frage, die ein anderes Build-Gate hält.
- Ein einzelner Lauf ist ein Punkt, kein Trend. Die Engine führt eine Lauf-Historie genau deshalb, weil eine einzelne Messung nicht sagen kann, ob der Scanner besser wird.
Warum sichert die Engine das Release ab?
Kryptografische Erkennung ist voller Randfälle, und eine Änderung an der AST-Analyse kann fünf Befunde reparieren und zwölf andere zerstören. Dieser Fehler ist lautlos, solange ihn nichts misst - deshalb ist der Genauigkeitslauf in der Release-Pipeline standardmäßig ein Pass/Fail-Schritt: ein Lauf, dessen Recall unter 0,8 fällt, endet mit einem Fehlercode, ohne dass auf der Kommandozeile eine Schwelle übergeben wurde. Messen ohne Absichern ist möglich, muss aber ausdrücklich verlangt werden.
Die Lauf-Historie dahinter ist bewusst schmal. Jeder Eintrag enthält Zeitstempel, Modus, Zeilentoleranz und die Kennzahlen - und niemals einen Befund, einen Dateipfad oder einen Quellcode-Ausschnitt. Das macht sie auf einem geteilten CI-Runner unbedenklich, und es ist dieselbe On-Premise-Logik, der das restliche Produkt folgt.
Aktuelle Messungen
Es ist noch keine Messung veröffentlicht. Engine und Methode stehen oben; die Zahlen erscheinen hier, sobald ein Lauf gegen ein stabiles Korpus geprüft und freigegeben ist. Eine unveröffentlichte Zahl ist keine zurückgehaltene - es ist eine, die noch nicht geprüft wurde.
Häufig gestellte Fragen
Wie hoch ist die False-Positive-Rate von Korthex?
Sie wird pro Korpus gemessen statt als eine Zahl behauptet, und zwar gegen ein nachweislich sauberes Korpus, sodass jeder Befund in diesem Lauf per Definition ein False Positive ist. Die veröffentlichten Werte und das jeweils zugehörige Korpus stehen unten auf dieser Seite.
Wie wird die Scanner-Genauigkeit berechnet?
Precision ist tp/(tp+fp), Recall ist tp/(tp+fn), F1 ist ihr harmonisches Mittel - wobei ein True Positive ein Befund ist, den die handgeprüfte Ground Truth an derselben Datei und Zeile führt, innerhalb einer konfigurierbaren Zeilentoleranz.
Gelten diese Genauigkeitswerte für meine Codebasis?
Nein. Ein an einem benannten Korpus gemessenes Verhältnis beschreibt dieses Korpus. Andere Sprachen, Bibliotheken oder Krypto-Wrapper ergeben andere Zahlen - deshalb steht das Korpus neben jedem Wert und wird nicht stillschweigend vorausgesetzt.
Veröffentlicht Korthex auch Messungen, die schlechter wurden?
Ja - genau darum geht es beim Veröffentlichen. Eine Methodikseite, die nur Verbesserungen zeigen kann, ist eine Broschüre. Die Veröffentlichung ist für jede Messung ein bewusster Schritt, aber das Kriterium ist, dass der Lauf gültig war, nicht dass das Ergebnis gut war.