Esta guía explica paso a paso cómo configurar Witness para instrumentar tu compilación y, a continuación, cómo utilizar SBOMit para generar un SBOM enriquecido a partir del attestation resultante.

Requisitos previos

Parte 1: Witness

Witness envuelve tu proceso de compilación y registra los archivos «attestations» firmados, un registro de auditoría criptográfica.

1. Instalar «Witness»

bash <(curl -s https://raw.githubusercontent.com/in-toto/witness/main/install-witness.sh)

O bien, descarga un archivo binario desde la página de versiones de Witness.

2. Crear un par de claves de firma

Witness firma cada archivo «attestation» con una clave privada. Para realizar una prueba rápida en el equipo local:

openssl genpkey -algorithm ed25519 -outform PEM -out testkey.pem
openssl pkey -in testkey.pem -pubout > testpub.pem

> Consejo: Witness también admite la firma sin clave a través de SPIRE/SPIFFE y > Sigstore Fulcio para entornos de CI/CD.

3. Configurar Witness

Crea un archivo .Witness.yaml en la raíz de tu proyecto. Este archivo suele incluirse en el commit junto con tu clave pública:

# .witness.yaml
run:
    signer-file-key-path: testkey.pem
    trace: false
verify:
    attestations:
        - "attestation.json"
    policy: policy-signed.json
    publickey: testpub.pem

Los parámetros de la línea de comandos tienen prioridad sobre los valores del archivo de configuración. Ejecuta «Witness help» para ver todas las opciones.

4. Compila tu proyecto

Añade al principio de tu comando de compilación «Witness run» para generar un archivo «attestation»:

witness run --step build -o attestation.json -- <your-build-command>

Proyecto Go:

witness run --step build -o attestation.json -- go build -o myapp .

Proyecto de Python:

witness run --step build -o attestation.json -- pip install -r requirements.txt

Witness siempre ejecuta un conjunto básico de verificadores; consulta Witness attestors list para ver la lista completa.

> Consejo: Para compilaciones que generan muchos archivos (por ejemplo, node_modules), utiliza > --dirhash-glob node_modules/* para calcular el hash del contenido del directorio en lugar de hacerlo con cada archivo por separado.

5. Revisa el attestation

El archivo «attestation» es un sobre DSSE firmado. Para ver la carga útil:

cat attestation.json | jq -r .payload | base64 -d | jq

Verás una colección «attestation» que contiene «attestations» con los siguientes tipos: material, command-run, product, environment y, opcionalmente, network-trace. Estos son los datos que utiliza SBOMit.

Parte 2: SBOMit

A partir de un archivo «attestation», SBOMit genera un «SBOM» enriquecido mediante la ejecución de resolventes de paquetes específicos de cada lenguaje sobre los datos de compilación Witness observados.

1. Instalar «SBOMit»

go install github.com/sbomit/sbomit@latest

2. Generar un archivo «SBOM» enriquecido

# SPDX 2.3 (default)
sbomit generate attestation.json

# SPDX 2.2
sbomit generate attestation.json -f spdx22

# CycloneDX 1.5
sbomit generate attestation.json -f cdx15

# CycloneDX 1.4
sbomit generate attestation.json -f cdx14

3. (Opcional) –catalog para capturar el árbol de dependencias

SBOMit Se puede utilizar Syft como fuente de catálogo adicional, fusionando sus resultados con los datos derivados de attestation:

sbomit generate attestation.json --catalog syft --project-dir /path/to/project

SBOMitgenera (por el momento) una lista plana de dependencias; sabe qué se ha instalado y utilizado, pero no reconstruye el árbol completo de dependencias. Syft, en el caso de ecosistemas en los que puede resolver la estructura en árbol (por ejemplo, módulos de Go o npm), conserva esa relación padre-hijo en su salida.

Al especificar --catalog syft, SBOMit utiliza el árbol de dependencias de Syft como base y luego lo complementa con todo aquello que Syft no puede detectar: las versiones reales instaladas en el momento de la compilación, las bibliotecas nativas, los archivos que no gestiona ningún gestor de paquetes y el origen de las llamadas de red capturado por Witness.