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 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](sbomgen-plugin-developer-guide.md) Para realizar pruebas, consulte[Guía de pruebas de complementos](sbomgen-plugin-testing-guide.md).
## 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_name``subscribe_to_event`, etc.) a las que sbomgen invoca en puntos definidos del ciclo de vida del complemento. Están documentadas en. [Plugin Lifecycle Globals](#sbomgen-plugin-api-reference-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](#sbomgen-plugin-api-reference-testing-api).
### 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. Parent-directory traversal (require("../shared")) está bloqueado. package.cpathy package.path están borrados. |
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 realizarse mediante sbomgen.\* funciones, que se distribuyen a través de la interfaz del artefacto para garantizar un comportamiento coherente en todos los tipos de artefactos (directorio, contenedor, volumen, etc.) y limitar las lecturas al artefacto que se encuentra en el inventario (consulte). [Límite de acceso a los archivos](#sbomgen-plugin-api-reference-file-access-boundary) |
| os | System-level las operaciones (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 llame. 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 visible 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 por humanos. |
## Archivo I/O
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](#sbomgen-plugin-api-reference-sandbox-restrictions) 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.
### Límite de acceso a los archivos
Las funciones del `sbomgen.*` archivo limitan las lecturas al artefacto que se encuentra en el inventario. Se rechaza una ruta que se resuelva 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 anfitrión. Esto se aplica a`read_file`, `open_file` `read_dir``file_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 host; en este caso, el artefacto es el sistema de archivos del anfitrión, por lo que las lecturas no se limitan a una raíz más estrecha.
*Este límite rige únicamente las lecturas de los archivos.* No limita lo que un complemento escribe en la SBOM; consulte. [El contenido de la SBOM no está desinfectado](#sbomgen-plugin-api-reference-sbom-contents-not-sanitized)
### `sbomgen.get_file_list ()`
Devuelve todas las rutas de los archivos del artefacto como una 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 adicional`string.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() | Conoce 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, completándolas en menos de 1 milisegundo, incluso con 300 artefactos. K-file Úsala `get_file_list()` solo cuando tu lógica de coincidencia no se pueda expresar con ninguna de las opciones anteriores.
`glob_find_files`Los ayudantes `find_files_by_*` y omiten los enlaces simbólicos y devuelven solo archivos concretos, por lo que no se inventarian el alias del enlace simbólico y su destino. `get_file_list()`devuelve todas las entradas, incluidos los enlaces simbólicos.
```
-- 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.
+ **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 (ruta)`
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 (patrón)`
Devuelve los archivos que coinciden con un patrón global de Go. `filepath.Match` El patrón coincide con el nombre de archivo base. Se omiten los enlaces simbólicos; solo se devuelven archivos concretos.
+ **Devoluciones:** `{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 (nombres)`
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 las iteraciones `sbomgen.get_file_list()` en Lua.
+ **Parámetros:** `names` — tabla de cadenas (los nombres base deben coincidir)
+ **Devuelve:** `{string, ...}` — rutas de archivos coincidentes, excluyendo los enlaces simbólicos (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 (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 `VERSION``Version`, y. `version` Por ejemplo`find_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 archivos coincidentes, excluyendo los enlaces simbólicos (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 (sufijos)`
Devuelve los archivos cuya ruta completa (normalizada con una barra diagonal) termina con uno de los sufijos dados. Por ejemplo, la coincidencia ocurre fuera de la máquina virtual `find_files_by_name` de Lua.
+ **Parámetros:** `suffixes` — tabla de cadenas (los sufijos de ruta deben coincidir)
+ **Devuelve:** `{string, ...}` — rutas de archivos coincidentes, excluyendo los enlaces simbólicos (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 (patrones)`
Devuelve archivos cuya ruta normalizada con barra inclinada 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 archivos coincidentes, excluyendo los enlaces simbólicos (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: find_files_by_* frente a get_file_list`
Para los complementos de detección, prefiera o sobreitere en Lua. `find_files_by_name` `find_files_by_suffix` `find_files_by_path_regex` `get_file_list()` 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 (ruta)`
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 (ruta)`
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 (ruta, 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 (ruta, expresión regular)`
Analiza un archivo como un ELF, PE o Mach-O binario y busca en la sección predeterminada una coincidencia de expresiones regulares de Go. constant/variable
+ **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 (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.
+ **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 (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.
+ **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 por`sbomgen.open_file()`.
### `fh:read_line ()`
Lee la siguiente línea (sin el carácter de nueva línea). Devuelve `nil` en EOF.
+ **Devoluciones:** `string|nil, err`
### `fh:read (n)`
Lee hasta bytes. `n` 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.hash (datos, algoritmo)`
Devuelve el resumen codificado en hexadecimal de una cadena de bytes en memoria según el algoritmo dado. Combínalo con `sbomgen.read_file(path)` 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 vuelve a leer el archivo.
+ **Devoluciones:** `string, err`
+ **Algoritmos:** consulte [Hashes de componentes](#sbomgen-plugin-api-reference-component-hashes) la lista de constantes de algoritmos aceptadas.
```
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 servidor local. Úselo cuando el resumen sea lo único que necesite del archivo.
+ **Devoluciones:** `string, err`
```
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)`
**importante**
**Obsoleto.** En su lugar, use `sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)`. Este alias se conserva por motivos de compatibilidad con versiones anteriores y seguirá funcionando, pero se eliminará en una versión futura. Los nuevos complementos deberían llamar `hash_file` para que la elección del algoritmo sea explícita.
Es igual que `sbomgen.hash_file(path, "SHA-256")`.
+ **Devoluciones:** `string, err`
```
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.
+ **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 (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 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 (ruta)`
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 leer`product_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 (ruta)`
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 leer`file_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 (paquete)`
Introduce el hallazgo 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 (por ejemplo,) 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](#sbomgen-plugin-api-reference-cyclonedx-properties) |
| hashes | tabla | No | Los hashes de los componentes están codificados por el nombre del algoritmo; consulte [Hashes de componentes](#sbomgen-plugin-api-reference-component-hashes) |
| children | tabla | No | Paquetes secundarios anidados, cada uno con la misma forma que pkg (los campos obligatorios se validan de forma 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",
},
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 codifican por el nombre del algoritmo y se serializan en la `components[].hashes` matriz CyclonedX, según el esquema que Amazon Inspector espera.
### Algoritmos admitidos
Utilice las constantes siguientes para que el nombre del algoritmo `sbomgen.hash_algorithms` que se pase a`sbomgen.hash()`/`sbomgen.hash_file()`sea la misma cadena aceptada por: `push_package({ hashes = ... })`
| **Constant** | **Valor** | **Longitud del resumen hexadecimal** |
| --- | --- | --- |
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 40 |
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 64 |
### Reglas de validación
`push_package()`valida `hashes` antes de emitir un hallazgo. Un paquete cuyos hashes no pasen la validación se descarta y se registra una advertencia. Validación:
+ Los nombres de los algoritmos deben coincidir con una entrada `sbomgen.hash_algorithms` (distingue entre mayúsculas y minúsculas, exactamente `"SHA-1"` o`"SHA-256"`).
+ Los valores no deben estar vacíos, deben ser dígitos hexadecimales en minúscula.
+ Los valores deben tener la longitud correcta para el algoritmo (40 caracteres para SHA-1, 64 caracteres para). SHA-256
+ La validación es recursiva: un hash interno mal formado `children[].hashes` rechaza todo el paquete.
### Ejemplo: codificar 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 necesita del archivo es el resumen, prefiera leerlo dos veces, ya que `sbomgen.hash_file(path, algo)` redirige la lectura a través de la I/O capa del artefacto 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 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?](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) 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.
**Plugin-defined las propiedades 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](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) 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** | **¿Recomendado 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 | Auto-prefixed a amazon:inspector:sbom\_generator:field | No, esto 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 ejemplo`acme:python-pip:*`):
```
properties = {
-- Custom namespace — safe to use (recommended)
["acme:python-pip:manifest_path"] = file_path,
["acme:python-pip:pinned"] = "true",
-- Fully-qualified key outside amazon:inspector:* — also fine
["my:custom:namespace:key"] = "value",
-- No colon: avoid — ends up as "amazon:inspector:sbom_generator:custom_field"
-- custom_field = "value",
}
```
### 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_path`siempre lo añade sbomgen.
+ `source_file_scanner`y `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](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) con Amazon Inspector.
### El contenido de la SBOM no está desinfectado
Sbomgenno inspecciona ni filtra los datos que emite un complemento. Los nombres, las versiones, las direcciones URL, los hashes y los valores de las propiedades de los componentes se escriben en la SBOM tal y como se indica. Sbomgenno detecta ni redacta secretos, credenciales, símbolos u otros datos confidenciales; si un complemento incluye ese valor en un hallazgo, aparece en la SBOM de salida y viaja dondequiera que se publique esa SBOM.
Eres responsable de lo que escriben tus complementos. Emite únicamente datos derivados del artefacto que pretendes inventariar y trata la SBOM como un artefacto compartible a la hora de decidir qué incluir.
## Constantes de propiedad
Built-in las constantes clave de propiedad están disponibles a través de. `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 arriba[Espacios de nombres reservados](#sbomgen-plugin-api-reference-reserved-namespaces).
Los autores de complementos personalizados deberían definir las propiedades en su propio espacio de nombres (por ejemplo`acme: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 mediante`get_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 del algoritmo de 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 del algoritmo hash CyclonedX, por lo que la misma constante recorre toda la ruta de hash sin traducción.
| **Constant** | **Valor** |
| --- | --- |
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" |
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" |
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 de`sbomgen.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 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 (por ejemplo,) del entorno del artefacto. `"C:"` 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/"
```
### `sbomgen.resolve_glob_paths (patrones)`
Amplía los patrones globales del sistema de archivos con respecto al 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:**
+ La sintaxis del patrón sigue la de Go [https://pkg.go.dev/path/filepath#Match](https://pkg.go.dev/path/filepath#Match): `*``?`,,`[abc]`,`[a-z]`.
+ Los patrones de entrada y las rutas de salida están normalizados: los separadores redundantes (`a//b`), los segmentos de puntos (`a/./b`) y los separadores finales () redundantes se contraen. `a/b/`
+ La salida se deduplica; gana la primera vez que aparece una ruta. El orden de los patrones de entrada se conserva en todo el resultado.
+ Los patrones que no coinciden con nada no devuelven ninguna entrada. Empty-string los patrones se omiten silenciosamente. Los patrones con formato incorrecto (p. ej., corchetes que no coinciden) emiten una advertencia y se omiten.
**Cross-platform separadores de rutas:**
+ **Utilice barras diagonales (`/`) para todas las rutas.** Las barras diagonales funcionan en Linux, macOS y Windows; la lógica de ruta de archivos de Go las traduce al separador nativo de Windows.
+ **Los separadores de barras invertidas solo funcionan en Windows.** En Linux y macOS, `\` es un carácter literal de nombre de archivo, no un separador de rutas, un patrón que no `"C:\\Users\\*"` coincide con nada en los sistemas POSIX.
+ **Evita las Windows-style rutas literales en las cadenas de Lua.** Una cadena de Lua como `"C:\Users"` se interpreta `C:sers` porque no `\U` es un escape de Lua válido (y`\f`,, `\t` etc. lo son)`\n`, por lo que el patrón falla silenciosamente. Utiliza barras diagonales, barras invertidas que escapen () o una cadena sin procesar (`"C:\\Users"`) entre corchetes largos. `[[C:\Users]]`
## 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, patrón)`
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, patrón)`
Devuelve los grupos de capturas de la primera coincidencia. 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, patrón [, n])`
Devuelve todas las coincidencias que no se superpongan. `n`Pasar para limitar los resultados (predeterminado: todos).
+ **Devoluciones:** `{string, ...}|nil, err`
```
local versions = sbomgen.regex_find_all(content, "\\d+\\.\\d+\\.\\d+")
```
### `sbomgen.regex_replace (str, patrón, reemplazo)`
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ímbolo`string.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éricos`1..n`: elementos secundarios
```
local doc, err = sbomgen.xml_decode('')
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 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). container/volume
### `sbomgen.registry_open_key (ruta)`
Abre una clave de registro. Devuelve un identificador de llave con el que se debe cerrar`registry_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 (clave, nombre_valor)`
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 (clave, nombre_valor)`
Lee un valor entero de una clave de registro abierta.
+ **Devuelve:** `number, err`
### `sbomgen.registry_get_strings (clave, nombre_valor)`
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 (clave)`
Devuelve todos los nombres de las subclaves de 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 (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 el prefijo de la etiqueta fuente y el ecosistema del complemento, por ejemplo:
```
[custom:python-pip] Parsing requirements.txt
```
`log_info``log_warn`, e imprime `log_error` siempre. `log_debug`solo 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 (mensaje)`
Imprime en `message` 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 en los archivos de prueba del complemento (`*_test.lua`), cargados por`inspector-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 ejemplo`sbomgen.read_file()`) solo producen resultados significativos cuando se invocan desde dentro de un escaneo. Para obtener una guía narrativa, consulte la[Guía de pruebas de complementos](sbomgen-plugin-testing-guide.md).
### Funciones de escaneo
Cada función de escaneo crea un artefacto del tipo indicado, ejecuta el proceso descubrimiento→colección del plugin actual en su conjunto 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
-- 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 de Go (RE2) dada. |
| testing.assert\_length | (tbl: table, expected: integer, message?: string) | Falla si no es \#tbl 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` es`nil`. 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.