Verificación de sus descargas

Los binarios de bits se ejecutan en sus hosts con visibilidad privilegiada, y bitcollector produce la evidencia de la que dependen usted y su auditor. Una evidencia nunca es más fiable que el instrumento que la produjo.

Así que antes de instalar nada, usted debería poder demostrar exactamente qué bytes está a punto de ejecutar. Esta página le muestra cómo, usando únicamente herramientas publicadas y sin conexión.

Si alguna comprobación falla

No instale el binario. No "vuelva a intentar la descarga a ver si suena la flauta". Conserve los ficheros y escriba a [email protected] indicando la versión de la release y la salida del comando que falló.

Qué se distribuye con cada versión

Fichero	Qué es
bitcollector-<os>-<arch>	El binario en sí
bitcollector-<os>-<arch>.sbom.json	SBOM CycloneDX — todo lo que hay dentro de ese binario
bitcollector-<os>-<arch>.sig	Paquete de firma cosign sobre esos bytes exactos
bitcollector-<os>-<arch>.att	Atestación cosign que liga el SBOM a esos bytes exactos
SHA256SUMS	Sumas de comprobación de todos los ficheros anteriores
SHA256SUMS.sig	Firma cosign sobre SHA256SUMS
release-provenance.json	Commit, cadena de herramientas de Go y plataformas desde las que se compiló la release

Las releases de bitscanner, bitenforcer y bitmapper tienen la misma estructura, con su propio nombre en lugar de bitcollector. Los cuatro productos se firman con la misma clave de release, así que una sola comprobación de clave cubre toda la familia — y una clave que cambiara entre dos de ellos sería motivo para detenerse, no para actualizar su copia.

Paso 0 — consiga las herramientas

Necesita cosign v3 o posterior, y sha256sum (parte de coreutils; en macOS, shasum -a 256 o brew install coreutils).

cosign version

Paso 1 — obtenga la clave pública, y compruebe que es la clave correcta

Descargue la clave de firma de la release junto al directorio de la release, no dentro de él:

# desde el directorio que CONTIENE su directorio de release
# DNS route — works from a CLI and inside CI. The HTTPS copy of this key is
# currently behind a bot challenge, so `curl` cannot fetch it; see the note below.
dig +short TXT _cosign-key.cert-ix.com | tr -d '"' | sed 's/.*key=//' \
  | base64 -d | openssl pkey -pubin -inform DER -out cosign.pub

Ponga la clave junto a la release, no dentro de ella

verify-release.sh trata todo fichero que haya dentro de un directorio de release como algo que debería estar firmado. Dejar ahí cosign.pub hace que informe de un fichero no justificado — lo que se lee exactamente como una release manipulada, aunque no lo sea. Mantenga la clave un nivel por encima. Por la misma razón, indíquela por ruta absoluta: el script se sitúa dentro del directorio de la release, de modo que un --key cosign.pub relativo deja de resolverse y el fallo que imprime es indistinguible de una firma incorrecta.

→ cosign.pub

No se salte esto. Es la comprobación que hace que todo lo demás signifique algo.

Un atacante que pueda sustituir un binario en nuestro sitio web puede sustituir también la clave pública que está justo al lado. La verificación entonces pasaría — contra la clave de él. Usted ejecutaría su binario y obtendría una marca verde.

Una comprobación de firma vale solo lo que valga el ancla de confianza que hay detrás. Confirme la huella de la clave desde una segunda fuente independiente antes de confiar en ella. De eso van exactamente las líneas siguientes, y es el paso que la mayoría de las instrucciones de verificación omiten.

La huella

Calcule la huella de la clave que descargó:

# The robust form: SHA-256 of the DER-encoded public key.
# Independent of PEM whitespace, so copy-paste through a browser cannot change it.
openssl pkey -pubin -in cosign.pub -outform DER | sha256sum

Debe ser exactamente:

552839f6b1b1eb0934557e1886326c7270584fa602fbf56f84754a98be3de822

Si prefiere calcular el hash del fichero tal cual:

sha256sum cosign.pub
# 150eacccc1bc26a83c746a1e441b0b0bdc8104c3ef07efd75c62deb5b069f914

Ese segundo valor cubre los bytes exactos del fichero publicado, salto de línea incluido, así que solo coincide si descargó el fichero en lugar de pegar su contenido.

La clave en sí es lo bastante corta como para leerla. Esto es todo lo que es:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEPA6gi66NIBXbSwYS3CL16Ien3sho
wCNOR8dRivdd07SQWto107QMDelUKMeebJQHSlOchNO4PJSWjCcrsUYb5w==
-----END PUBLIC KEY-----

Es una clave pública ECDSA P-256 (prime256v1). Puede confirmarlo usted mismo:

openssl pkey -pubin -in cosign.pub -text -noout | head -2
# Public-Key: (256 bit)

Segundas fuentes para la huella

No tome la huella de la misma página que le sirvió la clave, si puede evitarlo. Contrástela con al menos una de estas:

• Un registro DNS, servido por una infraestructura distinta de este sitio web. La misma huella se publica en un registro TXT en _cosign.cert-ix.com, y basta un comando para comprobarlo: dig +short TXT _cosign.cert-ix.com. Este es el contraste que merece la pena hacer: un atacante que hubiera tomado este servidor web tendría que tomar también nuestro DNS para que ambos coincidieran — son sistemas distintos, con credenciales distintas. Si no coinciden, deténgase: no ejecute los binarios y escriba a [email protected].
• Su contacto en Cert-IX, por un canal aparte. Pida a su contacto comercial o de seguridad que le lea la huella por un canal que no sea este sitio web — una llamada telefónica, un correo firmado desde [email protected], o su canal de soporte habitual.
• Una clave que ya tenga. Si verificó una release anterior de bits, compárela con la clave que conservó. Una clave de release que cambia sin un anuncio es motivo para detenerse y preguntar, no para actualizar su copia.

Una vez confirmada la huella, conserve su copia de la clave y reutilícela. El valor de un ancla de confianza viene de que no cambie.

Paso 2 — verifique primero el manifiesto de sumas de comprobación

El orden importa. Verifique la firma sobre SHA256SUMS antes de fiarse de ninguna suma de comprobación que haya dentro — un fichero de sumas sin firmar no demuestra nada, porque quien pueda sustituir un binario puede sustituir con la misma facilidad una lista de sumas en texto plano.

cosign verify-blob --key cosign.pub --bundle SHA256SUMS.sig \
  --insecure-ignore-tlog=true SHA256SUMS

Salida esperada:

WARNING: Skipping tlog verification is an insecure practice that lacks transparency and
auditability verification for the blob.
Verified OK

Ese aviso es esperable — esto es exactamente lo que significa

Cert-IX es una plataforma europea soberana y no opera ningún registro público de transparencia Sigstore. Las firmas son basadas en clave. Sin --insecure-ignore-tlog=true, cosign v3 busca una entrada en un registro de transparencia que intencionadamente no existe e informa de "no signatures found".

La opción no debilita la comprobación de la firma en sí. Lo que sí significa es que usted no obtiene un registro independiente y solo-de-adición de que esta firma existió alguna vez — así que el contraste de la huella del Paso 1 está haciendo el trabajo que de otro modo haría por usted un registro de transparencia. Ese es el compromiso, dicho sin rodeos.

Paso 3 — verifique que cada fichero coincide con su suma de comprobación

sha256sum -c SHA256SUMS

Paso 4 — verifique el binario que está a punto de instalar

cosign verify-blob --key cosign.pub --bundle bitcollector-linux-amd64.sig \
  --insecure-ignore-tlog=true bitcollector-linux-amd64

Paso 5 — verifique que el SBOM describe realmente estos bytes

cosign verify-blob-attestation --key cosign.pub --bundle bitcollector-linux-amd64.att \
  --type cyclonedx --insecure-ignore-tlog=true bitcollector-linux-amd64

El SBOM es cómo usted sabe qué hay dentro del collector que producirá su evidencia. Un binario cuya atestación no coincide con sus bytes es un binario cuyo contenido usted no puede enumerar.

Todo de una sola vez

Cert-IX distribuye el mismo script de verificación que ejecuta contra sus propias releases antes de publicarlas, en ci/verify-release.sh dentro del repositorio:

./verify-release.sh "$PWD/bitcollector-release" "$PWD/cosign.pub"

[verify-release] verifying the signature over SHA256SUMS
[verify-release]   SHA256SUMS signature OK
[verify-release] verifying checksums of every artefact
[verify-release]   all checksums OK
[verify-release]   bitcollector-darwin-amd64 signature OK
[verify-release]   bitcollector-darwin-amd64 SBOM attestation OK
[verify-release]   bitcollector-darwin-arm64 signature OK
[verify-release]   bitcollector-darwin-arm64 SBOM attestation OK
[verify-release]   bitcollector-linux-amd64 signature OK
[verify-release]   bitcollector-linux-amd64 SBOM attestation OK
[verify-release]   bitcollector-linux-arm64 signature OK
[verify-release]   bitcollector-linux-arm64 SBOM attestation OK
[verify-release]   bitcollector-windows-amd64.exe signature OK
[verify-release]   bitcollector-windows-amd64.exe SBOM attestation OK
[verify-release] VERIFIED: 5 binary/binaries, checksums, and signatures all valid
[verify-release] built from commit 8819759 with go1.25.12
OK: 5 verified

Un código de salida 0 y una línea que diga OK: <n> verified significan que todos los binarios son auténticos e íntegros. Cualquier otra cosa significa no instalar.

Pase rutas absolutas

El script entra en el directorio de la release antes de empezar a trabajar, así que una ruta relativa a la clave pública deja de resolverse y todas las comprobaciones de firma fallan con:

[verify-release] REFUSED: the signature over SHA256SUMS is NOT valid for this key.

Ese rechazo se lee exactamente igual que una release manipulada. Si lo ve, vuelva a ejecutarlo con rutas absolutas ("$PWD/cosign.pub") antes de concluir nada — y si sigue fallando con una ruta absoluta, entonces trátelo como real y contacte con [email protected].

Dos detalles que vale la pena notar, porque son la diferencia entre una comprobación y un ritual:

• Reporta un recuento. Una verificación que no encuentra nada que comprobar no debe reportar éxito, así que el script se niega cuando el directorio no contiene ningún binario, e imprime cuántos verificó realmente.
• Se niega ante una firma que falta. Un binario sin firmar dentro de una release firmada es exactamente el aspecto que tiene un ataque a la cadena de suministro, así que el script falla en lugar de saltárselo.

Qué demuestra hoy la firma

Sea preciso con esto, porque "firmado" se entiende a menudo como más de lo que es.

Lo que demuestra: estos bytes exactos fueron producidos por la canalización de release de Cert-IX y firmados por el poseedor de la clave cuya huella usted comprobó en el Paso 1, y no han cambiado desde entonces. Combinado con SHA256SUMS y la atestación del SBOM, usted puede enumerar qué hay dentro del binario y estar seguro de que la enumeración coincide con los bytes.

Lo que no demuestra, dicho con honestidad:

• La clave de firma vive actualmente en el host de compilación, protegida como un fichero con una frase de contraseña guardada fuera del control de versiones. No está en un módulo de seguridad de hardware (HSM). Así que la firma demuestra "este es el binario que produjo esa compilación" — no demuestra que el propio host de compilación estuviera libre de compromiso en el momento de firmar.
• No hay registro de transparencia. Usted no puede consultar un registro independiente y solo-de-adición para ver si alguna vez se emitió bajo esta clave una firma para otro binario distinto.

Esas dos cosas son la razón de que importe la compilación reproducible que se explica abajo, y de que el contraste de la huella del Paso 1 no sea opcional.

Recompilar el binario usted mismo

No tiene que fiarse de nuestra palabra sobre lo que hay en el binario — puede recompilarlo y comparar. Las releases de bits son reproducibles: el mismo commit, compilado con la misma cadena de herramientas de Go, produce una salida idéntica byte a byte.

Empiece por release-provenance.json, que registra exactamente desde qué se compiló la release:

{
  "service": "bitcollector",
  "version": "0.1.0-ga",
  "commit": "8819759",
  "go_toolchain": "go1.25.12",
  "source_date_epoch": 1786277293,
  "build_time": "2026-08-09T12:08:13Z",
  "platforms": ["linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64", "windows/amd64"],
  "reproducible": true,
  "signed": true
}

Con el código fuente y la cadena de herramientas que ahí se nombran:

git checkout <commit from release-provenance.json>

SOURCE_DATE_EPOCH=<source_date_epoch from release-provenance.json>
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
  -ldflags="-s -w -buildid= \
    -X main.version=<version> \
    -X main.buildTime=$(date -u -d @$SOURCE_DATE_EPOCH +%Y-%m-%dT%H:%M:%SZ) \
    -X main.gitCommit=<commit>" \
  -o bitcollector-linux-amd64 ./cmd/bitcollector

sha256sum bitcollector-linux-amd64   # must equal the value in SHA256SUMS

Un hash que coincide significa que el binario publicado no contiene nada que no esté en el código fuente que usted acaba de leer.

Releases actuales

Los cuatro bits están publicados, y los cuatro se firman con la misma clave — aquella cuya huella comprobó en el Paso 1. Una sola comprobación de clave cubre la familia.

Producto	Versión	Commit	Cadena de herramientas	Plataformas
bitcollector	0.1.0-ga	8819759	go1.25.12	linux amd64/arm64, macOS amd64/arm64, Windows amd64
bitscanner	0.1.3-ga	7db3d4c	go1.25.12	linux amd64/arm64
bitenforcer	0.1.0-ga	4c6ce93	go1.25.12	linux amd64/arm64
bitmapper	0.1.0-ga	64ebc64	go1.25.12	linux amd64

Las columnas de plataformas no son todas iguales, y las diferencias son deliberadas. Cuando falta una plataforma es porque el agente no haría allí su trabajo, no porque se olvidara la compilación. Cada página de producto da la razón:

Producto	Qué se retiene, y por qué
bitcollector	Nada. Se distribuye en las cinco — plataformas
bitscanner	Sin macOS/Windows: sus lectores de vecinos y de rutas son implementaciones de Linux, y una tabla de vecinos vacía se leería como un segmento tranquilo — plataformas
bitenforcer	Sin macOS/Windows: toda su superficie es iptables/sysctl/systemd/SELinux, así que una compilación allí informaría de cada módulo como NOT EXAMINED — plataformas
bitmapper	Solo linux amd64: la captura necesita una libpcap enlazada en la compilación, así que no puede compilarse de forma cruzada. Windows compila pero nunca se ha ejecutado allí, así que se retiene como laguna de pruebas — plataformas

Verifique la versión que realmente descargó

Los commits de arriba son aquellos a partir de los cuales se compilaron las releases actuales. release-provenance.json, dentro de su directorio de release, es el registro autoritativo de ese directorio — contrástelo con la tabla en lugar de suponer, y el propio binario imprime los mismos valores desde los bytes que está a punto de ejecutar. Si los tres no coinciden, deténgase y escriba a [email protected].

El comando no es el mismo en los cuatro binarios. Use el del binario que tenga:

Binario	Comando que imprime su versión
bitcollector	bitcollector --version
bitscanner	bitscanner version
bitenforcer	bitenforcer version
bitmapper	bitmapper version

Use exactamente estas grafías, porque la equivocada no se limita a mostrar un error:

• En bitcollector hasta la versión 0.1.0-ga incluida, bitcollector version no es un comando de versión. El argumento se ignora y el binario ARRANCA EL AGENTE: crea su clave de identidad en el directorio de datos y empieza a recolectar. Si lo ejecutó, detenga el proceso y borre el directorio de datos (/var/lib/bitcollector, salvo que lo haya cambiado) antes de enrolar el host de verdad. bitcollector --version imprime y sale, y siempre lo ha hecho.
• En bitscanner, bitenforcer y bitmapper, --version no es una opción que tengan; el comando falla con unknown flag: --version. Ese caso es inofensivo, solo inútil.

Los binarios y su clave de firma están en la página de descargas. Los pasos de arriba funcionan sin conexión sobre cualquier directorio de release que tenga, así que puede verificar en una máquina que nunca toque nuestro sitio web.

Próximos pasos

• bitcollector — qué recopila, y cómo se verifica su cadena de evidencia (una clave distinta, y una comprobación aparte).
• bitenforcer — qué hace v1 y qué no hace.
• Visión general de bits — empiece aquí si llegó primero a esta página.