Docker Socket Proxy

Configuring Docker socket proxies for secure container discovery.

Scanopy daemons can discover Docker containers by connecting to the Docker API. By default, daemons connect directly to /var/run/docker.sock. A Docker socket proxy provides an additional security layer by restricting which Docker API operations are allowed.

When to Use a Docker Proxy

Direct Socket Access (Default)

Mount the Docker socket directly:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Use when:

Daemon runs on same host as Docker
You trust the daemon with full Docker API access
Simplest setup

Route requests through a proxy:

environment:
  - SCANOPY_DOCKER_PROXY=http://docker-proxy:2375

Use when:

You want to restrict Docker API operations
Daemon runs in a more restricted security context
Compliance requires limiting Docker access

Supported Proxies

Scanopy has been tested with these Docker socket proxies:

Tecnativa docker-socket-proxy

services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1 # Required: list and inspect containers
      - NETWORKS=1 # Required: list networks for subnet discovery
      - EXEC=1 # Required: exec into containers for endpoint probing
      - POST=1 # Required: create exec instances
      - INFO=1 # Optional: system info
      - BUILD=0
      - COMMIT=0
      - CONFIGS=0
      - DISTRIBUTION=0
      - GRPC=0
      - IMAGES=0
      - NODES=0
      - PLUGINS=0
      - SECRETS=0
      - SERVICES=0
      - SESSION=0
      - SWARM=0
      - SYSTEM=0
      - TASKS=0
      - VOLUMES=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - '2375:2375'

wollomatic socket-proxy

services:
  docker-proxy:
    image: wollomatic/socket-proxy
    environment:
      - ALLOW_RESTARTS=0
      - LOG_LEVEL=info
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - '2375:2375'

Note: wollomatic's proxy uses allowlists. Refer to their documentation for configuring the required endpoints.

Configuration

HTTP Proxy (Non-SSL)

# Daemon configuration
environment:
  - SCANOPY_DOCKER_PROXY=http://docker-proxy:2375

Or via CLI:

scanopy-daemon --docker-proxy http://docker-proxy:2375 ...

HTTPS Proxy (SSL)

For SSL-enabled proxies, provide certificate paths:

environment:
  - SCANOPY_DOCKER_PROXY=https://docker-proxy:2376
  - SCANOPY_DOCKER_PROXY_SSL_CERT=/certs/client-cert.pem
  - SCANOPY_DOCKER_PROXY_SSL_KEY=/certs/client-key.pem
  - SCANOPY_DOCKER_PROXY_SSL_CHAIN=/certs/ca.pem
volumes:
  - ./certs:/certs:ro

Or via CLI:

scanopy-daemon \
  --docker-proxy https://docker-proxy:2376 \
  --docker-proxy-ssl-cert /certs/client-cert.pem \
  --docker-proxy-ssl-key /certs/client-key.pem \
  --docker-proxy-ssl-chain /certs/ca.pem \
  ...

Required Docker API Permissions

Scanopy daemon uses the following Docker API endpoints:

Endpoint	Method	Purpose
`/containers/json`	GET	List running containers
`/containers/{id}/json`	GET	Get container details (ports, networks, config)
`/networks`	GET	List Docker networks for subnet discovery
`/exec/{id}/json`	GET	Check exec instance status
`/containers/{id}/exec`	POST	Create exec instance for endpoint probing
`/exec/{id}/start`	POST	Start exec to probe HTTP endpoints inside containers

Why exec? Scanopy uses exec to probe HTTP endpoints from inside containers that don't expose ports to the host. Without exec access, containers are still discovered but service detection may be less accurate.

Troubleshooting

"Connection refused" to proxy

Verify proxy is running: docker ps | grep proxy
Check proxy is listening: curl http://docker-proxy:2375/version
Ensure daemon can reach proxy (same Docker network or exposed port)

"Permission denied" from proxy

Proxy is blocking required endpoints. For Tecnativa, ensure:

CONTAINERS=1
NETWORKS=1
EXEC=1 (for endpoint probing)
POST=1 (required for exec)

SSL certificate errors

Verify certificate paths are correct and mounted
Check certificate is valid: openssl x509 -in /certs/client-cert.pem -text -noout
Ensure CA chain is included if using self-signed certs

Docker Socket Proxy

On this page