FAQ & Troubleshooting
Die Fragen, die beim Lesen einer kunnus-SBOM tatsächlich auftauchen — die meisten führen auf eine Designentscheidung zurück: Der Scanner erfasst, was der Input behauptet, und weigert sich zu raten oder online zu gehen.
Warum fehlt eine Komponente in meiner SBOM?
Die häufigsten Ursachen sind Absicht: Deklarationen mit nicht aufgelösten Variablen in Identitätsfeldern (${...} in CMake oder platformio.ini) werden verworfen statt geraten; feature-bedingte vcpkg-Abhängigkeiten werden nicht verfolgt; lokale path:-Komponenten gelten als Code in Entwicklung und werden übersprungen. Fehlt ein ganzes Ökosystem, prüfen Sie, ob dessen Marker-Datei (Lockfile/Manifest) im gescannten Baum liegt, und starten Sie den Scan mit --verbosity info neu, um zu sehen, welche Extraktoren liefen.
Warum hat eine Komponente keine Version?
Weil der gescannte Input keine pinnt und kunnus Versionen nicht online auflöst. Beispiele: eine vcpkg-Abhängigkeit ohne Override und ohne Versionsuntergrenze, ein Git-Submodul in einem exportierten Baum ohne .git, ein west-Projekt ohne Revision oder Default. Der deklarierte Zustand wird wörtlich erfasst; ihn gegen eine Registry aufzulösen bräuchte Netzwerkzugriff, den der Scanner bewusst vermeidet.
Der Scanner endete mit Exit-Code 1, hat aber eine SBOM geschrieben — ist er kaputt?
Nein — das ist das Signal für einen unvollständigen Scan. Die SBOM wurde erzeugt, aber einzelne Extraktor-Plugins sind fehlgeschlagen; das Ergebnis kann Lücken haben. Die Fehlermeldung listet die betroffenen Plugins; --verbosity info liefert Details pro Plugin. Exit 0 ist Scans vorbehalten, bei denen jedes Plugin sauber lief — so kann CI beides unterscheiden.
Sendet kunnus-scanner meinen Code oder meine Daten irgendwohin?
Nein. Scans sind standardmäßig offline und stellen keine Netzwerkverbindungen her. Genau drei Features nutzen das Netzwerk, alle explizit: --online-licenses (deps.dev-Lizenzabfragen), das Scannen einer Remote-Container-Referenz (Registry-Pull) und kunnus upload. Alles andere, das nach Hause telefoniert, wäre ein Bug — und laut Security-Policy des Projekts eine meldepflichtige Schwachstelle.
Warum haben manche Komponenten keine Lizenz?
Lizenzen stammen aus offline verfügbaren Paketdaten: OS-Paketdatenbanken, Debian-Copyright-Dateien, Lockfiles mit eingebetteten Lizenzen (composer.lock) und den eigenen Manifesten installierter Pakete. Ökosysteme, deren Inputs keine Lizenzdaten tragen (Go-, Rust-, .NET-Lockfiles, Embedded-Manifeste), bleiben offline leer — --online-licenses schließt die Lücke via deps.dev, das einzige Opt-in-Online-Feature.
Warum erscheint dieselbe Bibliothek nur einmal, obwohl mehrere Teilprojekte sie deklarieren?
Die Deduplizierung ist Absicht: Komponenten mit derselben Package-URL werden zusammengeführt, und jeder Fundort bleibt in der evidence.occurrences-Liste der Komponente erhalten. Die SBOM bleibt duplikatfrei, ohne die Antwort auf „wo genau wird das benutzt?“ zu verlieren.
Welches SBOM-Format erzeugt der Scanner — und geht auch SPDX?
Ausschließlich CycloneDX 1.6 JSON, konform zur BSI TR-03183-2 — der Technischen Richtlinie, die die SBOM-Anforderungen des CRA operationalisiert. SPDX-Ausgabe wird derzeit nicht unterstützt; wer SPDX für einen nachgelagerten Abnehmer braucht, konvertiert die CycloneDX-Datei z. B. mit cyclonedx-cli.
Enthält die SBOM einen Abhängigkeitsgraphen oder nur eine flache Liste?
Beides, je nach Ökosystem. Wo ein Lockfile den aufgelösten Graphen pinnt — Cargo.lock, composer.lock, Gemfile.lock, package-lock.json/npm-shrinkwrap.json (v2/v3), packages.lock.json, renv.lock — werden die echten Kanten in CycloneDX dependencies[] übernommen. Alles andere steuert nur die Zugehörigkeit zur Root-Komponente bei. Das Dokument tut auch nicht so, als wäre es anders: compositions[] erklärt den Graphen als unvollständig — CycloneDX' native Form, ein bekanntes Unbekanntes auszusprechen.
Was bedeuten die kunnus:unknown:*-Properties an einer Komponente?
Dass eine CISA-Mindestangabe nicht ermittelbar war: producer, version, hash oder license. CISA verlangt, dass ein SBOM-Autor einen unbekannten Wert ausspricht, statt ihn stillschweigend wegzulassen, und CycloneDX 1.6 hat dafür keinen Marker auf Feldebene — deshalb diese Properties. Sie bedeuten immer „dem Scanner unbekannt“, nie „bekannt, aber zurückgehalten“. Eine Komponente mit Hersteller, Version, Hash oder Lizenz trägt den jeweiligen Marker nicht.
Eine Komponente, die früher doppelt auftauchte, steht jetzt nur noch einmal drin — was hat sich geändert?
Sie haben einen deklarierten Constraint und einen aufgelösten Pin nebeneinander gesehen: Das Manifest sagt >=2.0, das Lockfile 2.31.0, und die unterschiedlichen purls verhinderten das Zusammenführen. Die Phantom-Hälfte trug eine nie veröffentlichte Version und eine CPE, die auf kein Advisory passt — deshalb entfällt sie bei Cargo, NuGet und Python, sofern ein Lockfile das Manifest tatsächlich abdeckt. Hat ein Projekt kein Lockfile, bleiben seine Deklarationen unangetastet: Eine Komponente zu verlieren wäre schlimmer, als eine doppelt zu listen.
Teilen sich Rescans desselben Produkts eine Seriennummer?
Nur wenn Sie eine Identität mitgeben: --component-id (plus --component-version) macht die Seriennummer deterministisch, Rescans bilden dann eine Dokumentenserie. Container-Scans einer Registry-Referenz bekommen das kostenlos aus der Image-Referenz. Ohne Identitäts-Flags erhält jeder Lauf eine frische zufällige Seriennummer — siehe den Guide zur SBOM-Identität.