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. Parent-directory traversal (require("../shared")) ist blockiert. package.cpathund package.path sind gelöscht. |
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 weiterleiten, um ein einheitliches Verhalten bei allen Artefakttypen (Verzeichnis, Container, Volume usw.) zu gewährleisten und Lesevorgänge auf das Artefakt im Inventar zu beschränken (siehe). [Grenze für den Dateizugriff](#sbomgen-plugin-api-reference-file-access-boundary) |
| os | System-level Operationen (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 von Plugins nicht aufgerufen 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 I/O
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.
### Grenze für den Dateizugriff
Die `sbomgen.*` Dateifunktionen beschränken Lesevorgänge auf das Artefakt im Inventar. Ein Pfad, der außerhalb der Artefaktwurzel aufgelöst wird — zum Beispiel durch `../` Traversal — wird zurückgewiesen, und der Aufruf gibt einen Fehler zurück, anstatt das Host-Dateisystem zu lesen. Dies gilt für,`read_file`,`open_file`, und die binary/hash Helfer `read_dir``file_stat`, die einen Pfad verwenden.
Die Ausnahme ist der `localhost` Artefakttyp, der den Host selbst inventarisiert; dort ist das Host-Dateisystem das Artefakt, sodass Lesevorgänge nicht auf eine engere Wurzel beschränkt sind.
*Diese Grenze gilt nur für Lesevorgänge von Dateien.* Sie schränkt nicht ein, was ein Plugin in die SBOM schreibt — siehe. [Der SBOM-Inhalt wird nicht bereinigt](#sbomgen-plugin-api-reference-sbom-contents-not-sanitized)
### `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, denen Sie entsprechen müssen (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 Artefakten ist der Abgleich in weniger als 1 Millisekunde abgeschlossen. K-file Verwenden Sie diese `get_file_list()` Option nur, wenn Ihre Abgleichslogik mit keinem der oben genannten Werte ausgedrückt werden kann.
Die `glob_find_files` Hilfsprogramme `find_files_by_*` und überspringen Symlinks und geben nur konkrete Dateien zurück, sodass ein Symlink-Alias und sein Ziel nicht beide inventarisiert werden. `get_file_list()`gibt jeden Eintrag zurück, einschließlich Symlinks.
```
-- 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 (Pfad)`
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 (Pfad)`
Ö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 (Muster)`
Gibt Dateien zurück, die einem Go-Glob-Muster entsprechen. `filepath.Match` Das Muster wird mit dem Basisdateinamen abgeglichen. Symlinks werden übersprungen; es werden nur konkrete Dateien zurückgegeben.
+ **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 (Namen)`
Gibt Dateien zurück, deren Basisname (letzte Pfadkomponente) exakt einem der angegebenen Namen entspricht. 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, ausgenommen symbolische Links (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 (Namen)`
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, ohne symbolische Links (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 (Suffixe)`
Gibt Dateien zurück, deren vollständiger Pfad (durch Schrägstrich normalisiert) mit einem der angegebenen Suffixe endet. Der Abgleich findet sozusagen außerhalb der `find_files_by_name` Lua-VM statt.
+ **Parameter:** `suffixes` — Tabelle mit Zeichenketten (passende Pfadsuffixe)
+ **Gibt zurück:** `{string, ...}` — übereinstimmende Dateipfade, ohne symbolische Links (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 (Muster)`
Gibt Dateien zurück, deren durch Schrägstrich normalisierter Pfad mit einem der angegebenen Go-Regex-Muster (RE2) ü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, ...}` — übereinstimmende Dateipfade, ausgenommen symbolische Links (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: find_files_by_* vs get_file_list`
Ziehen Sie bei Discovery-Plugins die Iteration in Lua vor. `find_files_by_name` `find_files_by_suffix` `find_files_by_path_regex` `get_file_list()` 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 (Pfad)`
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 (Pfad)`
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 (Pfad, Eintragspfad)`
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 (Pfad, Regex)`
Analysiert eine Datei als ELF, PE oder Mach-O Binärdatei und durchsucht den Standardabschnitt nach einer Go-Regex-Übereinstimmung. constant/variable
+ **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 (Pfad, 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 (Pfad, regulärer Ausdruck)`
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.
+ **Gibt zurück:** `string|nil, err`
### `fh:read (n)`
Liest bis zu Byte. `n` 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.hash (Daten, Algorithmus)`
Gibt den hexadezimalen Digest einer speicherinternen Bytezeichenfolge unter dem angegebenen Algorithmus zurück. Kombinieren Sie mit`sbomgen.read_file(path)`, um eine Datei zu hashen, die Sie bereits zum Parsen gelesen haben. Dies ist vorzuziehen, `sbomgen.hash_file(path)` wenn Sie sowohl die Bytes als auch den Digest benötigen, da die Datei nicht erneut gelesen wird. `hash`
+ **Gibt zurück:** `string, err`
+ **Algorithmen:** Die Liste der akzeptierten Algorithmuskonstanten finden Sie unter[Komponenten-Hashes](#sbomgen-plugin-api-reference-component-hashes).
```
local data, err = sbomgen.read_file("/path/to/manifest.json")
if data then
local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)
sbomgen.log_info("SHA-256: " .. sha256)
end
```
### `sbomgen.hash_file (Pfad, Algorithmus)`
Gibt die hexadezimale Zusammenfassung des Inhalts einer Datei nach dem angegebenen Algorithmus zurück. Leitet den Lesevorgang durch die I/O Artefaktebene, sodass er für Verzeichnis-, Container-, Archiv-, Volume- und Localhost-Artefakte einheitlich funktioniert. Verwenden Sie diese Option, wenn der Digest das Einzige ist, was Sie aus der Datei benötigen.
+ **Gibt zurück:** `string, err`
```
local sha256, err = sbomgen.hash_file("/app/bin/server", sbomgen.hash_algorithms.SHA256)
if sha256 then
sbomgen.log_info("SHA-256: " .. sha256)
end
```
### `sbomgen.sha256 (Pfad)`
**Wichtig**
**Als veraltet gekennzeichnet.** Verwenden Sie stattdessen `sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)`. Dieser Alias wird aus Gründen der Abwärtskompatibilität beibehalten und wird weiterhin funktionieren, er wird jedoch in einer future Version entfernt. Neue Plugins sollten aufgerufen werden, `hash_file` sodass die Wahl des Algorithmus explizit ist.
Äquivalent mit `sbomgen.hash_file(path, "SHA-256")`.
+ **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 (Pfad, Muster)`
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 (Pfad)`
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 (Pfad)`
Praktischer Wrapper, der nur die Zeichenfolge der Produktversion aus 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 (Pfad)`
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 (Paket)`
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) [Eigenschaften von CyclonedX](#sbomgen-plugin-api-reference-cyclonedx-properties) |
| hashes | Tabelle | Nein | Komponenten-Hashes, die nach dem Namen des Algorithmus eingegeben sind; siehe [Komponenten-Hashes](#sbomgen-plugin-api-reference-component-hashes) |
| children | Tabelle | Nein | Verschachtelte untergeordnete Pakete, jedes mit derselben Form wie pkg (Pflichtfelder werden rekursiv überprüft) |
```
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",
},
hashes = {
[sbomgen.hash_algorithms.SHA256] = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
},
})
```
## Komponenten-Hashes
Das optionale `hashes` Feld für die Integrität von `sbomgen.push_package()` Datensätzen für eine Komponente. Die Einträge werden nach dem Namen des Algorithmus eingegeben und in das `components[].hashes` CyclonedX-Array serialisiert, sodass sie dem Schema entsprechen, das Amazon Inspector erwartet.
### Unterstützte Algorithmen
Verwenden Sie die Konstanten unter, `sbomgen.hash_algorithms` sodass der an`sbomgen.hash()`/übergebene Algorithmusname dieselbe Zeichenfolge ist, die akzeptiert `sbomgen.hash_file()` wird von: `push_package({ hashes = ... })`
| **Konstante** | **Wert** | **Länge des Hex-Digests** |
| --- | --- | --- |
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 40 |
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 64 |
### Validierungsregeln
`push_package()`validiert, `hashes` bevor ein Ergebnis ausgegeben wird. Ein Paket, dessen Hashes bei der Validierung fehlschlagen, wird gelöscht und eine Warnung wird protokolliert. Validierung:
+ Algorithmusnamen müssen mit einem Eintrag in übereinstimmen `sbomgen.hash_algorithms` (Groß- und Kleinschreibung beachten, genau `"SHA-1"` oder`"SHA-256"`).
+ Bei den Werten darf es sich um nicht leere Hexadezimalziffern in Kleinbuchstaben handeln.
+ Die Werte müssen die richtige Länge für den Algorithmus haben (40 Zeichen für, 64 Zeichen für SHA-1). SHA-256
+ Die Validierung erfolgt rekursiv: Ein fehlerhafter Hash im Inneren `children[].hashes` lehnt das gesamte Paket ab.
### Beispiel: Ein Manifest als Hashwert speichern und den Digest anhängen
```
function collect(file_path)
local data, err = sbomgen.read_file(file_path)
if err then return end
local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)
sbomgen.push_package({
name = "skill-manifest",
version = "1.0.0",
purl_type = "generic",
component_type = sbomgen.component_types.DATA,
hashes = {
[sbomgen.hash_algorithms.SHA256] = sha256,
},
})
end
```
Wenn der Digest das Einzige ist, was Sie von der Datei benötigen, `sbomgen.hash_file(path, algo)` ziehen Sie es vor, die Datei zweimal zu lesen — es leitet den Lesevorgang in einem einzigen Durchgang durch die I/O Artefaktebene.
## Eigenschaften von CyclonedX
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. Weitere Informationen finden Sie unter [Was ist eine Paket-URL](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html)? 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.
**Plugin-defined 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 | Auto-prefixed zu 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.
### Der SBOM-Inhalt wird nicht bereinigt
Sbomgenuntersucht oder filtert die Daten, die ein Plugin ausgibt, nicht. Komponentennamen, Versionen, PURLs, Hashes und Eigenschaftswerte werden wie angegeben in die SBOM geschrieben. Sbomgenerkennt oder redigiert keine geheimen Daten, Anmeldeinformationen, Token oder andere sensible Daten. Wenn ein Plugin einen solchen Wert in ein Ergebnis einfügt, erscheint er in der Ausgabe-SBOM und wird überall dort übertragen, wo diese SBOM veröffentlicht wird.
Sie sind dafür verantwortlich, was Ihre Plugins schreiben. Geben Sie nur Daten aus, die von dem Artefakt stammen, das Sie inventarisieren möchten, und behandeln Sie die SBOM bei der Entscheidung, was Sie aufnehmen möchten, als gemeinsam nutzbares Artefakt.
## Eigenschaftskonstanten
Built-in 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,
})
```
## Konstanten für den Hash-Algorithmus
Konstanten für den Algorithmusparameter von `sbomgen.hash()``sbomgen.hash_file()`, und das `hashes` Feld von. `sbomgen.push_package()` Die Zeichenkettenwerte stimmen mit den Namen des CyclonedX-Hash-Algorithmus überein, sodass dieselbe Konstante den gesamten Hash-Pfad ohne Übersetzung durchläuft.
| **Konstante** | **Wert** |
| --- | --- |
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" |
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" |
Beispiel:
```
local digest = sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)
sbomgen.push_package({
name = "example",
purl_type = "generic",
component_type = sbomgen.component_types.LIBRARY,
hashes = { [sbomgen.hash_algorithms.SHA256] = digest },
})
```
## Plattform-Konstanten
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 aktiviert hat. `--collect-licenses`
### `sbomgen.get_env_vars ()`
Gibt Umgebungsvariablen aus dem Artefakt als Tabelle mit Einträgen zurück. `{key, value}`
```
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.) aus der Umgebung des Artefakts zurück. `"C:"` 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/"
```
### `sbomgen.resolve_glob_paths (Muster)`
Erweitert die Glob-Muster des Dateisystems anhand des Host-Dateisystems. Localhost-only: gibt bei anderen `nil` Artefakttypen einen Fehler zurück.
```
function get_localhost_scan_paths()
return sbomgen.resolve_glob_paths({
"/home/*/.cache/huggingface/hub",
"/Users/*/.cache/huggingface/hub",
"C:/Users/*/.cache/huggingface/hub",
})
end
```
**Verhalten:**
+ Die Mustersyntax folgt der von Go [`filepath.Match`](https://pkg.go.dev/path/filepath#Match):`*`,`?`,`[abc]`,`[a-z]`.
+ Eingabemuster und Ausgabepfade sind normalisiert: Redundante Trennzeichen (`a//b`), Punktsegmente (`a/./b`) und nachfolgende Trennzeichen (`a/b/`) werden ausgeblendet.
+ Die Ausgabe ist dedupliziert; das erste Vorkommen eines Pfads gewinnt. Die Reihenfolge der Eingabemuster wird im gesamten Ergebnis beibehalten.
+ Muster, die mit nichts übereinstimmen, geben keine Einträge zurück. Empty-string Muster werden stillschweigend übersprungen. Fehlerhafte Muster (z. B. nicht übereinstimmende Klammern) geben eine Warnung aus und werden übersprungen.
**Cross-platform Pfadtrennzeichen:**
+ **Verwenden Sie Schrägstriche (`/`) für alle Pfade.** Schrägstriche funktionieren unter Linux, macOS und Windows; die Dateipfadlogik von Go übersetzt sie in das native Trennzeichen unter Windows.
+ **Backslash-Trennzeichen funktionieren nur unter Windows.** Unter Linux und macOS `\` ist es ein wörtliches Dateinamenzeichen, kein Pfadtrennzeichen — ein Muster, wie es auf POSIX-Systemen nichts `"C:\\Users\\*"` passt.
+ **Vermeiden Sie wörtliche Windows-style Pfade in Lua-Strings.** Eine Lua-Zeichenfolge wie `"C:\Users"` wird so interpretiert, als ob `C:sers` sie kein gültiges Lua-Escape `\U` ist (und `\t` usw. sind) `\f``\n`, sodass das Muster stillschweigend fehlschlägt. Verwenden Sie entweder Schrägstriche, maskierte Backslashes (`"C:\\Users"`) oder eine unformatierte Zeichenfolge mit langen Klammern (). `[[C:\Users]]`
## 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, Muster)`
Gibt die erste Übereinstimmung mit einem Go-Regex-Muster zurück, oder wenn es keine Übereinstimmung gibt. `nil`
+ **Gibt zurück:** `string|nil, err`
```
local version = sbomgen.regex_find(content, "\\d+\\.\\d+\\.\\d+")
```
### `sbomgen.regex_match (str, Muster)`
Gibt Capture-Gruppen aus dem ersten Treffer 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, Muster [, 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, Muster, Ersatz)`
Ersetzt alle Treffer. Die Ersatzzeichenfolge kann `$1``$2`, usw. für Capture-Gruppenverweise 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 Artefakten, die nicht zu Windows gehören, `registry_open_key` einen Fehler 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 (Scans). container/volume
### `sbomgen.registry_open_key (Pfad)`
Ö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 (Schlüssel, Wertname)`
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 (Schlüssel, Wertname)`
Liest einen Integer-Wert aus einem geöffneten Registrierungsschlüssel.
+ **Gibt zurück:** `number, err`
### `sbomgen.registry_get_strings (Schlüssel, Wertname)`
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 (Schlüssel)`
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 (Schlüssel)`
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 (Nachricht)`
Druckt `message` auf stderr und blockiert die Ausführung, bis der Benutzer die Eingabetaste drückt. Wenn `message` es weggelassen wird, 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) | Scheitert 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-Regex (RE2) ü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.