Docker Hosts
Install the Vigilhold agent on a Docker host with one docker run command.
Quick start
In Vigilhold, click Add host, generate a command and choose the Docker tab. Run it on the Docker host:
docker run --rm --privileged --pid=host debian:stable-slim \
nsenter -t 1 -m -u -i -n -- \
sh -c "curl -fsSL https://__DASHBOARD_HOST__/install-agent.sh | bash -s -- --token '<token>' --dashboard 'wss://__DASHBOARD_HOST__/agent-ws'"
The container exits when the install finishes, in under a minute. The server appears in Vigilhold as soon as the agent connects.
How it works
The agent has to run on the host, not inside a container: from inside one it would only see that container's own processes. The command starts a throwaway container that enters the host (--pid=host lets nsenter reach the host's first process) and runs the normal Linux installer there. The agent ends up as the sentinel-agent service on the host (systemd, or OpenRC on Alpine), exactly as with the curl install.
Requirements:
- Requirement — Why
- --privileged and --pid=host — To enter the host's namespaces
- systemd or OpenRC (Alpine) on the host — The agent runs as a service
- curl on the host — The installer is downloaded on the host
- Ubuntu 20.04+, Debian 11+, RHEL 8+ or compatible (Rocky, AlmaLinux, CentOS Stream), Fedora, Amazon Linux 2023, Arch or Alpine 3.19+ host, on x86_64 or ARM64 — Supported distributions
Docker Desktop on macOS or Windows is not supported: its "host" is Docker's own virtual machine, and the installer stops before using your token.
Container inventory
When the agent finds the Docker socket on the host, it keeps a list of the containers running there. Each container appears in the server's Containers tab with:
- CPU %, memory usage and limit
- Network bytes received and sent
- Image name
- Port bindings
- Container labels
Containers that exit are marked as exited.
Vigilhold's root helper reads the list from Docker every 30 seconds, read-only, so the agent needs no Docker access of its own (Docker access would be equivalent to root).
Security: container escape detection
The agent watches for a process breaking out of a container onto the host, or a process other than Docker's own opening the Docker socket, and raises an alert straight away with the process, its user and its command line.
Tips
- Each install command uses a one-time token, so generate a new command for each Docker host.
- Updates, restarts and logs work as on any Linux server: systemctl status sentinel-agent and journalctl -u sentinel-agent (on Alpine: rc-service sentinel-agent status and tail -f /var/log/sentinel-agent/agent.log).
- Re-running the Docker command on a host that already has the agent can raise a container-escape alert: entering the host from a container is what an escape looks like. That is expected.