InfraFenceInfraFence

Live Security Operations

Get Started

Docker

Run the InfraFence agent as a Docker container that protects its host - the image, the required privileges and mounts, and every environment variable.

Last updated:

The agent also runs as a container that protects its host. The image is multi-architecture (amd64 and arm64), published with every release and signed with cosign.

  • ghcr.io/infrafence/infrafence-agent:latest, or a version tag such as ghcr.io/infrafence/infrafence-agent:<version>
  • the same image on Docker Hub as infrafence/infrafence-agent

docker run

bash
docker run -d --name infrafence-agent --restart unless-stopped \
  --privileged --network host --pid host \
  -v /var/log:/var/log:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v infrafence-config:/etc/infrafence \
  -e INFRAFENCE_TOKEN=<YOUR_TOKEN> \
  ghcr.io/infrafence/infrafence-agent:latest

Why each part is needed:

  • --privileged, --network host: the agent manages the host firewall (iptables and ipset) and reads the host's network state.
  • --pid host: it sees the host's processes, for malware process detection and DNS attribution.
  • /var/log read-only: the logs it analyzes.
  • the Docker socket read-only: to find the containers whose ports and logs to protect.
  • /etc/infrafence in a named volume: the registration survives container upgrades. The token is used once; later starts reuse the stored registration.

Environment variables

Variable Default Effect
INFRAFENCE_TOKEN The install token, for the first registration.
INFRAFENCE_TOKEN_FILE A file holding the token, for Docker secrets.
INFRAFENCE_AGENT_NAME the short hostname The name in the dashboard.
INFRAFENCE_SERVER_URL https://infrafence.com The dashboard to register with.

Any of the agent's own variables (see Configuration), such as WEB_LOG_PATH, can be passed with -e too.

Without a token, a token file or a cluster key on the first start, the container stops with [infrafence] ERROR: No credentials provided for registration.

Docker Compose

Each host needs its own install token, as with any other server.

yaml
services:
  infrafence-agent:
    image: ghcr.io/infrafence/infrafence-agent:latest
    container_name: infrafence-agent
    restart: unless-stopped
    privileged: true
    network_mode: host
    pid: host
    environment:
      - INFRAFENCE_TOKEN=${INFRAFENCE_TOKEN}
    volumes:
      - /var/log:/var/log:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - infrafence-config:/etc/infrafence

volumes:
  infrafence-config:
bash
INFRAFENCE_TOKEN=<YOUR_TOKEN> docker compose up -d

Containers on the host

On a host where Docker runs, the agent jumps to its firewall chain from DOCKER-USER too, so bans also cover the ports your containers publish. An agent installed with install.sh on the host also finds the access logs of web containers (nginx, Apache and OpenResty images; for Traefik and Caddy, see below) and reads these labels on your containers:

Label Effect
infrafence.monitor true to always watch the container's logs, false to skip it.
infrafence.log-path Host paths of its access logs, comma-separated.
infrafence.domain Its domains, comma-separated.

Container discovery uses the docker command-line tool, which the agent image does not contain: inside the container, point the agent to the logs with WEB_LOG_PATH instead.

Domains behind a reverse proxy

From agent 1.0.35 the agent also lists the domains of your running containers from the labels their reverse proxy reads, through the Docker or Podman socket (read only, refreshed every 2 minutes, also inside the agent container):

  • Traefik router rules, traefik.http.routers.<name>.rule: every Host(...) of the rule. HostRegexp and path rules are skipped.
  • Caddy site addresses, caddy and caddy_0, caddy_1...
  • infrafence.domain.

This is what Coolify writes for its proxy (coolify-proxy, Traefik or Caddy), so a Coolify server needs no label. The domains appear under Monitor › Trust badge, where they are verified with a DNS TXT record, since the site has no document root on the host: see Trust badge. The agent never runs anything in the proxy container; it does not read Traefik's or Caddy's own JSON access logs.

Other commands

The image runs any agent command you give it, for example the read-only check:

bash
docker run --rm --privileged --network host --pid host ghcr.io/infrafence/infrafence-agent:latest preflight