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 di inspector-sbomgen. Per una guida sulla scrittura dei plugin, consulta. Guida per sviluppatori di plugin Per i test, consultaGuida al test dei plugin.

Panoramica di

Tutte le funzioni fornite dal runtime sono accessibili tramite la sbomgen tabella globale (file I/O, regex, logging, 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 plug-in. Queste sono documentate in. Plugin Lifecycle Globals

All'interno *_test.lua dei file, sbomgen espone inoltre un valore testing globale che consente agli autori dei test di guidare la pipeline discovery→collection e di fare asserzioni. Consulta API di test.

Restrizioni Sandbox

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

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

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

Plugin Lifecycle Globals

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

Plugin Discovery

Plugin di raccolta

File I/O

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

Limite di accesso ai file

Le funzioni sbomgen.* del file limitano le letture al manufatto presente nell'inventario. Un percorso che si risolve all'esterno della radice dell'artefatto, ad esempio tramite ../ traversal, viene rifiutato e la chiamata restituisce un errore anziché leggere il filesystem host. Questo vale perread_file,, e gli helper che open_file intraprendono un read_dir percorsofile_stat. binary/hash

L'eccezione è rappresentata dal tipo di localhost artefatto, che crea l'inventario dell'host stesso; in questo caso l'artefatto è il filesystem host, quindi le letture non sono limitate a una radice più stretta.

Questo limite regola solo le letture dei file. Non limita ciò che un plugin scrive nella SBOM, vedete. I contenuti SBOM non vengono disinfettati

sbomgen.get_file_list ()

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

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

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

local content, err = sbomgen.read_file("/app/package.json")
if err then
    sbomgen.log_error("read failed: " .. err)
    return
end

sbomgen.open_file (percorso)

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

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

Restituisce i file che corrispondono a un pattern Go glob. filepath.Match Il modello viene confrontato con il nome del file di base. I collegamenti simbolici vengono ignorati; vengono restituiti solo file concreti.

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

Usalo sbomgen.get_file_list() con string.match per la corrispondenza completa dei modelli di percorso.

sbomgen.find_files_by_name (nomi)

Restituisce i file il cui nome base (ultimo componente del percorso) corrisponde esattamente a uno dei nomi dati. L'iterazione e il confronto avvengono in Go, rendendola significativamente più veloce rispetto all'sbomgen.get_file_list()iterazione 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 (nomi)

Restituisce i file il cui nome base corrisponde a uno dei nomi dati, ignorando le maiuscole e minuscole. Ad esempio, "version" corrisponde a, VERSION eVersion. version Ad esempiofind_files_by_name, la corrispondenza avviene all'esterno della macchina virtuale Lua.

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

Restituisce i file il cui percorso completo (forward-slash-normalized) termina con uno dei suffissi specificati. Ad esempio, la corrispondenza avviene all'esterno della macchina virtuale Lua. find_files_by_name

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

Restituisce i file il cui percorso normalizzato con una barra in avanti corrisponde a uno qualsiasi dei modelli di espressione regolare Go (RE2) specificati. La corrispondenza avviene all'esterno della macchina virtuale Lua, il che la rende efficiente su elenchi di file di grandi dimensioni.

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

Prestazioni: find_files_by_* vs get_file_list

Per i plugin di individuazione, preferire o sovraiterare in Lua. find_files_by_name find_files_by_suffix find_files_by_path_regex get_file_list() In una scansione su localhost con 300.000 file, l'iterazione dell'elenco dei file in Lua string.match() richiede circa 15 secondi, mentre il completamento richiede meno di 1 millisecondo. find_files_by_name La differenza è che get_file_list() copia ogni percorso di file nella VM Lua come una stringa, quindi Lua interpreta il ciclo e la corrispondenza del pattern per ognuno di essi. Le find_files_by_* funzioni eseguono la corrispondenza all'esterno della VM Lua e restituiscono solo i percorsi corrispondenti, evitando il sovraccarico sia della copia che dell'interpretazione per percorso.

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

sbomgen.read_dir (percorso)

Elenca le voci in una directory.

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

Restituisce i metadati relativi a un file.

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 (percorso, entry_path)

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

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

sbomgen.search_binary (percorso, regex)

Analizza un file come ELF, PE o Mach-O binario e cerca nella sezione predefinita una corrispondenza regex Go. 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 (path, regex [, n])

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

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 (percorso, regex)

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

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). Restituisce nil in EOF.

fh:read (n)

Legge fino a byte. n Restituisce nil in EOF.

fh:close ()

Chiude l'handle del file. Quando hai finito, chiudi sempre le maniglie.

Utilità binarie

sbomgen.hash (dati, algoritmo)

Restituisce il digest con codifica esadecimale di una stringa di byte in memoria con l'algoritmo dato. Abbinalo sbomgen.read_file(path) per eseguire l'hashing di un file che hai già letto per l'analisi, preferibile rispetto a sbomgen.hash_file(path) quando hai bisogno sia dei byte che del digest, poiché non rilegge il file. 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 (percorso, algoritmo)

Restituisce il digest con codifica esadecimale del contenuto di un file secondo l'algoritmo dato. Indirizza la lettura attraverso il I/O livello degli artefatti, in modo che funzioni in modo uniforme su directory, contenitore, archivio, volume e artefatti localhost. Usalo quando il digest è l'unica cosa di cui hai bisogno dal file.

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

Equivalente a 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 (percorso, modelli)

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

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

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

I file_version campi product_version and provengono dalla FixedFileInfo struttura PE, formattata come"major.minor.build.revision". Il string_table campo è una tabella annidata con codice locale (ad esempio, "040904B0" per Unicode in inglese americano). Ogni locale è mappato a una tabella di name/value coppie tratte dal PE StringFileInfo (ProductVersion,, ProductNameFileDescription, ecc.). Un file 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 (percorso)

Comodo 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

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

sbomgen.parse_file_version (percorso)

Comodo 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

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

Uscita del pacchetto

sbomgen.push_package (pacchetto)

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

La pkg tabella supporta i seguenti campi:

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

Hash dei componenti

Il hashes campo opzionale sui riassunti di integrità dei sbomgen.push_package() record per un componente. Le voci vengono digitate in base al nome dell'algoritmo e serializzate nell'components[].hashesarray CyclonedX, corrispondente allo schema previsto da Amazon Inspector.

Algoritmi supportati

Utilizza le costanti in sbomgen.hash_algorithms modo che il nome dell'algoritmo passato a/sia la stessa stringa accettata dasbomgen.hash(): sbomgen.hash_file() push_package({ hashes = ... })

Regole di convalida

push_package()convalida hashes prima di emettere un risultato. Un pacchetto i cui hash falliscono la convalida viene eliminato e viene registrato un avviso. Convalida:

Esempio: eseguire l'hashing di un manifest e allegare il 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

Quando il digest è l'unica cosa di cui avete bisogno dal file, preferite piuttosto sbomgen.hash_file(path, algo) che leggerlo due volte: fa scorrere la lettura attraverso il livello degli artefatti I/O in un unico passaggio.

Proprietà CyclonedX

Le proprietà CyclonedX sono metadati chiave-valore allegati a un componente nella SBOM. Sono distinte dai qualificatori PURL:

Namespace riservati

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

Plugin-defined le proprietà non devono utilizzare questi namespace. La scrittura in un namespace riservato può oscurare o entrare in conflitto con i valori su cui si basa Inspector e l'SBOM risultante può essere interpretato in modo errato durante l'identificazione delle vulnerabilità. Consulta Utilizzo dei namespace CyclonedX con Amazon Inspector per l'elenco completo delle chiavi riservate.

Regole di denominazione delle chiavi

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

Includi sempre almeno i due punti nelle chiavi di proprietà che definisci. Usa un namespace univoco 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ò attribuire proprietà proprie a ogni componente che emette. Questi valori provengono dal amazon:inspector:sbom_generator:* namespace riservato e non devono essere prodotti dai plugin. Comportamento in fase di esecuzione osservato:

La tassonomia completa delle chiavi riservate è mantenuta nella guida per l'utente di Amazon Inspector: Utilizzo dei namespace CyclonedX con Amazon Inspector.

I contenuti SBOM non vengono disinfettati

Sbomgennon ispeziona o filtra i dati emessi da un plugin. I nomi dei componenti, le versioni, i PURL, gli hash e i valori delle proprietà vengono scritti nella SBOM come fornito. Sbomgennon rileva né oscura segreti, credenziali, token o altri dati sensibili: se un plug-in inserisce tale valore in un risultato, questo appare nell'SBOM di output e viaggia ovunque l'SBOM sia pubblicato.

Sei responsabile di ciò che scrivono i tuoi plugin. Emetti solo dati derivati dall'artefatto che intendi inventariare e considera l'SBOM come un artefatto condivisibile quando decidi cosa includere.

Costanti di proprietà

Built-in le costanti delle chiavi di proprietà sono disponibili tramite. sbomgen.properties Ogni costante seguente si risolve in una chiave all'interno del namespace 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 plugin personalizzati: utilizzandoli in un plug-in personalizzato si scrive in uno spazio dei nomi riservato, che può oscurare i valori su cui si basa Inspector. Vedi sopra. Namespace riservati

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

Gruppi di scanner

I plug-in 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

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 componente CyclonedX 1.5. Le costanti sono disponibili tramite: sbomgen.component_types

Esempio:

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

Costanti dell'algoritmo di hash

Costanti per il parametro dell'algoritmo di sbomgen.hash()sbomgen.hash_file(), e il hashes campo di. sbomgen.push_package() I valori della stringa corrispondono ai nomi degli algoritmi hash CyclonedX, quindi la stessa costante attraversa l'intero percorso di hashing senza traduzione.

Esempio:

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

Costanti della piattaforma

Costanti per il confronto con. sbomgen.get_platform() Disponibile tramitesbomgen.platform:

Esempio:

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

Informazioni sugli artefatti

sbomgen.get_platform ()

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

sbomgen.get_artifact_type ()

Restituisce il tipo di artefatto sottoposto a scansione (ad esempio,). "directory" "archive"

sbomgen.should_collect_licenses ()

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

sbomgen.get_env_vars ()

Restituisce le variabili di ambiente dall'artefatto come tabella di voci. {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 ()

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

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

sbomgen.resolve_glob_paths (modelli)

Espande i pattern glob del filesystem rispetto al filesystem host. Localhost-only: restituisce nil più un errore su altri tipi di artefatti.

function get_localhost_scan_paths()
    return sbomgen.resolve_glob_paths({
        "/home/*/.cache/huggingface/hub",
        "/Users/*/.cache/huggingface/hub",
        "C:/Users/*/.cache/huggingface/hub",
    })
end

Comportamento:

Cross-platform separatori di percorso:

sbomgen.get_home_dirs ()

Restituisce le radici della home directory dell'utente per l'artefatto, sotto forma di tabella di percorsi. Localhost enumera il vero filesystem host; gli artefatti relativi a contenitori e volumi enumerano il proprio filesystem (rootfs o montato); tutti gli altri tipi di artefatti restituiscono una tabella vuota. I percorsi vengono normalizzati con una barra in avanti, deduplicati e ordinati.

Questo è il modo in grado di individuare le directory per utente (come le cache dei modelli o la configurazione degli strumenti) senza codifica fissa o. /home/* /Users/* Include la home directory di root e salta le directory non utente più note (profili integrati come and on, on e on). Public Default 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

La composizione sopra riportata è solo per localhost, a causa di errori su elementi non appartenenti a localhost. resolve_glob_paths Per le scansioni di contenitori e volumi, confronta invece le radici iniziali restituite con l'elenco dei file dell'elemento (ad esempio, con). sbomgen.find_files_by_path_regex

Comportamento:

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, quando si esegue la scansione di una directory senza i metadati del sistema operativo).

Espressioni regolari

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

sbomgen.regex_find (str, pattern)

Restituisce la prima corrispondenza di un pattern regex Go, o se non corrisponde. nil

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

sbomgen.regex_match (str, modello)

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

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, modello [, n])

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

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

sbomgen.regex_replace (str, pattern, sostituzione)

Sostituisce tutte le corrispondenze. La stringa sostitutiva può utilizzare $1$2, ecc. per i riferimenti ai gruppi di acquisizione.

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

Quando usare i pattern regex e Lua

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

Analisi strutturata

Sbomgen presenta degli 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.

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.

I valori XML utilizzano la seguente forma:

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. Sugli artefatti non Windows, registry_open_key restituisce un errore. La funzione di accesso al registro viene inizializzata pigramente al primo utilizzo e supporta sia l'accesso live alle API di Windows (scansioni localhost su Windows) sia l'analisi hive REGF basata su file (scansioni). container/volume

sbomgen.registry_open_key (percorso)

Apre una chiave di registro. Restituisce una maniglia a chiave che deve essere chiusa conregistry_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 (chiave, nome_valore)

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

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

sbomgen.registry_get_integer (chiave, nome_valore)

Legge un valore intero da una chiave di registro aperta.

sbomgen.registry_get_strings (chiave, nome_valore)

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

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

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

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

Chiude l'handle di una chiave di registro. Anche le maniglie delle chiavi vengono chiuse automaticamente dal garbage collector, ma è consigliata una chiusura esplicita.

Registrazione dei log

I messaggi di registro 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 richiamato con. --verbose

Uso string.format per messaggi formattati:

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

Funzioni di debug

sbomgen.breakpoint (messaggio)

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

Usatelo come un semplice debugger posizionando i punti di interruzione nei punti chiave del plugin ed eseguendoli --verbose per visualizzare l'output del log circostante.

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 plugin (*_test.lua), caricati dainspector-sbomgen plugin test. Non sono disponibili in fase di esecuzione nei plugin di scoperta o raccolta. 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 su di esso la pipeline discovery→collection del plugin corrente e restituisce i risultati risultanti. L'pathargomento viene risolto rispetto alla directory del file di test.

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

Flusso di controllo

Scoperta del test

Qualsiasi funzione Lua globale il cui nome inizia con test_ in una corrispondenza di file *_test.lua viene considerata un test. Il file di test deve trovarsi accanto a un altro init.lua alla {phase}/{platform}/{category}/{ecosystem}/ profondità normale. I dati del dispositivo vengono inseriti _testdata/ accanto al file di test: il corridore non vi scende _testdata/ quando cerca i 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 plugin successivo. Gli altri plugin non sono interessati.