La imagen

El WhyStack Agent se entrega como una imagen de contenedor. Esta página describe lo que contiene: el material para una revisión de seguridad antes de entregarle credenciales.

Cómo obtenerla

# AWS (ECR)
docker pull <whystack-account>.dkr.ecr.<region>.amazonaws.com/whystack-agent:<version>

# GCP (Artifact Registry)
docker pull <region>-docker.pkg.dev/<whystack-project>/whystack/whystack-agent:<version>

El acceso se concede a tu cuenta de AWS o a tu proyecto de GCP: el pull usa la identidad de tu nube, y no hay ninguna credencial de WhyStack que tengas que guardar o rotar.

Autentícate antes del pull

El registry es privado, así que un docker pull sin autenticación falla con no basic auth credentials. Autentícate con tus credenciales, porque es la autorización que les concedimos a ellas la que habilita el pull.

AWS (ECR). El token viene de tu cuenta; el login apunta al registry de WhyStack:

aws ecr get-login-password --region <region> \
  | docker login --username AWS --password-stdin <whystack-account>.dkr.ecr.<region>.amazonaws.com

Usa la misma <region> de la dirección de la imagen. El acceso de lectura al repositorio ya se le concedió a tu cuenta de nuestro lado, pero un pull entre cuentas necesita permiso en los dos lados: el principal que hace el pull necesita ecr:GetAuthorizationToken y, sobre el repositorio de WhyStack, ecr:BatchGetImage, ecr:GetDownloadUrlForLayer y ecr:BatchCheckLayerAvailability. Las políticas administradas AmazonEC2ContainerRegistryReadOnly (común en los roles de nodo de EKS) y AmazonECSTaskExecutionRolePolicy (la de la task execution role de ECS) ya cubren las cuatro.

GCP (Artifact Registry). Registra el credential helper una vez:

gcloud auth configure-docker <region>-docker.pkg.dev

Tu principal necesita roles/artifactregistry.reader sobre el repositorio, que ya se le concedió al proyecto que nos indicaste.

En un orquestador no hay docker login

En ECS, EKS, GKE o Cloud Run quien hace el pull de la imagen es la plataforma, no tú. Y usa su propia identidad, no la tuya. Asegúrate de que la identidad que hace el pull tenga el mismo permiso de lectura:

• ECS: la task execution role.
• EKS: el role del node group (o un imagePullSecret, si no puedes cambiar el role).
• GKE / Cloud Run: la service account del node pool o del servicio.

Dinos cuál es esa cuenta o proyecto si es distinto del que ya autorizamos. La concesión es por cuenta/proyecto, y un pull desde una identidad no autorizada falla con el mismo error de credenciales.

Propiedad	Valor
Arquitecturas	linux/amd64 y linux/arm64
Base	node:22-alpine
Usuario	node (uid 1000), no root
Entrypoint	carga los PEMs desde /certs y ejecuta el proceso del Agent
Puertos expuestos	ninguno

Qué contiene la imagen

Solo lo que el proceso abre en tiempo de ejecución: los artefactos JavaScript compilados (dist/), los manifests de los paquetes y las dependencias de producción.

Qué no contiene la imagen

Por construcción, la etapa final del build no copia el árbol de desarrollo:

• ningún código fuente (src/);
• ningún test ni fixture de test;
• ninguna toolchain de compilación: python3, make y g++ existen solo en una etapa intermedia y nunca llegan al runtime;
• ningún secreto. La imagen es idéntica para todos los clientes; lo que varía es el certificado y las credenciales que tú montas en tiempo de ejecución.

Excluir los fixtures es deliberado y te importa: sin eso, los datos de prueba de un cliente viajarían a la infraestructura de otro.

Fija por digest

En producción, referencia la imagen por digest y no por tag:

<address>/whystack-agent@sha256:<digest>

El Agent es efímero y hace pull con frecuencia. Un tag móvil permite que réplicas distintas corran builds distintos sin que nadie lo note. El digest es inmutable.

Para encontrar el digest detrás de un tag:

docker buildx imagetools inspect <address>/whystack-agent:<version>

El mismo comando lista las arquitecturas presentes en el índice multiplataforma.

Verifica la firma

La imagen se firma al publicarse, sin clave: el workflow que la construye intercambia su propia identidad por un certificado efímero, y la firma queda registrada en un log público de transparencia. Lo que esto prueba no es “alguien con una clave firmó esto”, sino qué workflow, de qué repositorio, en qué tag produjo ese digest.

Requiere cosign:

cosign verify \
  --certificate-identity https://github.com/sunnysystems/whystack-edge/.github/workflows/release-image.yml@refs/tags/v<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  <address>/whystack-agent@sha256:<digest>

El flag --certificate-identity es el que importa, y por eso lleva la versión: sin fijar la identidad, cosign verify aceptaría cualquier firma válida de Sigstore, incluida una de un repositorio que no es el nuestro. Verificar sin él es casi lo mismo que no verificar.

Las versiones anteriores a 1.0.2 no están firmadas

La firma llegó después de la primera imagen publicada. Correr cosign verify contra una versión anterior falla porque la firma está ausente, no porque sea inválida. Son cosas distintas, y el mensaje de cosign no lo deja claro.

Si aplicas una policy de admisión en tu clúster (Kyverno, policy-controller), esa misma identidad es la que va en la regla. Recomendado, pero es tu decisión: nosotros publicamos la firma, no exigimos la verificación.

Requisitos de ejecución

Ningún privilegio especial: sin --privileged, sin capabilities añadidas, sin acceso al socket de Docker, sin montajes del sistema de archivos del host. El único volumen necesario es /certs, de solo lectura.

Esto vale para el Agent. El Profiler es otro artefacto, y su postura es la opuesta

El WhyStack Profiler (el segundo artefacto, opcional) es una imagen distinta (whystack-profiler), y exige privilegios: cinco capabilities de kernel, visibilidad de los procesos del host y un perfil de AppArmor dedicado. Una de ellas, CAP_SYS_ADMIN, equivale a root en un contenedor con hostPID.

No son negociables, y el Profiler se niega a arrancar si falta cualquiera de ellas. No existe un modo reducido. El razonamiento está en Seguridad → WhyStack Profiler, junto con lo que sale de tu infraestructura y qué hacer si tu respuesta es no.

Esta distinción es la razón de que sean dos artefactos y no un flag: la página que estás leyendo describe lo que instala todo cliente, y sigue siendo cierta. Quien nunca instala el Profiler nunca concede nada de esto.

Memoria y CPU: 0.5 vCPU y 512 MB alcanzan para la mayoría de las instalaciones. RUNNER_LEARNED_STORE_PATH tiene :memory: como valor por defecto, así que no se escribe nada en disco. Apúntalo a un volumen y el contenedor empieza a escribir ahí, con permisos que quedan bajo tu responsabilidad.