🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Docker Security Guide

This skill provides comprehensive security guidelines for Docker across all platforms, covering threats, mitigations, and compliance requirements.

Security Principles

Defense in Depth

Apply security at multiple layers:

1. Image security: Minimal, scanned, signed images
2. Build security: Secure build process, no secrets in layers
3. Runtime security: Restricted capabilities, resource limits
4. Network security: Isolation, least privilege
5. Host security: Hardened host OS, updated Docker daemon
6. Orchestration security: Secure configuration, RBAC
7. Monitoring: Detection, logging, alerting

Least Privilege

Grant only the minimum permissions necessary:

• Non-root users
• Dropped capabilities
• Read-only filesystems
• Minimal network exposure
• Restricted syscalls (seccomp)
• Limited resources

Image Security

Base Image Selection

Threat: Vulnerable or malicious base images

Mitigation:

# Use official images only
FROM node:20.11.0-alpine3.19  # Official, specific version

# NOT
FROM randomuser/node  # Unverified source
FROM node:latest      # Unpredictable, can break

Verification:

# Verify image source
docker image inspect node:20-alpine | grep -A 5 "Author"

# Enable Docker Content Trust (image signing)
export DOCKER_CONTENT_TRUST=1
docker pull node:20-alpine

Minimal Images

Threat: Larger attack surface, more vulnerabilities

Mitigation:

# Prefer minimal distributions
FROM alpine:3.19           # ~7MB
FROM gcr.io/distroless/static  # ~2MB
FROM scratch               # 0MB (for static binaries)

# vs
FROM ubuntu:22.04          # ~77MB with more packages

Benefits:

• Fewer packages = fewer vulnerabilities
• Smaller attack surface
• Faster downloads and starts
• Less disk space

Micro-Distros for Security-Critical Applications (2025)

Wolfi/Chainguard Images:

• Zero-CVE goal, SBOM included by default
• Nightly security patches, signed with provenance
• Available for: Node, Python, Go, Java, .NET, etc.

Usage:

# Development stage (includes build tools)
FROM cgr.dev/chainguard/node:latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Production stage (minimal, zero-CVE goal)
FROM cgr.dev/chainguard/node:latest
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER node
ENTRYPOINT ["node", "server.js"]

When to use: Security-critical apps, compliance requirements (SOC2, HIPAA, PCI-DSS), zero-trust environments, supply chain security emphasis.

See docker-best-practices skill for full image comparison table.

Vulnerability Scanning

Tools:

• Docker Scout (built-in)
• Trivy
• Grype
• Snyk
• Clair

Process:

# Scan with Docker Scout
docker scout cves IMAGE_NAME
docker scout recommendations IMAGE_NAME

# Scan with Trivy
trivy image IMAGE_NAME
trivy image --severity HIGH,CRITICAL IMAGE_NAME

# Scan Dockerfile
trivy config Dockerfile

# Scan for secrets
trivy fs --scanners secret .

CI/CD Integration:

# GitHub Actions example
- name: Scan image
  run: |
    docker scout cves my-image:${{ github.sha }}
    trivy image --exit-code 1 --severity CRITICAL my-image:${{ github.sha }}

Multi-Stage Builds for Security

Threat: Build tools and secrets in final image

Mitigation:

# Build stage with build tools
FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN go build -o app

# Final stage - minimal, no build tools
FROM gcr.io/distroless/base-debian11
COPY --from=builder /app/app /
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Benefits:

• No compiler/build tools in production image
• Secrets used in build don't persist
• Smaller, more secure final image

Build-Time Security

Secrets Management

NEVER:

# BAD - Secret in layer history
ENV API_KEY=abc123
RUN git clone https://user:[email protected]/repo.git
COPY .env /app/.env

DO:

# Use BuildKit secrets
# syntax=docker/dockerfile:1

FROM alpine
RUN --mount=type=secret,id=github_token \
    git clone https://$(cat /run/secrets/github_token)@github.com/repo.git

# Build with secret (not in image)
docker build --secret id=github_token,src=./token.txt .

BuildKit Frontend Security (2025)

Threat: Malicious or compromised BuildKit frontends can execute arbitrary code during build

🚨 2025 CRITICAL WARNING: BuildKit supports custom frontends (parsers) via # syntax= directive. Untrusted frontends have FULL BUILD-TIME code execution and can:

• Steal secrets from build context
• Modify build outputs
• Exfiltrate data
• Compromise the build environment

Risk Example:

# 🔴 DANGER - Untrusted frontend (code execution risk!)
# syntax=docker/dockerfile:1@sha256:abc123...untrusted

FROM alpine
RUN echo "This frontend could do anything during build"

Mitigation:

1. Only use official Docker frontends:

# ✅ Safe - Official Docker frontend
# syntax=docker/dockerfile:1

# ✅ Safe - Specific version
# syntax=docker/dockerfile:1.5

# ✅ Safe - Pinned with digest (verify from docker.com)
# syntax=docker/dockerfile:1@sha256:ac85f380a63b13dfcefa89046420e1781752bab202122f8f50032edf31be0021

2. Verify frontend sources:

• Use ONLY docker/dockerfile:* frontends
• Pin to specific versions with SHA256 digest
• Verify digests from official Docker documentation
• Never use third-party frontends without thorough vetting

3. Audit all Dockerfiles for unsafe syntax directives:

# Check all Dockerfiles for potentially malicious syntax directives
grep -r "^# syntax=" . --include="Dockerfile*"

# Verify all frontends are official Docker images
grep -r "^# syntax=" . --include="Dockerfile*" | grep -v "docker/dockerfile"

4. BuildKit security configuration (defense in depth):

# Restrict frontend sources in BuildKit config
# /etc/buildkit/buildkitd.toml
[frontend."dockerfile.v0"]
  # Only allow official Docker frontends
  allowedImages = ["docker.io/docker/dockerfile:*"]

Supply Chain Protection:

• Treat custom frontends as HIGH RISK code execution vectors
• Review ALL # syntax= directives in Dockerfiles before builds
• Use content trust for frontend images
• Monitor for frontend vulnerabilities
• Include frontend verification in CI/CD security gates

SBOM (Software Bill of Materials) Generation (2025)

Critical 2025 Requirement: Document origin and history of all components for supply chain transparency and compliance.

Why SBOM is Mandatory:

• Supply chain security visibility
• Vulnerability tracking and response
• Compliance requirements (Executive Order 14028, etc.)
• License compliance
• Incident response readiness

Generate SBOM with Docker Scout:

# Generate SBOM for image
docker scout sbom IMAGE_NAME

# Export SBOM in different formats
docker scout sbom --format spdx IMAGE_NAME > sbom.spdx.json
docker scout sbom --format cyclonedx IMAGE_NAME > sbom.cyclonedx.json

# Include SBOM attestation during build
# ⚠️ WARNING: BuildKit attestations are NOT cryptographically signed!
docker buildx build \
  --sbom=true \
  --provenance=true \
  --tag my-image:latest \
  .

# View SBOM attestations (unsigned metadata only)
docker buildx imagetools inspect my-image:latest --format "{{ json .SBOM }}"

🚨 CRITICAL SECURITY LIMITATION: BuildKit attestations (--sbom=true, --provenance=true) are NOT cryptographically signed. This means:

• Anyone with push access can create tampered attestations
• SBOMs can be incomplete or falsified
• Provenance data cannot be trusted without external verification
• For production: Use external signing tools (cosign, Notary) and Syft for SBOM generation

Generate SBOM with Syft:

# Install Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh

# Generate SBOM from image
syft my-image:latest

# Generate in specific format
syft my-image:latest -o spdx-json > sbom.spdx.json
syft my-image:latest -o cyclonedx-json > sbom.cyclonedx.json

# Generate from Dockerfile
syft dir:. -o spdx-json > sbom.spdx.json

SBOM in CI/CD Pipeline:

how to use docker-security-guide
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use docker-security-guide on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add docker-security-guide
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill docker-security-guidecopy
The skills CLI fetches docker-security-guide from GitHub repository josiahsiegel/claude-plugin-marketplace and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/docker-security-guide
Reload or restart Cursor to activate docker-security-guide. Access the skill through slash commands (e.g., /docker-security-guide) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?