SBOM com Syft no Node.js

Uma SBOM com Syft no Node.js registra os componentes encontrados no repositório, filesystem ou imagem de container. SBOM significa Software Bill of Materials e funciona como um inventário técnico: pacotes npm, bibliotecas do sistema, versões, licenças, identificadores e relações que ajudam a investigar vulnerabilidades e comprovar o conteúdo de um artefato.

Uma SBOM não garante que todos os componentes foram detectados nem que a aplicação está segura. A qualidade depende do alvo, do build, dos catalogers e do formato. O documento precisa estar vinculado ao digest correto e ser atualizado a cada release.

Neste guia, você aprenderá a gerar SBOMs com Syft, escolher SPDX ou CycloneDX, analisar diretórios e imagens, reduzir ruído, validar resultados, anexar attestations e usar o inventário em resposta a vulnerabilidades.

O que é Syft?

A documentação de SBOM Generation com Syft descreve a geração de inventários para imagens, diretórios e arquivos, com formatos como SPDX, CycloneDX e JSON nativo.

Instalação

Instale pelo método oficial e fixe a versão no CI. Verifique assinatura ou checksum do binário. Confirme:

syft version

Também é possível usar uma imagem do projeto, evitando instalação no runner.

SBOM do diretório

syft dir:. -o syft-json=sbom.syft.json

Esse alvo analisa arquivos presentes no workspace. Para Node.js, o lockfile é importante, mas o diretório pode conter devDependencies, artefatos temporários e arquivos que não chegam à produção.

SBOM da imagem

syft ghcr.io/acme/orders-api@sha256:abc123... \
  -o cyclonedx-json=sbom.cdx.json

Gerar a partir do digest final representa melhor o que será executado. Inclui dependências da aplicação e pacotes do sistema presentes nas camadas.

Veja GitHub Container Registry no Node.js.

Por que usar digest?

Uma tag como 1.4.3 pode ser sobrescrita. O digest liga o documento a bytes específicos. Grave no SBOM e nos metadados da release:

ghcr.io/acme/orders-api@sha256:abc123...

SPDX

syft image:orders-api \
  -o spdx-json=sbom.spdx.json

SPDX é um padrão da Linux Foundation amplamente usado para componentes, licenças e relações. A especificação está em SPDX Specifications.

CycloneDX

syft image:orders-api \
  -o cyclonedx-json=sbom.cdx.json

CycloneDX é voltado à análise de risco e supply chain, com componentes, serviços, dependências e vulnerabilidades em formatos relacionados. Consulte CycloneDX Specification.

Qual formato escolher?

• SPDX: interoperabilidade, licenças e compliance.
• CycloneDX: ecossistemas de AppSec e gestão de risco.
• Syft JSON: detalhes nativos e automação específica.

Escolha conforme consumidores. Muitas organizações publicam um formato padrão e preservam o JSON nativo como evidência interna.

Componentes npm

Syft identifica pacotes por manifests, lockfiles e conteúdo instalado. Uma entrada pode incluir nome, versão, purl, licença e localização. Exemplo conceitual:

{
  "name": "fastify",
  "version": "5.2.1",
  "purl": "pkg:npm/fastify@5.2.1"
}

Package URL facilita correlacionar componentes entre ferramentas.

DevDependencies

Uma SBOM do repositório pode incluir dependências de desenvolvimento. A imagem final com npm prune --omit=dev deve excluí-las. Compare os dois inventários para confirmar que ferramentas de build não foram copiadas.

Imagem multi-stage

Gere a SBOM do estágio final, não apenas do contexto de build. Veja Docker Multi-stage para Node.js.

Pacotes do sistema

A imagem Node.js pode incluir OpenSSL, libc, certificados e pacotes Debian ou Alpine. Esses componentes não aparecem no package-lock.json, mas podem conter CVEs. A SBOM da imagem fornece esse inventário.

Arquivos sem pacote

Binários copiados manualmente ou addons nativos podem não ter metadados completos. Revise artefatos críticos e use catalogers apropriados. Nenhuma ferramenta detecta perfeitamente software sem identificação.

Excluindo caminhos

Syft permite controlar seleção conforme a versão e a configuração. Evite excluir diretórios somente para reduzir o relatório. Exclua caches e dados irrelevantes, mas preserve caminhos que podem chegar à produção.

Configuração

Versione um arquivo de configuração:

output:
  - cyclonedx-json=sbom.cdx.json

exclude:
  - "./coverage/**"
  - "./.git/**"
  - "./tmp/**"

Valide a sintaxe com a versão fixada do Syft.

CI com GitHub Actions

- name: Generate SBOM
  uses: anchore/sbom-action@v0
  with:
    image: ghcr.io/${{ github.repository }}@${{ steps.build.outputs.digest }}
    format: cyclonedx-json
    output-file: sbom.cdx.json

- name: Upload SBOM
  uses: actions/upload-artifact@v4
  with:
    name: sbom
    path: sbom.cdx.json

Fixe Actions por commit em workflows de release. Consulte CI para Node.js com GitHub Actions.

Nomeando o arquivo

Inclua aplicação, versão e digest abreviado:

orders-api-1.4.3-sha256-abc123.cdx.json

O conteúdo deve guardar o digest completo. O nome é apenas conveniência.

Armazenamento

Preserve a SBOM junto com a release, registry ou repositório de artefatos. A retenção deve acompanhar o período em que a imagem pode ser implantada ou auditada.

Attestation com Cosign

cosign attest \
  --yes \
  --predicate sbom.spdx.json \
  --type spdxjson \
  ghcr.io/acme/orders-api@sha256:abc123...

Isso liga o documento ao digest e à identidade que atestou. Veja Cosign no Node.js.

Assinatura não valida conteúdo

Uma attestation assinada prova origem e integridade, não completude. A pipeline precisa gerar o SBOM do alvo correto e impedir substituição do arquivo antes da assinatura.

Scan com Grype

grype sbom:sbom.cdx.json

O scanner correlaciona componentes com vulnerabilidades. Uma SBOM antiga produz uma visão antiga do artefato, mas a base de vulnerabilidades pode ser atualizada.

Scan com Trivy

trivy sbom sbom.cdx.json

Consulte Trivy no Node.js.

Resposta a CVE

Quando surge uma vulnerabilidade:

1. obtenha identificadores do pacote;
2. pesquise todas as SBOMs;
3. liste imagens e ambientes afetados;
4. confirme explorabilidade;
5. priorize correção;
6. gere nova imagem e SBOM;
7. prove que o componente foi removido ou atualizado.

Comparando versões

Use JSON e ferramentas como jq para comparar componentes:

jq -r '.components[] | [.name, .version] | @tsv' \
  sbom.cdx.json \
  | sort

Uma mudança inesperada de pacote pode indicar dependência transitiva nova ou alteração da imagem base.

Licenças

SBOMs podem registrar licenças declaradas. Ausência ou expressão desconhecida exige revisão; não significa automaticamente violação. Combine com política jurídica e uma ferramenta de análise de licenças.

Services no CycloneDX

Alguns formatos permitem documentar serviços externos. Não inclua URLs internas, credenciais ou dados sensíveis em documentos que serão públicos.

Completude

Defina critérios de qualidade:

• digest presente;
• nome e versão da aplicação;
• pacotes npm de produção;
• pacotes do sistema;
• imagem base identificada;
• formato e versão do padrão;
• versão do gerador;
• timestamp;
• provenance da pipeline.

SBOM no build

BuildKit e registries modernos podem anexar attestations automaticamente. Compare o resultado com Syft e escolha um fluxo único para evitar documentos conflitantes.

Monorepo

Gere uma SBOM por artefato implantável, não apenas uma para todo o repositório. Uma API e um worker podem ter imagens e dependências diferentes.

Aplicação sem container

Para um pacote distribuído como tarball:

npm pack
syft file:orders-api-1.4.3.tgz \
  -o spdx-json=orders-api.spdx.json

Confirme que o alvo contém dependências necessárias ou gere a partir do diretório de produção.

Segurança do relatório

SBOMs podem revelar tecnologias, versões, caminhos e componentes internos. Defina quem pode acessá-las. SBOM pública é útil para transparência, mas precisa de revisão de metadados.

Supply chain

O inventário participa de um fluxo maior: build reproduzível, scan, assinatura, provenance, registry e policy. Veja Supply Chain no Node.js.

Observabilidade

Monitore:

• releases sem SBOM;
• SBOM sem digest;
• tempo entre build e geração;
• componentes sem versão;
• licenças desconhecidas;
• quantidade de dependências novas;
• SBOMs que falham na validação;
• artefatos implantados afetados por CVE.

Erros comuns

• SBOM do repositório apenas: pacotes do sistema ficam ausentes.
• Tag sem digest: o documento não identifica bytes específicos.
• DevDependencies como produção: inventário gera ruído.
• Arquivo não armazenado: investigação futura fica impossível.
• Assinar SBOM errada: integridade protege conteúdo incorreto.
• Formato não consumido: documento existe, mas ninguém usa.
• Exclusões amplas: componentes reais desaparecem.
• Tratar como scan: inventário não é análise de vulnerabilidade.

Conclusão

Uma SBOM com Syft no Node.js registra dependências npm, pacotes do sistema e metadados do artefato. Gerar o documento a partir da imagem por digest aproxima o inventário do que realmente será executado.

Escolha SPDX ou CycloneDX conforme os consumidores, preserve o arquivo e vincule-o à release. Use Cosign para attestation e scanners para CVEs. Com critérios de completude e automação no CI, a SBOM reduz o tempo entre uma nova vulnerabilidade e a identificação precisa dos ambientes afetados.