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 (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_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. 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](#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. ### `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 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() | 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 `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 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 ejemplo`find_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_name``find_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 por`sbomgen.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 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(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 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(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](#sbomgen-plugin-api-reference-cyclonedx-properties) | | 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?](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. **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](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** | **¿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 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. ## 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 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 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 `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. `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, 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í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 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 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(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_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(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 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 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 -- 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` 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.