As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Referência da API de plug-in Referência completa da API para plug-ins Lua inspector-sbomgen. Para obter um guia sobre como escrever plug-ins, consulte[Guia do desenvolvedor de plug-ins](sbomgen-plugin-developer-guide.md). Para testar, consulte[Guia de teste de plug-ins](sbomgen-plugin-testing-guide.md). ## Visão geral do Todas as funções fornecidas pelo tempo de execução são acessadas por meio da `sbomgen` tabela global (E/S de arquivo, regex, registro, constantes etc.). Além disso, cada plug-in define um pequeno conjunto de funções globais de alto nível (`discover`,, `collect` `get_scanner_name``subscribe_to_event`, e assim por diante) que o sbomgen chama em pontos definidos no ciclo de vida do plug-in. Eles estão documentados em[Ciclo de vida global do plug-in](#sbomgen-plugin-api-reference-plugin-lifecycle-globals). Dentro `*_test.lua` dos arquivos, o sbomgen também expõe um `testing` global que permite que os autores de testes conduzam o pipeline de descoberta → coleção e façam afirmações. Consulte [API de teste](#sbomgen-plugin-api-reference-testing-api). ### Restrições do Sandbox Os plug-ins são executados em uma VM Lua em sandbox com acesso restrito à biblioteca padrão. Os seguintes módulos da biblioteca padrão Lua estão **disponíveis**: | **Módulo** | **Observações** | | --- | --- | | base | Funções principais (printtype,tostring,tonumber,pairs,ipairs,pcall,error,select,unpack,rawget,rawset, etc.). dofile,loadfile, e loadstring são removidos. | | string | Manipulação completa de strings (string.matchstring.find,string.format,string.gsub, etc.) | | table | Manipulação completa da tabela (table.inserttable.remove,table.sort,table.concat, etc.) | | math | Biblioteca matemática completa (math.floor,math.max,math.min, etc.) | | package | require()está disponível, mas restrito aos módulos dentro da própria árvore de diretórios do plug-in. A travessia do diretório principal () require("../shared") está bloqueada. package.cpathe package.path estão limpos. | Os seguintes módulos de biblioteca padrão são **explicitamente proibidos** por questões de segurança e estabilidade: | **Módulo** | **Motivo** | | --- | --- | | io | O acesso direto ao sistema de arquivos está bloqueado. Todas as operações de arquivo devem passar por sbomgen.\* funções, que são roteadas pela interface do artefato para um comportamento consistente em todos os tipos de artefatos (diretório, contêiner, volume etc.). | | os | As operações no nível do sistema (os.execute,os.remove, os.renameos.getenv, etc.) são bloqueadas para impedir que os plug-ins modifiquem o sistema host. | | debug | A biblioteca de depuração está bloqueada para evitar a inspeção ou modificação dos componentes internos da Lua VM. | | coroutine | As corrotinas não estão carregadas. | Esses módulos não estão na lista de permissões da VM e não podem ser acessados por plug-ins. **nota** **Importante:** Todo arquivo I/O deve passar por `sbomgen.*` funções (por exemplo,`sbomgen.read_file`,`sbomgen.open_file`,`sbomgen.get_file_list`). O uso `io.open` ou qualquer acesso direto ao sistema de arquivos gerará um erro de tempo de execução. A `sbomgen` API garante que os plug-ins interajam com a camada de abstração do artefato, que fornece um comportamento consistente ao digitalizar um diretório, imagem de contêiner, arquivo ou volume. ## Ciclo de vida global do plug-in Um plug-in é um arquivo Lua chamado `init.lua` que define certas funções globais de nível superior. Esses globais **não** estão na `sbomgen` mesa — são funções que o plug-in define para o sbomgen chamar. O conjunto de globais válidos difere entre plug-ins de descoberta e plug-ins de coleção. Para cada função abaixo, se o plug-in a omitir, o padrão mostrado na tabela será usado. ### plug-ins Discovery | **Função** | **Arity** | **Obrigatório** | **Padrão (quando omitido)** | **Descrição** | | --- | --- | --- | --- | --- | | discover() | 0 | Sim | — | Retorna os arquivos que este plugin encontrou. Retorne uma tabela sequencial de cadeias de caminho (modo de evento único) ou uma tabela codificada por cadeias de nomes de eventos cujos valores são tabelas de caminhos (modo de vários eventos). | | get\_event\_name() | 0 | Não | "lua:{platform}/{category}/{ecosystem}" | Retorna o nome do evento sob o qual os arquivos são publicados. Deve ser exclusivo em todos os plug-ins de descoberta. | | get\_scanner\_name() | 0 | Não | nome do diretório do ecossistema | Retorna o nome de exibição do scanner. Deve ser exclusivo em todos os plug-ins de descoberta. | | get\_scanner\_description() | 0 | Não | "Lua discovery plugin: {ecosystem}" | Retorna uma descrição legível por humanos. | | get\_scanner\_groups() | 0 | Não | Derivado do diretório de categorias (consulte o guia do desenvolvedor) | Retorna uma tabela de cadeias de caracteres do grupo de scanners. Use sbomgen.groups.\* constantes. | | get\_localhost\_scan\_paths() | 0 | Não | — | Retorna uma tabela de file/directory caminhos a serem incluídos ao escanear um artefato localhost. Consultado apenas para localhost digitalizações. | ### Plugins de coleção | **Função** | **Arity** | **Obrigatório** | **Padrão (quando omitido)** | **Descrição** | | --- | --- | --- | --- | --- | | collect(file\_path) | 1 | Sim | — | Chamado uma vez por arquivo publicado no evento inscrito. Analise o arquivo e emita as descobertas via. sbomgen.push\_package() Não retorna nada. | | subscribe\_to\_event() | 0 | Não | "lua:{platform}/{category}/{ecosystem}" | Retorna o nome do evento no qual esse coletor se inscreve. Deve corresponder ao plug-in de descoberta correspondenteget\_event\_name(). | | get\_collector\_name() | 0 | Não | nome do diretório do ecossistema | Retorna o nome de exibição do coletor. Deve ser exclusivo em todos os plug-ins da coleção. | | get\_collector\_description() | 0 | Não | ""(vazio) | Retorna uma descrição legível por humanos. | ## E/S de arquivo Todas as operações de arquivo devem passar pela `sbomgen.*` API. O acesso direto ao sistema de arquivos via `io` biblioteca de Lua não está disponível (consulte). [Restrições do Sandbox](#sbomgen-plugin-api-reference-sandbox-restrictions) As I/O funções do `sbomgen` arquivo são roteadas pela interface do artefato, garantindo que seu plug-in funcione de forma idêntica, seja escaneando um diretório em disco, uma imagem de contêiner, um arquivo compactado ou um volume montado. ### `sbomgen.get_file_list()` Retorna todos os caminhos de arquivo no artefato como uma tabela de cadeias de caracteres. + **Retorna:** `{string, ...}` — tabela de cadeias de caracteres de caminho de arquivo absoluto + **Desempenho:** essa função copia cada caminho de arquivo no artefato para a Lua VM como uma string Lua. Em artefatos grandes (por exemplo, uma verificação do host local com mais de 300 mil arquivos), isso sozinho leva vários segundos. A iteração da tabela retornada em Lua `string.match()` adiciona mais sobrecarga — uma verificação completa pode levar mais de 15 segundos. **Quanto mais arquivos no artefato, mais lento será o seu plugin.** **nota** **Prefira essas alternativas específicas sempre que possível:** | **Função** | **Use quando...** | | --- | --- | | sbomgen.find\_files\_by\_name() | Você sabe o (s) nome (s) exato (s) de arquivo correspondente (por exemplo,,"requirements.txt") "curl" | | sbomgen.find\_files\_by\_name\_icase() | O mesmo que acima, mas não diferencia maiúsculas de minúsculas | | sbomgen.find\_files\_by\_suffix() | Você precisa combinar os sufixos do caminho (por exemplo,"/pom.properties","curlver.h") | | sbomgen.find\_files\_by\_path\_regex() | Você precisa de correspondência de regex de caminho completo | | sbomgen.glob\_find\_files() | Você precisa de uma correspondência de nome de base no estilo global | Essas funções realizam a correspondência fora da Lua VM e retornam somente os caminhos correspondentes, concluindo em menos de 1 milissegundo, mesmo em artefatos de 300K arquivos. Use `get_file_list()` somente quando sua lógica de correspondência não puder ser expressa com nenhuma das opções acima. ``` -- 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)` Lê todo o conteúdo de um arquivo e o retorna como uma string. + **Devoluções:** `string, err` + Em caso de falha: `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 um arquivo para streaming de leituras. Retorna um FileHandle objeto. Use isso para arquivos grandes em que carregar todo o conteúdo na memória é impraticável. + **Devoluções:** `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)` Retorna arquivos que correspondem a um padrão Go `filepath.Match` glob. O padrão é comparado com o nome do arquivo base. + **Devoluções:** `{string, ...}, err` ``` local files, err = sbomgen.glob_find_files("*.txt") ``` Use `sbomgen.get_file_list()` com `string.match` para correspondência completa de padrões de caminho. ### `sbomgen.find_files_by_name(names)` Retorna arquivos cujo nome base (último componente do caminho) corresponde exatamente a um dos nomes fornecidos. A iteração e a comparação acontecem em Go, tornando isso significativamente mais rápido do que a iteração `sbomgen.get_file_list()` em Lua. + **Parâmetros:** `names` — tabela de strings (nomes de base correspondentes) + **Retorna:** `{string, ...}` — caminhos de arquivo correspondentes (sem tupla de erro) ``` 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)` Retorna arquivos cujo nome base corresponde a um dos nomes fornecidos, ignorando maiúsculas e minúsculas. Por exemplo`VERSION`, `"version"` `Version` fósforos, `version` e. Por exemplo`find_files_by_name`, a correspondência acontece fora da Lua VM. + **Parâmetros:** `names` — tabela de strings (nomes de base correspondentes, sem distinção entre maiúsculas e minúsculas) + **Retorna:** `{string, ...}` — caminhos de arquivo correspondentes (sem tupla de erro) ``` 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)` Retorna arquivos cujo caminho full (forward-slash-normalized) termina com um dos sufixos fornecidos. Por exemplo`find_files_by_name`, a correspondência acontece fora da Lua VM. + **Parâmetros:** `suffixes` — tabela de strings (sufixos de caminho correspondentes) + **Retorna:** `{string, ...}` — caminhos de arquivo correspondentes (sem tupla de erro) ``` 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)` Retorna arquivos cujo forward-slash-normalized caminho corresponde a qualquer um dos padrões regex de Go (RE2) fornecidos. A correspondência acontece fora da Lua VM, o que a torna eficiente em grandes listas de arquivos. + **Parâmetros:** `patterns` — tabela de strings regex em Go + **Retorna:** `{string, ...}` — caminhos de arquivo correspondentes (sem tupla de erro) + **Gera:** um erro de Lua se algum padrão falhar na compilação ``` local configs = sbomgen.find_files_by_path_regex({"/etc/.*\\.conf$", "/opt/.*/config\\.json$"}) ``` ### Desempenho: `find_files_by_*` vs `get_file_list` Para plug-ins de descoberta `find_files_by_name``find_files_by_suffix`, prefira ou repita `find_files_by_path_regex` a iteração `get_file_list()` em Lua. Em uma varredura de host local com 300 mil arquivos, a iteração da lista de arquivos em Lua `string.match()` leva aproximadamente 15 segundos, enquanto é `find_files_by_name` concluída em menos de 1 milissegundo. A diferença é que `get_file_list()` copia cada caminho de arquivo na Lua VM como uma string e, em seguida, Lua interpreta a correspondência de loop e padrão para cada um. As `find_files_by_*` funções realizam a correspondência fora da Lua VM e retornam somente os caminhos correspondentes, evitando a sobrecarga de cópia e interpretação por caminho. Use `get_file_list()` somente quando precisar de uma lógica de correspondência personalizada que não possa ser expressa como nome base, sufixo ou correspondência de regex. ### `sbomgen.read_dir(path)` Lista as entradas em um diretório. + **Devoluções:** `{{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)` Retorna metadados sobre um arquivo. + **Devoluções:** `{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)` Lê uma única entrada de um arquivo ZIP, JAR ou WAR. + **Devoluções:** `string, err` ``` local manifest, err = sbomgen.read_zip_entry( "/app/lib/example.jar", "META-INF/MANIFEST.MF" ) ``` ### `sbomgen.search_binary(path, regex)` Analisa um arquivo como um binário ELF, PE ou Mach-O e pesquisa na constant/variable seção padrão por uma correspondência de regex em Go. + **Retorna:** `string|nil, err` — a string correspondente ou nula se não houver correspondência ``` 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])` Analisa um arquivo como um binário ELF, PE ou Mach-O e retorna todas as correspondências exclusivas do primeiro grupo de captura da seção padrão constant/variable . Passe `n` para limitar os resultados. + **Retorna:** `{string, ...}|nil, err` — tabela de cadeias de caracteres correspondentes ou nula se não houver correspondência ``` 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)` Pesquisa em todo o arquivo binário a primeira correspondência de regex, não se limitando a uma seção específica. Use quando a pesquisa baseada em seção (`search_binary`) for insuficiente — por exemplo, quando as cadeias de caracteres da versão estiverem em seções não padrão. + **Retorna:** `string|nil, err` — a string correspondente ou nula se não houver correspondência ``` local version, err = sbomgen.search_binary_raw(path, "ProductVersion[\\x00\\s]+([\\d.]+)") ``` ## FileHandle Métodos FileHandle objetos são retornados por`sbomgen.open_file()`. ### `fh:read_line()` Lê a próxima linha (sem o caractere de nova linha). Devoluções `nil` na EOF. + **Devoluções:** `string|nil, err` ### `fh:read(n)` Lê até `n` bytes. Devoluções `nil` na EOF. + **Devoluções:** `string|nil, err` ### `fh:close()` Fecha o identificador do arquivo. Sempre feche as alças quando terminar. ## Utilitários binários ### `sbomgen.sha256(path)` Retorna o hash SHA-256 codificado em hexadecimal do conteúdo de um arquivo. + **Devoluções:** `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)` Verifica se um arquivo contém cada um dos padrões de bytes fornecidos. Retorna uma tabela de booleanos na mesma ordem dos padrões de entrada. + **Devoluções:** `{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)` Analisa os recursos da versão do Windows PE a partir de um arquivo binário. Retorna uma tabela com campos de versão ou `nil, err` se o arquivo não for um binário PE ou não tiver recurso de versão. + **Devoluções:** `{product_version, file_version, string_table}, err` Os `file_version` campos `product_version` e vêm da `FixedFileInfo` estrutura PE, formatados como`"major.minor.build.revision"`. O `string_table` campo é uma tabela aninhada codificada por código de **localidade (por exemplo, `"040904B0"` para Unicode** em inglês dos EUA). Cada localidade é mapeada para uma tabela de name/value pares extraídos do PE `StringFileInfo` (`ProductVersion`,`ProductName`,`FileDescription`, etc.). Um binário PE pode expor uma ou mais localidades. ``` 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)` Embalagem de conveniência que retorna apenas a string da versão do produto de um binário FixedFileInfo PE. Equivalente a ligar `get_pe_version_info(path)` e ler`product_version`. + **Devoluções:** `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)` Invólucro de conveniência que retorna apenas a string da versão do arquivo de um binário FixedFileInfo PE. Equivalente a ligar `get_pe_version_info(path)` e ler`file_version`. + **Devoluções:** `string, err` ``` local version, err = sbomgen.parse_file_version(file_path) if version then sbomgen.log_info("file version: " .. version) end ``` ## Saída do pacote ### `sbomgen.push_package(pkg)` Empurra uma descoberta de pacote para o SBOM. Disponível apenas em plug-ins de coleção. A `pkg` tabela oferece suporte aos seguintes campos: | **Campo** | **Tipo** | **Obrigatório** | **Descrição** | | --- | --- | --- | --- | | name | string | Sim | Nome do pacote | | version | string | Não | Sequência de versão resolvida | | namespace | string | Não | namespace PURL (por exemplo,,) "curl" "wordpress/plugin" | | purl\_type | string | Sim | Tipo de URL (por exemplo,"pypi",,"npm", "cargo""deb","generic") | | component\_type | string | Sim | Tipo de componente CyclonedX; use sbomgen.component\_types.\* constantes (por exemplo,) sbomgen.component\_types.LIBRARY | | qualifiers | table | Não | Qualificadores PURL como pares de valores-chave (aparecem na URL do pacote) | | properties | table | Não | Propriedades do componente CyclonedX como pares de valores-chave (consulte) [Propriedades do CycloneDX](#sbomgen-plugin-api-reference-cyclonedx-properties) | | children | table | Não | Pacotes secundários aninhados, cada um com o mesmo formato de pkg (os campos obrigatórios são validados recursivamente) | ``` 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", }, }) ``` ## Propriedades do CycloneDX As propriedades do CycloneDX são metadados de valores-chave anexados a um componente no SBOM. Eles são diferentes dos qualificadores PURL: + **`qualifiers`**— Qualificadores PURL. Eles se tornam parte da string de URL do pacote (por exemplo,`pkg:deb/debian/curl@7.88.1?arch=amd64`). Alguns qualificadores de PURL têm significado semântico para o Amazon Inspector e influenciam a identificação de vulnerabilidades. Consulte [O que é um URL de pacote?](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) para as convenções por tipo do Inspector. + **`properties`**— Propriedades do componente CycloneDX. Eles aparecem na `components[].properties` matriz do SBOM e não alteram a forma como o componente é identificado. ### Namespaces reservados A `amazon:inspector:*` família de namespaces de propriedades CycloneDX está reservada para o Amazon Inspector: + `amazon:inspector:sbom_generator:*`— usado pelo sbomgen e seus scanners integrados. + `amazon:inspector:sbom_scanner:*`— usado pela API do Amazon Inspector Scan. **As propriedades definidas pelo plug-in não devem usar esses namespaces.** Escrever em um namespace reservado pode obscurecer ou entrar em conflito com os valores nos quais o Inspector confia, e o SBOM resultante pode ser interpretado incorretamente durante a identificação da vulnerabilidade. Consulte [Usando namespaces CycloneDX com o Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) para obter a lista completa de chaves reservadas. ### Principais regras de nomenclatura As chaves de propriedade passadas para `sbomgen.push_package()` são processadas da seguinte forma: | **Tecla de entrada** | **Chave resultante no SBOM** | **Recomendado para plug-ins personalizados?** | | --- | --- | --- | | Contém : (por exemplo,acme:my\_plugin:field) | Usado literalmente | Sim — coloque todas as propriedades definidas pelo plug-in em seu próprio namespace | | Não : (por exemplo,field) | Prefixado automaticamente para amazon:inspector:sbom\_generator:field | Não — isso grava em um namespace reservado | Sempre inclua pelo menos dois pontos nas chaves de propriedade que você definir. Use um namespace exclusivo para sua organização ou plug-in (por exemplo`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", } ``` ### Propriedades definidas por sbomgen O Sbomgen pode atribuir propriedades próprias a cada componente que emite. Esses valores vêm do `amazon:inspector:sbom_generator:*` namespace reservado e não devem ser produzidos por plug-ins. Comportamento de tempo de execução observado: + `source_path`é sempre adicionado pelo sbomgen. + `source_file_scanner`e `source_package_collector` são adicionados quando `--enable-debug-props` está habilitado. A taxonomia completa das chaves reservadas é mantida no guia do usuário do Amazon Inspector[: Usando namespaces CycloneDX](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) com o Amazon Inspector. ## Constantes de propriedade As constantes da chave de propriedade incorporadas estão disponíveis via`sbomgen.properties`. Cada constante abaixo é resolvida em uma chave dentro do `amazon:inspector:sbom_generator:*` namespace reservado. Essas constantes existem para que os scanners integrados do sbomgen emitam chaves de propriedade consistentes. **Eles não são pontos de extensão para plug-ins personalizados** — usá-los em um plug-in personalizado grava em um namespace reservado, que pode ocultar valores nos quais o Inspector confia. Veja [Namespaces reservados](#sbomgen-plugin-api-reference-reserved-namespaces) acima. Os autores de plug-ins personalizados devem definir propriedades em seu próprio namespace (por exemplo`acme:my_plugin:*`) em vez de reutilizar essas constantes. | **Constante** | **Valor resolvido** | | --- | --- | | 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 scanners Os plug-ins do Discovery devem declarar seus grupos de scanners via`get_scanner_groups()`. Os grupos categorizam os scanners e permitem que os usuários ativem ou desativem seletivamente as categorias. As constantes estão disponíveis via: `sbomgen.groups` | **Constante** | **Valor** | **Descrição** | | --- | --- | --- | | sbomgen.groups.OS | "os" | Gerenciadores de pacotes do sistema operacional (dpkg, rpm, etc.) | | sbomgen.groups.PROGRAMMING\_LANGUAGE | "programming-language-packages" | Gerenciadores de pacotes de idiomas (pip, npm, maven etc.) | | sbomgen.groups.BINARY | "binary" | Análise binária compilada (Go, Rust) | | sbomgen.groups.PACKAGE\_COLLECTOR | "pkg-scanner" | Coleção geral de pacotes | | sbomgen.groups.EXTRA\_ECOSYSTEMS | "extra-ecosystems" | Ecossistemas adicionais (curl, nginx, etc.) | | sbomgen.groups.CERTIFICATE | "certificate" | Digitalização de certificados | | sbomgen.groups.CUSTOM | "custom" | Adicionado automaticamente a todos os plug-ins personalizados carregados via --plugin-dir | | sbomgen.groups.MACHINE\_LEARNING | "machine-learning" | Detecção de modelos de aprendizado de máquina | Exemplo: ``` function get_scanner_groups() return {sbomgen.groups.PROGRAMMING_LANGUAGE, sbomgen.groups.PACKAGE_COLLECTOR} end ``` ## Constantes do tipo de componente O `component_type` campo em `push_package()` deve ser um dos tipos de componentes do CyclonedX 1.5. As constantes estão disponíveis via: `sbomgen.component_types` | **Constante** | **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" | Exemplo: ``` sbomgen.push_package({ name = "requests", version = "2.28.1", purl_type = "pypi", component_type = sbomgen.component_types.LIBRARY, }) ``` ## Constantes da plataforma Constantes para comparação `sbomgen.get_platform()` com. Disponível via`sbomgen.platform`: | **Constante** | **Valor** | | --- | --- | | sbomgen.platform.LINUX | "linux" | | sbomgen.platform.WINDOWS | "windows" | | sbomgen.platform.DARWIN | "darwin" | Exemplo: ``` if sbomgen.get_platform() == sbomgen.platform.WINDOWS then -- Windows-specific logic end ``` ## Informações sobre o Artifato ### `sbomgen.get_platform()` Retorna a string da plataforma de tempo de execução (por exemplo`"linux"`,`"windows"`,,`"darwin"`). ### `sbomgen.get_artifact_type()` Retorna o tipo de artefato que está sendo escaneado (por exemplo,`"directory"`,`"archive"`). ### `sbomgen.should_collect_licenses()` Retorna `true` se o usuário habilitou a coleta de licenças via`--collect-licenses`. ### `sbomgen.get_env_vars()` Retorna variáveis de ambiente do artefato como uma tabela 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()` Retorna a letra da unidade do sistema (por exemplo,`"C:"`) do ambiente do artefato. Lê a variável de `SystemDrive` ambiente, assumindo como padrão `"C:"` se não estiver definida. Isso é o equivalente de Lua de`strutils.GetSystemDriverLetter()`. ``` local drive = sbomgen.get_system_drive() local program_files = drive .. "/Program Files/" ``` ## Informações do sistema Essas funções retornam metadados sobre o sistema operacional e o hardware do artefato. Os valores podem ser cadeias de caracteres vazias se as informações não estiverem disponíveis (por exemplo, ao escanear um diretório sem metadados do sistema operacional). | **Função** | **Devoluções** | | --- | --- | | sbomgen.get\_os\_name() | Nome do sistema operacional (por exemplo,"Ubuntu","Alpine Linux") | | sbomgen.get\_os\_version() | Versão do sistema operacional (por exemplo,"22.04","3.18") | | sbomgen.get\_os\_codename() | Nome de código do sistema operacional (por exemplo,,"jammy") "bookworm" | | sbomgen.get\_os\_id() | Identificador do sistema operacional (por exemplo"ubuntu",,"alpine") | | sbomgen.get\_kernel\_name() | Nome do kernel (por exemplo,"Linux") | | sbomgen.get\_kernel\_version() | String da versão do kernel | | sbomgen.get\_cpu\_arch() | Arquitetura de CPU (por exemplo"x86\_64",,"aarch64") | | sbomgen.get\_hostname() | Nome do host do sistema | ## Expressões regulares Os padrões integrados de Lua carecem de recursos como alternação (`|`), intervalos de quantificadores (`{n,}`) e lookahead. Para fechar essa lacuna, o sbomgen expõe o pacote de `regexp` Go diretamente. Essas funções usam a sintaxe Go regex (RE2), não padrões Lua. ### `sbomgen.regex_find(str, pattern)` Retorna a primeira correspondência de um padrão Go regex ou, `nil` se não houver correspondência. + **Devoluções:** `string|nil, err` ``` local version = sbomgen.regex_find(content, "\\d+\\.\\d+\\.\\d+") ``` ### `sbomgen.regex_match(str, pattern)` Retorna grupos de captura da primeira partida. O índice 1 é a correspondência completa, 2\+ são grupos de captura. + **Devoluções:** `{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])` Retorna todas as correspondências não sobrepostas. Passe `n` para limitar os resultados (padrão: todos). + **Devoluções:** `{string, ...}|nil, err` ``` local versions = sbomgen.regex_find_all(content, "\\d+\\.\\d+\\.\\d+") ``` ### `sbomgen.regex_replace(str, pattern, replacement)` Substitui todas as partidas. A string de substituição pode usar`$1`,`$2`, etc. para capturar referências de grupos. + **Devoluções:** `string, err` ``` local cleaned = sbomgen.regex_replace(raw_version, "(1[6-9]\\d{8,}|buildkitsandbox.*)$", "") ``` ### Quando usar padrões regex versus Lua Use o`string.match`/integrado do Lua `string.find` para padrões simples — eles são mais rápidos e não precisam escapar de barras invertidas. Use `sbomgen.regex_*` quando precisar: + Alternância: `(foo|bar)` + Intervalos de quantificadores: `\d{8,}` + Classes de caracteres complexas não expressáveis nos padrões Lua ## Análise estruturada O Sbomgen expõe auxiliares leves para decodificar formatos de texto estruturado diretamente em tabelas Lua. ### `sbomgen.json_decode(str)` Analisa uma string JSON em uma tabela Lua. + **Devoluções:** `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)` Analisa uma string XML em uma tabela Lua. + **Devoluções:** `table|nil, err` Os valores XML usam a seguinte forma: + `_name`— nome do elemento + `_attr`— tabela de atributos, quando presente + `_text`— conteúdo de texto cortado, quando presente + índices numéricos `1..n` — elementos secundários ``` local doc, err = sbomgen.xml_decode('') if err then return end sbomgen.log_info(doc._attr.id) ``` ## Registro do Windows Essas funções fornecem acesso somente de leitura ao registro do Windows. Em artefatos que não são do Windows, `registry_open_key` retorna um erro. O acessador do registro é inicializado lentamente no primeiro uso e oferece suporte ao acesso ativo à API do Windows (verificações do host local no Windows) e à análise de colmeia REGF baseada em arquivo (varreduras de contêiner/volume). ### `sbomgen.registry_open_key(path)` Abre uma chave de registro. Retorna uma alça de chave que deve ser fechada com`registry_close`. + **Devoluções:** `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)` Lê um valor de string de uma chave de registro aberta. + **Devoluções:** `string, err` ``` local version, err = sbomgen.registry_get_string(key, "DisplayVersion") ``` ### `sbomgen.registry_get_integer(key, value_name)` Lê um valor inteiro de uma chave de registro aberta. + **Devoluções:** `number, err` ### `sbomgen.registry_get_strings(key, value_name)` Lê um valor de várias cadeias de caracteres (REG\_MULTI\_SZ) de uma chave de registro aberta. Retorna uma tabela de strings. + **Devoluções:** `{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)` Retorna todos os nomes de subchaves em uma chave de registro aberta. + **Devoluções:** `{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)` Fecha um identificador de chave de registro. As alças das teclas também são fechadas automaticamente pelo coletor de lixo, mas o fechamento explícito é recomendado. ## Registro em log As mensagens de log são gravadas na saída do console do sbomgen. Cada mensagem emitida por um plug-in é automaticamente prefixada com o rótulo de origem e o ecossistema do plug-in, por exemplo: ``` [custom:python-pip] Parsing requirements.txt ``` `log_info``log_warn`, e `log_error` sempre imprima. `log_debug`só imprime quando sbomgen é invocado com. `--verbose` | **Função** | **Nível** | **Visível por padrão?** | | --- | --- | --- | | sbomgen.log\_debug(message) | DEBUG | Não — requer --verbose | | sbomgen.log\_info(message) | INFO | Sim | | sbomgen.log\_warn(message) | WARN | Sim | | sbomgen.log\_error(message) | ERROR | Sim | Use `string.format` para mensagens formatadas: ``` sbomgen.log_info(string.format("found %d packages in %s", count, file_path)) ``` ## Funções de depuração ### `sbomgen.breakpoint(message)` Imprime `message` em stderr e bloqueia a execução até que o usuário pressione Enter. Se `message` for omitido, imprime uma mensagem padrão. Use isso como um depurador básico, colocando pontos de interrupção em pontos-chave do seu plug-in e executando com `--verbose` para ver a saída do log ao redor. ``` sbomgen.log_info("state: " .. some_variable) sbomgen.breakpoint("paused after state dump — press Enter to continue") ``` ## API de teste As funções na `testing` tabela global só estão disponíveis dentro dos arquivos de teste do plugin (`*_test.lua`), carregados por`inspector-sbomgen plugin test`. Eles não estão disponíveis em tempo de execução nos plug-ins de descoberta ou coleta. A `sbomgen.*` API completa também está disponível nos arquivos de teste, mas `sbomgen.*` as funções que exigem um artefato (por exemplo`sbomgen.read_file()`) só produzem resultados significativos quando chamadas de dentro de um escaneamento. Para obter um guia narrativo, consulte [Guia de teste de plug-ins](sbomgen-plugin-testing-guide.md) o. ### Funções de digitalização Cada função de escaneamento cria um artefato do tipo especificado, executa o pipeline de descoberta→coleção do plug-in atual contra ele e retorna as descobertas resultantes. O `path` argumento é resolvido em relação ao diretório do arquivo de teste. | **Função** | **Tipo de Artifato** | | --- | --- | | testing.scan\_directory(path) | Diretório | | testing.scan\_archive(path) | Diretório (alias descan\_directory) | | testing.scan\_localhost(path) | Anfitrião local | | testing.scan\_binary(path) | Binário | | testing.scan\_volume(path) | Volume | | testing.scan\_container(path) | Contêiner | Todos os seis retornam uma tabela de resultados com a forma abaixo. ### Forma do resultado Cada tabela de descoberta projeta somente os campos listados abaixo. Em particular, `namespace` e não `purl_type` são projetados separadamente — eles são incorporados à `purl` sequência 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) ``` ### Asserções | **Função** | **Assinatura** | **Descrição** | | --- | --- | --- | | testing.assert\_equals | (expected: any, actual: any, message?: string) | Falha setostring(expected) \~= tostring(actual). | | testing.assert\_not\_equals | (expected: any, actual: any, message?: string) | Falha setostring(expected) == tostring(actual). | | testing.assert\_true | (value: any, message?: string) | Falha se value for false ounil. | | testing.assert\_false | (value: any, message?: string) | Falha se não value for false e não fornil. | | testing.assert\_nil | (value: any, message?: string) | Falha se não value fornil. | | testing.assert\_not\_nil | (value: any, message?: string) | Falha se value fornil. | | testing.assert\_contains | (haystack: string, needle: string, message?: string) | Falha se haystack não contiver needle (correspondência de substring). | | testing.assert\_matches | (str: string, pattern: string, message?: string) | Falha se str não corresponder ao regex Go (RE2) fornecido. | | testing.assert\_length | (tbl: table, expected: integer, message?: string) | Falha se \#tbl não for igualexpected. | ### Controle o fluxo | **Função** | **Assinatura** | **Descrição** | | --- | --- | --- | | testing.fail | (message: string) | Falha imediatamente no teste atual com a mensagem fornecida. | | testing.skip | (message: string) | Ignora o teste atual. O resultado é relatado como ignorado, não falhado. | ### Descoberta de testes Qualquer função global do Lua cujo nome comece com `test_` em uma correspondência de arquivo `*_test.lua` é tratada como um teste. O arquivo de teste deve estar próximo `init.lua` a uma `{phase}/{platform}/{category}/{ecosystem}/` profundidade normal. Os dados do equipamento são colocados ao `_testdata/` lado do arquivo de teste — o executor não entra `_testdata/` ao pesquisar os arquivos de teste. ## Tratamento de erros Funções de API que podem falhar retornam dois valores:`value, err`. Sobre o sucesso, `err` é`nil`. Em caso de falha, o primeiro valor é `nil` e `err` é uma string de erro. ``` local content, err = sbomgen.read_file(path) if err then sbomgen.log_error("failed to read " .. path .. ": " .. err) return end -- content is safe to use here ``` Se um plug-in gerar um erro Lua não tratado, o sbomgen registra um aviso e continua com o próximo arquivo ou plug-in. Outros plug-ins não são afetados.