Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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](sbomgen-plugin-developer-guide.md) Per i test, vedi[Guida al test dei plugin](sbomgen-plugin-testing-guide.md). ## 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_name``subscribe_to_event`, e così via) che sbomgen chiama in punti definiti del ciclo di vita del plugin. Queste sono documentate in. [Plugin Lifecycle Globals](#sbomgen-plugin-api-reference-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](#sbomgen-plugin-api-reference-testing-api). ### 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'`sbomgen`API 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](#sbomgen-plugin-api-reference-sandbox-restrictions) 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` e`Version`. `version` Ad esempio`find_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 esempio`find_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_name``find_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 da`sbomgen.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`,, `ProductName``FileDescription`, 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](#sbomgen-plugin-api-reference-cyclonedx-properties) | | 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?](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) per le convenzioni per tipo di Inspector. + **`properties`**— proprietà del componente CyclonedX. Queste appaiono nell'`components[].properties`array 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](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) 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 esempio`acme:python-pip:*`): ``` properties = { -- Custom namespace — safe to use (recommended) ["acme:python-pip:manifest_path"] = file_path, ["acme:python-pip:pinned"] = "true", -- Fully-qualified key outside amazon:inspector:* — also fine ["my:custom:namespace:key"] = "value", -- No colon: avoid — ends up as "amazon:inspector:sbom_generator:custom_field" -- custom_field = "value", } ``` ### 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_path`viene sempre aggiunto da sbomgen. + `source_file_scanner`e `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](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) 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](#sbomgen-plugin-api-reference-reserved-namespaces) Gli autori di plugin personalizzati dovrebbero definire le proprietà nel proprio spazio dei nomi (ad esempio`acme: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 tramite`sbomgen.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 o`nil`, 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 Usa`string.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('') 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 con`registry_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_info``log_warn`, e stampa `log_error` sempre. `log_debug`stampa 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 da`inspector-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 esempio`sbomgen.read_file()`) producono risultati significativi solo se richiamate dall'interno di una scansione. Per una guida narrativa, consulta il. [Guida al test dei plugin](sbomgen-plugin-testing-guide.md) ### 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'`path`argomento 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 -- 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.