Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Plugin-API-Referenz Vollständige API-Referenz für Inspector-Sbomgen-Lua-Plugins. Eine Anleitung zum Schreiben von Plugins finden Sie unter. [Leitfaden für Plugin-Entwickler](sbomgen-plugin-developer-guide.md) Informationen zum Testen finden Sie unter[Leitfaden zum Testen von Plugins](sbomgen-plugin-testing-guide.md). ## -Übersicht Auf alle von der Laufzeit bereitgestellten Funktionen wird über die globale `sbomgen` Tabelle zugegriffen (Datei-I/O, Regex, Protokollierung, Konstanten usw.). Darüber hinaus definiert jedes Plugin einen kleinen Satz globaler Funktionen der obersten Ebene (`discover`,,, usw.) `collect` `get_scanner_name``subscribe_to_event`, die sbomgen an definierten Punkten im Plugin-Lebenszyklus aufruft. Diese sind dokumentiert in. [Globaler Lebenszyklus von Plugins](#sbomgen-plugin-api-reference-plugin-lifecycle-globals) In `*_test.lua` Dateien stellt sbomgen zusätzlich eine `testing` globale Option zur Verfügung, die es Testautoren ermöglicht, die Discovery→Collection-Pipeline zu steuern und Aussagen zu treffen. Siehe [API testen](#sbomgen-plugin-api-reference-testing-api). ### Sandbox-Einschränkungen Plugins werden in einer Sandbox-Lua-VM mit eingeschränktem Zugriff auf die Standardbibliothek ausgeführt. **Die folgenden Lua-Standardbibliotheksmodule sind verfügbar:** | **Modul** | **Hinweise** | | --- | --- | | base | Kernfunktionen (printtype,tostring,tonumber,pairs,ipairs,pcall,error,select,unpack, rawgetrawset,, usw.). dofile,loadfile, und loadstring werden entfernt. | | string | Vollständige Bearbeitung von Zeichenketten (string.matchstring.findstring.format,string.gsub,, usw.) | | table | Vollständige Tabellenmanipulation (table.inserttable.remove,table.sort,table.concat, usw.) | | math | Vollständige Mathe-Bibliothek (math.floormath.maxmath.min,, usw.) | | package | require()ist verfügbar, aber auf Module innerhalb des eigenen Verzeichnisbaums des Plugins beschränkt. Das Durchqueren des übergeordneten Verzeichnisses () ist blockiertrequire("../shared"). package.cpathund sind gelöscht. package.path | Die folgenden Standardbibliotheksmodule sind aus Sicherheits- und Stabilitätsgründen **ausdrücklich nicht zulässig**: | **Modul** | **Grund** | | --- | --- | | io | Der direkte Dateisystemzugriff ist blockiert. Alle Dateioperationen müssen sbomgen.\* Funktionen durchlaufen, die über die Artefaktschnittstelle weitergeleitet werden, um ein einheitliches Verhalten bei allen Artefakttypen (Verzeichnis, Container, Volume usw.) zu gewährleisten. | | os | Operationen auf Systemebene (os.execute,, os.removeos.rename, usw.) werden blockiertos.getenv, um zu verhindern, dass Plugins das Hostsystem verändern. | | debug | Die Debug-Bibliothek ist blockiert, um eine Überprüfung oder Änderung der internen Funktionen der Lua-VM zu verhindern. | | coroutine | Coroutinen werden nicht geladen. | Diese Module befinden sich nicht in der Zulassungsliste der VM und sie können nicht von Plugins abgerufen werden. **Anmerkung** **Wichtig:** Alle Dateien I/O müssen `sbomgen.*` Funktionen (z. B., `sbomgen.read_file``sbomgen.open_file`,`sbomgen.get_file_list`) durchlaufen. Die Verwendung von `io.open` oder irgendein direkter Dateisystemzugriff führt zu einem Laufzeitfehler. Die `sbomgen` API stellt sicher, dass Plugins mit der Artefakt-Abstraktionsebene interagieren, was für ein einheitliches Verhalten sorgt, unabhängig davon, ob ein Verzeichnis, ein Container-Image, ein Archiv oder ein Volume gescannt wird. ## Globaler Lebenszyklus von Plugins Ein Plugin ist eine Lua-Datei mit dem Namen`init.lua`, die bestimmte globale Funktionen der obersten Ebene definiert. Diese Globals sind **nicht** in der `sbomgen` Tabelle enthalten — es sind Funktionen, die das Plugin für den Aufruf durch sbomgen definiert. Der Satz gültiger Globalwerte unterscheidet sich zwischen Discovery-Plugins und Sammlungs-Plugins. Wenn das Plugin sie auslässt, wird für jede der unten aufgeführten Funktionen die in der Tabelle angegebene Standardeinstellung verwendet. ### Discovery-Plugins | **Funktion** | **Arity** | **Erforderlich** | **Standard (wenn weggelassen)** | **Beschreibung** | | --- | --- | --- | --- | --- | | discover() | 0 | Ja | — | Gibt die Dateien zurück, die dieses Plugin gefunden hat. Gibt eine sequentielle Tabelle mit Pfadzeichenfolgen zurück (Einzelereignismodus) oder eine Tabelle, die durch Zeichenketten mit Ereignisnamen gekennzeichnet ist, deren Werte Pfadtabellen sind (Mehrereignismodus). | | get\_event\_name() | 0 | Nein | "lua:{platform}/{category}/{ecosystem}" | Gibt den Namen des Ereignisses zurück, unter dem Dateien veröffentlicht werden. Muss für alle Discovery-Plugins eindeutig sein. | | get\_scanner\_name() | 0 | Nein | Name des Ökosystem-Verzeichnisses | Gibt den Anzeigenamen des Scanners zurück. Muss für alle Discovery-Plug-ins eindeutig sein. | | get\_scanner\_description() | 0 | Nein | "Lua discovery plugin: {ecosystem}" | Gibt eine für Menschen lesbare Beschreibung zurück. | | get\_scanner\_groups() | 0 | Nein | Abgeleitet aus dem Kategorieverzeichnis (siehe Entwicklerhandbuch) | Gibt eine Tabelle mit Zeichenketten für Scanner-Gruppen zurück. Verwenden Sie sbomgen.groups.\* Konstanten. | | get\_localhost\_scan\_paths() | 0 | Nein | — | Gibt eine Tabelle mit file/directory Pfaden zurück, die beim Scannen eines Localhost-Artefakts berücksichtigt werden sollen. Wird nur für Scans verwendetlocalhost. | ### Plugins für Sammlungen | **Funktion** | **Arity** | **Erforderlich** | **Standard (wenn weggelassen)** | **Beschreibung** | | --- | --- | --- | --- | --- | | collect(file\_path) | 1 | Ja | — | Wird einmal pro Datei aufgerufen, die für das abonnierte Ereignis veröffentlicht wurde. Analysiert die Datei und sendet die Ergebnisse über. sbomgen.push\_package() Gibt nichts zurück. | | subscribe\_to\_event() | 0 | Nein | "lua:{platform}/{category}/{ecosystem}" | Gibt den Namen des Ereignisses zurück, den dieser Collector abonniert hat. Sollte mit den entsprechenden Discovery-Plug-ins get\_event\_name() übereinstimmen. | | get\_collector\_name() | 0 | Nein | Name des Ökosystem-Verzeichnisses | Gibt den Anzeigenamen des Collectors zurück. Muss für alle Sammlungs-Plugins eindeutig sein. | | get\_collector\_description() | 0 | Nein | ""(leer) | Gibt eine für Menschen lesbare Beschreibung zurück. | ## Datei-E/A Alle Dateioperationen müssen über die `sbomgen.*` API abgewickelt werden. Direkter Dateisystemzugriff über die `io` Bibliothek von Lua ist nicht verfügbar (siehe[Sandbox-Einschränkungen](#sbomgen-plugin-api-reference-sandbox-restrictions)). Die `sbomgen` I/O Dateifunktionen werden über die Artifact-Schnittstelle weitergeleitet und stellen so sicher, dass Ihr Plugin identisch funktioniert, egal ob es ein Verzeichnis auf der Festplatte, ein Container-Image, ein komprimiertes Archiv oder ein gemountetes Volume scannt. ### `sbomgen.get_file_list()` Gibt alle Dateipfade im Artefakt als Tabelle mit Zeichenketten zurück. + **Gibt zurück:** `{string, ...}` — Tabelle mit absoluten Dateipfadzeichenfolgen + **Leistung:** Diese Funktion kopiert jeden Dateipfad im Artefakt als Lua-Zeichenfolge in die Lua-VM. Bei großen Artefakten (z. B. einem Localhost-Scan mit mehr als 300.000 Dateien) dauert dies allein mehrere Sekunden. Das Iterieren der zurückgegebenen Tabelle in Lua mit `string.match()` fügt weiteren Aufwand hinzu — ein vollständiger Scan kann mehr als 15 Sekunden dauern. **Je mehr Dateien das Artefakt enthält, desto langsamer wird dein Plugin sein.** **Anmerkung** **Bevorzugen Sie diese gezielten Alternativen, wann immer dies möglich ist:** | **Funktion** | **Verwenden Sie, wenn...** | | --- | --- | | sbomgen.find\_files\_by\_name() | Sie kennen die genauen Dateinamen, die übereinstimmen sollen (z. B."requirements.txt","curl") | | sbomgen.find\_files\_by\_name\_icase() | Wie oben, aber unabhängig von Groß- und Kleinschreibung | | sbomgen.find\_files\_by\_suffix() | Sie müssen Pfadsuffixe abgleichen (z. B.,,) "/pom.properties" "curlver.h" | | sbomgen.find\_files\_by\_path\_regex() | Sie benötigen einen vollständigen Pfadabgleich mit Regex | | sbomgen.glob\_find\_files() | Sie benötigen einen Basisnamenabgleich im Glob-Stil | Diese Funktionen führen den Abgleich außerhalb der Lua-VM durch und geben nur die übereinstimmenden Pfade zurück. Selbst bei 300.000 Dateiartefakten ist der Abgleich in weniger als 1 Millisekunde abgeschlossen. Verwenden Sie diese `get_file_list()` Option nur, wenn Ihre Abgleichslogik mit keinem der oben genannten Werte ausgedrückt werden kann. ``` -- AVOID in discovery plugins when possible: local files = sbomgen.get_file_list() for _, f in ipairs(files) do if string.match(f, "pattern$") then ... end end -- PREFER: local matches = sbomgen.find_files_by_name({"target-file.txt"}) ``` ### `sbomgen.read_file(path)` Liest den gesamten Inhalt einer Datei und gibt ihn als Zeichenfolge zurück. + **Gibt zurück:** `string, err` + Bei einem Fehler: `nil, error_string` ``` local content, err = sbomgen.read_file("/app/package.json") if err then sbomgen.log_error("read failed: " .. err) return end ``` ### `sbomgen.open_file(path)` Öffnet eine Datei zum Streamen von Lesevorgängen. Gibt ein FileHandle Objekt zurück. Verwenden Sie dies für große Dateien, bei denen das Laden des gesamten Inhalts in den Speicher nicht praktikabel ist. + **Gibt zurück:** `FileHandle, err` ``` local fh, err = sbomgen.open_file(path) if err then return end local line = fh:read_line() while line do -- process line line = fh:read_line() end fh:close() ``` ### `sbomgen.glob_find_files(pattern)` Gibt Dateien zurück, die einem `filepath.Match` Go-Glob-Muster entsprechen. Das Muster wird mit dem Basisdateinamen abgeglichen. + **Gibt zurück:** `{string, ...}, err` ``` local files, err = sbomgen.glob_find_files("*.txt") ``` Verwenden Sie `sbomgen.get_file_list()` with `string.match` für den vollständigen Pfadmusterabgleich. ### `sbomgen.find_files_by_name(names)` Gibt Dateien zurück, deren Basisname (letzte Pfadkomponente) genau mit einem der angegebenen Namen übereinstimmt. Die Iteration und der Vergleich erfolgen in Go, was dies deutlich schneller macht als die Iteration `sbomgen.get_file_list()` in Lua. + **Parameter:** `names` — Tabelle mit Zeichenketten (passende Basisnamen) + **Gibt zurück:** `{string, ...}` — übereinstimmende Dateipfade (kein Fehlertupel) ``` local curl_bins = sbomgen.find_files_by_name({"curl", "curl.exe"}) local headers = sbomgen.find_files_by_name({"curlver.h"}) ``` ### `sbomgen.find_files_by_name_icase(names)` Gibt Dateien zurück, deren Basisname mit einem der angegebenen Namen übereinstimmt, wobei Groß- und Kleinschreibung ignoriert wird. Stimmt beispielsweise `"version"` mit `VERSION``Version`, und überein. `version` Der `find_files_by_name` Abgleich findet sozusagen außerhalb der Lua-VM statt. + **Parameter:** `names` — Tabelle mit Zeichenketten (abzugleichende Basisnamen, Groß- und Kleinschreibung wird nicht beachtet) + **Gibt zurück:** `{string, ...}` — übereinstimmende Dateipfade (kein Fehlertupel) ``` local version_files = sbomgen.find_files_by_name_icase({"version"}) local war_files = sbomgen.find_files_by_name_icase({"jenkins.war"}) ``` ### `sbomgen.find_files_by_suffix(suffixes)` Gibt Dateien zurück, deren vollständiger Pfad (forward-slash-normalized) mit einem der angegebenen Suffixe endet. Der Abgleich findet `find_files_by_name` sozusagen außerhalb der Lua-VM statt. + **Parameter:** `suffixes` — Tabelle mit Zeichenketten (passende Pfadsuffixe) + **Gibt zurück:** `{string, ...}` — übereinstimmende Dateipfade (kein Fehlertupel) ``` local pom_files = sbomgen.find_files_by_suffix({"/pom.properties"}) local release_headers = sbomgen.find_files_by_suffix({"ap_release.h", "opensslv.h"}) ``` ### `sbomgen.find_files_by_path_regex(patterns)` Gibt Dateien zurück, deren forward-slash-normalized Pfad mit einem der angegebenen Go (RE2) -Regex-Muster übereinstimmt. Der Abgleich erfolgt außerhalb der Lua-VM, was dies bei großen Dateilisten effizient macht. + **Parameter:** `patterns` — Tabelle mit Go-Regex-Zeichenketten + **Gibt zurück:** `{string, ...}` — passende Dateipfade (kein Fehlertupel) + **Löst aus:** einen Lua-Fehler, wenn ein Muster nicht kompiliert werden kann ``` local configs = sbomgen.find_files_by_path_regex({"/etc/.*\\.conf$", "/opt/.*/config\\.json$"}) ``` ### Leistung: vs `find_files_by_*` `get_file_list` Bei Discovery-Plugins sollten Sie lieber `find_files_by_name` oder `find_files_by_path_regex` lieber `get_file_list()` in Lua iterieren. `find_files_by_suffix` Bei einem Localhost-Scan mit 300.000 Dateien `string.match()` dauert die Iteration der Dateiliste in Lua mit \~15 Sekunden und ist in weniger als 1 Millisekunde abgeschlossen. `find_files_by_name` Der Unterschied besteht darin, dass jeder Dateipfad als Zeichenfolge in die Lua-VM `get_file_list()` kopiert wird. Anschließend interpretiert Lua die Schleife und den Mustervergleich für jeden einzelnen. Die `find_files_by_*` Funktionen führen den Abgleich außerhalb der Lua-VM durch und geben nur die übereinstimmenden Pfade zurück, wodurch sowohl der Kopier- als auch der Interpretationsaufwand pro Pfad vermieden wird. Verwenden Sie diese `get_file_list()` Option nur, wenn Sie eine benutzerdefinierte Abgleichslogik benötigen, die nicht als Basisname, Suffix oder Regex-Übereinstimmung ausgedrückt werden kann. ### `sbomgen.read_dir(path)` Listet Einträge in einem Verzeichnis auf. + **Gibt zurück:** `{{name, is_dir}, ...}, err` ``` local entries, err = sbomgen.read_dir("/app/node_modules") if err then return end for _, e in ipairs(entries) do if e.is_dir then sbomgen.log_debug("directory: " .. e.name) end end ``` ### `sbomgen.file_stat(path)` Gibt Metadaten zu einer Datei zurück. + **Gibt zurück:** `{is_regular, is_dir, size}, err` ``` local info, err = sbomgen.file_stat(path) if err then return end if info.is_regular and info.size > 0 then -- process file end ``` ### `sbomgen.read_zip_entry(path, entry_path)` Liest einen einzelnen Eintrag aus einem ZIP-, JAR- oder WAR-Archiv. + **Gibt zurück:** `string, err` ``` local manifest, err = sbomgen.read_zip_entry( "/app/lib/example.jar", "META-INF/MANIFEST.MF" ) ``` ### `sbomgen.search_binary(path, regex)` Analysiert eine Datei als ELF-, PE- oder Mach-O-Binärdatei und durchsucht den constant/variable Standardabschnitt nach einer Go-Regex-Übereinstimmung. + **Gibt zurück:** `string|nil, err` — die übereinstimmende Zeichenfolge oder nil, wenn keine Übereinstimmung vorliegt ``` local version, err = sbomgen.search_binary(path, "Version:\\s+([\\d.]+)") if version then sbomgen.log_info("found version: " .. version) end ``` ### `sbomgen.search_binary_all(path, regex [, n])` Analysiert eine Datei als ELF-, PE- oder Mach-O-Binärdatei und gibt alle eindeutigen Treffer der ersten Capture-Gruppe aus dem Standardabschnitt zurück. constant/variable Übergeben, `n` um die Ergebnisse einzuschränken. + **Gibt zurück:** `{string, ...}|nil, err` — Tabelle mit übereinstimmenden Zeichenketten oder Null, wenn keine Treffer gefunden wurden ``` local versions, err = sbomgen.search_binary_all(path, "version[= ]+([\\d.]+)", 5) if versions then for _, v in ipairs(versions) do sbomgen.log_info("found: " .. v) end end ``` ### `sbomgen.search_binary_raw(path, regex)` Durchsucht die gesamte Binärdatei nach der ersten Regex-Übereinstimmung und ist nicht auf einen bestimmten Abschnitt beschränkt. Wird verwendet, wenn die abschnittsbasierte Suche (`search_binary`) nicht ausreicht, z. B. wenn sich Versionszeichenfolgen in Abschnitten befinden, die nicht dem Standard entsprechen. + **Gibt zurück:** `string|nil, err` — die übereinstimmende Zeichenfolge oder nil, wenn keine Übereinstimmung vorliegt ``` local version, err = sbomgen.search_binary_raw(path, "ProductVersion[\\x00\\s]+([\\d.]+)") ``` ## FileHandle Methoden FileHandle Objekte werden von zurückgegeben`sbomgen.open_file()`. ### `fh:read_line()` Liest die nächste Zeile (ohne das Zeilenumbruchzeichen). Kehrt `nil` bei EOF zurück. + **Retouren:** `string|nil, err` ### `fh:read(n)` Liest bis zu `n` Byte. Kehrt `nil` bei EOF zurück. + **Retouren:** `string|nil, err` ### `fh:close()` Schließt das Datei-Handle. Schließt die Griffe immer, wenn Sie fertig sind. ## Binäre Dienstprogramme ### `sbomgen.sha256(path)` Gibt den hexadezimalen SHA-256-Hash des Inhalts einer Datei zurück. + **Gibt zurück:** `string, err` ``` local hash, err = sbomgen.sha256("/app/bin/server") if hash then sbomgen.log_info("SHA-256: " .. hash) end ``` ### `sbomgen.contains_bytes(path, patterns)` Prüft, ob eine Datei jedes der angegebenen Byte-Muster enthält. Gibt eine Tabelle mit booleschen Werten in derselben Reihenfolge wie die Eingabemuster zurück. + **Gibt zurück:** `{bool, ...}, err` ``` local results, err = sbomgen.contains_bytes(path, { "\xff Go buildinf:", -- Go build identifier "/rustc/", -- Rust build identifier }) if results then local is_go = results[1] local is_rust = results[2] end ``` ### `sbomgen.get_pe_version_info(path)` Analysiert Windows PE-Versionsressourcen aus einer Binärdatei. Gibt eine Tabelle mit Versionsfeldern zurück, oder `nil, err` wenn die Datei keine PE-Binärdatei ist oder keine Versionsressource hat. + **Gibt zurück:** `{product_version, file_version, string_table}, err` Die `file_version` Felder `product_version` und stammen aus der `FixedFileInfo` PE-Struktur, formatiert als`"major.minor.build.revision"`. Das `string_table` Feld ist eine verschachtelte Tabelle, die mit einem **Gebietsschema-Code** versehen ist (z. B. `"040904B0"` für US-amerikanisches Unicode). Jedes Gebietsschema ist einer Tabelle mit name/value Paaren zugeordnet, die aus dem PE `StringFileInfo` (`ProductVersion`, `ProductName``FileDescription`, usw.) gezogen wurden. Eine PE-Binärdatei kann ein oder mehrere Gebietsschemas verfügbar machen. ``` local info, err = sbomgen.get_pe_version_info(file_path) if err then return end -- Fixed version fields (always flat) local product_ver = info.product_version -- e.g. "25.1.0.0" local file_ver = info.file_version -- e.g. "25.1.0.0" -- String table — iterate locales, or address a known locale by key for locale, fields in pairs(info.string_table or {}) do sbomgen.log_info(string.format("%s ProductName=%s", locale, fields.ProductName or "")) end -- US English Unicode is the most common locale for PE files local us = (info.string_table or {})["040904B0"] if us then local display_ver = us.ProductVersion -- e.g. "25.01" local name = us.ProductName -- e.g. "7-Zip" end ``` ### `sbomgen.parse_product_version(path)` Praktischer Wrapper, der nur die Produktversionszeichenfolge einer PE-Binärdatei zurückgibt. FixedFileInfo Entspricht dem Aufrufen `get_pe_version_info(path)` und Lesen`product_version`. + **Gibt zurück:** `string, err` ``` local version, err = sbomgen.parse_product_version(file_path) if version then sbomgen.log_info("product version: " .. version) end ``` ### `sbomgen.parse_file_version(path)` Praktischer Wrapper, der nur die Dateiversionszeichenfolge aus einer PE-Binärdatei zurückgibt. FixedFileInfo Entspricht dem Aufrufen `get_pe_version_info(path)` und Lesen`file_version`. + **Gibt zurück:** `string, err` ``` local version, err = sbomgen.parse_file_version(file_path) if version then sbomgen.log_info("file version: " .. version) end ``` ## Paket-Ausgabe ### `sbomgen.push_package(pkg)` Verschiebt eine Paketsuche in die SBOM. Nur in Sammlungs-Plugins verfügbar. Die `pkg` Tabelle unterstützt die folgenden Felder: | **Feld** | **Typ** | **Erforderlich** | **Beschreibung** | | --- | --- | --- | --- | | name | Zeichenfolge | Ja | Package name | | version | Zeichenfolge | Nein | Aufgelöste Versionszeichenfolge | | namespace | Zeichenfolge | Nein | PURL-Namespace (z. B.,,"curl") "wordpress/plugin" | | purl\_type | Zeichenfolge | Ja | PURL-Typ (z. B.,,,"pypi","npm","cargo") "deb" "generic" | | component\_type | Zeichenfolge | Ja | CyclonedX-Komponententyp; verwendet sbomgen.component\_types.\* Konstanten (z. B.) sbomgen.component\_types.LIBRARY | | qualifiers | Tabelle | Nein | PURL-Qualifizierer als Schlüssel-Wert-Paare (erscheinen in der Paket-URL) | | properties | Tabelle | Nein | Eigenschaften von CyclonedX-Komponenten als Schlüssel-Wert-Paare (siehe) [CyclonedX-Eigenschaften](#sbomgen-plugin-api-reference-cyclonedx-properties) | | children | Tabelle | Nein | Verschachtelte untergeordnete Pakete, jedes mit derselben Form wie pkg (Pflichtfelder werden rekursiv validiert) | ``` sbomgen.push_package({ name = "requests", version = "2.28.1", purl_type = "pypi", component_type = sbomgen.component_types.LIBRARY, qualifiers = { example_qualifier = "example_qualifier_value" }, properties = { -- Use your own namespace; amazon:inspector:* is reserved for Amazon Inspector. ["acme:example:extra_field"] = "example_value", }, }) ``` ## CyclonedX-Eigenschaften CyclonedX-Eigenschaften sind Schlüsselwertmetadaten, die an eine Komponente in der SBOM angehängt sind. Sie unterscheiden sich von PURL-Qualifizierern: + **`qualifiers`**— PURL-Qualifizierer. Diese werden Teil der Paket-URL-Zeichenfolge (z. B.`pkg:deb/debian/curl@7.88.1?arch=amd64`). Einige PURL-Qualifier haben für Amazon Inspector eine semantische Bedeutung und beeinflussen die Identifizierung von Sicherheitslücken. Siehe [Was ist eine](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) Paket-URL? für die spezifischen Konventionen von Inspector. + **`properties`**— Eigenschaften der CyclonedX-Komponente. Diese erscheinen im `components[].properties` Array der SBOM und ändern nicht, wie die Komponente identifiziert wird. ### Reservierte Namespaces Die `amazon:inspector:*` Familie der CyclonedX-Eigenschaftsnamespaces ist Amazon Inspector vorbehalten: + `amazon:inspector:sbom_generator:*`— wird von sbomgen und seinen eingebauten Scannern verwendet. + `amazon:inspector:sbom_scanner:*`— wird von der Amazon Inspector Scan API verwendet. **Von Plugins definierte Eigenschaften dürfen diese Namespaces nicht verwenden.** Das Schreiben in einen reservierten Namespace kann Werte, auf die sich Inspector stützt, überlagern oder mit ihnen in Konflikt geraten, und die resultierende SBOM kann bei der Identifizierung von Sicherheitslücken falsch interpretiert werden. Eine vollständige [Liste der reservierten Schlüssel finden Sie unter Verwenden von CyclonedX-Namespaces mit Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html). ### Regeln zur Benennung von Schlüsseln Eigenschaftsschlüssel, die an übergeben wurden, `sbomgen.push_package()` werden wie folgt verarbeitet: | **Eingabeschlüssel** | **Resultierender Schlüssel in SBOM** | **Für benutzerdefinierte Plugins empfohlen?** | | --- | --- | --- | | Enthält : (z. B.acme:my\_plugin:field) | Wird wörtlich verwendet | Ja — platziere jede vom Plugin definierte Eigenschaft in deinem eigenen Namespace | | Nein : (z. B.) field | Automatisch mit dem Präfix amazon:inspector:sbom\_generator:field | Nein — das schreibt in einen reservierten Namespace | Fügen Sie in Eigenschaftsschlüsseln, die Sie definieren, immer mindestens einen Doppelpunkt ein. Verwenden Sie einen Namespace, der für Ihre Organisation oder Ihr Plugin einzigartig ist (zum Beispiel`acme:python-pip:*`): ``` properties = { -- Custom namespace — safe to use (recommended) ["acme:python-pip:manifest_path"] = file_path, ["acme:python-pip:pinned"] = "true", -- Fully-qualified key outside amazon:inspector:* — also fine ["my:custom:namespace:key"] = "value", -- No colon: avoid — ends up as "amazon:inspector:sbom_generator:custom_field" -- custom_field = "value", } ``` ### Von sbomgen festgelegte Eigenschaften Sbomgen kann jeder Komponente, die es ausgibt, eigene Eigenschaften zuweisen. Diese Werte stammen aus dem reservierten `amazon:inspector:sbom_generator:*` Namespace und sollten nicht von Plugins erzeugt werden. Beobachtetes Laufzeitverhalten: + `source_path`wird immer von sbomgen hinzugefügt. + `source_file_scanner`und `source_package_collector` werden hinzugefügt, wenn es aktiviert `--enable-debug-props` ist. Die vollständige Taxonomie der reservierten Schlüssel finden Sie im Amazon Inspector-Benutzerhandbuch: [Verwenden von CyclonedX-Namespaces](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) mit Amazon Inspector. ## Eigenschaftenkonstanten Integrierte Eigenschaftsschlüsselkonstanten sind über verfügbar. `sbomgen.properties` Jede der folgenden Konstanten wird zu einem Schlüssel innerhalb des reservierten `amazon:inspector:sbom_generator:*` Namespaces aufgelöst. Diese Konstanten existieren, sodass die integrierten Scanner von sbomgen konsistente Eigenschaftsschlüssel ausgeben. **Sie sind keine Erweiterungspunkte für benutzerdefinierte Plugins** — wenn sie in einem benutzerdefinierten Plugin verwendet werden, wird in einen reservierten Namespace geschrieben, der Werte überschatten kann, auf die sich Inspector stützt. Siehe [Reservierte Namespaces](#sbomgen-plugin-api-reference-reserved-namespaces) oben. Autoren benutzerdefinierter Plugins sollten Eigenschaften (zum Beispiel`acme:my_plugin:*`) in ihrem eigenen Namespace definieren, anstatt diese Konstanten wiederzuverwenden. | **Konstante** | **Gelöster Wert** | | --- | --- | | sbomgen.properties.NAMESPACE | amazon:inspector:sbom\_generator: | | sbomgen.properties.VENDOR | amazon:inspector:sbom\_generator:vendor | | sbomgen.properties.FILE\_SIZE\_BYTES | amazon:inspector:sbom\_generator:file\_size\_bytes | | sbomgen.properties.KERNEL\_COMPONENT | amazon:inspector:sbom\_generator:kernel\_component | | sbomgen.properties.RUNNING\_KERNEL | amazon:inspector:sbom\_generator:running\_kernel | | sbomgen.properties.UNRESOLVED\_VERSION | amazon:inspector:sbom\_generator:unresolved\_version | | sbomgen.properties.TRANSITIVE\_DEPENDENCY | amazon:inspector:sbom\_generator:experimental:transitive\_dependency | | sbomgen.properties.GO\_REPLACE\_DIRECTIVE | amazon:inspector:sbom\_generator:replaced\_by | | sbomgen.properties.DUPLICATE\_PACKAGE | amazon:inspector:sbom\_generator:is\_duplicate\_package | | sbomgen.properties.DUPLICATE\_PURL | amazon:inspector:sbom\_generator:duplicate\_purl | | sbomgen.properties.DOCKERFILE\_CHECK | amazon:inspector:sbom\_generator:dockerfile\_finding | | sbomgen.properties.CERTIFICATE\_FINDING | amazon:inspector:sbom\_generator:certificate\_finding | | sbomgen.properties.CERTIFICATE\_SUBJECT\_NAME | amazon:inspector:sbom\_generator:certificate:subject\_name | | sbomgen.properties.CERTIFICATE\_ISSUER\_NAME | amazon:inspector:sbom\_generator:certificate:issuer\_name | | sbomgen.properties.CERTIFICATE\_SIGNATURE\_ALGORITHM | amazon:inspector:sbom\_generator:certificate:signature\_algorithm | | sbomgen.properties.CERTIFICATE\_NOT\_VALID\_BEFORE | amazon:inspector:sbom\_generator:certificate:not\_valid\_before | | sbomgen.properties.CERTIFICATE\_NOT\_VALID\_AFTER | amazon:inspector:sbom\_generator:certificate:not\_valid\_after | | sbomgen.properties.WINDOWS\_REGISTRY\_KEY | amazon:inspector:sbom\_generator:registry\_key | | sbomgen.properties.SUBSCRIPTION\_ENABLED | amazon:inspector:sbom\_generator:subscription:enabled | | sbomgen.properties.SUBSCRIPTION\_NAME | amazon:inspector:sbom\_generator:subscription:name | | sbomgen.properties.SUBSCRIPTION\_LOCKED\_VERSION | amazon:inspector:sbom\_generator:subscription:locked\_version | | sbomgen.properties.OPENSSL\_FULL\_VERSION | amazon:inspector:sbom\_generator:openssl:full\_version | | sbomgen.properties.HARDENED\_IMAGE\_VENDOR | amazon:inspector:sbom\_generator:hardened\_image:vendor | ## Scanner-Gruppen Discovery-Plugins müssen ihre Scanner-Gruppen über deklarieren`get_scanner_groups()`. Gruppen kategorisieren Scanner und ermöglichen es Benutzern, Kategorien selektiv zu aktivieren oder zu deaktivieren. Konstanten sind verfügbar über: `sbomgen.groups` | **Konstante** | **Wert** | **Beschreibung** | | --- | --- | --- | | sbomgen.groups.OS | "os" | Betriebssystem-Paketmanager (dpkg, rpm usw.) | | sbomgen.groups.PROGRAMMING\_LANGUAGE | "programming-language-packages" | Sprachpaketmanager (pip, npm, maven usw.) | | sbomgen.groups.BINARY | "binary" | Kompilierte Binäranalyse (Go, Rust) | | sbomgen.groups.PACKAGE\_COLLECTOR | "pkg-scanner" | Allgemeine Paketabholung | | sbomgen.groups.EXTRA\_ECOSYSTEMS | "extra-ecosystems" | Zusätzliche Ökosysteme (Curl, Nginx usw.) | | sbomgen.groups.CERTIFICATE | "certificate" | Scannen von Zertifikaten | | sbomgen.groups.CUSTOM | "custom" | Wird automatisch zu allen benutzerdefinierten Plugins hinzugefügt, die über geladen wurden --plugin-dir | | sbomgen.groups.MACHINE\_LEARNING | "machine-learning" | Modellerkennung durch maschinelles Lernen | Beispiel: ``` function get_scanner_groups() return {sbomgen.groups.PROGRAMMING_LANGUAGE, sbomgen.groups.PACKAGE_COLLECTOR} end ``` ## Konstanten für den Komponententyp Das `component_type` Feld in `push_package()` muss einer der CyclonedX 1.5-Komponententypen sein. Konstanten sind verfügbar über: `sbomgen.component_types` | **Konstante** | **Wert** | | --- | --- | | sbomgen.component\_types.APPLICATION | "application" | | sbomgen.component\_types.FRAMEWORK | "framework" | | sbomgen.component\_types.LIBRARY | "library" | | sbomgen.component\_types.CONTAINER | "container" | | sbomgen.component\_types.PLATFORM | "platform" | | sbomgen.component\_types.OPERATING\_SYSTEM | "operating-system" | | sbomgen.component\_types.DEVICE | "device" | | sbomgen.component\_types.DEVICE\_DRIVER | "device-driver" | | sbomgen.component\_types.FIRMWARE | "firmware" | | sbomgen.component\_types.FILE | "file" | | sbomgen.component\_types.MACHINE\_LEARNING\_MODEL | "machine-learning-model" | | sbomgen.component\_types.DATA | "data" | Beispiel: ``` sbomgen.push_package({ name = "requests", version = "2.28.1", purl_type = "pypi", component_type = sbomgen.component_types.LIBRARY, }) ``` ## Plattformkonstanten Konstanten zum Vergleich mit. `sbomgen.get_platform()` Verfügbar über`sbomgen.platform`: | **Konstante** | **Wert** | | --- | --- | | sbomgen.platform.LINUX | "linux" | | sbomgen.platform.WINDOWS | "windows" | | sbomgen.platform.DARWIN | "darwin" | Beispiel: ``` if sbomgen.get_platform() == sbomgen.platform.WINDOWS then -- Windows-specific logic end ``` ## Informationen zum Artifact ### `sbomgen.get_platform()` Gibt die Zeichenfolge der Laufzeitplattform zurück (z. B.,`"linux"`,`"windows"`,`"darwin"`). ### `sbomgen.get_artifact_type()` Gibt den Typ des Artefakts zurück, das gescannt wird (z. B.`"directory"`,`"archive"`). ### `sbomgen.should_collect_licenses()` Gibt zurück`true`, ob der Benutzer die Lizenzerfassung über `--collect-licenses` aktiviert hat. ### `sbomgen.get_env_vars()` Gibt Umgebungsvariablen aus dem Artefakt als Tabelle mit `{key, value}` Einträgen zurück. ``` local env_vars = sbomgen.get_env_vars() for _, env in ipairs(env_vars) do if env.key == "NODE_ENV" then sbomgen.log_info("Node environment: " .. env.value) end end ``` ### `sbomgen.get_system_drive()` Gibt den Systemlaufwerksbuchstaben (z. B.`"C:"`) aus der Umgebung des Artefakts zurück. Liest die `SystemDrive` Umgebungsvariable und verwendet standardmäßig diese, `"C:"` falls sie nicht gesetzt ist. Dies ist das Lua-Äquivalent von. `strutils.GetSystemDriverLetter()` ``` local drive = sbomgen.get_system_drive() local program_files = drive .. "/Program Files/" ``` ## Informationen zum System Diese Funktionen geben Metadaten über das Betriebssystem und die Hardware des Artefakts zurück. Werte können leere Zeichenketten sein, wenn die Informationen nicht verfügbar sind (z. B. beim Scannen eines Verzeichnisses ohne Betriebssystem-Metadaten). | **Funktion** | **Rückgabewerte** | | --- | --- | | sbomgen.get\_os\_name() | Name des Betriebssystems (z. B.,"Ubuntu","Alpine Linux") | | sbomgen.get\_os\_version() | Betriebssystemversion (z. B.,"22.04","3.18") | | sbomgen.get\_os\_codename() | Betriebssystem-Codename (z. B.,,"jammy") "bookworm" | | sbomgen.get\_os\_id() | Betriebssystem-ID (z. B.,,"ubuntu") "alpine" | | sbomgen.get\_kernel\_name() | Kernelname (z. B."Linux") | | sbomgen.get\_kernel\_version() | Zeichenfolge für die Kernel-Version | | sbomgen.get\_cpu\_arch() | CPU-Architektur (z. B.,"x86\_64","aarch64") | | sbomgen.get\_hostname() | Hostname des Systems | ## Reguläre Ausdrücke Den integrierten Mustern von Lua fehlen Funktionen wie Alternation (`|`), Quantifier Ranges (`{n,}`) und Lookahead. Um diese Lücke zu schließen, stellt sbomgen das Paket von Go direkt zur Verfügung. `regexp` Diese Funktionen verwenden die Go-Regex-Syntax (RE2), keine Lua-Muster. ### `sbomgen.regex_find(str, pattern)` Gibt die erste Übereinstimmung mit einem Go-Regex-Muster zurück, oder wenn keine Übereinstimmung vorliegt. `nil` + **Gibt zurück:** `string|nil, err` ``` local version = sbomgen.regex_find(content, "\\d+\\.\\d+\\.\\d+") ``` ### `sbomgen.regex_match(str, pattern)` Gibt Capture-Gruppen aus dem ersten Spiel zurück. Index 1 ist die vollständige Übereinstimmung, 2\+ sind Capture-Gruppen. + **Gibt zurück:** `{string, ...}|nil, err` ``` local groups = sbomgen.regex_match(content, "(MySQL|MariaDB) (\\d+)\\.(\\d+)\\.(\\d+)") if groups then local db_type = groups[2] -- "MySQL" or "MariaDB" local major = groups[3] end ``` ### `sbomgen.regex_find_all(str, pattern [, n])` Gibt alle Treffer zurück, die sich nicht überschneiden. An `n` das Limit der Ergebnisse übergeben (Standardeinstellung: alle). + **Gibt zurück:** `{string, ...}|nil, err` ``` local versions = sbomgen.regex_find_all(content, "\\d+\\.\\d+\\.\\d+") ``` ### `sbomgen.regex_replace(str, pattern, replacement)` Ersetzt alle Treffer. Die Ersatzzeichenfolge kann `$1``$2`, usw. für Erfassungsgruppenverweise verwenden. + **Gibt zurück:** `string, err` ``` local cleaned = sbomgen.regex_replace(raw_version, "(1[6-9]\\d{8,}|buildkitsandbox.*)$", "") ``` ### Wann sollten Regex- und Lua-Muster verwendet werden Verwenden Sie das in Lua integrierte`string.match`/`string.find`für einfache Muster — sie sind schneller und erfordern keine maskierten Backslashes. Verwenden Sie `sbomgen.regex_*` es, wenn Sie Folgendes benötigen: + Abwechslung: `(foo|bar)` + Bereiche des Quantifizierers: `\d{8,}` + Komplexe Zeichenklassen, die in Lua-Mustern nicht ausgedrückt werden können ## Strukturiertes Parsen Sbomgen stellt einfache Hilfsprogramme zur Verfügung, mit denen strukturierte Textformate direkt in Lua-Tabellen dekodiert werden können. ### `sbomgen.json_decode(str)` Analysiert eine JSON-Zeichenfolge in eine Lua-Tabelle. + **Gibt zurück:** `table|nil, err` ``` local doc, err = sbomgen.json_decode('{"name":"requests","version":"2.28.1"}') if err then return end sbomgen.log_info(doc.name) ``` ### `sbomgen.xml_decode(str)` Analysiert eine XML-Zeichenfolge in eine Lua-Tabelle. + **Gibt zurück:** `table|nil, err` XML-Werte haben die folgende Form: + `_name`— Name des Elements + `_attr`— Attributtabelle, falls vorhanden + `_text`— getrimmter Textinhalt, falls vorhanden + numerische Indizes `1..n` — untergeordnete Elemente ``` local doc, err = sbomgen.xml_decode('') if err then return end sbomgen.log_info(doc._attr.id) ``` ## Windows Registry Diese Funktionen bieten schreibgeschützten Zugriff auf die Windows-Registrierung. Gibt bei Nicht-Windows-Artefakten einen Fehler `registry_open_key` zurück. Der Registrierungs-Accessor wird bei der ersten Verwendung verzögert initialisiert und unterstützt sowohl Live-Windows-API-Zugriff (Localhost-Scans unter Windows) als auch dateibasiertes REGF-Hive-Parsing (Container-/Volume-Scans). ### `sbomgen.registry_open_key(path)` Öffnet einen Registrierungsschlüssel. Gibt ein Schlüssel-Handle zurück, das mit geschlossen werden muss`registry_close`. + **Gibt zurück:** `key, err` ``` local key, err = sbomgen.registry_open_key("SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\7-Zip") if err then return end -- use key... sbomgen.registry_close(key) ``` ### `sbomgen.registry_get_string(key, value_name)` Liest einen Zeichenkettenwert aus einem geöffneten Registrierungsschlüssel. + **Gibt zurück:** `string, err` ``` local version, err = sbomgen.registry_get_string(key, "DisplayVersion") ``` ### `sbomgen.registry_get_integer(key, value_name)` Liest einen Integer-Wert aus einem geöffneten Registrierungsschlüssel. + **Gibt zurück:** `number, err` ### `sbomgen.registry_get_strings(key, value_name)` Liest einen Wert mit mehreren Zeichenketten (REG\_MULTI\_SZ) aus einem geöffneten Registrierungsschlüssel. Gibt eine Tabelle mit Zeichenketten zurück. + **Gibt zurück:** `{string, ...}, err` ``` local paths, err = sbomgen.registry_get_strings(key, "DependsOnService") if paths then for _, p in ipairs(paths) do sbomgen.log_info("depends on: " .. p) end end ``` ### `sbomgen.registry_get_subkeys(key)` Gibt alle Unterschlüsselnamen unter einem geöffneten Registrierungsschlüssel zurück. + **Gibt zurück:** `{string, ...}, err` ``` local subkeys, err = sbomgen.registry_get_subkeys(key) for _, name in ipairs(subkeys) do local subkey, err = sbomgen.registry_open_key(parent_path .. "\\" .. name) -- ... end ``` ### `sbomgen.registry_close(key)` Schließt ein Registrierungsschlüssel-Handle. Schlüsselhandles werden ebenfalls automatisch vom Garbage-Collector geschlossen, es wird jedoch empfohlen, sie explizit zu schließen. ## Protokollierung Protokollnachrichten werden in die Konsolenausgabe von sbomgen geschrieben. Jeder Nachricht, die von einem Plugin ausgegeben wird, wird automatisch das Quelllabel und das Ökosystem des Plugins vorangestellt, zum Beispiel: ``` [custom:python-pip] Parsing requirements.txt ``` `log_info``log_warn`, und `log_error` immer drucken. `log_debug`druckt nur, wenn sbomgen mit aufgerufen wird. `--verbose` | **Funktion** | **Stufe** | **Standardmäßig sichtbar?** | | --- | --- | --- | | sbomgen.log\_debug(message) | DEBUG | Nein — erfordert --verbose | | sbomgen.log\_info(message) | INFO | Ja | | sbomgen.log\_warn(message) | WARN | Ja | | sbomgen.log\_error(message) | ERROR | Ja | `string.format`Für formatierte Nachrichten verwenden: ``` sbomgen.log_info(string.format("found %d packages in %s", count, file_path)) ``` ## Debugging-Funktionen ### `sbomgen.breakpoint(message)` Druckt `message` nach stderr und blockiert die Ausführung, bis der Benutzer die Eingabetaste drückt. Wenn nicht angegeben, `message` wird eine Standardnachricht gedruckt. Verwenden Sie dies als einfachen Debugger, indem Sie Breakpoints an wichtigen Punkten in Ihrem Plugin platzieren und mit ausführen, um die umliegende Protokollausgabe `--verbose` zu sehen. ``` sbomgen.log_info("state: " .. some_variable) sbomgen.breakpoint("paused after state dump — press Enter to continue") ``` ## API testen Funktionen in der globalen `testing` Tabelle sind nur in Plugin-Testdateien (`*_test.lua`) verfügbar, die von geladen wurden`inspector-sbomgen plugin test`. Sie sind zur Laufzeit in Discovery- oder Collection-Plugins nicht verfügbar. Die vollständige `sbomgen.*` API ist auch in Testdateien verfügbar, aber `sbomgen.*` Funktionen, die beispielsweise `sbomgen.read_file()` ein Artefakt erfordern, führen nur dann zu aussagekräftigen Ergebnissen, wenn sie innerhalb eines Scans aufgerufen werden. Eine ausführliche Anleitung finden Sie in der[Leitfaden zum Testen von Plugins](sbomgen-plugin-testing-guide.md). ### Funktionen scannen Jede Scanfunktion erzeugt ein Artefakt der angegebenen Art, führt die Discovery→Collection-Pipeline des aktuellen Plugins anhand dieses Artefakts durch und gibt die resultierenden Ergebnisse zurück. Das `path` Argument wird relativ zum Verzeichnis der Testdatei aufgelöst. | **Funktion** | **Art des Artefakts** | | --- | --- | | testing.scan\_directory(path) | Verzeichnis | | testing.scan\_archive(path) | Verzeichnis (Alias vonscan\_directory) | | testing.scan\_localhost(path) | Lokaler Host | | testing.scan\_binary(path) | Binär | | testing.scan\_volume(path) | Volume | | testing.scan\_container(path) | Behälter | Alle sechs geben eine Ergebnistabelle mit der folgenden Form zurück. ### Form des Ergebnisses Jede Suchtabelle projiziert nur die unten aufgeführten Felder. Insbesondere `namespace` und `purl_type` werden nicht separat projiziert — sie sind in der gesamten `purl` Zeichenfolge enthalten. ``` local result = testing.scan_directory("_testdata/example") -- result.findings -- array of finding tables -- result.findings[i].name -- string -- result.findings[i].version -- string -- result.findings[i].component_type -- string -- result.findings[i].purl -- string (the full Package URL, or "" if none) -- result.findings[i].properties -- table -- result.findings[i].children -- array of finding tables (same shape, recursive) ``` ### Assertionen | **Funktion** | **Signature** | **Beschreibung** | | --- | --- | --- | | testing.assert\_equals | (expected: any, actual: any, message?: string) | Schlägt fehl, wenntostring(expected) \~= tostring(actual). | | testing.assert\_not\_equals | (expected: any, actual: any, message?: string) | Schlägt fehl, wenntostring(expected) == tostring(actual). | | testing.assert\_true | (value: any, message?: string) | Schlägt fehl, wenn value es false oder istnil. | | testing.assert\_false | (value: any, message?: string) | Schlägt fehl, wenn value nicht false und nichtnil. | | testing.assert\_nil | (value: any, message?: string) | Schlägt fehlvalue, wenn nichtnil. | | testing.assert\_not\_nil | (value: any, message?: string) | Scheitert, wenn value es so istnil. | | testing.assert\_contains | (haystack: string, needle: string, message?: string) | Schlägt fehl, wenn haystack es nicht enthält needle (Teilzeichenfolge entspricht). | | testing.assert\_matches | (str: string, pattern: string, message?: string) | Schlägt fehl, wenn str es nicht mit der angegebenen Go (RE2) -Regex übereinstimmt. | | testing.assert\_length | (tbl: table, expected: integer, message?: string) | Schlägt fehl, wenn \#tbl nicht identisch. expected | ### Kontrollfluss | **Funktion** | **Signature** | **Beschreibung** | | --- | --- | --- | | testing.fail | (message: string) | Schlägt den aktuellen Test sofort mit der angegebenen Nachricht fehl. | | testing.skip | (message: string) | Überspringt den aktuellen Test. Das Ergebnis wird als übersprungen und nicht als Fehlschlag gemeldet. | ### Testen Sie die Entdeckung Jede globale Lua-Funktion, deren Name `test_` in einem Dateiabgleich mit „beginnt“, `*_test.lua` wird als Test behandelt. Die Testdatei muss neben und in der normalen `{phase}/{platform}/{category}/{ecosystem}/` Tiefe liegen. `init.lua` Die Fixture-Daten werden `_testdata/` neben der Testdatei eingegeben — der Runner rutscht nicht hinein, `_testdata/` wenn er nach Testdateien sucht. ## Fehlerbehandlung API-Funktionen, die fehlschlagen können, geben zwei Werte zurück:. `value, err` Bei Erfolg `err` ist`nil`. Bei einem Fehler ist `nil` und `err` ist der erste Wert eine Fehlerzeichenfolge. ``` local content, err = sbomgen.read_file(path) if err then sbomgen.log_error("failed to read " .. path .. ": " .. err) return end -- content is safe to use here ``` Wenn ein Plugin einen unbehandelten Lua-Fehler auslöst, protokolliert sbomgen eine Warnung und fährt mit der nächsten Datei oder dem nächsten Plugin fort. Andere Plugins sind nicht betroffen.