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 Informationen zum Testen finden Sie unterLeitfaden zum Testen von Plugins.

-Ü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_namesubscribe_to_event, die sbomgen an definierten Punkten im Plugin-Lebenszyklus aufruft. Diese sind dokumentiert in. Globaler Lebenszyklus von Plugins

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.

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_filesbomgen.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 Nameninit.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 (sieheSandbox-Einschränkungen). 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 VERSIONVersion, 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ückgegebensbomgen.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, ProductNameFileDescription, 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 Lesenproduct_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 Lesenfile_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
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 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.

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 Beispielacme: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_pathwird immer von sbomgen hinzugefügt.

• source_file_scannerund 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 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 oben.

Autoren benutzerdefinierter Plugins sollten Eigenschaften (zum Beispielacme: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 deklarierenget_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 übersbomgen.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ücktrue, 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 integriertestring.match/string.findfü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('<package id="Newtonsoft.Json" version="13.0.3" />')
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 mussregistry_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_infolog_warn, und log_error immer drucken. log_debugdruckt 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.formatFü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 wurdeninspector-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 derLeitfaden zum Testen von Plugins.

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<string, string>
-- 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 istnil. 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.