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

Referência de API completa para plug-ins Lua do inspetor-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 em tempo de execução são acessadas por meio da sbomgen tabela global (arquivo I/O, regex, registro, constantes etc.). Além disso, cada plug-in define um pequeno conjunto de funções globais de nível superior (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 de plug-ins 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→coleta e façam afirmações. Consulte API de teste.

Restrições do Sandbox

Os plug-ins são executados em uma VM Lua em área restrita com acesso restrito à biblioteca padrão. Os seguintes módulos da biblioteca padrão Lua estão disponíveis:

Os seguintes módulos de biblioteca padrão são explicitamente proibidos por motivos de segurança e estabilidade:

Esses módulos não estão na lista de permissões da VM e não podem ser acessados por plug-ins.

Ciclo de vida de plug-ins Globals

Um plugin é um arquivo Lua chamado init.lua que define certas funções globais de alto nível. Esses globais não estão na sbomgen mesa — são funções que o plugin 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.

Plugins de descoberta

Plugins de coleção

Arquivo I/O

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 (veja). Restrições do Sandbox As I/O funções do sbomgen arquivo percorrem a interface do artefato, garantindo que seu plug-in funcione de forma idêntica, seja digitalizando um diretório no disco, uma imagem de contêiner, um arquivo compactado ou um volume montado.

Limite de acesso a arquivos

As funções sbomgen.* do arquivo limitam as leituras ao artefato em inventário. Um caminho que é resolvido fora da raiz do artefato — por exemplo, por meio de ../ travessia — é rejeitado e a chamada retorna um erro em vez de ler o sistema de arquivos hospedeiro. Isso se aplica a read_fileopen_file,read_dir,file_stat, e aos binary/hash ajudantes que seguem um caminho.

A exceção é o tipo de localhost artefato, que inventa o próprio hospedeiro; nesse caso, o sistema de arquivos hospedeiro é o artefato, portanto, as leituras não ficam confinadas a uma raiz mais estreita.

Esse limite governa somente as leituras de arquivos. Ele não restringe o que um plug-in grava no SBOM — veja. O conteúdo do SBOM não é higienizado

sbomgen.get_file_list ()

Retorna todos os caminhos de arquivo no artefato como uma tabela de cadeias de caracteres.

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

Lê todo o conteúdo de um arquivo e o retorna como uma string.

local content, err = sbomgen.read_file("/app/package.json")
if err then
    sbomgen.log_error("read failed: " .. err)
    return
end

sbomgen.open_file (caminho)

Abre um arquivo para fazer streaming de leituras. Retorna um FileHandle objeto. Use isso para arquivos grandes em que carregar todo o conteúdo na memória é impraticável.

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 (padrão)

Retorna arquivos que correspondem a um padrão Go filepath.Match glob. O padrão é comparado com o nome do arquivo base. Os links simbólicos são ignorados; somente arquivos concretos são retornados.

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

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.

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

Retorna arquivos cujo nome base corresponde a um dos nomes fornecidos, ignorando maiúsculas e minúsculas. Por exemploVERSION, "version" jogosVersion, version e. Por exemplofind_files_by_name, a correspondência acontece fora da Lua VM.

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

Retorna arquivos cujo caminho completo (normalizado por barra frontal) termina com um dos sufixos fornecidos. Por exemplofind_files_by_name, a correspondência acontece fora da Lua VM.

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 (padrões)

Retorna arquivos cujo caminho normalizado por barra frontal corresponde a qualquer um dos padrões de regex Go (RE2) fornecidos. A correspondência acontece fora da Lua VM, o que torna isso eficiente em grandes listas de arquivos.

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 find_files_by_path_regex supere 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 VM Lua 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 interpretação por cópia e 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 (caminho)

Lista as entradas em um diretório.

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

Retorna metadados sobre um arquivo.

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 (caminho, caminho_de_entrada)

Lê uma única entrada de um arquivo ZIP, JAR ou WAR.

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

sbomgen.search_binary (caminho, regex)

Analisa um arquivo como ELF, PE ou Mach-O binário e pesquisa na constant/variable seção padrão uma correspondência de regex Go.

local version, err = sbomgen.search_binary(path, "Version:\\s+([\\d.]+)")
if version then
    sbomgen.log_info("found version: " .. version)
end

sbomgen.search_binary_all (caminho, regex [, n])

Analisa um arquivo como ELF, PE ou Mach-O binário e retorna todas as correspondências exclusivas do primeiro grupo de captura da constant/variable seção padrão. Passe n para limitar os resultados.

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 (caminho, 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 strings de versão estão em seções não padrão.

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). nilRetorna na EOF.

fh: read (n)

Lê até n bytes. nilRetorna na EOF.

fh: fechar ()

Fecha o identificador do arquivo. Sempre feche as alças quando terminar.

Utilitários binários

sbomgen.hash (dados, algoritmo)

Retorna o resumo codificado em hexadecimal de uma string de bytes na memória sob o algoritmo fornecido. Emparelhe com sbomgen.read_file(path) para fazer o hash de um arquivo que você já leu para análise — de preferência sbomgen.hash_file(path) quando você precisa dos bytes e do resumo, pois hash não releia o arquivo.

local data, err = sbomgen.read_file("/path/to/manifest.json")
if data then
    local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)
    sbomgen.log_info("SHA-256: " .. sha256)
end

sbomgen.hash_file (caminho, algoritmo)

Retorna o resumo codificado em hexadecimal do conteúdo de um arquivo sob o algoritmo fornecido. Encaminha a leitura pela I/O camada de artefato, para que ela funcione uniformemente em artefatos de diretório, contêiner, arquivo, volume e host local. Use isso quando o resumo for a única coisa que você precisa do arquivo.

local sha256, err = sbomgen.hash_file("/app/bin/server", sbomgen.hash_algorithms.SHA256)
if sha256 then
    sbomgen.log_info("SHA-256: " .. sha256)
end

sbomgen.sha256 (caminho)

Equivale a sbomgen.hash_file(path, "SHA-256").

local hash, err = sbomgen.sha256("/app/bin/server")
if hash then
    sbomgen.log_info("SHA-256: " .. hash)
end

sbomgen.contains_bytes (caminho, padrões)

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.

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

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 nenhum recurso de versão.

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 pelo código local (por exemplo, "040904B0" para Unicode em inglês americano). Cada localidade é mapeada para uma tabela de name/value pares extraída 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 (caminho)

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.

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

sbomgen.parse_file_version (caminho)

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

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

Envia a localização de um pacote para o SBOM. Disponível apenas em plug-ins de coleção.

A pkg tabela suporta os seguintes campos:

sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
    qualifiers = { example_qualifier = "example_qualifier_value" },
    properties = {
        -- Use your own namespace; amazon:inspector:* is reserved for Amazon Inspector.
        ["acme:example:extra_field"] = "example_value",
    },
    hashes = {
        [sbomgen.hash_algorithms.SHA256] = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
    },
})

Hashes de componentes

O hashes campo opcional sobre resumos de integridade de sbomgen.push_package() registros de um componente. As entradas são digitadas pelo nome do algoritmo e serializadas na components[].hashes matriz CycloneDX, correspondendo ao esquema que o Amazon Inspector espera.

Algoritmos compatíveis

Use as constantes abaixo sbomgen.hash_algorithms para que o nome do algoritmo passado parasbomgen.hash()/sbomgen.hash_file()seja a mesma string aceita porpush_package({ hashes = ... }):

Regras de validação

push_package()valida hashes antes de emitir uma descoberta. Um pacote cujos hashes falham na validação é descartado e um aviso é registrado. Validação:

Exemplo: fazer hash de um manifesto e anexar o resumo

function collect(file_path)
    local data, err = sbomgen.read_file(file_path)
    if err then return end

    local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)

    sbomgen.push_package({
        name = "skill-manifest",
        version = "1.0.0",
        purl_type = "generic",
        component_type = sbomgen.component_types.DATA,
        hashes = {
            [sbomgen.hash_algorithms.SHA256] = sha256,
        },
    })
end

Quando o resumo é a única coisa que você precisa do arquivo, prefira sbomgen.hash_file(path, algo) ler o arquivo duas vezes — ele encaminha a leitura pela I/O camada de artefato em uma única passagem.

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 do PURL:

Namespaces reservados

A amazon:inspector:* família de namespaces de propriedades CycloneDX está reservada para o Amazon Inspector:

Plugin-defined as propriedades não devem usar esses namespaces. A gravação em um namespace reservado pode obscurecer ou entrar em conflito com os valores nos quais o Inspector se baseia, e o SBOM resultante pode ser interpretado incorretamente durante a identificação da vulnerabilidade. Consulte Como usar namespaces CycloneDX com o Amazon Inspector para ver a lista completa de chaves reservadas.

Principais regras de nomenclatura

As chaves de propriedade passadas sbomgen.push_package() são processadas da seguinte forma:

Sempre inclua pelo menos dois pontos nas chaves de propriedade que você definir. Use um namespace exclusivo para sua organização ou plugin (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:

A taxonomia completa das chaves reservadas é mantida no guia do usuário do Amazon Inspector: Uso de namespaces CycloneDX com o Amazon Inspector.

O conteúdo do SBOM não é higienizado

Sbomgennão inspeciona nem filtra os dados que um plug-in emite. Nomes de componentes, versões, PURLs, hashes e valores de propriedades são gravados no SBOM conforme fornecido. Sbomgennão detecta nem edita segredos, credenciais, tokens ou outros dados confidenciais — se um plug-in colocar esse valor em uma descoberta, ele aparecerá no SBOM de saída e viajará para onde quer que o SBOM seja publicado.

Você é responsável pelo que seus plug-ins escrevem. Somente emita dados derivados do artefato que você pretende inventariar e trate o SBOM como um artefato compartilhável ao decidir o que incluir.

Constantes de propriedade

Built-in as constantes da chave de propriedade estão disponíveis viasbomgen.properties. Cada constante abaixo é resolvida para uma chave dentro do amazon:inspector:sbom_generator:* namespace reservado. Essas constantes existem para que os scanners integrados do sbomgen emitam chaves de propriedades consistentes. Eles não são pontos de extensão para plug-ins personalizados — usá-los em um plug-in personalizado é gravado em um namespace reservado, que pode ocultar os 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.

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 por meio sbomgen.groups de:

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 por meio sbomgen.component_types de:

Exemplo:

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

Constantes do algoritmo de hash

Constantes para o parâmetro do algoritmo desbomgen.hash(),sbomgen.hash_file(), e o hashes campo desbomgen.push_package(). Os valores das strings correspondem aos nomes do algoritmo de hash CycloneDX, então a mesma constante flui por todo o caminho de hash sem tradução.

Exemplo:

local digest = sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)
sbomgen.push_package({
    name = "example",
    purl_type = "generic",
    component_type = sbomgen.component_types.LIBRARY,
    hashes = { [sbomgen.hash_algorithms.SHA256] = digest },
})

Constantes da plataforma

Constantes para comparaçãosbomgen.get_platform(). Disponível viasbomgen.platform:

Exemplo:

if sbomgen.get_platform() == sbomgen.platform.WINDOWS then
    -- Windows-specific logic
end

Informações sobre o artefato

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, usando como padrão "C:" se não estiver definida. Isso é o equivalente em Lua destrutils.GetSystemDriverLetter().

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

sbomgen.resolve_glob_paths (padrões)

Expande os padrões globais do sistema de arquivos em relação ao sistema de arquivos hospedeiro. Localhost-only: retorna nil mais um erro em outros tipos de artefatos.

function get_localhost_scan_paths()
    return sbomgen.resolve_glob_paths({
        "/home/*/.cache/huggingface/hub",
        "/Users/*/.cache/huggingface/hub",
        "C:/Users/*/.cache/huggingface/hub",
    })
end

Comportamento:

Cross-platform separadores de caminho:

sbomgen.get_home_dirs ()

Retorna as raízes do diretório inicial do usuário para o artefato, como uma tabela de caminhos. O localhost enumera o sistema de arquivos do host real; os artefatos de contêiner e volume enumeram seu próprio sistema de arquivos (rootfs ou montado); todos os outros tipos de artefatos retornam uma tabela vazia. Os caminhos são normalizados com barra frontal, desduplicados e classificados.

Essa é a maneira com reconhecimento de artefatos de localizar diretórios por usuário (como caches de modelo ou configuração de ferramentas) sem codificar ou. /home/* /Users/* Ele inclui o diretório inicial do root e ignora diretórios conhecidos de não usuários (perfis integrados, como Public and Default onWindows, on e Shared onmacOS). lost+found Linux

function get_localhost_scan_paths()
    local patterns = {}
    for _, home in ipairs(sbomgen.get_home_dirs()) do
        table.insert(patterns, home .. "/.cache/huggingface/hub")
    end
    return sbomgen.resolve_glob_paths(patterns)
end

A composição acima é somente para localhost, devido a resolve_glob_paths erros em artefatos não localhost. Para escaneamentos de contêiner e volume, compare as raízes iniciais retornadas com a lista de arquivos do artefato (por exemplo, comsbomgen.find_files_by_path_regex).

Comportamento:

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 digitalizar um diretório sem metadados do sistema operacional).

Expressões regulares

Os padrões embutidos de Lua carecem de recursos como alternation (|), quantifier ranges ({n,}) e lookahead. Para fechar essa lacuna, o sbomgen expõe diretamente o pacote de regexp Go. Essas funções usam a sintaxe Go regex (RE2), não os padrões Lua.

sbomgen.regex_find (str, padrão)

Retorna a primeira correspondência de um padrão de regex Go, ou nil se não houver correspondência.

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

sbomgen.regex_match (str, padrão)

Retorna grupos de captura da primeira partida. O índice 1 é a partida completa, 2+ são grupos de captura.

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, padrão [, n])

Retorna todas as correspondências não sobrepostas. Passe n para limitar os resultados (padrão: todos).

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

sbomgen.regex_replace (str, padrão, substituição)

Substitui todas as partidas. A string de substituição pode usar$1,$2, etc. para capturar referências de grupos.

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

Quando usar padrões regex versus Lua

Use ostring.match/embutido de Lua string.find para padrões simples — eles são mais rápidos e não exigem o escape de barras invertidas. Use sbomgen.regex_* quando precisar:

Análise estruturada

O Sbomgen expõe auxiliares leves para decodificar formatos de texto estruturados diretamente em tabelas Lua.

sbomgen.json_decode (str)

Analisa uma string JSON em uma tabela Lua.

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.

Os valores XML usam a seguinte forma:

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 para 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 ao Windows ao vivo à API (escaneamentos de host local no Windows) e à análise de colmeia REGF baseada em arquivos (escaneamentos). container/volume

sbomgen.registry_open_key (caminho)

Abre uma chave de registro. Retorna um identificador de chave com o qual deve ser fechadoregistry_close.

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 (chave, nome_do_valor)

Lê um valor de string de uma chave de registro aberta.

local version, err = sbomgen.registry_get_string(key, "DisplayVersion")

sbomgen.registry_get_integer (chave, nome_do_valor)

Lê um valor inteiro de uma chave de registro aberta.

sbomgen.registry_get_strings (chave, nome_do_valor)

Lê um valor de várias cadeias de caracteres (REG_MULTI_SZ) de uma chave de registro aberta. Retorna uma tabela de strings.

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

Retorna todos os nomes de subchaves em uma chave de registro aberta.

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

Fecha um identificador de chave de registro. Os identificadores das chaves também são fechados 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_debugsó imprime quando sbomgen é invocado com. --verbose

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

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 bruto, colocando pontos de interrupção em pontos-chave do seu plug-in e executando-o --verbose para ver a saída do log circundante.

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 coleção. A sbomgen.* API completa também está disponível em arquivos de teste, mas sbomgen.* 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 varredura cria um artefato de determinado tipo, executa o pipeline de descoberta→coleção do plug-in atual e retorna as descobertas resultantes. O path argumento é resolvido em relação ao diretório do arquivo de teste.

Todos os seis retornam uma tabela de resultados com a forma abaixo.

Forma do resultado

Cada tabela de localização projeta somente os campos listados abaixo. Em particular, namespace 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

Controle o fluxo

Descoberta de testes

Qualquer função Lua global cujo nome comece com test_ em uma correspondência de arquivo *_test.lua é tratada como um teste. O arquivo de teste deve ficar próximo a um init.lua na {phase}/{platform}/{category}/{ecosystem}/ profundidade normal. Os dados da luminária entram _testdata/ ao lado do arquivo de teste — o executor não desce _testdata/ ao pesquisar arquivos de teste.

Tratamento de erros

As funções da 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 cadeia 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.