Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Referencia de la API de complementos

Referencia de API completa para los complementos de Lua de Inspector-sbomgen. Para obtener una guía sobre cómo escribir complementos, consulte. Guía para desarrolladores de complementos Para realizar pruebas, consulteGuía de pruebas de complementos.

Descripción general de

Se accede a todas las funciones proporcionadas en tiempo de ejecución a través de la sbomgen tabla global (archivo I/O, expresión regular, registro, constantes, etc.). Además, cada complemento define un pequeño conjunto de funciones globales de nivel superior (discover,,,, collect get_scanner_namesubscribe_to_event, etc.) a las que sbomgen llama en puntos definidos del ciclo de vida del complemento. Estas están documentadas en. El ciclo de vida de los complementos es global

Dentro de *_test.lua los archivos, sbomgen también expone una información testing global que permite a los autores de las pruebas gestionar el proceso de descubrimiento→recopilación y hacer afirmaciones. Consulte API de pruebas.

Restricciones de Sandbox

Los complementos se ejecutan en una máquina virtual Lua en espacio aislado con acceso restringido a la biblioteca estándar. Están disponibles los siguientes módulos de biblioteca estándar de Lua:

Por motivos de seguridad y estabilidad, no se permiten de forma explícita los siguientes módulos de biblioteca estándar:

Estos módulos no están en la lista de módulos permitidos de la máquina virtual y los complementos no pueden acceder a ellos.

El ciclo de vida de los complementos es global

Un complemento es un archivo Lua llamado init.lua que define ciertas funciones globales de nivel superior. Estos valores globales no están sobre la sbomgen mesa, son funciones que el plugin define para que sbomgen las invoque. El conjunto de valores globales válidos difiere entre los complementos de detección y los complementos de recopilación. Para cada una de las funciones siguientes, si el complemento la omite, se utiliza la función predeterminada que se muestra en la tabla.

Plugins de Discovery

Plugins de colección

Archivo I/O

Todas las operaciones con los archivos deben pasar por la sbomgen.* API. El acceso directo al sistema de archivos a través de la io biblioteca de Lua no está disponible (consulteRestricciones de Sandbox). I/O Las funciones de los sbomgen archivos se distribuyen a través de la interfaz del artefacto, lo que garantiza que el complemento funcione de manera idéntica, ya sea que escanee un directorio en un disco, una imagen contenedora, un archivo comprimido o un volumen montado.

Límite de acceso a los archivos

Las funciones de sbomgen.* archivo limitan las lecturas al artefacto del inventario. Se rechaza una ruta que se resuelve fuera de la raíz del artefacto (por ejemplo, mediante un ../ recorrido) y la llamada devuelve un error en lugar de leer el sistema de archivos del host. Esto se aplica aread_file,, open_file read_dirfile_stat, y a los binary/hash ayudantes que toman una ruta.

La excepción es el tipo de localhost artefacto, que hace un inventario del propio servidor; en este caso, el sistema de archivos del host es el artefacto, por lo que las lecturas no se limitan a una raíz más estrecha.

Este límite rige únicamente la lectura de archivos. No restringe lo que un complemento escribe en la SBOM; consulte. El contenido de SBOM no está desinfectado

sbomgen.get_file_list ()

Devuelve todas las rutas de archivo del artefacto en forma de tabla de cadenas.

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

Lee todo el contenido de un archivo y lo devuelve en forma de cadena.

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

sbomgen.open_file (ruta)

Abre un archivo para leer en streaming. Devuelve un FileHandle objeto. Utilícela para archivos de gran tamaño en los que cargar todo el contenido en la memoria no sea práctico.

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 (patrón)

Devuelve los archivos que coinciden con un patrón global de Go. filepath.Match El patrón se compara con el nombre de archivo base. Los enlaces simbólicos se omiten; solo se devuelven archivos concretos.

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

sbomgen.get_file_list()Utilícelo con string.match para hacer coincidir todos los patrones de ruta.

sbomgen.find_files_by_name (nombres)

Devuelve archivos cuyo nombre base (último componente de ruta) coincide exactamente con uno de los nombres dados. La iteración y la comparación se realizan en Go, lo que hace que sea significativamente más rápido que la iteración sbomgen.get_file_list() en 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 (nombres)

Devuelve los archivos cuyo nombre base coincide con uno de los nombres de pila, ignorando mayúsculas y minúsculas. Por ejemplo, "version" coincide con VERSIONVersion, y. version Por ejemplofind_files_by_name, la coincidencia ocurre fuera de la máquina virtual de 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 (sufijos)

Devuelve los archivos cuya ruta completa (normalizada mediante barras inclinadas) termina con uno de los sufijos dados. Por ejemplo, la coincidencia ocurre fuera de la máquina virtual find_files_by_name de Lua.

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

Devuelve archivos cuya ruta normalizada mediante barras inclinadas coincide con cualquiera de los patrones de expresiones regulares de Go (RE2) dados. La coincidencia se produce fuera de la máquina virtual de Lua, lo que la hace eficiente en listas de archivos grandes.

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

Rendimiento: find_files_by_* frente a get_file_list

En el caso de los complementos de detección, prefiera o iterar en lugar de hacerlo en Lua. find_files_by_name find_files_by_suffix find_files_by_path_regex get_file_list() En un análisis de servidor local con 300 000 archivos, la iteración de la lista de archivos en Lua string.match() tarda unos 15 segundos, mientras que se completa en menos de 1 milisegundo. find_files_by_name La diferencia es que get_file_list() copia cada ruta de archivo en la máquina virtual de Lua en forma de cadena y, a continuación, Lua interpreta el bucle y la coincidencia de patrones para cada una de ellas. Las find_files_by_* funciones realizan la comparación fuera de la máquina virtual de Lua y devuelven solo las rutas coincidentes, lo que evita la sobrecarga de copiar y interpretar por ruta.

Úsala get_file_list() solo cuando necesites una lógica de coincidencia personalizada que no pueda expresarse como una coincidencia de nombre base, sufijo o expresión regular.

sbomgen.read_dir (ruta)

Muestra las entradas de un directorio.

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

Devuelve los metadatos de un archivo.

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 (ruta, entry_ruta)

Lee una sola entrada de un archivo ZIP, JAR o WAR.

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

sbomgen.search_binary (ruta, expresión regular)

Analiza un archivo como ELF, PE o Mach-O binario y busca en la sección predeterminada una expresión regular de Go que coincida con la expresión regular. 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 (ruta, expresión regular [, n])

Analiza un archivo como ELF, PE o Mach-O binario y devuelve todas las coincidencias únicas del primer grupo de captura de la sección predeterminada. constant/variable Pase n para limitar los resultados.

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 (ruta, expresión regular)

Busca en todo el archivo binario la primera coincidencia de expresiones regulares, sin limitarse a una sección específica. Se utiliza cuando la búsqueda basada en secciones (search_binary) no es suficiente, por ejemplo, cuando las cadenas de versión se encuentran en secciones no estándar.

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

FileHandle Métodos

FileHandle los objetos son devueltos porsbomgen.open_file().

fh:read_line ()

Lee la siguiente línea (sin el carácter de nueva línea). Devuelve nil en EOF.

fh:read (n)

Lee hasta bytes. n Devuelve nil en EOF.

fh:close ()

Cierra el identificador del archivo. Cierre siempre las manijas cuando haya terminado.

Utilidades binarias

sbomgen.hash (datos, algoritmo)

Devuelve el resumen codificado en hexadecimal de una cadena de bytes en memoria según el algoritmo dado. Emparéjalo sbomgen.read_file(path) para crear un hash de un archivo que ya hayas leído para analizarlo. Es preferible hacerlo sbomgen.hash_file(path) cuando necesitas tanto los bytes como el resumen, ya que hash no se vuelve a leer el archivo.

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 (ruta, algoritmo)

Devuelve el resumen codificado en hexadecimal del contenido de un archivo según el algoritmo dado. Dirige la lectura a través de la I/O capa de artefactos para que funcione de manera uniforme en todos los artefactos de directorio, contenedor, archivo, volumen y localhost. Utilízala cuando el resumen sea lo único que necesites del archivo.

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

Es igual que 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 (ruta, patrones)

Comprueba si un archivo contiene cada uno de los patrones de bytes dados. Devuelve una tabla de valores booleanos en el mismo orden que los patrones de entrada.

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

Analiza los recursos de la versión de Windows PE desde un archivo binario. Devuelve una tabla con campos de versión o nil, err si el archivo no es un archivo binario de PE o no tiene ningún recurso de versión.

Los file_version campos product_version y provienen de la FixedFileInfo estructura PE, formateados como"major.minor.build.revision". El string_table campo es una tabla anidada con claves según el código de configuración regional (por ejemplo, "040904B0" para el Unicode en inglés de EE. UU.). Cada configuración regional se asigna a una tabla de name/value pares extraída del PE StringFileInfo (ProductVersion,,ProductName, FileDescription etc.). Un binario de PE puede exponer una o más configuraciones regionales.

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

Práctico envoltorio que devuelve solo la cadena de la versión del producto de un binario de PE. FixedFileInfo Equivale a llamar get_pe_version_info(path) y leer. 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 (ruta)

Práctico envoltorio que devuelve solo la cadena de versión del archivo de un binario de PE. FixedFileInfo Equivale a llamar get_pe_version_info(path) y leer. file_version

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

Salida del paquete

sbomgen.push_package (paquete)

Introduce la búsqueda de un paquete en la SBOM. Solo está disponible en los complementos de colección.

La pkg tabla admite los siguientes campos:

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

Hashes de componentes

El hashes campo opcional de los resúmenes de integridad de sbomgen.push_package() los registros de un componente. Las entradas se escriben según el nombre del algoritmo y se serializan en la components[].hashes matriz CyclonedX, de forma que coincide con el esquema esperado por Amazon Inspector.

Algoritmos admitidos

Utilice las constantes de abajo sbomgen.hash_algorithms para que el nombre del algoritmo pasado asbomgen.hash()/sbomgen.hash_file()sea la misma cadena aceptada por: push_package({ hashes = ... })

Reglas de validación

push_package()valida hashes antes de emitir un hallazgo. Un paquete cuyos hashes no se validan se descarta y se registra una advertencia. Validación:

Ejemplo: crear un hash en un manifiesto y adjuntar el resumen

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

Si lo único que necesitas del archivo es el resumen, es preferible leerlo dos veces en lugar de leerlo dos veces, ya que sbomgen.hash_file(path, algo) redirige la lectura a través de la I/O capa de artefactos en una sola pasada.

Propiedades de CyclonedX

Las propiedades de CyclonedX son metadatos de valores clave adjuntos a un componente de la SBOM. Son distintos de los calificadores PURL:

Espacios de nombres reservados

La amazon:inspector:* familia de espacios de nombres de propiedades CyclonedX está reservada para Amazon Inspector:

Plugin-defined las propiedades no deben usar estos espacios de nombres. Escribir en un espacio de nombres reservado puede ocultar los valores en los que se basa Inspector o entrar en conflicto con ellos, y la SBOM resultante puede interpretarse incorrectamente durante la identificación de la vulnerabilidad. Consulte Uso de los espacios de nombres CyclonedX con Amazon Inspector para obtener la lista completa de claves reservadas.

Reglas de nomenclatura de claves

Las claves de propiedad a las que se sbomgen.push_package() transfieren se procesan de la siguiente manera:

Incluya siempre al menos dos puntos en las claves de propiedad que defina. Usa un espacio de nombres exclusivo para tu organización o complemento (por ejemploacme: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",
}

Propiedades establecidas por sbomgen

Sbomgen puede adjuntar propiedades propias a cada componente que emite. Estos valores provienen del espacio de amazon:inspector:sbom_generator:* nombres reservado y no deben ser producidos por complementos. Comportamiento observado en tiempo de ejecución:

La taxonomía completa de las claves reservadas se encuentra en la guía del usuario de Amazon Inspector: Uso de los espacios de nombres CyclonedX con Amazon Inspector.

El contenido de SBOM no está desinfectado

Sbomgenno inspecciona ni filtra los datos que emite un complemento. Los nombres, las versiones, las URL, los hashes y los valores de propiedad de los componentes se escriben en la SBOM según lo previsto. Sbomgenno detecta ni redacta secretos, credenciales, tokens u otros datos confidenciales; si un complemento añade ese valor a un hallazgo, aparece en la SBOM de salida y viaja a cualquier lugar en el que se publique.

Eres responsable de lo que escriban tus plugins. Emite únicamente datos derivados del artefacto que quieras inventariar y trata la SBOM como un artefacto que se puede compartir a la hora de decidir qué incluir.

Constantes de propiedad

Built-in Las constantes de las claves de propiedad están disponibles mediante. sbomgen.properties Cada constante que aparece a continuación se convierte en una clave dentro del espacio de amazon:inspector:sbom_generator:* nombres reservado. Estas constantes existen para que los escáneres integrados de sbomgen emitan claves de propiedad consistentes. No son puntos de extensión para complementos personalizados; al utilizarlos en un complemento personalizado, se escriben en un espacio de nombres reservado, que puede ocultar los valores en los que se basa Inspector. Consulta más Espacios de nombres reservados arriba.

Los autores de complementos personalizados deben definir las propiedades en su propio espacio de nombres (por ejemploacme:my_plugin:*) en lugar de reutilizar estas constantes.

Grupos de escáneres

Los complementos de Discovery deben declarar sus grupos de escáneres medianteget_scanner_groups(). Los grupos clasifican los escáneres y permiten a los usuarios activar o desactivar las categorías de forma selectiva. Las constantes están disponibles a través de: sbomgen.groups

Ejemplo:

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

Constantes de tipo de componente

El component_type campo en push_package() debe ser uno de los tipos de componentes de CyclonedX 1.5. Las constantes están disponibles a través de: sbomgen.component_types

Ejemplo:

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

Constantes del algoritmo hash

Constantes para el parámetro del algoritmo de sbomgen.hash()sbomgen.hash_file(), y el hashes campo de. sbomgen.push_package() Los valores de las cadenas coinciden con los nombres de los algoritmos de hash de CyclonedX, por lo que la misma constante recorre toda la ruta de hash sin necesidad de traducción.

Ejemplo:

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

Constantes de plataforma

Constantes con las que comparar. sbomgen.get_platform() Disponible a través desbomgen.platform:

Ejemplo:

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

Información del artefacto

sbomgen.get_platform ()

Devuelve la cadena de la plataforma de ejecución (por ejemplo,,,). "linux" "windows" "darwin"

sbomgen.get_artifact_type ()

Devuelve el tipo de artefacto que se está escaneando (p. ej.,). "directory" "archive"

sbomgen.should_collect_licenses ()

Devuelve si el usuario habilitó la recopilación de licencias a través de. true --collect-licenses

sbomgen.get_env_vars ()

Devuelve las variables de entorno del artefacto como una tabla de entradas. {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 ()

Devuelve la letra de la unidad del sistema (p. ej.,) del entorno del artefacto. "C:" Lee la variable de SystemDrive entorno, de forma predeterminada "C:" si no está configurada. Este es el equivalente en Lua de. strutils.GetSystemDriverLetter()

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

sbomgen.resolve_glob_paths (patrones)

Amplía los patrones globales del sistema de archivos comparándolos con los del sistema de archivos anfitrión. Localhost-only: devuelve nil más un error en otros tipos de artefactos.

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

Comportamiento:

Cross-platform separadores de rutas:

sbomgen.get_home_dirs ()

Devuelve las raíces del directorio principal del usuario del artefacto, en forma de tabla de rutas. Localhost enumera el sistema de archivos real del host; los artefactos de contenedor y volumen enumeran su propio sistema de archivos (rootfs o montado); todos los demás tipos de artefactos devuelven una tabla vacía. Las rutas se normalizan mediante barra diagonal, se deduplican y se ordenan.

Esta es la forma de localizar directorios por usuario (como las cachés de modelos o la configuración de herramientas) sin necesidad de programar o. /home/* /Users/* Incluye el directorio principal de root y omite los directorios conocidos que no son de usuario (los perfiles integrados, por ejemplo, Public y Default así sucesivamente). 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 composición anterior es solo para localhost, debido resolve_glob_paths a errores en artefactos que no son de localhost. En el caso de los escaneos de contenedores y volúmenes, mejor compare las raíces iniciales devueltas con la lista de archivos del artefacto (por ejemplo, con). sbomgen.find_files_by_path_regex

Comportamiento:

Información del sistema

Estas funciones devuelven metadatos sobre el sistema operativo y el hardware del artefacto. Los valores pueden ser cadenas vacías si la información no está disponible (por ejemplo, al escanear un directorio sin metadatos del sistema operativo).

Expresiones regulares

Los patrones integrados de Lua carecen de funciones como la alternancia (|), los rangos de cuantificación ({n,}) y la visualización anticipada. Para cerrar esta brecha, sbomgen expone directamente el paquete de Go. regexp Estas funciones utilizan la sintaxis de expresiones regulares de Go (RE2), no los patrones de Lua.

sbomgen.regex_find (str, pattern)

Devuelve la primera coincidencia de un patrón de expresiones regulares de Go, o si no coincide. nil

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

sbomgen.regex_match (str, patrón)

Devuelve los grupos de captura de la primera coincidencia. El índice 1 es la coincidencia completa y los 2 son grupos de captura.

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

Devuelve todas las coincidencias que no se superponen. Pase n para limitar los resultados (predeterminado: todos).

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

sbomgen.regex_replace (str, patrón, reemplazo)

Sustituye todos los partidos. La cadena de reemplazo puede usar $1$2, etc. para capturar referencias a grupos.

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

Cuándo usar patrones de expresiones regulares frente a patrones de Lua

Usa elstring.match/incorporado de Lua string.find para patrones simples: son más rápidos y no es necesario eliminar las barras invertidas. Utilízalos cuando necesitessbomgen.regex_*:

Análisis estructurado

Sbomgen presenta ayudantes ligeros para decodificar formatos de texto estructurado directamente en tablas Lua.

sbomgen.json_decode (str)

Analiza una cadena JSON para convertirla en una tabla de 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)

Analiza una cadena XML para convertirla en una tabla de Lua.

Los valores XML utilizan la siguiente 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 de Windows

Estas funciones proporcionan acceso de solo lectura al registro de Windows. En artefactos que no sean de Windows, registry_open_key devuelve un error. El identificador de acceso del registro se inicializa de forma lenta la primera vez que se usa y admite tanto el acceso directo a la API de Windows (localhost escanea en Windows) como el análisis del subárbol REGF basado en archivos (escaneos). container/volume

sbomgen.registry_open_key (ruta)

Abre una clave de registro. Devuelve un identificador de clave con el que se debe cerrarregistry_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 (clave, valor_name)

Lee un valor de cadena de una clave de registro abierta.

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

sbomgen.registry_get_integer (key, value_name)

Lee un valor entero de una clave de registro abierta.

sbomgen.registry_get_strings (key, value_name)

Lee un valor de varias cadenas (REG_MULTI_SZ) de una clave de registro abierta. Devuelve una tabla de cadenas.

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

Devuelve todos los nombres de subclaves de una clave de registro abierta.

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

Cierra un identificador de clave de registro. El recolector de basura también cierra automáticamente los identificadores de claves, pero se recomienda cerrarlos de forma explícita.

Registro

Los mensajes de registro se escriben en la salida de la consola de sbomgen. Cada mensaje emitido por un complemento lleva automáticamente como prefijo la etiqueta fuente y el ecosistema del complemento, por ejemplo:

[custom:python-pip] Parsing requirements.txt

log_infolog_warn, y log_error siempre imprime. log_debugsolo imprime cuando se invoca sbomgen con. --verbose

Úselo string.format para mensajes formateados:

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

Funciones de depuración

sbomgen.breakpoint (mensaje)

Imprime en stderr y bloquea la ejecución message hasta que el usuario pulse Entrar. Si message se omite, imprime un mensaje predeterminado.

Utilízalo como un depurador rudimentario. Para ello, coloca puntos de interrupción en los puntos clave de tu plugin y ejecútalos --verbose para ver el resultado del registro circundante.

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

API de pruebas

Las funciones de la testing tabla global solo están disponibles dentro de los archivos de prueba del complemento (*_test.lua), cargados porinspector-sbomgen plugin test. No están disponibles durante el tiempo de ejecución en los complementos de descubrimiento o recopilación. La sbomgen.* API completa también está disponible en los archivos de prueba, pero sbomgen.* las funciones que requieren un artefacto (por ejemplosbomgen.read_file()) solo producen resultados significativos cuando se invocan desde el interior de un escaneo. Para obtener una guía narrativa, consulte. Guía de pruebas de complementos

Funciones de escaneo

Cada función de escaneo crea un artefacto del tipo determinado, lo compara con el proceso discovery→collection del complemento actual y devuelve los resultados resultantes. El path argumento se resuelve en relación con el directorio del archivo de prueba.

Los seis devuelven una tabla de resultados con la siguiente forma.

Forma del resultado

Cada tabla de búsqueda proyecta solo los campos que se enumeran a continuación. En particular, namespace y no purl_type se proyectan por separado, sino que se incorporan a la purl cadena 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)

Aserciones

Controla el flujo

Detección de pruebas

Cualquier función global de Lua cuyo nombre comience por test_ la coincidencia de un archivo *_test.lua se considera una prueba. El archivo de prueba debe estar al lado de un init.lua a la {phase}/{platform}/{category}/{ecosystem}/ profundidad normal. Los datos de la luminaria se encuentran _testdata/ junto al archivo de prueba; el corredor no desciende al archivo de prueba _testdata/ cuando busca archivos de prueba.

Gestión de errores

Las funciones de API que pueden fallar devuelven dos valores:value, err. En caso de éxito, err esnil. En caso de error, el primer valor es nil y err es una cadena de error.

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

Si un complemento genera un error de Lua no controlado, sbomgen registra una advertencia y continúa con el siguiente archivo o complemento. El resto de plugins no se ven afectados.