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

-Übersicht

Auf alle zur 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. 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.

Sandbox-Einschränkungen

Plugins werden auf einer Lua-VM in Sandbox mit eingeschränktem Zugriff auf die Standardbibliothek ausgeführt. Die folgenden Lua-Standardbibliotheksmodule sind verfügbar:

Die folgenden Standardbibliotheksmodule sind aus Sicherheits- und Stabilitätsgründen ausdrücklich verboten:

Diese Module sind nicht in der Zulassungsliste der VM enthalten und Plugins können nicht darauf zugreifen.

Plugin Lifecycle Globals

Ein Plugin ist eine Lua-Datei mit dem Nameninit.lua, die bestimmte globale Funktionen der obersten Ebene definiert. Diese Globals liegen nicht auf der sbomgen Tabelle — es sind Funktionen, die das Plugin für den Aufruf durch sbomgen definiert. Die Menge der gültigen Globals unterscheidet sich zwischen Discovery-Plugins und Sammlungs-Plugins. Wenn das Plugin sie weglässt, wird für jede der unten aufgeführten Funktionen die in der Tabelle angegebene Standardeinstellung verwendet.

Discovery-Plugins

Plugins für Sammlungen

Datei I/O

Alle Dateioperationen müssen die sbomgen.* API durchlaufen. Direkter Dateisystemzugriff über Luas io Bibliothek ist nicht verfügbar (sieheSandbox-Einschränkungen). Die sbomgen I/O Dateifunktionen werden über die Artefaktschnittstelle weitergeleitet und stellen so sicher, dass Ihr Plugin identisch funktioniert, egal ob Sie ein Verzeichnis auf der Festplatte, ein Container-Image, ein komprimiertes Archiv oder ein gemountetes Volume scannen.

Grenze für den Dateizugriff

Die sbomgen.* Dateifunktionen beschränken Lesevorgänge auf das Artefakt, das sich im Inventar befindet. Ein Pfad, der außerhalb des Artefaktstamms aufgelöst wird — zum Beispiel durch ../ Traversal — wird zurückgewiesen, und der Aufruf gibt einen Fehler zurück, anstatt das Host-Dateisystem zu lesen. Das gilt für,read_file, und die binary/hash Helfer open_file read_dirfile_stat, die einen Pfad einschlagen.

Die Ausnahme ist der localhost Artefakt-Typ, der den Host selbst inventarisiert; da ist das Host-Dateisystem das Artefakt, sodass Lesevorgänge nicht auf einen engeren Stamm beschränkt sind.

Diese Grenze bestimmt nur das Lesen von Dateien. Sie schränkt nicht ein, was ein Plugin in die SBOM schreibt — siehe. SBOM-Inhalte werden nicht bereinigt

sbomgen.get_file_list ()

Gibt alle Dateipfade im Artefakt als Tabelle mit Zeichenketten zurück.

-- 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.

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 für Streaming-Lesevorgänge. 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.

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.

local files, err = sbomgen.glob_find_files("*.txt")

Verwenden Sie sbomgen.get_file_list() mit string.match für den vollständigen Pfadmusterabgleich.

sbomgen.find_files_by_name (Namen)

Gibt Dateien zurück, deren Basisname (letzte Pfadkomponente) genau mit einem der angegebenen Namen übereinstimmt. Die Iteration und der Vergleich erfolgen in Go, wodurch dies erheblich schneller ist als die Iteration sbomgen.get_file_list() in Lua.

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 VERSIONVersion, und überein. version Zum find_files_by_name Beispiel findet der Abgleich außerhalb der Lua-VM statt.

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 (mit Schrägstrich normalisierter) Pfad mit einem der angegebenen Suffixe endet. Zum Beispiel findet der Abgleich außerhalb der find_files_by_name Lua-VM statt.

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 (RE2) -Regex-Muster übereinstimmt. Der Abgleich erfolgt außerhalb der Lua-VM, was dies bei großen Dateilisten effizient macht.

local configs = sbomgen.find_files_by_path_regex({"/etc/.*\\.conf$", "/opt/.*/config\\.json$"})

Leistung: find_files_by_* im Vergleich zu get_file_list

Für Discovery-Plugins bevorzuge oder übertreibe Iteration in Lua. 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 das Iterieren der Dateiliste in Lua mit ~15 Sekunden, während es in weniger als 1 Millisekunde abgeschlossen ist. find_files_by_name Der Unterschied besteht darin, dass jeder Dateipfad als Zeichenfolge in die Lua-VM get_file_list() kopiert wird und Lua dann die Schleife und die Musterübereinstimmung für jeden einzelnen interpretiert. 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 Kopieraufwand als auch der Aufwand für die Interpretation pro Pfad vermieden werden.

Verwenden Sie diese get_file_list() Option nur, wenn Sie eine benutzerdefinierte Abgleichslogik benötigen, die nicht als Basisnamen-, Suffix- oder Regex-Match ausgedrückt werden kann.

sbomgen.read_dir (Pfad)

Listet Einträge in einem Verzeichnis auf.

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 über eine Datei zurück.

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.

local manifest, err = sbomgen.read_zip_entry(
    "/app/lib/example.jar",
    "META-INF/MANIFEST.MF"
)

sbomgen.search_binary (Pfad, regulärer Ausdruck)

Analysiert eine Datei als ELF, PE oder Mach-O Binärdatei und durchsucht den Standardabschnitt nach einem Go-Regex-Match. constant/variable

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, regulärer Ausdruck [, 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 Übergebenn, um die Ergebnisse zu begrenzen.

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 dem ersten Regex-Match und ist nicht auf einen bestimmten Abschnitt beschränkt. Wird verwendet, wenn die abschnittsbasierte Suche (search_binary) nicht ausreicht — zum Beispiel, wenn Versionszeichenfolgen in nicht standardmäßigen Abschnitten enthalten sind.

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.

fh:read (n)

Liest bis zu 4 Byte. n Kehrt nil bei EOF zurück.

fh:close ()

Schließt das Datei-Handle. Schließen Sie 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 mitsbomgen.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

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 unter 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.

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)

Äquivalent mit sbomgen.hash_file(path, "SHA-256").

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 Bytemuster enthält. Gibt eine Tabelle mit booleschen Werten in derselben Reihenfolge wie die Eingabemuster zurück.

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 enthält.

Die file_version Felder product_version und stammen aus der FixedFileInfo PE-Struktur und sind formatiert als"major.minor.build.revision". Das string_table Feld ist eine verschachtelte Tabelle, die mit einem Gebietsschemacode versehen ist (z. B. "040904B0" für US-amerikanisches Englisch). Jedes Gebietsschema ist einer Tabelle mit name/value Paaren zugeordnet, die aus dem PE StringFileInfo (ProductVersion, ProductNameFileDescription, usw.) stammen. 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 Produktversionszeichenfolge aus einer PE-Binärdatei zurückgibt. FixedFileInfo Entspricht dem Anrufen get_pe_version_info(path) und Lesenproduct_version.

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 Anrufen get_pe_version_info(path) und Lesenfile_version.

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:

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 in sbomgen.push_package() Datensatzintegritätsanalysen für eine Komponente. Die Einträge werden anhand des Algorithmusnamens eingegeben und in das components[].hashes CyclonedX-Array serialisiert, was dem Schema entspricht, das Amazon Inspector erwartet.

Unterstützte Algorithmen

Verwenden Sie die Konstanten unter, sbomgen.hash_algorithms sodass der ansbomgen.hash()/übergebene Algorithmusname dieselbe Zeichenfolge ist, die akzeptiert sbomgen.hash_file() wird von: push_package({ hashes = ... })

Regeln für die Validierung

push_package()validiert, hashes bevor ein Ergebnis ausgegeben wird. Ein Paket, dessen Hashes die Validierung nicht bestehen, wird gelöscht und eine Warnung wird protokolliert. Validierung:

Beispiel: Hashing eines Manifests und Anhängen des Digest

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 aus der Datei benötigen, sbomgen.hash_file(path, algo) ziehen Sie es vor, die Datei zweimal zu lesen — er 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:

Reservierte Namespaces

Die amazon:inspector:* Familie der CyclonedX-Eigenschaftsnamespaces ist Amazon Inspector vorbehalten:

Plugin-defined Eigenschaften dürfen diese Namespaces nicht verwenden. Das Schreiben in einen reservierten Namespace kann Werte, auf die sich Inspector stützt, überschattet oder in Konflikt geraten. Die daraus resultierende SBOM kann bei der Identifizierung der Sicherheitslücke falsch interpretiert werden. Eine vollständige Liste der reservierten Schlüssel finden Sie unter Verwenden von CyclonedX-Namespaces mit Amazon Inspector.

Wichtige Regeln für die Benennung

Eigenschaftsschlüssel, die an übergeben sbomgen.push_package() werden, werden wie folgt verarbeitet:

Fügen Sie in den 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 aussendet, eigene Eigenschaften zuweisen. Diese Werte stammen aus dem reservierten amazon:inspector:sbom_generator:* Namespace und sollten nicht von Plugins erzeugt werden. Beobachtetes Laufzeitverhalten:

Die vollständige Taxonomie der reservierten Schlüssel wird im Amazon Inspector-Benutzerhandbuch behandelt: Verwenden von CyclonedX-Namespaces mit Amazon Inspector.

SBOM-Inhalte werden nicht bereinigt

Sbomgenüberprüft 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 Geheimnisse, Anmeldeinformationen, Token oder andere vertrauliche Daten — wenn ein Plugin einen solchen Wert in ein Ergebnis einfügt, erscheint er in der Ausgabe-SBOM und wird überall dort übertragen, wo das 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 als gemeinsam nutzbares Artefakt, wenn Sie entscheiden, was aufgenommen werden soll.

Konstanten für Eigenschaften

Built-in Eigenschaftsschlüsselkonstanten sind über verfügbar. sbomgen.properties Jede der unten aufgeführten Konstanten wird in einen Schlüssel innerhalb des amazon:inspector:sbom_generator:* reservierten Namespace aufgelöst. Diese Konstanten existieren, damit die eingebauten Scanner von sbomgen konsistente Eigenschaftsschlüssel ausgeben. Sie sind keine Erweiterungspunkte für benutzerdefinierte Plugins — wenn Sie sie in einem benutzerdefinierten Plugin verwenden, wird in einen reservierten Namespace geschrieben, der Werte, auf die sich Inspector verlässt, überlagern kann. Siehe Reservierte Namespaces oben.

Autoren benutzerdefinierter Plugins sollten Eigenschaften (zum Beispielacme:my_plugin:*) in ihrem eigenen Namespace definieren, anstatt diese Konstanten wiederzuverwenden.

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

Beispiel:

function get_scanner_groups()
    return {sbomgen.groups.PROGRAMMING_LANGUAGE, sbomgen.groups.PACKAGE_COLLECTOR}
end

Konstanten des Komponententyps

Das component_type Feld in push_package() muss einer der CyclonedX 1.5-Komponententypen sein. Konstanten sind verfügbar über: sbomgen.component_types

Beispiel:

sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
})

Konstanten des Hash-Algorithmus

Konstanten für den Algorithmusparameter von sbomgen.hash()sbomgen.hash_file(), und das hashes Feld von. sbomgen.push_package() Die Zeichenfolgenwerte entsprechen den Namen des CyclonedX-Hashalgorithmus, sodass dieselbe Konstante ohne Übersetzung den gesamten Hashing-Pfad durchläuft.

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 },
})

Plattformkonstanten

Konstanten für den Vergleich mit. sbomgen.get_platform() Verfügbar übersbomgen.platform:

Beispiel:

if sbomgen.get_platform() == sbomgen.platform.WINDOWS then
    -- Windows-specific logic
end

Informationen zum Artefakt

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 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. Die Standardeinstellung ist, "C:" wenn 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 nil plus einen Fehler bei anderen Artefakttypen 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:

Cross-platform Pfadtrennzeichen:

sbomgen.get_home_dirs ()

Gibt die Stammverzeichniswurzeln des Benutzers für das Artefakt als Pfadtabelle zurück. Localhost zählt das echte Host-Dateisystem auf; Container- und Volume-Artefakte zählen ihr eigenes Dateisystem (Rootfs oder gemountet) auf; alle anderen Artefakttypen geben eine leere Tabelle zurück. Pfade werden mit Schrägstrichen normalisiert, dedupliziert und sortiert.

Dies ist die Methode, um Verzeichnisse pro Benutzer (wie Modell-Caches oder Tool-Konfigurationen) ohne harte Codierung von oder zu lokalisieren. /home/* /Users/* Es beinhaltet das Home-Verzeichnis von root und überspringt bekannte Nicht-Benutzerverzeichnisse (integrierte Profile wie Public und on, on und Default on). Windows Shared macOS lost+found Linux

function get_localhost_scan_paths()
    local patterns = {}
    for _, home in ipairs(sbomgen.get_home_dirs()) do
        table.insert(patterns, home .. "/.cache/huggingface/hub")
    end
    return sbomgen.resolve_glob_paths(patterns)
end

Die obige Zusammenstellung gilt nur für Localhost, da resolve_glob_paths Fehler bei Artefakten auftreten, die nicht von Localhost stammen. Ordnen Sie bei Container- und Volume-Scans stattdessen die zurückgegebenen Home-Roots der Dateiliste des Artefakts zu (z. B. mit). sbomgen.find_files_by_path_regex

Verhalten:

Systeminformationen

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).

Reguläre Ausdrücke

Den eingebauten Mustern von Lua fehlen Funktionen wie Alteration (|), Quantifier Ranges ({n,}) und Lookahead. Um diese Lücke zu schließen, macht sbomgen das Paket von Go direkt verfügbar. regexp Diese Funktionen verwenden die Go-Regex-Syntax (RE2), keine Lua-Muster.

sbomgen.regex_find (str, muster)

Gibt die erste Übereinstimmung eines Go-Regex-Musters zurück, oder wenn keine Übereinstimmung vorliegt. nil

local version = sbomgen.regex_find(content, "\\d+\\.\\d+\\.\\d+")

sbomgen.regex_match (str, Muster)

Gibt Capture-Gruppen aus dem ersten Spiel zurück. Index 1 ist der vollständige Treffer, mindestens 2 sind Capture-Gruppen.

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. Übergebenn, um die Ergebnisse zu begrenzen (Standardeinstellung: alle).

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.

local cleaned = sbomgen.regex_replace(raw_version, "(1[6-9]\\d{8,}|buildkitsandbox.*)$", "")

Wann sollten Regex- oder Lua-Muster verwendet werden

Verwende das eingebautestring.match/von Lua string.find für einfache Muster — sie sind schneller und erfordern keine Umgehung von Backslashes. Verwenden Sie, wenn Sie Folgendes benötigensbomgen.regex_*:

Strukturiertes Parsen

Sbomgen stellt einfache Helfer 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.

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-String in eine Lua-Tabelle.

XML-Werte verwenden die folgende Form:

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 nur Lesezugriff auf die Windows-Registrierung. Gibt bei Nicht-Windows-Artefakten einen Fehler registry_open_key zurück. Der Registry Accessor wird bei der ersten Verwendung verzögert initialisiert und unterstützt sowohl den Live-Zugriff auf die Windows-API (Localhost-Scans unter Windows) als auch das dateibasierte 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 mussregistry_close.

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.

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.

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.

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.

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üssel-Handles werden ebenfalls automatisch vom Garbage Collector geschlossen, ein explizites Schließen wird jedoch empfohlen.

Protokollierung

Log-Meldungen werden in die Konsolenausgabe von sbomgen geschrieben. Jeder von einem Plugin ausgegebenen Nachricht 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

string.formatFü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 Stellen in Ihrem Plugin platzieren und es ausführen, um die umgebende 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 den Plugin-Testdateien (*_test.lua) verfügbar, geladen voninspector-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 (zum Beispielsbomgen.read_file()) ein Artefakt benötigen, liefern nur dann aussagekräftige Ergebnisse, wenn sie innerhalb eines Scans aufgerufen werden. Eine ausführliche Anleitung finden Sie imLeitfaden zum Testen von Plugins.

Scan-Funktionen

Jede Scan-Funktion erstellt ein Artefakt der angegebenen Art, führt die Discovery→Collection-Pipeline des aktuellen Plugins gegen dieses Objekt aus und gibt die resultierenden Ergebnisse zurück. Das path Argument wird relativ zum Verzeichnis der Testdatei aufgelöst.

Alle sechs geben eine Ergebnistabelle mit der folgenden Form zurück.

Form des Ergebnisses

Jede Ergebnistabelle projiziert nur die unten aufgeführten Felder. Insbesondere purl_type werden sie nicht separat projiziert, namespace sondern in die gesamte purl Zeichenfolge aufgenommen.

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

Ablauf kontrollieren

Erkennung testen

Jede globale Lua-Funktion, deren Name mit test_ einem Dateiabgleich beginnt, *_test.lua wird als Test behandelt. Die Testdatei muss neben einer init.lua in normaler {phase}/{platform}/{category}/{ecosystem}/ Tiefe liegen. Die Fixture-Daten werden _testdata/ neben der Testdatei eingegeben — der Runner taucht _testdata/ bei der Suche nach Testdateien nicht ab.

Fehlerbehandlung

API-Funktionen, die fehlschlagen können, geben zwei Werte zurück:. value, err Bei Erfolg err istnil. Im Fehlerfall 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.