Set up Docker discovery

Scanopy daemons discover Docker containers by connecting to the Docker API. On the daemon's own host, a Docker Socket credential connects it to the local socket. Reaching a restricted API, or one on another machine, needs a Docker Proxy credential.

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 on macvlan or ipvlan networks, each as its own host
• The container serving the Docker API on a proxy credential's port, as a Docker API Proxy service under Docker

Bridge-networked containers appear as Docker Container services on their host. A container on a macvlan or ipvlan network has its own address on the LAN, so it becomes its own host, tagged macvlan or ipvlan and linked to the Docker service on the Docker host. The container-to-host relationship shows up in the Workloads perspective.

With a proxy credential, the container that publishes the credential's port is the proxy in front of Docker. It is recorded as a Docker API Proxy service under the Docker service and holds that port, whatever port you set. A proxy running with host networking is identified only when its image declares the port as exposed.

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, or the \\.\pipe\docker_engine named pipe on a Windows 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 takes the PEM text with Enter value, or a path with File on daemon host. A path must be absolute for the credential's Daemon OS, and ~ is not expanded.

Supported proxies

Configuration for two common 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

A Docker Socket credential connects the daemon directly to the Docker API on its own host. The default Docker Socket credential is added on the Integration Setup step when you create a daemon; remove it there to skip the local socket. You can also add it to a scan in the Discovery modal. The daemon doesn't read the local socket without one.

With Socket Path left blank, the daemon uses:

• Linux, macOS, BSD: the socket DOCKER_HOST names, or /var/run/docker.sock
• Windows: the \\.\pipe\docker_engine named pipe

Enter a Socket Path only when the socket or pipe is somewhere else. It replaces the defaults above.

Socket Path takes the form the credential's Daemon OS uses. The form shows Daemon OS once Socket Path is set, and a daemon on another OS skips the credential.

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 > Scans 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" on the Docker socket (Linux)

The user the daemon runs as can't read the socket. Add it to the docker group, then restart the daemon:

sudo usermod -aG docker <daemon user>

"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.