Cosign no Node.js

O Cosign no Node.js assina e verifica imagens de container, blobs e attestations. Em uma pipeline, ele permite associar um digest OCI a uma identidade confiável, como um workflow específico do GitHub Actions, e rejeitar artefatos que não foram produzidos pelo processo esperado.

Uma assinatura não afirma que a imagem está livre de vulnerabilidades ou que o código é correto. Ela responde principalmente quem assinou, qual conteúdo foi assinado e, conforme o modelo, quando o evento foi registrado. Segurança exige combinar assinatura, scan, SBOM, provenance e políticas de deploy.

Neste guia, você aprenderá a usar assinatura keyless com Sigstore, assinar imagens do GHCR, verificar issuer e identity, gerar attestations, proteger workflows e aplicar políticas no Kubernetes.

O que é Cosign?

A documentação oficial de assinatura com Cosign explica o modelo keyless do Sigstore. O cliente cria uma chave efêmera, obtém um certificado curto do Fulcio vinculado a uma identidade OIDC e registra o evento no transparency log Rekor.

Por que assinar por digest?

Tags podem ser movidas. O digest identifica o conteúdo:

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

Assine sempre o digest retornado pelo registry. Veja GitHub Container Registry no Node.js.

Instalação

Instale Cosign pelo método oficial e fixe a versão no CI. Verifique checksum ou assinatura da própria ferramenta. Para consultar:

cosign version

Assinatura keyless local

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

Cosign abre ou exibe um fluxo de autenticação OIDC. O certificado liga a chave efêmera à identidade usada no login. A chave privada é descartada após a operação.

Verificação de identidade

cosign verify \
  --certificate-identity="developer@example.com" \
  --certificate-oidc-issuer="https://github.com/login/oauth" \
  ghcr.io/acme/orders-api@sha256:abc123...

Não use apenas cosign verify sem restringir a identidade esperada. Uma assinatura válida de qualquer pessoa não autoriza o artefato para produção.

Keyless no GitHub Actions

O workflow precisa emitir token OIDC:

permissions:
  contents: read
  packages: write
  id-token: write
  attestations: write

Exemplo:

- name: Install Cosign
  uses: sigstore/cosign-installer@v3

- name: Build and push
  id: build
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

- name: Sign image
  env:
    DIGEST: ${{ steps.build.outputs.digest }}
    IMAGE: ghcr.io/${{ github.repository }}
  run: cosign sign --yes "$IMAGE@$DIGEST"

Fixe Actions por commit quando a política de supply chain exigir.

Identity do workflow

Em GitHub Actions, o certificado inclui identidade derivada do workflow. A verificação pode restringir um caminho:

cosign verify \
  --certificate-identity-regexp="^https://github.com/acme/orders-api/.github/workflows/release.yml@refs/tags/v[0-9].*$" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/acme/orders-api@sha256:abc123...

A expressão deve ser restrita. Não permita qualquer branch ou workflow da organização quando apenas releases assinadas devem passar.

Protegendo o workflow

• Use branch e tag protection.
• Exija revisão para o arquivo de release.
• Restrinja environments de produção.
• Não execute assinatura em pull requests de forks.
• Use permissões mínimas.
• Fixe dependências e Actions.
• Assine somente depois de testes e scans.

Consulte CI para Node.js com GitHub Actions.

Transparency log

Rekor registra eventos de assinatura para auditoria. Isso ajuda a detectar uso inesperado de uma identidade. Monitore entradas associadas à organização e investigue assinaturas fora da pipeline aprovada.

Modo offline e bundles

Versões atuais do ecossistema Sigstore usam bundles que reúnem materiais necessários à verificação. Em ambientes isolados, distribua roots e bundles de forma controlada. Não desative verificações de transparência sem compreender o modelo de confiança.

Assinatura com chave gerenciada

Quando keyless não é adequado, Cosign aceita chaves locais, KMS e HSM:

cosign generate-key-pair
cosign sign --key cosign.key \
  ghcr.io/acme/orders-api@sha256:abc123...

A chave privada precisa de criptografia, acesso mínimo, backup, rotação e auditoria. Nunca armazene cosign.key no repositório.

Verificação com chave pública

cosign verify \
  --key cosign.pub \
  ghcr.io/acme/orders-api@sha256:abc123...

Distribuir a chave pública com autenticidade é parte do problema. Keyless reduz gestão de chaves, mas transfere confiança para identidade OIDC, Fulcio, Rekor e roots do Sigstore.

Assinando blobs

cosign sign-blob \
  --yes \
  --bundle artifact.bundle.json \
  dist/package.tgz

Verificação:

cosign verify-blob \
  --bundle artifact.bundle.json \
  --certificate-identity="developer@example.com" \
  --certificate-oidc-issuer="https://github.com/login/oauth" \
  dist/package.tgz

Blobs são úteis para pacotes, manifests e arquivos de release.

Attestations

Uma attestation associa uma declaração estruturada ao artefato. Exemplo de predicate:

{
  "builder": "github-actions",
  "workflow": "release.yml",
  "commit": "abc123",
  "tests": "passed"
}

cosign attest \
  --yes \
  --predicate predicate.json \
  --type https://example.com/build/v1 \
  ghcr.io/acme/orders-api@sha256:abc123...

O conteúdo da attestation precisa ser gerado por uma etapa confiável. Assinar uma afirmação falsa apenas torna a falsidade autenticada.

SBOM attestation

Gere um SBOM da imagem e anexe:

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

Consulte SBOM no Node.js.

Verificando attestations

cosign verify-attestation \
  --type spdxjson \
  --certificate-identity-regexp="^https://github.com/acme/orders-api/.*$" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/acme/orders-api@sha256:abc123...

Depois da assinatura criptográfica, valide também o conteúdo do predicate com uma policy.

Trivy e Cosign

Trivy encontra vulnerabilidades e misconfigurations; Cosign autentica o artefato e declarações. Uma pipeline pode escanear o digest e só assinar quando a política passa. Veja Trivy no Node.js.

Ordem da pipeline

1. checkout de commit protegido;
2. instalação de dependências;
3. testes e análise;
4. build da imagem;
5. scan do digest;
6. geração de SBOM;
7. push para o registry;
8. assinatura do digest;
9. attestations;
10. verificação antes do deploy.

Verificação no Kubernetes

Um admission controller ou Sigstore Policy Controller pode rejeitar imagens não assinadas. A política deve restringir issuer, identidade, repositório e, quando necessário, attestations.

O manifesto deve usar digest:

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

Policy Controller

A documentação do Sigstore Policy Controller descreve políticas para validação no cluster. Teste em modo audit antes de bloquear todos os workloads.

Rotação e revogação

Em keyless, certificados são curtos, mas uma identidade ou workflow comprometido pode assinar artefatos. Remova permissões, proteja branches e atualize policies para não aceitar identidades comprometidas. Em chaves próprias, mantenha processo de revogação e rotação.

Assinatura de imagens multi-arch

Assine o digest do índice OCI que referencia as arquiteturas. Verifique se a ferramenta e a policy tratam o manifest list esperado. Não assine tags antes de o push multi-arch terminar.

Promoção entre ambientes

Construa e assine uma vez. Homologação e produção devem usar o mesmo digest. Não reconstrua a imagem em cada ambiente, pois a assinatura seria de artefatos diferentes.

Registro privado

Cosign precisa de credenciais para acessar o registry. Use token temporário e escopo mínimo. Não exponha credenciais em argumentos, logs ou arquivos de shell.

Observabilidade

Registre:

• digest assinado;
• identidade e issuer;
• workflow e commit;
• horário;
• entrada de transparência;
• SBOM e provenance;
• resultado da verificação;
• policy aplicada no deploy.

Ameaças que a assinatura não resolve

• workflow autorizado, mas malicioso;
• dependência comprometida antes do build;
• vulnerabilidade desconhecida;
• segredo incluído na imagem;
• configuração insegura no cluster;
• assinatura de digest diferente do implantado;
• policy permissiva demais.

Supply chain completa

Combine Cosign com controles descritos em Supply Chain no Node.js: lockfiles, builds isolados, provenance, SBOM, scans, registry e admission policy.

Erros comuns

• Verificar qualquer identidade: uma assinatura externa passa.
• Assinar tag: o conteúdo pode mudar.
• OIDC em PR não confiável: código malicioso alcança a etapa privilegiada.
• Chave no repositório: qualquer pessoa pode assinar.
• Sem transparência: eventos inesperados não são auditados.
• Assinar antes do scan: artefato reprovado recebe confiança.
• Attestation sem policy: conteúdo não é validado.
• Build novamente em produção: o digest assinado não é o implantado.

Conclusão

O Cosign no Node.js autentica imagens e attestations por digest. Com assinatura keyless, uma chave efêmera é associada a uma identidade OIDC e o evento pode ser auditado no transparency log.

Restrinja issuer e identity, proteja o workflow e assine somente depois dos testes e scans. Gere SBOM e provenance, implante o mesmo digest e verifique no admission control. Assim, a assinatura acrescenta confiança mensurável sem ser confundida com prova de ausência de vulnerabilidades.