Set up Docker discovery

Scanopy daemons discover Docker containers by connecting to the Docker API. On the daemon's own host that happens automatically; reaching a restricted API, or one on another machine, needs a proxy.

What gets discovered

• Running containers, with their names and metadata
• Container networks and published port bindings, including automatically created bridge subnets
• Containerized services, identified from the API rather than from a port scan — so containers that publish nothing to the host are still detected

Containers appear as Docker Container services on their host, and the container-to-host relationship shows up in the Workloads perspective.

Discovery is local to one host: the daemon sees the containers on its own machine, or on the single host a proxy credential points at. See Docker host matching for what that means for deduplication.

Prerequisites

• Docker running on the host whose containers you want to discover
• For direct socket access, the daemon can read /var/run/docker.sock on its own host
• For proxied access, a socket proxy deployed and reachable from the daemon — see Docker Proxy below for supported proxies and the operations they must allow

Choosing a credential type

Docker Proxy

A socket proxy sits in front of the Docker socket and allows only the API operations you permit. One credential type covers both reasons to use one — restricting local access, and reaching Docker on another machine — since only the address changes.

To discover containers on a machine with no daemon: deploy a proxy there, create a Docker Proxy credential with its port, and assign it to that host. Containers are then reported as services on the remote host.

The TLS fields apply to HTTPS proxies only. Each can be entered inline or as a file path readable by the daemon.

Supported proxies

Scanopy has been tested with these 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'

wollomatic's proxy uses allowlists rather than per-capability flags. Refer to their documentation for configuring the endpoints below.

Required API operations

Whatever proxy you use, allow these endpoints:

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

Docker Socket

The daemon connects directly to /var/run/docker.sock on its own host. This needs no credential and no toggle — the daemon uses the socket whenever it's accessible.

Create a Docker Socket credential only to point the daemon at a socket somewhere other than the default path.

Because the socket is reachable only over the daemon's own loopback, this credential type can be assigned to a daemon host and nowhere else.

Verifying it works

1. Go to Discover > Scan > Scheduled and run a discovery, or wait for the next scheduled run
2. Open the host running Docker and go to its Services tab
3. Look for Docker Container services, each with its published ports
4. Open the Workloads perspective and confirm the containers appear nested under their host

Troubleshooting

"Connection refused" to proxy

1. Verify the proxy is running: docker ps | grep proxy
2. Check the proxy is listening: curl http://docker-proxy:2375/version
3. Ensure the daemon can reach it — same Docker network, or an exposed port

"Permission denied" from proxy

The proxy is blocking a required endpoint. For Tecnativa, confirm CONTAINERS=1, NETWORKS=1, EXEC=1, and POST=1 (the last is required for exec).

SSL certificate errors

1. Verify certificate paths are correct and mounted
2. Check the certificate is valid: openssl x509 -in /certs/client-cert.pem -text -noout
3. Include the CA chain if using self-signed certs
4. Check that the cert and key aren't swapped

For diagnosing credential loading and file read or PEM errors from daemon logs, see Credential troubleshooting.