Set up a Docker Proxy

Scanopy daemons can discover Docker containers by connecting to the Docker API. By default, daemons connect directly to the local Docker socket (/var/run/docker.sock). A Docker socket proxy provides an additional security layer by restricting which Docker API operations are allowed — and enables discovering containers on remote hosts.

For background on how credentials work — types, scope models, resolution order, and auto-assignment — see Credentials.

Docker Discovery Modes

There are three ways to connect a daemon to the Docker API, depending on where Docker runs and your security requirements:

Direct Socket Access (Default)

The daemon connects directly to /var/run/docker.sock on its own host. No proxy or credential needed.

Use when: The daemon runs on the same host as Docker and you trust it with full Docker API access. This is the simplest setup.

Enable this during daemon setup by selecting Local Socket in the Docker mode selector, or toggle Scan local Docker socket in the discovery settings.

Local Proxy

The daemon connects to a Docker socket proxy running on the same host. The proxy restricts which Docker API operations are allowed.

Use when: You want to limit what the daemon can do with the Docker API — for example, to satisfy compliance requirements or reduce the blast radius of a compromised daemon.

Remote Proxy

The daemon connects to a Docker socket proxy on a different host, enabling container discovery on remote machines.

Use when: You want to discover containers on a host where the daemon isn't running. Deploy a proxy on the remote host, then create a Docker Proxy credential pointing to it.

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.

Creating a Docker Proxy Credential

Once your proxy is running, create a credential in Scanopy so the daemon knows how to connect.

1. Go to Assets > Credentials
2. Click Create Credential
3. Select Docker Proxy as the type
4. Configure the connection:
   • Port — the proxy's listening port (default: 2376)
   • Path — optional URL path prefix (leave empty for most proxies)
   • SSL Certificate, SSL Key, SSL Chain — for HTTPS proxies, provide the client certificate, private key, and CA chain. These can be entered inline or as file paths readable by the daemon.
5. Save the credential

Assigning to a host

Docker Proxy is a PerHost credential — it must be assigned to the specific host where you want Docker discovery.

For new hosts (not yet discovered): Add the credential during daemon setup or from the discovery Credentials tab, along with the target IP of the Docker host. The credential will be auto-assigned after the first scan discovers the host.

For existing hosts: Open the host edit modal, go to the Credentials tab, and add the Docker Proxy credential. You can optionally scope it to a specific network interface.

Remote Docker Scanning

Docker Proxy credentials can point to any reachable Docker API endpoint — the proxy doesn't need to be on the daemon's host. This enables container discovery on remote machines:

1. Deploy a Docker socket proxy on the remote host
2. Create a Docker Proxy credential pointing to the remote proxy's address and port
3. Assign the credential to the remote host in Scanopy

The daemon will connect to the remote proxy during discovery and report discovered containers as services on that host.

Required Docker API Permissions

Scanopy daemon uses the following Docker API endpoints:

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

1. Verify proxy is running: docker ps | grep proxy
2. Check proxy is listening: curl http://docker-proxy:2375/version
3. 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

1. Verify certificate paths are correct and mounted
2. Check certificate is valid: openssl x509 -in /certs/client-cert.pem -text -noout
3. Ensure CA chain is included if using self-signed certs
4. Check that cert and key files aren't swapped — see Credential troubleshooting for diagnosing file read and PEM errors in daemon logs