| name | marsai:dev-docker-security |
| description | Creates or audits Dockerfiles and Docker image configurations to achieve
Docker Hub Health Score grade A. Enforces all evaluable security policies
and supply chain best practices.
|
| trigger | - Creating a new Dockerfile
- Auditing an existing Dockerfile for security
- Preparing images for Docker Hub publication
- Docker Hub health score is below grade A
|
| skip_when | - Project has no Dockerfile and none is being created
- Changes are application-code only with no Docker modifications
- Using pre-built images without custom Dockerfile
|
| related | {"complementary":["marsai:dev-devops","marsai:dev-sre"]} |
| input_schema | {"required":[{"name":"dockerfile_path","type":"string","description":"Path to the Dockerfile to create or audit"}],"optional":[{"name":"base_image","type":"string","description":"Preferred base image (e.g., gcr.io/distroless/static-debian12)"},{"name":"language","type":"string","enum":["typescript","python","rust","java"],"description":"Programming language of the application"},{"name":"service_type","type":"string","enum":["api","worker","batch","cli"],"description":"Type of service"},{"name":"mode","type":"string","enum":["create","audit"],"default":"audit","description":"Create a new Dockerfile or audit an existing one"}]} |
| output_schema | {"format":"markdown","required_sections":[{"name":"Health Score Compliance","pattern":"^## Health Score Compliance","required":true},{"name":"Policy Results","pattern":"^### Policy Results","required":true},{"name":"Actions Taken","pattern":"^## Actions Taken","required":true}],"metrics":[{"name":"result","type":"enum","values":["PASS","FAIL"]},{"name":"policies_met","type":"integer"},{"name":"policies_total","type":"integer"}]} |
Docker Security — Docker Hub Health Score Grade A
Overview
General Dockerfile patterns are documented in dev-team/docs/standards/devops.md#containers. This skill focuses specifically on Docker Hub Health Score compliance.
This skill creates or audits Dockerfiles and image configurations to achieve Docker Hub Health Score grade A.
Docker Hub Health Score Policies
| # | Policy | Weight | How to Comply |
|---|
| 1 | Default non-root user | Required | Dockerfile MUST have a USER directive with a non-root user |
| 2 | No fixable critical/high CVEs | Required | Zero critical/high vulnerabilities with available fixes |
| 3 | No high-profile vulnerabilities | Required | Zero CVEs in the CISA KEV catalog |
| 4 | No AGPL v3 licenses | Required | No packages with AGPL-3.0 licenses |
| 5 | Supply chain attestations | Required | SBOM + provenance attached to pushed images (pipeline config) |
| 6 | No outdated base images | Optional | Only evaluated for Docker Hub hosted base images |
| 7 | No unapproved base images | Optional | Only evaluated for Docker Hub hosted base images |
Policies 6 and 7 are optional — not evaluated when using non-Docker Hub base images (e.g., gcr.io/distroless). Do not treat them as blockers.
Pipeline Enforcement
These policies are automatically enforced on every PR that changes application components. The PR Security Scan workflow blocks merge if any required policy fails.
What happens on every PR
- Docker image is built from the Dockerfile in the PR
- Trivy scans the image for vulnerabilities and AGPL-3.0 licenses
- Dockerfile analysis verifies the
USER directive
- CISA KEV cross-reference checks found CVEs against the Known Exploited Vulnerabilities catalog
- Health Score Compliance table is posted as a PR comment
Merge gate
Any policy failure blocks the PR — missing USER directive, a fixable critical/high CVE, a KEV vulnerability, or an AGPL-3.0 package.
Policy 5 (SBOM + provenance) is evaluated only on release builds via pipeline config:
sbom: generator=docker/scout-sbom-indexer:latest
provenance: mode=max
Step 1: Analyze Current State
1. Read the Dockerfile (if mode=audit)
2. Identify: base image, build stages, USER directive, package installation
3. If mode=create, gather requirements from inputs
Step 2: Apply Security Policies
Policy 1 — Default Non-Root User
Every Dockerfile MUST set a non-root user after all RUN/COPY steps:
USER nonroot:nonroot # distroless (pre-existing user)
# Alpine: create user first
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
# Debian/Ubuntu: create user first
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser
USER root does NOT satisfy this policy. The user must be non-root and must exist in the image.
Policies 2 & 3 — No Fixable CVEs / No KEV Vulnerabilities
Both policies share the same remediation — minimize the attack surface:
- Prefer distroless — ~0 CVEs (no shell, no package manager)
- Alpine over Debian/Ubuntu — fewer packages = fewer CVEs
- Multi-stage builds — build tools stay in builder, only runtime in final
- Pin versions — avoid pulling newly vulnerable packages
- Update base images regularly
FROM gcr.io/distroless/base-debian12 # Dynamically linked
FROM node:22-alpine # Node.js
Policy 4 — No AGPL v3 Licenses
Audit dependencies before adding them. Use trivy fs --scanners license to check. If AGPL-3.0 is found, replace the dependency. This applies to ALL packages in the final image, including OS packages.
Policy 5 — Supply Chain Attestations
Not a Dockerfile concern — configured in the build pipeline (sbom: + provenance: mode=max). When auditing, verify the CI/CD pipeline includes both parameters.
Step 3: Dockerfile Templates
Node.js Service
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
FROM node:22-alpine
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
USER appuser
CMD ["node", "dist/index.js"]
Python Service
FROM python:3.13-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
COPY . .
FROM python:3.13-slim
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
WORKDIR /app
COPY --from=builder /install /usr/local
COPY --from=builder /app .
EXPOSE 8000
USER appuser
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Step 4: Audit Checklist
CRITICAL (blocks grade A):
[ ] USER directive exists with non-root user
[ ] Multi-stage build (build tools not in final image)
[ ] Minimal base image (distroless/alpine preferred)
[ ] No secrets or credentials in image layers
HIGH (impacts CVE count):
[ ] Base image is up to date
[ ] Package versions are pinned
[ ] No development dependencies in final image
MEDIUM (best practices):
[ ] .dockerignore excludes .git, node_modules, etc.
[ ] COPY used instead of ADD
[ ] Build cache leveraged (COPY deps before source)
SUPPLY CHAIN (pipeline):
[ ] sbom: parameter in build-push-action
[ ] provenance: mode=max in build-push-action
Step 5: Generate Report
## Health Score Compliance
**Target:** Grade A
**Result:** [PASS|FAIL]
### Policy Results
| Policy | Status | Details |
|--------|--------|---------|
| Default non-root user | [PASS/FAIL] | USER [username] at line [N] |
| No fixable critical/high CVEs | [PASS/RISK] | Base: [image], [N] packages in final |
| No high-profile vulnerabilities | [PASS/RISK] | Base image [up to date/outdated] |
| No AGPL v3 licenses | [PASS/RISK] | [N] dependencies audited |
| Supply chain attestations | [PASS/MISSING] | sbom: [yes/no], provenance: [yes/no] |
## Actions Taken
| File | Action | Changes |
|------|--------|---------|
| Dockerfile | [CREATED/UPDATED] | [summary] |
| .dockerignore | [CREATED/UPDATED/UNCHANGED] | [summary] |
Severity Calibration
| Severity | Criteria | Examples |
|---|
| CRITICAL | Blocks grade A | Missing USER, running as root, secrets in layers |
| HIGH | Causes CVE failures | Full debian base, unpinned versions, outdated base |
| MEDIUM | Reduces security posture | No .dockerignore, ADD instead of COPY, no multi-stage |
| LOW | Best practice deviation | Missing labels, suboptimal layer ordering |
