This document describes the security protections implemented in the proxy and recommended best practices.

The proxy implements several security layers enabled by default to prevent privilege escalation.

Automatically blocks mounting of the Docker socket to prevent an unsecured container from taking full control of Docker.

Paths blocked by default:

• /var/run/docker.sock
• /run/docker.sock

Example of blocked attempt:

docker run -v /var/run/docker.sock:/var/run/docker.sock alpine
# ❌ Denied: "Volume creation denied by advanced filter"
# Reason: "host path is denied: /var/run/docker.sock"

The dockershield container protects itself against any manipulation via the API it exposes.

Automatic protection:

• ❌ Cannot stop the proxy container
• ❌ Cannot restart the proxy container
• ❌ Cannot delete the proxy container
• ❌ Cannot modify the proxy container
• ❌ Cannot execute commands in the proxy

Example of blocked attempt:

# Attempt to stop the proxy via the API it exposes
docker stop dockershield
# ❌ Denied: "Container operation denied by advanced filter"
# Reason: "container name is denied: dockershield"

If the proxy uses a dedicated network, it is also protected.

Example:

docker network rm dockershield
# ❌ Denied: "Network operation denied by advanced filter"
# Reason: "network name is denied: dockershield"

# Name of container to protect (default: dockershield)
export PROXY_CONTAINER_NAME="dockershield"

# Name of network to protect (optional)
export PROXY_NETWORK_NAME="dockershield-network"

services:
  dockershield:
    container_name: dockershield
    environment:
      - PROXY_CONTAINER_NAME=dockershield
      - PROXY_NETWORK_NAME=dockershield
    networks:
      - dockershield

networks:
  dockershield:
    name: dockershield

export DKRPRX__DISABLE_DEFAULTS="true"

Consequences:

• Docker socket can be mounted freely
• Proxy container can be manipulated
• Proxy network can be removed
• High risk of privilege escalation

To allow only the Docker socket:

# Via env var (overrides defaults for volumes only)
export DKRPRX__VOLUMES__ALLOWED_PATHS="^/var/run/docker\\.sock$"

Or via JSON:

{
  "volumes": {
    "allowed_paths": ["^/var/run/docker\\.sock$"]
  }
}

Attack:

# Attacker tries to mount Docker socket
docker run -v /var/run/docker.sock:/var/run/docker.sock \
  alpine sh -c "docker run --privileged --pid=host alpine nsenter -t 1 -m -u -i sh"

Protection:

• ✅ Socket mounting blocked by default
• ✅ Even if VOLUMES=1, path filter blocks it

Attack:

# Attacker tries to stop proxy to bypass restrictions
docker stop dockershield
docker run -v /var/run/docker.sock:/var/run/docker.sock alpine

Protection:

• ✅ Proxy container manipulation blocked
• ✅ Proxy API refuses operations on itself

Attack:

# Attacker tries to get full network access
docker run --network=host alpine

Protection (optional):

export DKRPRX__CONTAINERS__DENY_HOST_NETWORK="true"

Attack:

# Attacker tries to launch privileged container
docker run --privileged alpine

Protection (optional):

export DKRPRX__CONTAINERS__DENY_PRIVILEGED="true"

• Docker socket read-only: -v /var/run/docker.sock:/var/run/docker.sock:ro
• Default protections enabled: Do not set DKRPRX__DISABLE_DEFAULTS
• Container name configured: PROXY_CONTAINER_NAME=dockershield
• Dedicated network: PROXY_NETWORK_NAME=dockershield
• Read-only mode: POST=0, DELETE=0, PUT=0
• Minimal endpoints: Only enable necessary endpoints
• No public exposure: NEVER expose on the Internet
• Advanced filters: Configure filters adapted to your use case

# Forbid privileged containers
export DKRPRX__CONTAINERS__DENY_PRIVILEGED="true"

# Forbid host network
export DKRPRX__CONTAINERS__DENY_HOST_NETWORK="true"

# Forbid mounting sensitive directories
export DKRPRX__VOLUMES__DENIED_PATHS="^/etc/.*,^/root/.*,^/sys/.*,^/proc/.*"

# Allow only images from private registry
export DKRPRX__CONTAINERS__ALLOWED_IMAGES="^registry.private.com/.*"

# Forbid :latest tag
export DKRPRX__IMAGES__DENIED_TAGS="^latest$"

The proxy logs all blocked attempts:

{
  "level": "warn",
  "msg": "Volume creation denied",
  "reason": "host path is denied: /var/run/docker.sock",
  "path": "/v1.43/volumes/create",
  "method": "POST"
}

Monitor these events in logs:

• "denied" - Blocked attempts
• "forbidden" - Refused access
• "privileged" - Privileged container attempts
• "docker.sock" - Socket mounting attempts

• ADVANCED_FILTERS.md - Complete filter documentation
• ENV_FILTERS.md - Configuration via environment variables
• Docker Security Best Practices
• CIS Docker Benchmark

If you discover a security vulnerability, please report it responsibly via GitHub Issues marking it as "security".

Do NOT publicly disclose critical vulnerabilities before a fix is available.