Riferimento all'API del plugin

Riferimento API completo per i plugin Lua inspector-sbomgen. Per una guida sulla scrittura di plugin, vedi. Guida per sviluppatori di plugin Per i test, vediGuida al test dei plugin.

Panoramica di

È possibile accedere a tutte le funzioni fornite in fase di esecuzione tramite la sbomgen tabella globale (file I/O, regex, registrazione, costanti, ecc.). Inoltre, ogni plugin definisce un piccolo insieme di funzioni globali di primo livello (discover,, collect get_scanner_namesubscribe_to_event, e così via) che sbomgen chiama in punti definiti del ciclo di vita del plugin. Queste sono documentate in. Plugin Lifecycle Globals

All'interno *_test.lua dei file, sbomgen presenta inoltre una funzionalità testing globale che consente agli autori dei test di guidare la pipeline discovery→collection e fare asserzioni. Per informazioni, consulta API di test.

Restrizioni della sandbox

I plugin vengono eseguiti in una macchina virtuale Lua in modalità sandbox con accesso limitato alla libreria standard. Sono disponibili i seguenti moduli di libreria standard Lua:

Modulo	Note
base	Funzioni principali (printtype,tostring,tonumber,pairs, ipairspcall,error,select,unpack,rawget,rawset, ecc.). dofileloadfile, e loadstring vengono rimossi.
string	Manipolazione completa delle stringhe (string.matchstring.findstring.format,,string.gsub, ecc.)
table	Manipolazione completa della tabella (table.inserttable.remove,, table.sorttable.concat, ecc.)
math	Libreria matematica completa (math.floor, math.maxmath.min, ecc.)
package	require()è disponibile ma limitato ai moduli all'interno dell'albero di directory del plugin. L'attraversamento della directory principale () require("../shared") è bloccato. package.cpathe vengono cancellati. package.path

I seguenti moduli di libreria standard non sono esplicitamente consentiti per motivi di sicurezza e stabilità:

Modulo	Motivo
io	L'accesso diretto al file system è bloccato. Tutte le operazioni sui file devono passare attraverso sbomgen.* funzioni, che passano attraverso l'interfaccia Artifact per un comportamento coerente tra i tipi di artefatti (directory, contenitore, volume, ecc.).
os	Le operazioni a livello di sistema (os.execute,, os.remove os.renameos.getenv, ecc.) sono bloccate per impedire ai plugin di modificare il sistema host.
debug	La libreria di debug è bloccata per impedire l'ispezione o la modifica degli interni della VM Lua.
coroutine	Le coroutine non vengono caricate.

Questi moduli non sono nella lista consentita della VM e non sono accessibili dai plugin.

Nota

Importante: tutti i file I/O devono essere sottoposti a sbomgen.* funzioni (ad esempio,,sbomgen.read_file,sbomgen.open_file). sbomgen.get_file_list L'utilizzo io.open o l'accesso diretto al filesystem genererà un errore di runtime. L'sbomgenAPI assicura che i plugin interagiscano con il livello di astrazione degli artefatti, che fornisce un comportamento coerente durante la scansione di una directory, di un'immagine del contenitore, di un archivio o di un volume.

Plugin Lifecycle Globals

Un plugin è un file Lua denominato init.lua che definisce alcune funzioni globali di primo livello. Questi valori globali non sono sul sbomgen tavolo: sono funzioni che il plugin definisce per la chiamata a sbomgen. L'insieme di globals validi differisce tra i plugin di scoperta e i plugin di raccolta. Per ogni funzione riportata di seguito, se il plugin la omette, viene utilizzata l'impostazione predefinita mostrata nella tabella.

Plugin Discovery

Funzione	Arity	Campo obbligatorio	Predefinito (se omesso)	Descrizione
discover()	0	Sì	—	Restituisce i file trovati da questo plugin. Restituisce una tabella sequenziale di stringhe di percorso (modalità a evento singolo) o una tabella composta da stringhe di nomi di eventi i cui valori sono tabelle di percorsi (modalità multievento).
get_event_name()	0	No	"lua:{platform}/{category}/{ecosystem}"	Restituisce il nome dell'evento con cui vengono pubblicati i file. Deve essere unico per tutti i plugin di discovery.
get_scanner_name()	0	No	nome della directory dell'ecosistema	Restituisce il nome visualizzato dello scanner. Deve essere unico per tutti i plugin di discovery.
get_scanner_description()	0	No	"Lua discovery plugin: {ecosystem}"	Restituisce una descrizione leggibile dall'uomo.
get_scanner_groups()	0	No	Derivato dalla directory delle categorie (consulta la guida per gli sviluppatori)	Restituisce una tabella di stringhe di gruppi di scanner. Usa sbomgen.groups.* costanti.
get_localhost_scan_paths()	0	No	—	Restituisce una tabella di file/directory percorsi da includere durante la scansione di un artefatto localhost. Consultato solo per le scansioni. localhost

Plugin di raccolta

Funzione	Arity	Campo obbligatorio	Predefinito (se omesso)	Descrizione
collect(file_path)	1	Sì	—	Chiamato una volta per file pubblicato nell'evento sottoscritto. Analizza il file ed emette i risultati tramite. sbomgen.push_package() Non restituisce nulla.
subscribe_to_event()	0	No	"lua:{platform}/{category}/{ecosystem}"	Restituisce il nome dell'evento a cui questo raccoglitore è abbonato. Dovrebbe corrispondere al plugin di scoperta corrispondente. get_event_name()
get_collector_name()	0	No	nome della directory dell'ecosistema	Restituisce il nome visualizzato del raccoglitore. Deve essere unico per tutti i plugin di raccolta.
get_collector_description()	0	No	""(vuoto)	Restituisce una descrizione leggibile dall'uomo.

I/O del file

Tutte le operazioni sui file devono passare attraverso l'sbomgen.*API. L'accesso diretto al file system tramite la io libreria di Lua non è disponibile (vedi). Restrizioni della sandbox I/O Le funzioni dei sbomgen file vengono instradate attraverso l'interfaccia Artifact, assicurando che il plugin funzioni in modo identico sia che si esegua la scansione di una directory su disco, di un'immagine di un contenitore, di un archivio compresso o di un volume montato.

sbomgen.get_file_list()

Restituisce tutti i percorsi dei file nell'artefatto come tabella di stringhe.

• Restituisce: {string, ...} — tabella di stringhe di percorsi assoluti dei file

• Prestazioni: questa funzione copia ogni percorso di file nell'artefatto nella macchina virtuale Lua come stringa Lua. Su artefatti di grandi dimensioni (ad esempio, una scansione localhost con oltre 300.000 file), solo questo richiede diversi secondi. L'iterazione della tabella restituita in Lua con un string.match() ulteriore sovraccarico: una scansione completa può richiedere più di 15 secondi. Maggiore è il numero di file nell'artefatto, più lento sarà il plugin.

Nota

Preferisci queste alternative mirate quando possibile:

Funzione	Usa quando...
sbomgen.find_files_by_name()	Conosci i nomi esatti dei file da abbinare (ad esempio,,"requirements.txt") "curl"
sbomgen.find_files_by_name_icase()	Come sopra, ma senza distinzione tra maiuscole e minuscole
sbomgen.find_files_by_suffix()	È necessario che i suffissi del percorso corrispondano (ad es.,) "/pom.properties" "curlver.h"
sbomgen.find_files_by_path_regex()	È necessaria la corrispondenza delle espressioni regolari a percorso completo
sbomgen.glob_find_files()	È necessaria una corrispondenza dei nomi di base in stile glob

Queste funzioni eseguono la corrispondenza all'esterno della macchina virtuale Lua e restituiscono solo i percorsi corrispondenti, completandosi in meno di 1 millisecondo anche su artefatti di file da 300K. Utilizza get_file_list() solo quando la logica di corrispondenza non può essere espressa con nessuno dei precedenti.

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

Legge l'intero contenuto di un file e lo restituisce come stringa.

• Restituisce: string, err

• In caso di fallimento: 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)

Apre un file per le letture in streaming. Restituisce un FileHandle oggetto. Usalo per file di grandi dimensioni in cui caricare l'intero contenuto in memoria non è pratico.

• Restituisce: 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)

Restituisce i file che corrispondono a un pattern filepath.Match Go glob. Il modello viene confrontato con il nome del file di base.

• Restituisce: {string, ...}, err

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

Usa sbomgen.get_file_list() with string.match per la corrispondenza completa del modello di percorso.

sbomgen.find_files_by_name(names)

Restituisce file il cui nome di base (ultimo componente del percorso) corrisponde esattamente a uno dei nomi indicati. L'iterazione e il confronto avvengono in Go, il che lo rende significativamente più veloce rispetto all'sbomgen.get_file_list()iterazione in Lua.

• Parametri: names — tabella di stringhe (nomi di base da abbinare)

• Restituisce: {string, ...} — percorsi di file corrispondenti (nessuna tupla di errore)

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)

Restituisce i file il cui nome di base corrisponde a uno dei nomi indicati, ignorando le maiuscole e minuscole. Ad esempio, "version" corrisponde a, VERSION eVersion. version Ad esempiofind_files_by_name, l'abbinamento avviene al di fuori della macchina virtuale Lua.

• Parametri: names — tabella di stringhe (nomi di base da abbinare, senza distinzione tra maiuscole e minuscole)

• Restituisce: {string, ...} — percorsi di file corrispondenti (nessuna tupla di errore)

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)

Restituisce i file il cui percorso completo (forward-slash-normalized) termina con uno dei suffissi indicati. Ad esempiofind_files_by_name, l'abbinamento avviene al di fuori della macchina virtuale Lua.

• Parametri: suffixes — tabella di stringhe (suffissi di percorso da abbinare)

• Restituisce: {string, ...} — percorsi di file corrispondenti (nessuna tupla di errore)

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)

Restituisce file il cui forward-slash-normalized percorso corrisponde a uno qualsiasi dei modelli regex Go (RE2) specificati. La corrispondenza avviene all'esterno della macchina virtuale Lua, il che la rende efficiente su elenchi di file di grandi dimensioni.

• Parametri: patterns — tabella delle stringhe regex Go

• Restituisce: {string, ...} — percorsi di file corrispondenti (nessuna tupla di errore)

• Genera: un errore Lua se qualche pattern non riesce a essere compilato

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

Prestazioni: vs. find_files_by_* get_file_list

Per i plugin di scoperta find_files_by_namefind_files_by_suffix, preferisci o esegui un'iterazione find_files_by_path_regex eccessiva get_file_list() in Lua. In una scansione localhost con 300.000 file, l'iterazione dell'elenco dei file in Lua string.match() richiede ~ 15 secondi, mentre viene completata in meno di 1 millisecondo. find_files_by_name La differenza è che get_file_list() copia ogni percorso di file nella macchina virtuale Lua come una stringa, quindi Lua interpreta il ciclo e il pattern match per ognuno di essi. Le find_files_by_* funzioni eseguono la corrispondenza all'esterno della macchina virtuale Lua e restituiscono solo i percorsi corrispondenti, evitando sia il sovraccarico di copia che quello di interpretazione per percorso.

Utilizzare get_file_list() solo quando è necessaria una logica di corrispondenza personalizzata che non può essere espressa come nome di base, suffisso o corrispondenza regex.

sbomgen.read_dir(path)

Elenca le voci in una directory.

• Restituisce: {{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)

Restituisce i metadati relativi a un file.

• Restituisce: {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)

Legge una singola voce da un archivio ZIP, JAR o WAR.

• Restituisce: string, err

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

sbomgen.search_binary(path, regex)

Analizza un file come binario ELF, PE o Mach-O e cerca constant/variable nella sezione predefinita una corrispondenza regex Go.

• Restituisce: string|nil, err — la stringa corrispondente o nil se nessuna corrispondenza

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

Analizza un file come binario ELF, PE o Mach-O e restituisce tutte le corrispondenze univoche del primo gruppo di acquisizione presenti nella sezione predefinita. constant/variable Passa per limitare n i risultati.

• Restituisce: {string, ...}|nil, err — tabella delle stringhe corrispondenti o nil se nessuna corrispondenza

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)

Cerca nell'intero file binario la prima corrispondenza regex, non limitata a una sezione specifica. Viene utilizzato quando la ricerca basata sulle sezioni (search_binary) è insufficiente, ad esempio quando le stringhe di versione si trovano in sezioni non standard.

• Restituisce: string|nil, err — la stringa corrispondente o nil se nessuna corrispondenza

local version, err = sbomgen.search_binary_raw(path, "ProductVersion[\\x00\\s]+([\\d.]+)")

FileHandle Metodi

FileHandle gli oggetti vengono restituiti dasbomgen.open_file().

fh:read_line()

Legge la riga successiva (senza il carattere di nuova riga). Ritorna a nil EOF.

• Restituisce: string|nil, err

fh:read(n)

Legge fino a n byte. Restituisce nil in EOF.

• Restituisce: string|nil, err

fh:close()

Chiude l'handle del file. Al termine, chiudi sempre le maniglie.

Utilità binarie

sbomgen.sha256(path)

Restituisce l'hash SHA-256 con codifica esadecimale del contenuto di un file.

• Restituisce: 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)

Controlla se un file contiene ciascuno dei modelli di byte specificati. Restituisce una tabella di booleani nello stesso ordine dei pattern di input.

• Restituisce: {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)

Analizza le risorse della versione di Windows PE da un file binario. Restituisce una tabella con i campi della versione o nil, err se il file non è un file binario PE o non ha una risorsa di versione.

• Restituisce: {product_version, file_version, string_table}, err

I file_version campi product_version and provengono dalla FixedFileInfo struttura PE, formattata come"major.minor.build.revision". Il string_table campo è una tabella nidificata con codice locale (ad esempio, "040904B0" per Unicode in inglese americano). Ogni locale è mappato su una tabella di name/value coppie tratte dal PE StringFileInfo (ProductVersion,, ProductNameFileDescription, ecc.). Un binario PE può esporre una o più impostazioni locali.

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)

Convenience wrapper che restituisce solo la stringa della versione del prodotto da un file binario PE. FixedFileInfo Equivalente a chiamare get_pe_version_info(path) e leggere. product_version

• Restituisce: 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)

Comvenience wrapper che restituisce solo la stringa della versione del file da un file binario PE. FixedFileInfo Equivalente a chiamare get_pe_version_info(path) e leggere. file_version

• Restituisce: string, err

local version, err = sbomgen.parse_file_version(file_path)
if version then
    sbomgen.log_info("file version: " .. version)
end

Output del pacchetto

sbomgen.push_package(pkg)

Inserisce la ricerca di un pacchetto nello SBOM. Disponibile solo nei plugin di raccolta.

La pkg tabella supporta i seguenti campi:

Campo	Tipo	Campo obbligatorio	Descrizione
name	stringa	Sì	Nome pacchetto
version	stringa	No	Stringa di versione risolta
namespace	stringa	No	Namespace PURL (ad es.,) "curl" "wordpress/plugin"
purl_type	stringa	Sì	Tipo PURL (ad es.,,,"pypi","npm") "cargo" "deb" "generic"
component_type	stringa	Sì	Tipo di componente CyclonedX; usa sbomgen.component_types.* costanti (ad es.) sbomgen.component_types.LIBRARY
qualifiers	table	No	qualificatori PURL come coppie chiave-valore (appaiono nell'URL del pacchetto)
properties	table	No	Proprietà dei componenti CyclonedX come coppie chiave-valore (vedi) Proprietà CyclonedX
children	table	No	Pacchetti secondari annidati, ciascuno con la stessa forma di (i campi obbligatori vengono convalidati in modo pkg ricorsivo)

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

Proprietà CyclonedX

Le proprietà CyclonedX sono metadati chiave-valore collegati a un componente nello SBOM. Sono distinti dai qualificatori PURL:

• qualifiers— qualificatori PURL. Questi diventano parte della stringa dell'URL del pacchetto (ad es.). pkg:deb/debian/curl@7.88.1?arch=amd64 Alcuni qualificatori PURL hanno un significato semantico per Amazon Inspector e influenzano l'identificazione delle vulnerabilità. Vedi Cos'è l'URL di un pacchetto? per le convenzioni per tipo di Inspector.

• properties— proprietà del componente CyclonedX. Queste appaiono nell'components[].propertiesarray di SBOM e non modificano il modo in cui il componente viene identificato.

Spazi dei nomi riservati

La amazon:inspector:* famiglia di namespace di proprietà CyclonedX è riservata ad Amazon Inspector:

• amazon:inspector:sbom_generator:*— utilizzato da sbomgen e dai suoi scanner integrati.

• amazon:inspector:sbom_scanner:*— utilizzato dall'API Amazon Inspector Scan.

Le proprietà definite dal plug-in non devono utilizzare questi namespace. La scrittura in uno spazio dei nomi riservato può creare un'ombra o entrare in conflitto con i valori su cui si basa Inspector e lo SBOM risultante potrebbe essere interpretato in modo errato durante l'identificazione delle vulnerabilità. Vedi Utilizzo degli spazi dei nomi CyclonedX con Amazon Inspector per l'elenco completo delle chiavi riservate.

Regole di denominazione delle chiavi

Le chiavi di proprietà passate a sbomgen.push_package() vengono elaborate come segue:

Chiave di input	Chiave risultante in SBOM	Consigliato per plugin personalizzati?
Contiene : (ad es.) acme:my_plugin:field	Usato alla lettera	Sì, posiziona ogni proprietà definita dal plug-in nel tuo spazio dei nomi
No : (ad esempio,) field	Con prefisso automatico a amazon:inspector:sbom_generator:field	No: viene scritto in uno spazio dei nomi riservato

Includi sempre almeno un punto nelle chiavi di proprietà che definisci. Usa uno spazio dei nomi unico per la tua organizzazione o il tuo plugin (ad esempioacme: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",
}

Proprietà impostate da sbomgen

Sbomgen può assegnare proprietà proprie a ogni componente che emette. Questi valori provengono dallo spazio dei amazon:inspector:sbom_generator:* nomi riservato e non dovrebbero essere prodotti dai plugin. Comportamento di runtime osservato:

• source_pathviene sempre aggiunto da sbomgen.

• source_file_scannere source_package_collector vengono aggiunti quando --enable-debug-props è abilitato.

La tassonomia completa delle chiavi riservate è gestita nella guida per l'utente di Amazon Inspector: Utilizzo degli spazi dei nomi CyclonedX con Amazon Inspector.

Costanti di proprietà

Le costanti delle chiavi di proprietà integrate sono disponibili tramite. sbomgen.properties Ogni costante seguente si risolve in una chiave all'interno dello spazio dei nomi riservato. amazon:inspector:sbom_generator:* Queste costanti esistono in modo che gli scanner integrati di sbomgen emettano chiavi di proprietà coerenti. Non sono punti di estensione per plug-in personalizzati: utilizzandoli in un plug-in personalizzato si scrive in uno spazio dei nomi riservato, su cui può fare affidamento i valori shadow di Inspector. Vedi sopra. Spazi dei nomi riservati

Gli autori di plugin personalizzati dovrebbero definire le proprietà nel proprio spazio dei nomi (ad esempioacme:my_plugin:*) anziché riutilizzare queste costanti.

Costante	Valore risolto
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

Gruppi di scanner

I plugin Discovery devono dichiarare i propri gruppi di scanner tramite. get_scanner_groups() I gruppi classificano gli scanner e consentono agli utenti di abilitare o disabilitare selettivamente le categorie. Le costanti sono disponibili tramite: sbomgen.groups

Costante	Valore	Descrizione
sbomgen.groups.OS	"os"	gestori di pacchetti del sistema operativo (dpkg, rpm, ecc.)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	Gestori di pacchetti linguistici (pip, npm, maven, ecc.)
sbomgen.groups.BINARY	"binary"	Analisi binaria compilata (Go, Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	Raccolta generale di pacchetti
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	Ecosistemi aggiuntivi (curl, nginx, ecc.)
sbomgen.groups.CERTIFICATE	"certificate"	Scansione dei certificati
sbomgen.groups.CUSTOM	"custom"	Aggiunto automaticamente a tutti i plugin personalizzati caricati tramite --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	Rilevamento di modelli di apprendimento automatico

Esempio:

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

Costanti del tipo di componente

Il component_type campo in push_package() deve essere uno dei tipi di componenti CyclonedX 1.5. Le costanti sono disponibili tramite: sbomgen.component_types

Costante	Valore
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"

Esempio:

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

Costanti della piattaforma

Costanti con cui confrontare. sbomgen.get_platform() Disponibile tramitesbomgen.platform:

Costante	Valore
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

Esempio:

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

Informazioni sull'Artifact

sbomgen.get_platform()

Restituisce la stringa della piattaforma di runtime (ad es., "linux""windows","darwin").

sbomgen.get_artifact_type()

Restituisce il tipo di artefatto da scansionare (ad esempio,,"directory"). "archive"

sbomgen.should_collect_licenses()

Restituisce true se l'utente ha abilitato la raccolta delle licenze tramite. --collect-licenses

sbomgen.get_env_vars()

Restituisce le variabili di ambiente dall'artefatto come tabella di {key, value} voci.

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

Restituisce la lettera dell'unità di sistema (ad esempio"C:") dall'ambiente dell'artefatto. Legge la variabile di SystemDrive ambiente, impostata come predefinita se non è impostata. "C:" Questo è l'equivalente Lua di. strutils.GetSystemDriverLetter()

local drive = sbomgen.get_system_drive()
local program_files = drive .. "/Program Files/"

Informazioni di sistema

Queste funzioni restituiscono metadati sul sistema operativo e sull'hardware dell'artefatto. I valori possono essere stringhe vuote se le informazioni non sono disponibili (ad esempio, durante la scansione di una directory senza metadati del sistema operativo).

Funzione	Valori restituiti
sbomgen.get_os_name()	Nome del sistema operativo (ad es.,"Ubuntu") "Alpine Linux"
sbomgen.get_os_version()	Versione del sistema operativo (ad es."22.04","3.18")
sbomgen.get_os_codename()	Nome in codice del sistema operativo (ad es.,"jammy") "bookworm"
sbomgen.get_os_id()	Identificatore del sistema operativo (ad es.,) "ubuntu" "alpine"
sbomgen.get_kernel_name()	Nome del kernel (ad esempio,) "Linux"
sbomgen.get_kernel_version()	Stringa della versione del kernel
sbomgen.get_cpu_arch()	Architettura della CPU (ad es."x86_64","aarch64")
sbomgen.get_hostname()	Nome host del sistema

Espressioni regolari

I pattern integrati di Lua mancano di funzionalità come alternation (|), quantifier ranges ({n,}) e lookahead. Per colmare questa lacuna, sbomgen espone direttamente il pacchetto di Go. regexp Queste funzioni usano la sintassi Go regex (RE2), non i pattern Lua.

sbomgen.regex_find(str, pattern)

Restituisce la prima corrispondenza di un pattern regex Go onil, in caso di assenza di corrispondenza.

• Restituisce: string|nil, err

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

sbomgen.regex_match(str, pattern)

Restituisce i gruppi di cattura della prima partita. L'indice 1 è la partita completa, 2+ sono i gruppi di acquisizione.

• Restituisce: {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])

Restituisce tutte le corrispondenze non sovrapposte. Passa n ai risultati limite (impostazione predefinita: tutti).

• Restituisce: {string, ...}|nil, err

local versions = sbomgen.regex_find_all(content, "\\d+\\.\\d+\\.\\d+")

sbomgen.regex_replace(str, pattern, replacement)

Sostituisce tutte le partite. La stringa sostitutiva può utilizzare $1$2, ecc. per acquisire riferimenti al gruppo.

• Restituisce: string, err

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

Quando usare i pattern regex vs Lua

Usastring.match/() integrato in Lua string.find per modelli semplici: sono più veloci e non richiedono l'evasione delle barre rovesciate. sbomgen.regex_*Usalo quando ne hai bisogno:

• Alternanza: (foo|bar)

• Intervalli di quantificazione: \d{8,}

• Classi di caratteri complesse non esprimibili nei modelli Lua

Analisi strutturata

Sbomgen espone aiutanti leggeri per la decodifica di formati di testo strutturati direttamente nelle tabelle Lua.

sbomgen.json_decode(str)

Analizza una stringa JSON in una tabella Lua.

• Restituisce: 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)

Analizza una stringa XML in una tabella Lua.

• Restituisce: table|nil, err

I valori XML utilizzano la forma seguente:

• _name— nome dell'elemento

• _attr— tabella degli attributi, se presente

• _text— contenuto testuale tagliato, se presente

• indici numerici — elementi 1..n secondari

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)

Registro di sistema di Windows

Queste funzioni forniscono l'accesso in sola lettura al registro di Windows. Su elementi non Windows, restituisce un errore. registry_open_key L'accessor del registro viene inizializzato pigramente al primo utilizzo e supporta sia l'accesso live alle API di Windows (scansioni localhost su Windows) che l'analisi degli hive REGF basata su file (scansioni di contenitori/volumi).

sbomgen.registry_open_key(path)

Apre una chiave di registro. Restituisce una maniglia chiave che deve essere chiusa conregistry_close.

• Restituisce: 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)

Legge un valore di stringa da una chiave di registro aperta.

• Restituisce: string, err

local version, err = sbomgen.registry_get_string(key, "DisplayVersion")

sbomgen.registry_get_integer(key, value_name)

Legge un valore intero da una chiave di registro aperta.

• Restituisce: number, err

sbomgen.registry_get_strings(key, value_name)

Legge un valore multistringa (REG_MULTI_SZ) da una chiave di registro aperta. Restituisce una tabella di stringhe.

• Restituisce: {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)

Restituisce tutti i nomi delle sottochiavi in una chiave di registro aperta.

• Restituisce: {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)

Chiude un handle di chiave di registro. Anche le maniglie dei tasti vengono chiuse automaticamente dal Garbage Collector, ma si consiglia una chiusura esplicita.

Registrazione dei log

I messaggi di log vengono scritti nell'output della console di sbomgen. Ogni messaggio emesso da un plugin viene automaticamente preceduto dall'etichetta sorgente e dall'ecosistema del plugin, ad esempio:

[custom:python-pip] Parsing requirements.txt

log_infolog_warn, e stampa log_error sempre. log_debugstampa solo quando sbomgen viene invocato con. --verbose

Funzione	Livello	Visibile per impostazione predefinita?
sbomgen.log_debug(message)	DEBUG	No, richiede --verbose
sbomgen.log_info(message)	INFO	Sì
sbomgen.log_warn(message)	WARN	Sì
sbomgen.log_error(message)	ERRORE	Sì

Usa string.format per messaggi formattati:

sbomgen.log_info(string.format("found %d packages in %s", count, file_path))

Funzioni di debug

sbomgen.breakpoint(message)

Stampa su message stderr e blocca l'esecuzione finché l'utente non preme Invio. Se message viene omesso, stampa un messaggio predefinito.

Utilizzatelo come semplice debugger posizionando i breakpoint nei punti chiave del plugin ed eseguitelo per vedere l'output del log circostante. --verbose

sbomgen.log_info("state: " .. some_variable)
sbomgen.breakpoint("paused after state dump — press Enter to continue")

API di test

Le funzioni nella testing tabella globale sono disponibili solo all'interno dei file di test del plug-in (*_test.lua), caricati dainspector-sbomgen plugin test. Non sono disponibili in fase di esecuzione nei plugin di discovery o collection. L'sbomgen.*API completa è disponibile anche all'interno dei file di test, ma sbomgen.* le funzioni che richiedono un artefatto (ad esempiosbomgen.read_file()) producono risultati significativi solo se richiamate dall'interno di una scansione. Per una guida narrativa, consulta il. Guida al test dei plugin

Funzioni di scansione

Ogni funzione di scansione crea un artefatto del tipo specificato, esegue la pipeline discovery→collection del plugin corrente e restituisce i risultati risultanti. L'pathargomento viene risolto in relazione alla directory del file di test.

Funzione	Tipo di artefatto
testing.scan_directory(path)	Directory
testing.scan_archive(path)	Directory (alias di) scan_directory
testing.scan_localhost(path)	Host locale
testing.scan_binary(path)	Binario
testing.scan_volume(path)	Volume
testing.scan_container(path)	Contenitore

Tutti e sei restituiscono una tabella dei risultati con la forma seguente.

Forma del risultato

Ogni tabella di ricerca proietta solo i campi elencati di seguito. In particolare, namespace e non purl_type vengono proiettati separatamente, ma sono incorporati nella purl stringa completa.

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)

Asserzioni

Funzione	Firma	Descrizione
testing.assert_equals	(expected: any, actual: any, message?: string)	Fallisce setostring(expected) ~= tostring(actual).
testing.assert_not_equals	(expected: any, actual: any, message?: string)	Fallisce setostring(expected) == tostring(actual).
testing.assert_true	(value: any, message?: string)	Fallisce se value è false onil.
testing.assert_false	(value: any, message?: string)	Fallisce se non lo value è false e non lo ènil.
testing.assert_nil	(value: any, message?: string)	Fallisce se non lo value ènil.
testing.assert_not_nil	(value: any, message?: string)	Fallisce se value lo ènil.
testing.assert_contains	(haystack: string, needle: string, message?: string)	Fallisce se haystack non contiene needle (corrispondenza tra le sottostringhe).
testing.assert_matches	(str: string, pattern: string, message?: string)	Fallisce se str non corrisponde all'espressione regolare Go (RE2) specificata.
testing.assert_length	(tbl: table, expected: integer, message?: string)	Fallisce se #tbl non è ugualeexpected.

Flusso di controllo

Funzione	Firma	Descrizione
testing.fail	(message: string)	Fallisce immediatamente il test corrente con il messaggio fornito.
testing.skip	(message: string)	Salta il test corrente. Il risultato viene segnalato come ignorato, non fallito.

Scoperta del test

Qualsiasi funzione Lua globale il cui nome inizia con test_ una corrispondenza tra file *_test.lua viene considerata un test. Il file di test deve trovarsi accanto init.lua a una {phase}/{platform}/{category}/{ecosystem}/ profondità normale. I dati del dispositivo vengono inseriti _testdata/ accanto al file di test, in cui il runner non scende _testdata/ durante la ricerca dei file di test.

Gestione errori

Le funzioni API che possono fallire restituiscono due valori:. value, err In caso di successo, err ènil. In caso di errore, il primo valore è nil ed err è una stringa di errore.

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

Se un plugin genera un errore Lua non gestito, sbomgen registra un avviso e continua con il file o il plugin successivo. Gli altri plugin non sono interessati.