> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Exportações de SBOM do SCA
> Artefatos CycloneDX, SPDX, VEX e ML-BOM baseados nos inventários de SCA e de IA do ZeroPath
Visão geral
O serviço de SBOM do ZeroPath gera documentos CycloneDX, SPDX, VEX e ML-BOM prontos para exportação, diretamente a partir dos inventários de SCA e de IA que seus scans já produziram. Um SBOM construído a partir do inventário de SCA reutiliza o mesmo grafo de dependências normalizado que alimenta os alertas, de modo que o artefato corresponde ao que você vê na interface. O mesmo inventário alimenta a [cobertura de dependências](/pt/sca/ecosystems) e os [dados de licença por pacote](/pt/sca/licenses), então um SBOM é apenas tão completo quanto o scan por trás dele. O fallback de snapshot pré-scan descrito abaixo usa um scanner de componentes padrão e pode divergir, e não se aplica aos formatos VEX ou ML-BOM — veja [Fontes de Dados](#data-sources).
Aceita uma solicitação vinculada a um scan. Você pode opcionalmente especificar um scan de SCA para dados de inventário mais ricos, mas isso não é obrigatório — SBOMs podem ser gerados a partir de qualquer scan de código concluído.
O job é enfileirado e processado de forma assíncrona; consulte seu status ou receba um webhook quando ele terminar.
O SBOM é construído a partir da fonte de dados escolhida (preferencialmente o inventário de SCA).
Faz upload do artefato JSON para armazenamento de objetos gerenciado e retorna uma URL de download pré-assinada.
Rastreia status, contagem de tentativas e expiração, para que você possa consultar ou receber atualizações por webhook.
Fluxo de Solicitação
Escolha o scan, o formato desejado (CycloneDX JSON, SPDX JSON, VEX independente ou ML-BOM) e, para CycloneDX JSON, se deve incluir dados de VEX incorporados. Jobs podem ser criados pela interface ou pela API.
O ZeroPath processa o job, hidrata o inventário de dependências e gera o artefato. Novas tentativas automáticas lidam com quaisquer interrupções.
SBOMs finalizados são enviados ao bucket de artefatos do ZeroPath com uma política de retenção por tempo limitado (24 horas por padrão, configurável por tenant).
A API retorna uma URL assinada; webhooks opcionais são disparados quando o job transiciona para `Succeeded` ou `Failed`.
Ideal para ferramentas que esperam grafos de componentes, relações de dependência e VEX incorporado. Quando o VEX é solicitado, cada vulnerabilidade carrega um `analysis.state` do CycloneDX: `not_affected` quando o caminho de código vulnerável não é alcançável, `exploitable` quando é alcançável e confirmado, ou `in_triage` quando é alcançável mas ainda não validado. O ZeroPath também inclui referências de CWE, uma classificação CVSS quando o advisory carrega dados reais de CVSS, e [inteligência de exploits KEV/EPSS](#vulnerability-intelligence-properties) como propriedades no namespace `zeropath:`.
Quando o scan tem dados de [Inventário de IA](/pt/sca/ai-inventory), esta exportação é automaticamente enriquecida com os componentes de IA/ML que o ZeroPath detectou — nenhuma solicitação separada é necessária. Veja [Conteúdo dos Artefatos](#artifact-contents) para o que isso adiciona.
Alinha-se a fluxos de procurement/jurídico. O ZeroPath inclui anotações para dependências diretas vs transitivas, declarações de licença e relações de dependência (`DEPENDS_ON`, `DESCRIBES`). O SPDX não carrega dados de VEX nem de Inventário de IA — use CycloneDX JSON, VEX independente ou ML-BOM para isso.
Um complemento ao CycloneDX JSON: disponível apenas quando o SBOM tem origem no inventário de SCA do ZeroPath, que contém o status de vulnerabilidade que o VEX exige. Se um job tem como alvo um snapshot do repositório, o VEX deve ser desabilitado. Para um documento contendo apenas dados de vulnerabilidade, use o VEX independente.
Um documento CycloneDX que carrega apenas `vulnerabilities[]` — sem componentes, sem grafo de dependências — para ferramentas que consomem declarações de explorabilidade separadamente do inventário de componentes. Construído inteiramente a partir do inventário de SCA, então sempre exige um scan de SCA concluído; não há caminho de snapshot de repositório para este formato. Baixado como `{codeScanId}-vex.json`.
Uma lista de materiais de machine learning em CycloneDX 1.6, com escopo no [Inventário de IA](/pt/sca/ai-inventory) de um repositório: SDKs de LLM, frameworks de agentes e pacotes detectados semelhantes como componentes `library`, arquivos de modelo como componentes `machine-learning-model`, e configurações de agentes, templates de prompt e datasets como componentes `data`. Cada componente carrega propriedades `zeropath:ai:*` para os campos que o ZeroPath realmente conhece sobre ele — tipo, uso, tier, provedor, formato do modelo, fonte de detecção, caminho do manifesto/arquivo e alcançabilidade —, então uma propriedade ausente significa que aquele campo não é conhecido, não que está vazio.
Construído inteiramente a partir do inventário de IA, então sempre exige um scan de código concluído; um repositório que só executou scans de SCA independentes retorna um erro claro até que um scan completo seja executado. Um inventário de IA vazio produz um documento válido sem componentes, em vez de um erro. Baixado como `{codeScanId}-mlbom.json`.
Fontes de Dados
* Usa o inventário canônico construído pelo serviço de SCA do ZeroPath, então inclui a classificação direta/transitiva, dados de licença, atribuição a aplicações e contexto de vulnerabilidades previamente validado.
* SBOMs gerados a partir do inventário são consistentes: o conjunto de pacotes, a ordenação e as arestas de dependência correspondem exatamente à interface e aos alertas. Identificadores em nível de documento, como o número serial e o timestamp do CycloneDX, são únicos por geração.
* Dados de VEX estão disponíveis porque o inventário sabe quais pacotes são alcançáveis, não alcançáveis ou ainda em triagem.
* Usada quando uma equipe solicita um SBOM CycloneDX JSON ou SPDX JSON antes de um scan de SCA completo terminar.
* O ZeroPath clona o repositório no commit solicitado e executa um scanner de componentes padrão sobre seus manifestos/lockfiles, produzindo a mesma estrutura CycloneDX/SPDX.
* Como ainda não existe inventário, esses SBOMs carregam apenas dados de componentes/relações — sem VEX e sem alcançabilidade. Se um lockfile estiver faltando para um ecossistema que precisa de um, as dependências transitivas podem ser subnotificadas. Para um SBOM completo que inclua alcançabilidade e dados de VEX, use uma exportação baseada no inventário.
* VEX independente e ML-BOM não têm fallback de snapshot de repositório. O VEX independente exige um scan de SCA concluído; o ML-BOM exige um scan de código concluído e usa o scan de SCA vinculado quando um existe.
Conteúdo dos Artefatos
Toda exportação CycloneDX JSON e SPDX JSON inclui:
* Metadados do repositório (nome, SHA do commit, timestamp do scan).
* Uma entrada por caminho de manifesto (package-lock.json, requirements.txt, go.mod, pom.xml, Podfile, etc.).
* Ecossistemas normalizados e Package URLs (PURL) para cada dependência.
* Anotações de direta vs transitiva, além de um resumo do caminho de dependência, para que as equipes saibam como um pacote entrou no build. Dependências transitivas do Maven agora incluem cadeias completas de caminho de dependência pai-filho.
* Informações de licença por pacote, obtidas de campos do manifesto e metadados externos. Esses campos são informativos, não aconselhamento jurídico.
* Relações de dependência (`dependencies` do CycloneDX, `relationships` do SPDX).
* Blocos de VEX opcionais (incorporados, via a opção de VEX do CycloneDX JSON) exibindo o status atual, IDs de vulnerabilidade do ZeroPath, classificações CVSS/EPSS, CWEs e dicas de correção. O VEX independente carrega as mesmas entradas de vulnerabilidade, sem o grafo de componentes.
O CycloneDX JSON adicionalmente carrega o enriquecimento do Inventário de IA quando o scan tem dados de Inventário de IA: pacotes marcados como IA/ML carregam propriedades `zeropath:ai:*` (tipo, uso, tier, provedor, formato do modelo, fonte de detecção, caminho do manifesto/arquivo e alcançabilidade — cada uma presente apenas quando conhecida), e sinais de IA derivados de arquivos sem identidade de pacote — arquivos de modelo, configurações de agentes — aparecem como componentes adicionais. O SPDX não é enriquecido dessa forma; use ML-BOM para um inventário de IA/ML dedicado, por repositório.
Propriedades de inteligência de vulnerabilidades
KEV e EPSS — veja [Inteligência de exploits: KEV e EPSS](/pt/sca/reachability#exploit-intelligence-kev-and-epss) para o significado desses sinais — aparecem em cada entrada de vulnerabilidade do CycloneDX (VEX incorporado ou independente) como propriedades no namespace `zeropath:`:
| Propriedade | Significado |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `zeropath:kev` | `"true"` ou `"false"` — se a CVE está no catálogo KEV da CISA. |
| `zeropath:kev:dateAdded` | Data ISO em que a CISA adicionou a CVE ao KEV. Presente apenas quando `zeropath:kev` é `"true"`. |
| `zeropath:kev:knownRansomware` | `"true"` ou `"false"` — vinculada a uma campanha de ransomware conhecida. Presente apenas quando `zeropath:kev` é `"true"`. |
| `zeropath:epss:score` | Probabilidade de exploração EPSS, `0`–`1`, como string. |
| `zeropath:epss:percentile` | Percentil EPSS, `0`–`1`, como string. |
Uma propriedade é incluída apenas quando o ZeroPath realmente conhece o valor: a ausência significa desconhecido, nunca um "não explorado" fabricado ou uma pontuação zero.
O EPSS adicionalmente aparece como uma classificação do CycloneDX ao lado de qualquer classificação CVSS, para que ferramentas que leem apenas `ratings[]` também o vejam:
```json theme={null}
{
"method": "other",
"source": { "name": "EPSS", "url": "https://www.first.org/epss/" },
"score": 0.42
}
```
Armazenamento e Acesso
* SBOMs são armazenados em armazenamento de objetos gerenciado pelo ZeroPath, com uma política de expiração automática (24 horas por padrão; pode ser estendida para tenants enterprise).
* Os links de download são URLs pré-assinadas que carregam a mesma expiração. Copie o artefato para o seu próprio armazenamento se precisar de retenção mais longa.
* Cada job registra organização, repositório, solicitante, formato e expiração, para que você sempre saiba quem gerou qual SBOM.
Guia de Adoção
Isso desbloqueia SBOMs baseados em inventário e exportações de VEX. Scans agendados mantêm o inventário atualizado.
Dispare um job sempre que você cortar um branch de release, tag ou artefato que precise de proveniência.
Use CycloneDX JSON (com VEX incorporado ou independente) para fluxos de engenharia/segurança, SPDX para stakeholders de procurement/jurídico, e ML-BOM quando precisar de um inventário de IA/ML por repositório de forma isolada.
Conecte as URLs pré-assinadas a aprovações de CI/CD, registries de artefatos ou tickets de auditoria, para que os revisores obtenham o documento automaticamente.
Se a política exigir retenção de vários anos, copie o SBOM para o seu próprio armazenamento antes que o link expire.
Dicas de Solução de Problemas
Aplica-se tanto ao VEX incorporado (a opção do CycloneDX JSON) quanto ao formato VEX independente. Execute o job novamente com um scan de SCA concluído selecionado, ou desabilite o VEX para exportações baseadas em snapshot.
Exibido quando um repositório só executou scans de SCA independentes e nunca um scan completo/de código. O Inventário de IA está ancorado a um scan de código, então execute um scan completo para o repositório e tente exportar novamente.
Geralmente causado por credenciais de SCM ausentes ou por um branch/tag excluído. Execute novamente após corrigir o acesso ou aponte para outro commit.
Verifique se o scan de SCA mais recente terminou com sucesso e se os manifestos foram incluídos (exibido na aba de SCA). SBOMs espelham o que quer que o scan tenha capturado.
Jobs de SBOM agora atualizam seu status automaticamente quando a geração conclui ou falha, mesmo que você feche o navegador ou saia da página antes de o resultado aparecer. Se um job ainda aparecer como pendente após dez minutos, verifique se os workers de SBOM estão em execução para o seu workspace e contate o suporte se persistir.
Jobs de SBOM reportam um motivo de falha específico. Categorias comuns de falha incluem:
* **Artifact download failed** — o SBOM gerado não pôde ser recuperado do armazenamento. Isso geralmente é transitório; tente o job novamente.
* **Artifact missing** — a geração foi concluída, mas nenhum arquivo baixável foi produzido. Execute novamente com um scan que tenha dados de inventário.
* **Generation failed** — ocorreu um erro durante a montagem do SBOM. A mensagem de erro incluirá detalhes do pipeline de processamento.
* **Timeout** — o job não terminou dentro da janela permitida. Isso pode acontecer com repositórios muito grandes; contate o suporte se persistir.
O motivo de falha no job indica se o problema está nos dados do scan, no armazenamento de artefatos ou no processamento.
Ao comparar SBOMs do ZeroPath com ferramentas como Syft, Trivy ou Grype, você pode notar diferenças nas contagens de pacotes.
Por que as Contagens de Pacotes Diferem
| Fator | ZeroPath | Outras ferramentas (por exemplo, Syft) |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Dependências de desenvolvimento** | Dev deps declaradas são registradas a partir do manifesto; a expansão transitiva foca no grafo de produção | Frequentemente incluem toda transitiva de dev instalada (por exemplo, de `node_modules`) |
| **Fonte de dados** | Lockfiles e manifestos | Podem também escanear o diretório `node_modules`, binários ou camadas de contêiner |
| **Dependências opcionais/peer** | As declaradas são registradas a partir do manifesto; suas subárvores são incluídas quando a resolução as cobre | Podem incluir dependências opcionais não resolvidas |
| **Pacotes de workspace/monorepo** | Escopo limitado ao manifesto alvo | Podem incluir todos os pacotes do workspace |