<!-- AUTO-GENERATED by export-plugins.py — DO NOT EDIT -->

---

name: container-security-guide description: Docker and Kubernetes security hardening guide covering images, builds, runtime, and orchestration tags: [ai, security]

Container Security Guide

Overview

Containers introduce a unique attack surface spanning the image build pipeline, container runtime, orchestration layer, and host OS. Security must be applied at every stage of the container lifecycle:

Stage	Threats	Key Controls
Build	Malicious base images, embedded secrets, bloat	Minimal images, scanning, signing
Registry	Image tampering, unauthorized access	Content trust, access control
Deploy	Misconfigured pods, excessive privileges	Admission control, PodSecurity
Runtime	Container escape, lateral movement, cryptomining	Seccomp, AppArmor, monitoring
Orchestration	RBAC bypass, API server exposure, secret leaks	NetworkPolicy, RBAC, external secrets

This guide covers Docker image and build security, Kubernetes-specific hardening, and runtime protection. It is tailored for teams running containerized workloads on GKE but applies broadly to any Kubernetes distribution.

When to Use This Skill

• You are writing or reviewing Dockerfiles for production services
• You are configuring Kubernetes security settings (PodSecurityStandards, NetworkPolicies, RBAC)
• You need to harden a container runtime environment against known attack vectors
• You are building a CI/CD pipeline and need image scanning and signing gates
• You are investigating a container security incident or preparing for an audit
• You want to implement defense-in-depth for containerized microservices

How It Works

Step 1: Scan Container Images

Scan images for known vulnerabilities before they reach production:

# Trivy: comprehensive vulnerability scanner
trivy image --severity HIGH,CRITICAL faos-api:latest

# Grype: fast alternative scanner
grype faos-api:latest --only-fixed --fail-on high

# Snyk: SaaS scanner with fix suggestions
snyk container test faos-api:latest --severity-threshold=high

# GCP Artifact Registry: automatic scanning
gcloud artifacts docker images list-vulnerabilities \
  REGION-docker.pkg.dev/PROJECT/REPO/my-app:latest \
  --format=json | jq '.[] | select(.vulnerability.effectiveSeverity == "CRITICAL")'

Integrate scanning into CI/CD pipelines with a gate:

# GitHub Actions: scan and fail on critical vulnerabilities
- name: Scan container image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.IMAGE }}
    format: 'sarif'
    output: 'trivy-results.sarif'
    severity: 'CRITICAL,HIGH'
    exit-code: '1'  # Fail the build on findings

Step 2: Harden Dockerfiles

Build minimal, secure container images following these principles:

• Use minimal base images (distroless, Alpine, or scratch)
• Run as non-root user
• Use multi-stage builds to exclude build tools from production images
• Never embed secrets, credentials, or private keys in images
• Pin base image versions with digest for reproducibility
• Set the filesystem to read-only where possible
• Include health checks for orchestrator integration

Step 3: Apply PodSecurityStandards

Kubernetes PodSecurityStandards (PSS) define three progressive security profiles:

Profile	Level of Security	Use Case
Privileged	None	System-level workloads (kube-system)
Baseline	Moderate	General workloads, prevents known escalations
Restricted	Strict	Security-sensitive and multi-tenant workloads

Apply PSS enforcement at the namespace level:

# Enforce restricted profile on production namespace
kubectl label namespace faos-api \
  pod-security.kubernetes.io/enforce=restricted \
  pod-security.kubernetes.io/enforce-version=latest \
  pod-security.kubernetes.io/warn=restricted \
  pod-security.kubernetes.io/audit=restricted

Step 4: Configure NetworkPolicies

By default, all pods in a Kubernetes cluster can communicate with all other pods. NetworkPolicies implement microsegmentation:

• Start with a default-deny policy for all namespaces
• Explicitly allow only required communication paths
• Use label selectors for fine-grained pod-to-pod rules
• Allow DNS resolution (kube-dns) in every policy

Step 5: Enable Runtime Monitoring

Runtime security tools detect anomalous container behavior:

# Falco: runtime threat detection
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm install falco falcosecurity/falco \
  --namespace falco-system \
  --create-namespace \
  --set falcosidekick.enabled=true \
  --set falcosidekick.config.slack.webhookurl=$SLACK_WEBHOOK

# Falco detects:
# - Shell spawned in container
# - Sensitive file access (/etc/shadow, /etc/passwd)
# - Unexpected network connections
# - Privilege escalation attempts
# - Cryptocurrency miner signatures

Runtime protection layers:

Technology	Protection Level	Performance Impact
Seccomp	System call filtering	Minimal
AppArmor	Mandatory access control profiles	Low
SELinux	Type enforcement and RBAC	Low
gVisor	User-space kernel (full syscall interception)	Moderate
Kata	VM-level isolation per container	Higher

Examples

Example 1: Secure Dockerfile for Python FastAPI App

# ============================================
# Stage 1: Build dependencies
# ============================================
FROM python:3.12-slim AS builder

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Create virtual environment
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# ============================================
# Stage 2: Production image
# ============================================
FROM python:3.12-slim AS production

# Security: Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser -d /app -s /sbin/nologin appuser

# Install only runtime dependencies (no gcc/build tools)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy virtual environment from builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copy application code
WORKDIR /app
COPY --chown=appuser:appuser ./src ./src

# Security: No secrets in image (use env vars or mounted secrets)
# Security: Read-only filesystem compatible
# Security: Drop all capabilities in K8s securityContext

# Health check for Kubernetes probes
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Security: Run as non-root user
USER appuser

# Security: Use exec form (no shell injection risk)
ENTRYPOINT ["uvicorn", "src.main:app"]
CMD ["--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

Security features in this Dockerfile:

Feature	Security Benefit
Multi-stage build	Build tools not in production image (smaller attack surface)
python:3.12-slim	Minimal base image (fewer vulnerabilities)
Non-root user	Prevents container escape to host root
--no-cache-dir	No pip cache (smaller image, no cached credentials)
--no-install-recommends	Minimal OS packages
rm -rf /var/lib/apt	No package manager cache
Exec form ENTRYPOINT	No shell injection via CMD override
HEALTHCHECK	Enables K8s liveness/readiness probes

Example 2: Kubernetes NetworkPolicy for Namespace Isolation

# 1. Default deny all ingress and egress traffic
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: faos-api
spec:
  podSelector: {}  # Applies to all pods in namespace
  policyTypes:
    - Ingress
    - Egress

---
# 2. Allow DNS resolution (required for service discovery)
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-dns
  namespace: faos-api
spec:
  podSelector: {}
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kube-system
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53

---
# 3. Allow ingress from gateway to API pods only
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-gateway-to-api
  namespace: faos-api
spec:
  podSelector:
    matchLabels:
      app: faos-api
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: faos-gateway
          podSelector:
            matchLabels:
              app: gateway
      ports:
        - protocol: TCP
          port: 8000

---
# 4. Allow API pods to reach database
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-api-to-database
  namespace: faos-api
spec:
  podSelector:
    matchLabels:
      app: faos-api
  policyTypes:
    - Egress
  egress:
    - to:
        - ipBlock:
            cidr: 10.0.0.0/8  # Cloud SQL private IP range
      ports:
        - protocol: TCP
          port: 5432  # PostgreSQL

---
# 5. Allow API pods to reach Redis
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-api-to-redis
  namespace: faos-api
spec:
  podSelector:
    matchLabels:
      app: faos-api
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: faos-cache
          podSelector:
            matchLabels:
              app: redis
      ports:
        - protocol: TCP
          port: 6379

Example 3: PodSecurityStandard (Restricted) Configuration

# Pod specification compliant with PSS restricted profile
apiVersion: apps/v1
kind: Deployment
metadata:
  name: faos-api
  namespace: faos-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: faos-api
  template:
    metadata:
      labels:
        app: faos-api
    spec:
      # Security: Use dedicated service account (not default)
      serviceAccountName: my-app-sa
      automountServiceAccountToken: false  # Disable unless needed

      # Security: Prevent privilege escalation via hostPID/hostNetwork
      hostPID: false
      hostNetwork: false
      hostIPC: false

      # Security: Set filesystem group for shared volumes
      securityContext:
        runAsNonRoot: true
        runAsUser: 65534      # nobody user
        runAsGroup: 65534
        fsGroup: 65534
        seccompProfile:
          type: RuntimeDefault

      containers:
        - name: faos-api
          image: REGION-docker.pkg.dev/PROJECT/REPO/my-app@sha256:abc123...
          ports:
            - containerPort: 8000
              protocol: TCP

          # Security: Container-level security context
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 65534
            capabilities:
              drop:
                - ALL
            seccompProfile:
              type: RuntimeDefault

          # Resource limits (prevent resource abuse)
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 512Mi

          # Health probes
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10

          # Mount secrets from external secret manager (not K8s Secrets)
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: faos-api-secrets
                  key: database-url

          # Writable directories for temp files (read-only root filesystem)
          volumeMounts:
            - name: tmp
              mountPath: /tmp
            - name: cache
              mountPath: /app/.cache

      volumes:
        - name: tmp
          emptyDir:
            sizeLimit: 100Mi
        - name: cache
          emptyDir:
            sizeLimit: 50Mi

Best Practices

Do This

• Use distroless or slim base images to minimize the attack surface
• Scan images in CI/CD and block deployments with critical or high vulnerabilities
• Sign images with cosign or Notary and verify signatures with Binary Authorization
• Run all containers as non-root with runAsNonRoot: true
• Drop all Linux capabilities with capabilities.drop: [ALL]
• Set readOnlyRootFilesystem: true and mount writable directories as emptyDir volumes
• Apply PodSecurityStandards at restricted level for production namespaces
• Implement default-deny NetworkPolicies in every namespace
• Use external secret managers (GCP Secret Manager, HashiCorp Vault) instead of K8s Secrets
• Pin image references by digest (@sha256:...) rather than mutable tags
• Enable Seccomp profiles (at minimum RuntimeDefault) for all containers
• Implement pod disruption budgets alongside security to maintain availability

Don't Do This

• Do not use latest tag for production images -- it is mutable and unpredictable
• Do not run containers as root or with privileged: true
• Do not embed secrets, API keys, or credentials in Docker images
• Do not expose the Docker socket (/var/run/docker.sock) to containers
• Do not use hostPID, hostNetwork, or hostIPC unless absolutely required
• Do not skip NetworkPolicies -- default Kubernetes networking allows unrestricted pod-to-pod traffic
• Do not grant cluster-admin ClusterRole to application service accounts
• Do not auto-mount service account tokens (automountServiceAccountToken: false by default)
• Do not install shells (bash, sh) in production images if they are not needed
• Do not use package managers (apt, apk) at runtime -- install everything at build time

Security Checklist

Image Security

• Base images are minimal (distroless, Alpine, or slim variants)
• Images are scanned for vulnerabilities in CI/CD with a blocking gate
• No secrets, credentials, or private keys are embedded in images
• Multi-stage builds exclude build tools from production images
• Images are signed and verified before deployment (cosign / Binary Authorization)
• Image references use digests (@sha256:...) not mutable tags
• Base images are regularly updated to include security patches

Build Security

• Dockerfiles use a non-root USER directive
• .dockerignore excludes .env, .git, node_modules, and other sensitive files
• Build arguments do not contain secrets (use BuildKit secret mounts instead)
• Layer caching does not leak sensitive data between stages
• HEALTHCHECK is defined for orchestrator integration

Runtime Security

• All containers run as non-root (runAsNonRoot: true)
• All capabilities are dropped (capabilities.drop: [ALL])
• Root filesystem is read-only (readOnlyRootFilesystem: true)
• Seccomp profile is set to RuntimeDefault or a custom profile
• Resource requests and limits are defined for all containers
• Service account tokens are not auto-mounted unless required

Kubernetes Security

• PodSecurityStandards are enforced at restricted or baseline level
• Default-deny NetworkPolicies are applied in every namespace
• RBAC follows least privilege -- no broad ClusterRole bindings
• Admission controllers validate configurations before deployment
• Secrets are managed externally (GCP Secret Manager, Vault, ExternalSecrets)
• Pod disruption budgets ensure availability during security updates
• Runtime monitoring (Falco or equivalent) is deployed

Related Skills

• @cis-benchmarks -- CIS Docker and Kubernetes Benchmark automated scanning
• @cloud-security-patterns -- cloud-native security architectures for GCP, AWS, Azure
• @owasp-top10 -- application-layer security for containerized web applications

Additional Resources

• NIST SP 800-190 -- Application Container Security Guide
• Kubernetes Pod Security Standards -- official PSS documentation
• Docker Security Best Practices -- official Docker guidance
• Kubernetes Network Policies -- NetworkPolicy reference
• Falco Runtime Security -- open-source container runtime threat detection
• cosign -- container image signing and verification
• Trivy -- comprehensive container vulnerability scanner
• GKE Security Overview -- GKE-specific security features

<!-- Source: .faos/custom/skills/security/container-security-guide/SKILL.md -->