container-security

Container Security

Rules (for AI agents)

ALWAYS

• Use multi-stage builds: separate builder/test stages from the final runtime image so build toolchains and source aren't shipped. The last stage should be a minimal base — gcr.io/distroless/<variant>, scratch, or a versioned -slim / -alpine variant — pinned by SHA256 digest, not just tag. Two bases have nothing to pin: scratch, and a reference to an earlier stage in the same file (FROM base), which is pinned on that stage's own FROM line.
• Run as a non-root user: set USER explicitly on the final stage, as a number not a name. Omitting it leaves the container running as root. K8s runAsNonRoot rejects UID 0 and cannot resolve a username, so USER appuser fails at startup with "image has non-numeric user"; any non-zero UID passes, and 10000+ by convention also avoids colliding with host accounts.
• Use npm ci (and equivalents pnpm install --frozen-lockfile, yarn install --frozen-lockfile) in container builds, not npm install. npm install mutates the lockfile and resolves versions per-build, producing non-deterministic images that drift from the lockfile.
• Add a .dockerignore excluding .git, node_modules, .env, *.pem, *.key, target/, .terraform/, dist/, coverage/.
• Build with BuildKit (default since Docker Engine 23; DOCKER_BUILDKIT=1 on older engines) so RUN --mount=type=secret,id=<name> is available for build-time credentials. # syntax=docker/dockerfile:1 selects the frontend and does not enable BuildKit by itself.
• Emit an SBOM (docker buildx --sbom=true / syft) and attach it to the image so downstream scanners can audit the dependency set.
• Pin apt packages and clean lists in the same layer: apt-get update && apt-get install -y --no-install-recommends pkg=1.2.3 && rm -rf /var/lib/apt/lists/*. The update must be in that same RUN — without it there are no package lists; in an earlier layer it goes stale behind the build cache.
• Set explicit HEALTHCHECK for long-running services, and separately set livenessProbe / readinessProbe / startupProbe in K8s. Kubernetes never runs the image's HEALTHCHECK — probes are the only mechanism there, so neither one covers the other.
• Set resource requests and limits on every container (CPU and memory). Without a memory limit, one container can exhaust the node and take down every pod scheduled beside it — the limit is what bounds a runaway's blast radius to its own container.
• Harden at the container-level securityContext (spec.containers[].securityContext): capabilities.drop: [ALL] then add back only what's needed, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false. These three exist only at container level — under the pod's spec.securityContext they are silently ignored while the manifest still applies, so the control vanishes with nothing to show for it. Use emptyDir for paths that must stay writable.
• Apply a seccomp profile (seccompProfile.type: RuntimeDefault at minimum) and AppArmor / SELinux where available. This one — like runAsNonRoot and runAsUser — may be set on the pod and inherited by its containers.
• Scan every image in CI (Trivy, Grype, Snyk, or your registry's scanner) and triage findings on severity, reachability and fix availability together. Fail the build on fixable CRITICAL / HIGH findings; a material vulnerability with no published fix needs mitigation or a recorded risk acceptance, not an automatic pass — "unfixable" is remediation information, not a reason it stopped mattering.
• Set automountServiceAccountToken: false on every workload that does not call the Kubernetes API. The default mounts a real ServiceAccount token into the container, so an RCE in an app that never needed cluster access still hands the attacker one.
• For multi-tenant workloads (per-user/per-customer sessions on shared infra), isolate tenants at the kernel boundary: a separate VM — or gVisor / Kata — per tenant, never just separate containers on one shared daemon. Drop privileged, enable user namespaces, and give each tenant its own network. A privileged container on a shared host escapes to the host trivially, so on shared infra that is full compromise of every co-tenant.
• Expose container orchestration to clients only through a scoped, authenticated broker API that performs the few operations a client may request (start/stop my session). The client must never hold direct daemon or cluster access.
• Consult iam-best-practices for cluster RBAC and the identity a workload runs as, and supply-chain-security for base-image provenance. This skill owns the container's own configuration, not what it inherits.