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, consulteGuia do desenvolvedor de plug-ins. Para testar, consulteGuia de teste de plug-ins.

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_namesubscribe_to_event, e assim por diante) que o sbomgen chama em pontos definidos no ciclo de vida do plug-in. Eles estão documentados emCiclo de vida global do plug-in.

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.

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 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 exemploVERSION, "version" Version fósforos, version e. Por exemplofind_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 exemplofind_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_namefind_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 porsbomgen.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 lerproduct_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 lerfile_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
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? 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 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 exemploacme: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_scannere 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 com o Amazon Inspector.

Constantes de propriedade

As constantes da chave de propriedade incorporadas estão disponíveis viasbomgen.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 acima.

Os autores de plug-ins personalizados devem definir propriedades em seu próprio namespace (por exemploacme: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 viaget_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 viasbomgen.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 destrutils.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 ostring.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('<package id="Newtonsoft.Json" version="13.0.3" />')
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 comregistry_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_infolog_warn, e log_error sempre imprima. log_debugsó 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 porinspector-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 exemplosbomgen.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 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<string, string>
-- 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.