O que é o Amazon Inspector SBOM Generator?
O Amazon Inspector é um serviço de gerenciamento de vulnerabilidades que escaneia continuamente workloads da Amazon Web Services (AWS) em busca de falhas de segurança em software. O motor por trás dessa capacidade é o Amazon Inspector SBOM Generator — conhecido como inspector-sbomgen — uma ferramenta de linha de comando independente que gera uma Lista de Materiais de Software (SBOM — Software Bill of Materials) a partir de imagens de contêiner, diretórios, arquivos compactados, sistemas locais, binários compilados e muito mais.
Ao longo dos últimos dois anos, a AWS expandiu a cobertura do inspector-sbomgen para dezenas de ecossistemas de linguagens de programação, sistemas operacionais e aplicações amplamente utilizadas. Agora, a empresa anuncia uma novidade relevante para quem constrói com essa ferramenta: um sistema de plugins para criação de coletores de pacotes personalizados.
Por que a AWS construiu um sistema de plugins?
Ecossistemas de software são dinâmicos por natureza. Novos gerenciadores de pacotes, formatos de lockfile e aplicações surgem constantemente — muitas vezes com pouco escrutínio de segurança. Isso deixa equipes de segurança com uma lacuna de visibilidade: workloads em produção rodando software que as ferramentas de SBOM ainda não reconhecem.
Antes dos plugins, o único caminho para suportar um novo ecossistema era abrir uma solicitação de funcionalidade e aguardar que a equipe do inspector-sbomgen integrasse o ecossistema e publicasse uma nova versão. O sistema de plugins muda esse cenário completamente.
Com plugins, é possível:
- Integrar ecossistemas não suportados nativamente: novos ecossistemas open source, formatos de pacote de nicho e ferramentas internas ou proprietárias podem ser inventariados sem modificar o
inspector-sbomgen. - Prototipar detecção rapidamente: o sistema foi projetado para ser amigável tanto para desenvolvedores quanto para assistentes de codificação com IA. Os plugins são escritos em Lua, carregados em tempo de execução e não exigem toolchain Go nem compilação.
- Construir sobre uma base estável: a API de plugins abstrai as diferenças entre tipos de artefatos, então a lógica de detecção é escrita uma única vez e funciona em imagens de contêiner, arquivos compactados, sistemas locais e mais.
Internamente, a AWS já utilizou o sistema de plugins para acelerar a entrega de novos ecossistemas. Na versão 1.13, mais de 20 ecossistemas que antes eram implementados em Go — incluindo Apache Tomcat, NGINX, MySQL, Redis, WordPress e a toolchain do OpenSSH — foram convertidos para plugins embutidos no binário. A mesma versão também adicionou mais de dez ecossistemas totalmente novos como plugins, incluindo Apache Cassandra, Apache Struts, Conda, pacotes Swift e coletores de agentes de IA (Amazon Q Developer, Kiro CLI, Claude Code, GitHub Copilot e Ollama).
Como os plugins do inspector-sbomgen funcionam
Os plugins seguem um pipeline de duas etapas:
- Descoberta (Discovery): varre o sistema de arquivos do artefato para identificar arquivos que contêm metadados de pacotes instalados.
- Coleta (Collection): abre cada arquivo descoberto, analisa seu conteúdo e publica os resultados no SBOM.
Por baixo dos panos, um barramento de eventos conecta os plugins de descoberta e coleta. Os plugins de descoberta publicam eventos listando os arquivos encontrados, e um ou mais plugins de coleta se inscrevem nesses eventos para disparar a coleta de pacotes. Desenvolvedores familiarizados com padrões de design vão reconhecer esse comportamento como o padrão observer.
Esse desacoplamento permite que um único plugin de descoberta alimente múltiplos coletores — por exemplo, um extraindo metadados de pacotes, outro buscando segredos e outro verificando políticas — tudo a partir da mesma lista de arquivos, sem precisar percorrer o sistema de arquivos do artefato novamente.
Criando seu primeiro plugin em 5 minutos
O inspector-sbomgen facilita a criação de um ambiente de plugin. O comando plugin new cria um novo workspace de plugin, e a flag --with-example popula o workspace com um par de plugins de descoberta e coleta prontos para execução imediata.
inspector-sbomgen plugin new --with-exampleApós invocar o comando, será solicitado um nome para o plugin e um diretório para o workspace. É possível fornecer valores personalizados ou usar os valores padrão:
Plugin name (identifies the software ecosystem your plugin will inventory, e.g. debian-dpkg, rhel-rpm, python-pip, cmake) [my-custom-ecosystem]: <enter>
Project directory [my-sbomgen-plugins]: <enter>
Created plugin "my-custom-ecosystem" in my-sbomgen-plugins/Também é possível pular os prompts interativos especificando o nome do plugin e o diretório diretamente via argumentos de Interface de Linha de Comando (CLI — Command Line Interface):
inspector-sbomgen plugin new \
--with-example \
--name my-custom-ecosystem \
--path my-sbomgen-pluginsApós criar o workspace, o inspector-sbomgen exibe uma tela de próximos passos que guia desenvolvedores e assistentes de IA aos arquivos que precisam ser modificados e à documentação de suporte:
Next steps:
Get started:
1. Open plugin folder in a code editor (VS Code recommended)
2. Add test files that your plugin will discover and parse (e.g., config files, lockfiles, binaries, etc.):
my-sbomgen-plugins/discovery/cross-platform/extra-ecosystems/my-custom-ecosystem/_testdata/
Develop:
3. Edit discovery: my-sbomgen-plugins/discovery/cross-platform/extra-ecosystems/my-custom-ecosystem/init.lua
4. Edit collection: my-sbomgen-plugins/collection/cross-platform/extra-ecosystems/my-custom-ecosystem/init.lua
Test:
5. Write unit tests: my-sbomgen-plugins/discovery/cross-platform/extra-ecosystems/my-custom-ecosystem/init_test.lua
6. Run unit tests: inspector-sbomgen plugin test --path my-sbomgen-plugins
Deploy:
7. Distribute your plugin directory wherever you run inspector-sbomgen:
inspector-sbomgen <arguments> --plugin-dir /path/to/my-sbomgen-plugins
Example:
inspector-sbomgen container --image alpine:latest -o /tmp/sbom.json --plugin-dir /path/to/my-sbomgen-plugins
For code completion, install the VS Code Lua language server extension:
https://luals.github.io/#vscode-install
For more information:
- Plugin guide: my-sbomgen-plugins/docs/sbomgen-plugin-developer-guide.md
- Testing guide: my-sbomgen-plugins/docs/sbomgen-plugin-testing-guide.md
- API reference: my-sbomgen-plugins/docs/sbomgen-plugin-api-reference.md
- Documentation: https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.htmlA estrutura do workspace gerado é a seguinte:
tree my-sbomgen-plugins
├── AGENTS.md
├── collection
│ └── cross-platform
│ └── extra-ecosystems
│ └── my-custom-ecosystem
│ └── init.lua
├── discovery
│ └── cross-platform
│ └── extra-ecosystems
│ └── my-custom-ecosystem
│ ├── _testdata
│ │ ├── empty
│ │ └── example.lock
│ ├── init_test.lua
│ └── init.lua
├── docs
│ ├── sbomgen-plugin-api-reference.md
│ ├── sbomgen-plugin-developer-guide.md
│ └── sbomgen-plugin-testing-guide.md
├── library
│ └── sbomgen.lua
└── README.mdO projeto gerado inclui um par funcional de plugins de descoberta e coleta, testes unitários com fixtures em _testdata/, integração com o Ambiente de Desenvolvimento Integrado (IDE — Integrated Development Environment) e uma cópia local da documentação do desenvolvedor. O scaffolding é deliberadamente conciso e completo, com comentários claros em cada arquivo explicando o que cada função faz.
Exemplo de plugin de descoberta
O plugin de exemplo inventaria um arquivo fictício example.lock com o seguinte conteúdo:
my-package-alpha==1.0.0
my-package-beta==2.3.1
my-package-gamma==0.9.5O plugin de descoberta sabe como localizar instâncias de example.lock no sistema de arquivos do artefato:
-- my-custom-ecosystem discovery plugin
-- Discovers example.lock files in the artifact file list.
function discover()
return sbomgen.find_files_by_name({"example.lock"})
endExemplo de plugin de coleta
O plugin de coleta sabe como analisar o conteúdo de example.lock e publicar os pacotes encontrados no SBOM de saída:
-- my-custom-ecosystem collection plugin
-- Parses example.lock files and extracts package name and version.
function collect(file_path)
local content = sbomgen.read_file(file_path)
if content == nil then
return
end
for line in content:gmatch("[^\n]+") do
local name, ver = line:match("^(.+)==(.+)$")
if name and ver then
sbomgen.push_package({
name = name,
version = ver,
purl_type = "generic",
namespace = "my-custom-ecosystem",
component_type = sbomgen.component_types.APPLICATION,
})
end
end
endExecutando os testes
Os plugins incluem um framework de testes integrado para validar a lógica antes de escanear um artefato real. Os testes são escritos em Lua, ficam ao lado do plugin em init_test.lua e referenciam dados de fixture em _testdata/:
function test_discovers_packages()
local result = testing.scan_directory("_testdata")
testing.assert_equals(3, #result.findings)
testing.assert_equals("my-package-alpha", result.findings[1].name)
testing.assert_equals("1.0.0", result.findings[1].version)
end
function test_no_findings_for_empty_directory()
local result = testing.scan_directory("_testdata/empty")
testing.assert_equals(0, #result.findings)
endExecute os testes com o seguinte comando:
inspector-sbomgen plugin test --path my-sbomgen-plugins -v
=== RUN my-custom-ecosystem/discovery/init_test/test_discovers_packages
--- PASS: my-custom-ecosystem/discovery/init_test/test_discovers_packages (0.04s)
=== RUN my-custom-ecosystem/discovery/init_test/test_no_findings_for_empty_directory
--- PASS: my-custom-ecosystem/discovery/init_test/test_no_findings_for_empty_directory (0.04s)
ok 2 tests passedEsse é o ciclo de desenvolvimento mais ágil possível: sem toolchain Go, sem recompilação, sem inicialização de contêiner. Escreva o teste, execute, itere.
Escaneando um artefato real
Para que os plugins produzam resultados, o inspector-sbomgen precisa de um artefato que contenha os arquivos que o plugin procura. Para o plugin de exemplo, qualquer diretório com um arquivo example.lock funciona:
inspector-sbomgen directory \
--plugin-dir ./my-sbomgen-plugins \
--path ./my-sbomgen-plugins/discovery/cross-platform/extra-ecosystems/my-custom-ecosystem/_testdata \
-o sbom.jsonA flag --plugin-dir indica ao inspector-sbomgen onde carregar os plugins Lua. O SBOM resultante contém um componente CycloneDX para cada um dos três pacotes do example.lock, por exemplo:
{
"bom-ref": "comp-2",
"type": "application",
"name": "my-package-alpha",
"version": "1.0.0",
"scope": "optional",
"purl": "pkg:generic/my-sbomgen-plugin/my-package-alpha@1.0.0",
"properties": [
{
"name": "amazon:inspector:sbom_generator:source_path",
"value": "./my-sbomgen-plugins/example.lock"
}
]
}Todo componente gerado por plugin carrega uma propriedade amazon:inspector:sbom_generator:source_path que registra o arquivo de origem, permitindo rastrear cada componente até o artefato que o produziu.
Escaneamento de vulnerabilidades com o Amazon Inspector
Os resultados gerados por plugins são componentes SBOM de primeira classe e funcionam com qualquer consumidor downstream que leia SBOMs CycloneDX, incluindo o próprio Amazon Inspector. Para enviar um SBOM ao Amazon Inspector para análise de vulnerabilidades, basta adicionar a flag --scan-sbom (requer uma conta AWS ativa):
inspector-sbomgen directory \
--path ./my-sbomgen-plugins/discovery/cross-platform/extra-ecosystems/my-custom-ecosystem/_testdata \
--plugin-dir ./my-sbomgen-plugins \
--scan-sbom \
--aws-profile your_profile \
--aws-region your_region \
-o /tmp/sbom.jsonUm ponto importante: plugins podem inventariar ecossistemas arbitrários, mas o Amazon Inspector só consegue reportar vulnerabilidades para componentes cujos ecossistemas já estão em seus feeds de avisos. Quando um componente de ecossistema ainda não suportado é enviado, o Inspector retorna o componente com a propriedade Component skipped: no supported rules found. — comportamento esperado, não um erro. O SBOM ainda é gerado corretamente e o componente continua sendo rastreado. Quando o Inspector adicionar cobertura para aquele ecossistema, o mesmo SBOM passará a produzir resultados de vulnerabilidades automaticamente, sem nenhuma alteração no plugin.
Suporte a IDE de primeira classe
Todo projeto de plugin gerado com o comando plugin new inclui um arquivo library/sbomgen.lua e um .vscode/settings.json que se integra automaticamente à extensão sumneko.lua do Servidor de Linguagem Lua para o VS Code. Com isso, cada função sbomgen.* passa a ter:
- Dicas de parâmetros com tipos.
- Documentação ao passar o cursor.
- Autocompletar para constantes (
sbomgen.component_types.*,sbomgen.groups.*,sbomgen.platform.*). - Verificação de tipos nas chamadas de função.
- Avisos inline quando campos obrigatórios estão ausentes em
push_package().
O mesmo arquivo de definição torna o desenvolvimento de plugins eficiente com assistentes de codificação por IA, pois os tipos e a documentação estão embutidos em um formato que essas ferramentas conseguem ler.
Modelo de segurança dos plugins
Como os plugins executam código real dentro do mesmo processo do inspector-sbomgen, o ambiente de execução foi projetado para manter esse código estável e endurecido do ponto de vista de segurança. Cada plugin Lua roda em um sandbox isolado, com acesso apenas a um subconjunto restrito da biblioteca padrão Lua:
- Sem acesso direto ao sistema de arquivos: a biblioteca
iodo Lua não é carregada. Todas as operações de arquivo passam pelas funçõessbomgen.*. - Sem execução de subprocessos ou mutação de ambiente: a biblioteca
osdo Lua é bloqueada, impedindo que plugins iniciem processos, modifiquem variáveis de ambiente ou toquem em arquivos fora do artefato. - Sem introspecção da Máquina Virtual (VM — Virtual Machine): a biblioteca
debugdo Lua é bloqueada. - Sem carregamento irrestrito de código:
dofile,loadfileeloadstringsão removidos. Orequire()está disponível, mas restrito à árvore de diretórios do próprio plugin.
Se um plugin gerar um erro Lua não tratado, o inspector-sbomgen registra um aviso e continua com o próximo arquivo ou plugin — um plugin com falha não impede os demais de rodar. Além disso, plugins nunca sobrescrevem os coletores internos do inspector-sbomgen: todo plugin precisa declarar um nome único, e se um plugin personalizado usar um nome já reservado por um plugin oficial, ele é ignorado com um aviso. Os plugins internos sempre têm precedência.
Próximos passos
Para começar a construir seus próprios plugins, a AWS recomenda:
- Instalar a versão mais recente do
inspector-sbomgenpelo guia do usuário do Amazon Inspector. - Executar
inspector-sbomgen plugin new --with-examplee seguir os prompts. - Rodar
inspector-sbomgen plugin test --path ./my-sbomgen-plugins -vpara ver os testes de exemplo passando. - Substituir a lógica de exemplo pela detecção do seu próprio ecossistema.
A documentação de referência completa cobre todas as funções, constantes e comandos em profundidade:
- Guia do desenvolvedor de plugins Lua: conceitos, estrutura de diretórios e ciclo de vida.
- Guia de testes de plugins Lua: referência do framework de testes e convenções de fixtures.
- Referência da API de plugins Lua: catálogo completo da superfície da API
sbomgen.*.
Conclusão
O sistema de plugins do inspector-sbomgen foi projetado para encurtar ao máximo o caminho entre uma ideia e um SBOM funcional — seja para adicionar suporte a um formato interno de lockfile, prototipar detecção para um novo ecossistema open source ou substituir um scanner caseiro por algo que toda a organização possa executar em escala. Com Lua, sandbox seguro, suporte a IDE e integração nativa com o Amazon Inspector, a AWS entrega uma extensibilidade real sem abrir mão da segurança e da previsibilidade da ferramenta.
Fonte
Extend Amazon Inspector SBOM Generator with Plugins (https://aws.amazon.com/blogs/security/extend-amazon-inspector-sbom-generator-with-plugins/)
