apps-registry/workloads/docs-portal/docs/devsecops/cosign.md

Cosign — firma de imágenes

!!! info "Qué problema resuelve" Todo lo anterior en esta sección (Gitleaks, Trivy, Semgrep, SBOM) responde a la pregunta "¿esta imagen es segura de construir?". Cosign responde una pregunta distinta, y que pasa después: "la imagen que está corriendo ahora mismo en el cluster, ¿es exactamente la que armó el pipeline — o pudo haber sido reemplazada, modificada, o subida por otra vía?".

Analogía simple

Pensalo como el sello de cera en un sobre antiguo. Cualquiera puede leer la carta (la imagen es pública, cualquiera puede bajarla del registry) — eso Cosign no lo esconde. Lo que el sello garantiza es otra cosa: que la carta salió exactamente de donde dice que salió, y que nadie la abrió y volvió a cerrar en el camino.

• La llave privada (guardada como secret de Gitea, nunca en el repo) es el sello físico — solo el pipeline de CI puede estampar una firma válida, porque solo él tiene el sello.
• La llave pública (workloads/ecommerce/cosign.pub, commiteada sin problema — es pública a propósito) es la forma de reconocer el sello: cualquiera puede mirar la carta, ver el sello, y confirmar "sí, esto lo selló quien tiene la llave privada" — sin necesitar la llave privada para verificarlo.

Si alguien sube una imagen distinta con el mismo tag, o modifica un solo byte de la imagen original, la firma deja de coincidir. No es que Cosign "detecte" la alteración activamente — es que la verificación simplemente falla, porque la firma fue calculada sobre el digest exacto de la imagen original.

Cómo funciona en este pipeline

flowchart LR
    A["docker push"] --> B["cosign sign<br/>(llave privada, secret)"]
    B --> C["cosign verify<br/>(llave pública, repo)"]
    C -- "firma válida" --> D["✅ pipeline termina OK"]
    C -- "firma inválida/ausente" --> X["❌ pipeline falla"]

1. Par de llaves: generado una vez con cosign generate-key-pair, protegido por password. La privada (cosign.key) se subió como secret de Gitea Actions (COSIGN_PRIVATE_KEY + COSIGN_PASSWORD) — nunca se commiteó al repo, ni existe en el disco de este equipo después de subirla. La pública (cosign.pub) sí vive commiteada en workloads/ecommerce/cosign.pub, porque su función es poder compartirse.
2. Firma: después de subir la imagen al registry, el pipeline la firma con la llave privada (leída desde el secret vía --key env://COSIGN_PRIVATE_KEY, sin escribirla nunca a disco).
3. Verificación (smoke test): en el mismo pipeline, inmediatamente después, se verifica la firma recién creada contra la llave pública del repo. Si algo salió mal (llave incorrecta, imagen corrupta), el pipeline falla ahí mismo — antes de que nadie más intente confiar en esa imagen.

Por qué --tlog-upload=false

Cosign, por defecto, publica cada firma en el transparency log público de Sigstore (Rekor) — un registro público, auditable, de "quién firmó qué y cuándo", pensado para proyectos open source donde esa transparencia es el punto. Este registry (gitea.cruzcloud.net) es privado; no tiene sentido — y sería una fuga de metadata innecesaria — anunciar públicamente que este lab construyó una imagen v1.0.97 en tal fecha. Por eso el pipeline firma solo con el par de llaves propio, localmente, sin tocar el transparency log público (--use-signing-config=false --tlog-upload=false al firmar, --insecure-ignore-tlog=true al verificar).

!!! warning "Trade-off consciente, no gratis" Sin transparency log, la garantía es "esta firma la generó quien tiene la llave privada" — pero no hay un registro público e inmutable de cuándo se generó cada firma. Para un registry privado de un lab personal, ese trade-off tiene sentido. Para un proyecto open source con más de una persona firmando, seguramente no.

Qué NO se firma

No se firma :latest en ningún caso — es un tag mutable, se re-apunta a una imagen distinta en cada build, así que firmarlo no significaría nada útil. Y desde 2026-08-16 (ver más abajo) tampoco se firma directamente por el tag versionado — se firma por digest, que es la única referencia que realmente identifica una imagen de forma inequívoca.

Verificar manualmente

Con la llave pública del repo, cualquiera puede confirmar la firma de una imagen sin necesitar acceso a nada privado. Apuntando al digest exacto (lo que firma el pipeline hoy):

cosign verify \
  --key workloads/ecommerce/cosign.pub \
  --insecure-ignore-tlog=true \
  gitea.cruzcloud.net/devops/ecommerce-frontend@sha256:<digest>

También funciona apuntando a un tag — Cosign lo resuelve al digest que tenga en ese momento antes de verificar —, pero por eso mismo es menos preciso: si el tag fue reasignado después de la firma original, estarías verificando una imagen distinta de la firmada, sin que nada te avise.

Si la imagen fue firmada por este pipeline, el comando termina con exit 0 y muestra el detalle de la firma. Si no — sea porque nunca se firmó, porque la firmó otra llave, o porque la imagen fue modificada después — termina con exit 1 y un error explícito.

Decisiones ya resueltas (antes eran TODO)

Dos preguntas abiertas al validar el pipeline end-to-end por primera vez, ambas ya cerradas — se documentan igual, porque el por qué de cada decisión sigue siendo útil.

1. Firma por digest, no por tag — implementado 2026-08-16

Hasta el 2026-08-15, el pipeline firmaba ecommerce-frontend:v1.0.104 — un tag, no un digest (sha256:...). Un tag es una etiqueta mutable: nada impedía que, después de firmada la imagen, alguien (o un bug en el propio pipeline) volviera a subir contenido distinto bajo el mismo tag v1.0.104. La firma original seguiría "verificando" — porque Cosign, al verificar por tag, resuelve el tag al digest que tenga en ese momento, no al que tenía cuando se firmó.

Esto no era hipotético: el propio Cosign lo advertía en cada firma de este pipeline:

WARNING: Image reference gitea.cruzcloud.net/.../ecommerce-frontend:v1.0.102
uses a tag, not a digest, to identify the image to sign.
This can lead you to sign a different image than the intended one.

Fix aplicado: el pipeline ahora captura el digest real que devuelve docker push (parseando sha256:[a-f0-9]{64} de la salida) y lo usa tanto para firmar como para verificar — gitea.cruzcloud.net/devops/ecommerce-frontend@sha256:... en vez de :v1.0.104 — en los tres pipelines (ecommerce-frontend, commerce-backend, docs-portal). Esa advertencia de Cosign ya no debería aparecer en los logs.

2. El transparency log (Rekor) se mantiene deshabilitado — decisión, no pendiente

Ya se explicó arriba, en la sección "Por qué --tlog-upload=false" de esta misma página, la decisión de no publicar en el transparency log para este registry privado. Vale la pena nombrar en simple qué es lo que se está dejando afuera:

Un transparency log (Rekor, el de Sigstore) es un registro público, append-only, criptográficamente verificable, de "quién firmó qué imagen y cuándo" — pensalo como un libro contable público que nadie puede editar ni borrar después de escrito, solo agregar filas nuevas. Cualquiera puede consultar ese libro para confirmar de forma independiente (sin confiar en el propio proyecto, ni en la llave privada, ni en el registry) que una firma específica existió en un momento específico.

Sin transparency log, la garantía que queda es más débil: "esta firma la generó quien tuviera la llave privada en el momento en que se verificó" — pero no hay ningún registro externo e inmutable que demuestre cuándo se generó, ni una forma de detectar si alguien con acceso a la llave privada firmó algo por fuera del pipeline sin que quede rastro.

Revisado explícitamente el 2026-08-16 (ya no es un TODO sin decidir, es una elección consciente confirmada): se mantiene deshabilitado. Motivos concretos para este lab — habilitarlo agregaría una llamada de red saliente por build hacia rekor.sigstore.dev, atravesando el mismo túnel de Cloudflare que ya tuvo un incidente de SNI/orden de reglas con Cosign (ver el playbook de realm HTTP y Cosign) — más superficie de fallo por build, sin beneficio real, ya que el registry es privado y no hay a quién auditar públicamente. Revisar esta decisión de nuevo si el registry deja de ser exclusivamente privado, o si se suma más de una persona con acceso a la llave de firma.

Qué falta (a propósito, todavía)

Hoy la verificación de firma corre como smoke test dentro del mismo pipeline que la creó — útil para confirmar que el mecanismo funciona, pero no impide que alguien despliegue manualmente una imagen sin firmar en el cluster. El siguiente paso natural, que no se implementó en esta primera vuelta, sería un admission controller en el cluster (ej. Sigstore's policy-controller o Kyverno con una política de verificación de imágenes) que rechace cualquier Pod cuya imagen no tenga una firma válida de cosign.pub — momento en el que Argo CD dejaría de poder desplegar una imagen sin firmar, no solo el pipeline de CI.

Si la llave privada se compromete

1. Generar un par nuevo (cosign generate-key-pair).
2. Reemplazar COSIGN_PRIVATE_KEY y COSIGN_PASSWORD en los secrets de Gitea Actions del repo.
3. Reemplazar workloads/ecommerce/cosign.pub con la nueva llave pública, en un commit normal (no es secreto, no hace falta reescribir historial).
4. Las imágenes ya firmadas con la llave vieja siguen verificando contra la llave vieja — no se "invalidan" solas. Si se sospecha compromiso real, hay que decidir explícitamente qué imágenes ya desplegadas se consideran no confiables, no asumir que rotar la llave alcanza.