Referencia de la API de complementos

Referencia completa de la API para los complementos de Lua 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 (E/S de archivos, expresiones regulares, 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 invoca en puntos definidos del ciclo de vida del complemento. Están documentadas en. Plugin Lifecycle Globals

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

Restricciones de sandbox

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

Módulo	Notas
base	Funciones principales (print,type,tostring,tonumber,pairs,ipairs,pcall,error,select,unpack,rawget,rawset,, etc.). dofile,loadfile, y loadstring se eliminan.
string	Manipulación completa de cadenas (string.matchstring.findstring.format,string.gsub,,, etc.)
table	Manipulación completa de la tabla (table.inserttable.removetable.sort,table.concat,,, etc.)
math	Biblioteca matemática completa (math.floormath.max,math.min,, etc.)
package	require()está disponible pero está restringido a los módulos del propio árbol de directorios del complemento. El recorrido del directorio principal (require("../shared")) está bloqueado. package.cpathy están borrados. package.path

Los siguientes módulos de biblioteca estándar no están permitidos de forma explícita por motivos de seguridad y estabilidad:

Módulo	Motivo
io	El acceso directo al sistema de archivos está bloqueado. Todas las operaciones con los archivos deben pasar por sbomgen.* funciones, que se distribuyen a través de la interfaz del artefacto para lograr un comportamiento coherente en todos los tipos de artefactos (directorio, contenedor, volumen, etc.).
os	Las operaciones a nivel del sistema (os.execute,os.remove, os.renameos.getenv, etc.) están bloqueadas para evitar que los complementos modifiquen el sistema anfitrión.
debug	La biblioteca de depuración está bloqueada para impedir la inspección o modificación de las partes internas de la máquina virtual Lua.
coroutine	Las corrutinas no están cargadas.

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

nota

Importante: Todos los archivos I/O deben pasar por sbomgen.* funciones (por ejemplo,sbomgen.read_file,sbomgen.open_file,sbomgen.get_file_list). El uso io.open o cualquier acceso directo al sistema de archivos generará un error de tiempo de ejecución. La sbomgen API garantiza que los complementos interactúen con la capa de abstracción de artefactos, lo que proporciona un comportamiento coherente al escanear un directorio, una imagen de contenedor, un archivo o un volumen.

Plugin Lifecycle Globals

Un complemento es un nombre de archivo de Lua init.lua que define ciertas funciones globales de nivel superior. Estas 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 descubrimiento y los complementos de recopilación. Para cada función que se muestra a continuación, si el complemento la omite, se utiliza la función predeterminada que se muestra en la tabla.

Plugins de Discovery

Función	Arity	Obligatorio	Predeterminado (si se omite)	Descripción
discover()	0	Sí	—	Devuelve los archivos que ha encontrado este complemento. Devuelve una tabla secuencial de cadenas de rutas (modo de evento único) o una tabla codificada por cadenas de nombres de eventos cuyos valores son tablas de rutas (modo de eventos múltiples).
get_event_name()	0	No	"lua:{platform}/{category}/{ecosystem}"	Devuelve el nombre del evento con el que se publican los archivos. Debe ser único en todos los complementos de detección.
get_scanner_name()	0	No	nombre del directorio del ecosistema	Devuelve el nombre para mostrar del escáner. Debe ser único en todos los complementos de detección.
get_scanner_description()	0	No	"Lua discovery plugin: {ecosystem}"	Devuelve una descripción legible para los humanos.
get_scanner_groups()	0	No	Derivado del directorio de categorías (consulta la guía para desarrolladores)	Devuelve una tabla de cadenas de grupos de escáneres. Usa sbomgen.groups.* constantes.
get_localhost_scan_paths()	0	No	—	Devuelve una tabla de file/directory rutas para incluirla al escanear un artefacto de un host local. Solo se consulta para escaneos. localhost

Plugins de colección

Función	Arity	Obligatorio	Predeterminado (si se omite)	Descripción
collect(file_path)	1	Sí	—	Se llama una vez por cada archivo publicado en el evento suscrito. Analice el archivo y emita los hallazgos a través desbomgen.push_package(). No devuelve nada.
subscribe_to_event()	0	No	"lua:{platform}/{category}/{ecosystem}"	Devuelve el nombre del evento al que está suscrito este recopilador. Debe coincidir con el complemento de descubrimiento correspondiente. get_event_name()
get_collector_name()	0	No	nombre del directorio del ecosistema	Devuelve el nombre para mostrar del recopilador. Debe ser único en todos los complementos de la colección.
get_collector_description()	0	No	""(vacío)	Devuelve una descripción legible para los humanos.

E/S de archivos

Todas las operaciones de 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 (consulte). Restricciones de sandbox I/O Las funciones de los sbomgen archivos se distribuyen a través de la interfaz de artefactos, lo que garantiza que el plugin funcione de la misma manera al escanear un directorio en el disco, una imagen de contenedor, un archivo comprimido o un volumen montado.

sbomgen.get_file_list()

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

• Devuelve: {string, ...} — tabla de cadenas de rutas absolutas de archivos

• Rendimiento: esta función copia todas las rutas de archivo del artefacto en la máquina virtual de Lua como una cadena de Lua. En el caso de artefactos de gran tamaño (por ejemplo, un escaneo de un servidor local con más de 300 000 archivos), esto por sí solo tarda varios segundos. La iteración de la tabla devuelta en Lua supone una sobrecarga adicionalstring.match(): una exploración completa puede tardar más de 15 segundos. Cuantos más archivos haya en el artefacto, más lento será el plugin.

nota

Prefiere estas alternativas específicas siempre que sea posible:

Función	Úselo cuando...
sbomgen.find_files_by_name()	Sabe los nombres de archivo exactos que deben coincidir (por ejemplo,"requirements.txt","curl")
sbomgen.find_files_by_name_icase()	Igual que el anterior, pero no distingue entre mayúsculas y minúsculas
sbomgen.find_files_by_suffix()	Debe hacer coincidir los sufijos de las rutas (por ejemplo,,) "/pom.properties" "curlver.h"
sbomgen.find_files_by_path_regex()	Necesita una coincidencia de expresiones regulares de ruta completa
sbomgen.glob_find_files()	Necesita una coincidencia de nombres base al estilo global

Estas funciones realizan la coincidencia fuera de la máquina virtual de Lua y devuelven solo las rutas coincidentes, lo que se completa en menos de 1 milisegundo incluso con artefactos de 300 000 archivos. Úselo get_file_list() solo cuando su lógica de coincidencia no se pueda expresar con ninguna de las opciones anteriores.

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

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

• Devuelve: string, err

• En caso de fallo: 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)

Abre un archivo para la transmisión de lecturas. Devuelve un FileHandle objeto. Úselo para archivos grandes en los que no sea práctico cargar todo el contenido en la memoria.

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

Devuelve los archivos que coinciden con un patrón filepath.Match global de Go. El patrón coincide con el nombre de archivo base.

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

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

Úselo sbomgen.get_file_list() con string.match para la coincidencia de patrones de ruta completa.

sbomgen.find_files_by_name(names)

Devuelve los archivos cuyo nombre base (componente de la última ruta) coincide exactamente con uno de los nombres de pila. La iteración y la comparación se realizan en Go, lo que las hace considerablemente más rápidas que en Lua. sbomgen.get_file_list()

• Parámetros: names — tabla de cadenas (los nombres base deben coincidir)

• Devuelve: {string, ...} — rutas de archivo coincidentes (tupla sin errores)

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)

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.

• Parámetros: names — tabla de cadenas (los nombres base deben coincidir, no distingue mayúsculas de minúsculas)

• Devuelve: {string, ...} — rutas de archivo coincidentes (tupla sin errores)

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)

Devuelve los archivos cuya ruta completa (forward-slash-normalized) termina con uno de los sufijos dados. Por ejemplofind_files_by_name, la coincidencia ocurre fuera de la máquina virtual de Lua.

• Parámetros: suffixes — tabla de cadenas (los sufijos de ruta deben coincidir)

• Devuelve: {string, ...} — rutas de archivo coincidentes (tupla sin errores)

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)

Devuelve los archivos cuya forward-slash-normalized ruta 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.

• Parámetros: patterns — tabla de cadenas de expresiones regulares de Go

• Devuelve: {string, ...} — rutas de archivo coincidentes (tupla sin errores)

• Genera: un error de Lua si algún patrón no se compila

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

Rendimiento: vs find_files_by_* get_file_list

Para los complementos de descubrimiento find_files_by_namefind_files_by_suffix, prefiera o find_files_by_path_regex iterar get_file_list() en exceso en Lua. En un escaneo de un servidor local con 300 000 archivos, la iteración de la lista de archivos en Lua string.match() tarda unos 15 segundos y se completa en menos de 1 milisegundo. find_files_by_name La diferencia es que get_file_list() copia todas las rutas de los archivos en la máquina virtual de Lua como una cadena y, a continuación, Lua interpreta la coincidencia de bucles y patrones de cada una de ellas. Las find_files_by_* funciones realizan la coincidencia fuera de la máquina virtual de Lua y devuelven solo las rutas coincidentes, lo que evita la sobrecarga de interpretación tanto por ruta como por copia.

Úselo get_file_list() solo cuando necesite una lógica de coincidencia personalizada que no se pueda expresar como una coincidencia de nombre base, sufijo o expresión regular.

sbomgen.read_dir(path)

Muestra las entradas de un directorio.

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

Devuelve los metadatos de un archivo.

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

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

• Devoluciones: string, err

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

sbomgen.search_binary(path, regex)

Analiza un archivo como un binario ELF, PE o Mach-O y busca en la constant/variable sección predeterminada una coincidencia de expresiones regulares de Go.

• Devuelve: string|nil, err — la cadena coincidente, o cero si no hay coincidencia

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

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

• Devuelve: {string, ...}|nil, err — tabla de cadenas coincidentes, o cero si no hay coincidencias

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)

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.

• Devuelve: string|nil, err — la cadena coincidente, o cero si no hay coincidencia

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 línea siguiente (sin el carácter de nueva línea). Devuelve nil en EOF.

• Devoluciones: string|nil, err

fh:read(n)

Lee hasta n bytes. Devuelve nil en EOF.

• Devoluciones: string|nil, err

fh:close()

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

Utilidades binarias

sbomgen.sha256(path)

Devuelve el hash SHA-256 codificado en hexadecimal del contenido de un archivo.

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

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.

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

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 binario de PE o no tiene ningún recurso de versión.

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

Los file_version campos product_version y provienen de la FixedFileInfo estructura PE, formateada como"major.minor.build.revision". El string_table campo es una tabla anidada con una clave de código regional (por ejemplo, "040904B0" para Unicode en inglés estadounidense). Cada configuración regional se asigna a una tabla de name/value pares extraídos del PE StringFileInfo (ProductVersion,,ProductName, FileDescription etc.). Un binario 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(path)

Práctico contenedor que devuelve solo la cadena de versión del producto de un binario PE. FixedFileInfo Equivale a llamar get_pe_version_info(path) y leerproduct_version.

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

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

• Devoluciones: string, err

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

Package Output

sbomgen.push_package(pkg)

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

La pkg tabla admite los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre del paquete
version	cadena	No	Cadena de versión resuelta
namespace	cadena	No	Espacio de nombres PURL (por ejemplo,,) "curl" "wordpress/plugin"
purl_type	cadena	Sí	Tipo de PURL (p. ej.,,,"pypi","npm") "cargo" "deb" "generic"
component_type	cadena	Sí	Tipo de componente CyclonedX; utilice sbomgen.component_types.* constantes (p. ej.,) sbomgen.component_types.LIBRARY
qualifiers	tabla	No	Los calificadores de PURL son pares clave-valor (aparecen en la URL del paquete)
properties	tabla	No	Propiedades del componente CyclonedX como pares clave-valor (consulte) Propiedades de CyclonedX
children	tabla	No	Paquetes secundarios anidados, cada uno con la misma forma que (los campos obligatorios se validan de forma pkg recursiva)

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

Propiedades de CyclonedX

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

• qualifiers— Calificadores de PURL. Pasan a formar parte de la cadena URL del paquete (por ejemplo,pkg:deb/debian/curl@7.88.1?arch=amd64). Algunos calificadores de PURL tienen un significado semántico para Amazon Inspector e influyen en la identificación de vulnerabilidades. Consulte ¿Qué es la URL de un paquete? para ver las convenciones por tipo de Inspector.

• properties— Propiedades del componente CyclonedX. Aparecen en la components[].properties matriz de la SBOM y no cambian la forma en que se identifica el componente.

Espacios de nombres reservados

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

• amazon:inspector:sbom_generator:*— utilizado por sbomgen y sus escáneres integrados.

• amazon:inspector:sbom_scanner:*— utilizada por la API de escaneo de Amazon Inspector.

Las propiedades definidas por el complemento no deben usar estos espacios de nombres. Escribir en un espacio de nombres reservado puede ocultar o entrar en conflicto con los valores en los que se basa el Inspector, y la SBOM resultante puede interpretarse incorrectamente durante la identificación de la vulnerabilidad. Consulte Uso de espacios de nombres CyclonedX con Amazon Inspector para ver la lista completa de claves reservadas.

Reglas de nomenclatura clave

Las claves de propiedad transferidas sbomgen.push_package() se procesan de la siguiente manera:

Tecla de entrada	Clave resultante en SBOM	¿Se recomienda para complementos personalizados?
Contiene : (por ejemplo,acme:my_plugin:field)	Se usa textualmente	Sí, coloca todas las propiedades definidas por el plugin en tu propio espacio de nombres
No (por ejemplo,) : field	Prefijo automáticamente a amazon:inspector:sbom_generator:field	No, se escribe en un espacio de nombres reservado

Incluye siempre al menos dos puntos en las claves de propiedad que definas. 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 emita. Estos valores provienen del espacio de amazon:inspector:sbom_generator:* nombres reservado y no deben ser generados por complementos. Comportamiento observado en tiempo de ejecución:

• source_pathsiempre lo añade sbomgen.

• source_file_scannery source_package_collector se añaden cuando --enable-debug-props está activado.

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

Constantes de propiedad

Las constantes clave de propiedad integradas están disponibles en. 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 en sbomgen emitan claves de propiedad consistentes. No son puntos de extensión para complementos personalizados: su uso en un complemento personalizado se escribe en un espacio de nombres reservado, que puede ocultar los valores en los que se basa Inspector. Véase más arribaEspacios de nombres reservados.

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

Constant	Valor resuelto
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

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 categorías de forma selectiva. Las constantes están disponibles a través de: sbomgen.groups

Constant	Valor	Descripción
sbomgen.groups.OS	"os"	Administradores de paquetes del sistema operativo (dpkg, rpm, etc.)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	Administradores de paquetes de idiomas (pip, npm, maven, etc.)
sbomgen.groups.BINARY	"binary"	Análisis binario compilado (Go, Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	Colección general de paquetes
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	Ecosistemas adicionales (curl, nginx, etc.)
sbomgen.groups.CERTIFICATE	"certificate"	Escaneo de certificados
sbomgen.groups.CUSTOM	"custom"	Se agrega automáticamente a todos los complementos personalizados cargados mediante --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	Detección de modelos de aprendizaje automático

Ejemplo:

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

Constantes de tipo de componente

El component_type campo de entrada 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

Constant	Valor
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"

Ejemplo:

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

Constantes de plataforma

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

Constant	Valor
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

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 en tiempo de ejecución (por ejemplo,"linux","windows","darwin").

sbomgen.get_artifact_type()

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

sbomgen.should_collect_licenses()

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

sbomgen.get_env_vars()

Devuelve las variables de entorno del artefacto en forma de tabla de {key, value} entradas.

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 (por ejemplo,"C:") del entorno del artefacto. Lee la variable de SystemDrive entorno, cuyo valor predeterminado es "C:" si no está establecida. Este es el equivalente en Lua de. strutils.GetSystemDriverLetter()

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

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

Función	Devuelve
sbomgen.get_os_name()	Nombre del sistema operativo (p. ej."Ubuntu","Alpine Linux")
sbomgen.get_os_version()	Versión del sistema operativo (por ejemplo,"22.04","3.18")
sbomgen.get_os_codename()	Nombre en clave del sistema operativo (por ejemplo,,"jammy") "bookworm"
sbomgen.get_os_id()	Identificador del sistema operativo (por ejemplo,,"ubuntu") "alpine"
sbomgen.get_kernel_name()	Nombre del núcleo (por ejemplo,"Linux")
sbomgen.get_kernel_version()	Cadena de versión del núcleo
sbomgen.get_cpu_arch()	Arquitectura de la CPU (por ejemplo,"x86_64","aarch64")
sbomgen.get_hostname()	Nombre de host del sistema

Expresiones regulares

Los patrones integrados de Lua carecen de funciones como la alternancia (|), los rangos del cuantificador ({n,}) y la visualización anticipada. Para cerrar esta brecha, sbomgen expone el paquete de Go directamente. 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 hay coincidencia. nil

• Devuelve: string|nil, err

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

sbomgen.regex_match(str, pattern)

Devuelve los grupos de captura de la primera partida. El índice 1 es la coincidencia completa, el 2+ son los grupos de captura.

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

Devuelve todas las coincidencias que no se superpongan. nPasar para limitar los resultados (predeterminado: todos).

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

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

sbomgen.regex_replace(str, pattern, replacement)

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

• Devoluciones: string, err

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

Cuándo usar patrones regex frente a Lua

Usa el símbolostring.match/integrado en Lua string.find para crear patrones simples: son más rápidos y no requieren usar barras invertidas. sbomgen.regex_*Úsalo cuando necesites:

• Alternancia: (foo|bar)

• Rangos de cuantificadores: \d{8,}

• Clases de caracteres complejas que no se pueden expresar en los patrones de Lua

Análisis estructurado

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

sbomgen.json_decode(str)

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

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

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

• Devuelve: table|nil, err

Los valores XML utilizan la siguiente forma:

• _name— nombre del elemento

• _attr— tabla de atributos, cuando esté presente

• _text— contenido de texto recortado, cuando esté presente

• índices numéricos1..n: elementos secundarios

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 los artefactos que no son de Windows, registry_open_key devuelve un error. El descriptor de acceso al registro se inicializa de forma lenta la primera vez que se usa y admite tanto el acceso directo a la API de Windows (el host local escanea en Windows) como el análisis de subconjuntos de REGF basado en archivos (escaneos de contenedores y volúmenes).

sbomgen.registry_open_key(path)

Abre una clave de registro. Devuelve un identificador de llave con el que se debe cerrarregistry_close.

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

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

• Devuelve: string, err

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.

• Devuelve: number, err

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.

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

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

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

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 el prefijo de la etiqueta fuente y el ecosistema del complemento, por ejemplo:

[custom:python-pip] Parsing requirements.txt

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

Función	Nivel	¿Visible por defecto?
sbomgen.log_debug(message)	DEBUG	No, requiere --verbose
sbomgen.log_info(message)	INFO	Sí
sbomgen.log_warn(message)	WARN	Sí
sbomgen.log_error(message)	ERROR	Sí

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

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

Utilízalo como un depurador rudimentario: coloca puntos de interrupción en los puntos clave de tu complemento 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 en 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 dentro de un escaneo. Para obtener una guía narrativa, consulte laGuía de pruebas de complementos.

Funciones de escaneo

Cada función de escaneo crea un artefacto del tipo indicado, ejecuta el proceso descubrimiento→colección del complemento actual y devuelve los resultados obtenidos. El path argumento se resuelve en relación con el directorio del archivo de prueba.

Función	Tipo de artefacto
testing.scan_directory(path)	Directorio
testing.scan_archive(path)	Directorio (alias descan_directory)
testing.scan_localhost(path)	Anfitrión local
testing.scan_binary(path)	Binario
testing.scan_volume(path)	Volume
testing.scan_container(path)	Container

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

Función	Signature	Descripción
testing.assert_equals	(expected: any, actual: any, message?: string)	Falla sitostring(expected) ~= tostring(actual).
testing.assert_not_equals	(expected: any, actual: any, message?: string)	Falla sitostring(expected) == tostring(actual).
testing.assert_true	(value: any, message?: string)	Falla si value es false onil.
testing.assert_false	(value: any, message?: string)	Falla si no value lo es false y no lo esnil.
testing.assert_nil	(value: any, message?: string)	Falla si no lo value esnil.
testing.assert_not_nil	(value: any, message?: string)	Falla si value lo esnil.
testing.assert_contains	(haystack: string, needle: string, message?: string)	Falla si haystack no contiene needle (coincidencia de subcadena).
testing.assert_matches	(str: string, pattern: string, message?: string)	Falla si str no coincide con la expresión regular Go (RE2) dada.
testing.assert_length	(tbl: table, expected: integer, message?: string)	Falla si #tbl no es igual. expected

Controle el flujo

Función	Signature	Descripción
testing.fail	(message: string)	No pasa la prueba actual inmediatamente con el mensaje dado.
testing.skip	(message: string)	Omite la prueba actual. El resultado se notifica como omitido, no fallido.

Detección de pruebas

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

Gestión de errores

Las funciones de la 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. Los demás complementos no se ven afectados.