Add DDoS Detection to Your
Docker Compose Stack

Back to Blog

Why Run DDoS Detection in Docker

If your services run in Docker, your DDoS detection should too. Running ftagent as a container in your Compose stack means it deploys with the rest of your services, scales the same way, and fits into your existing deployment pipeline. No separate installation, no SSH access needed, no agent running outside your container orchestration.

The ftagent Docker image is published on Docker Hub and updated with every release.

Basic docker-compose.yml

Here is the minimal setup. Add the ftagent service to your existing docker-compose.yml:

version: "3.8"

services:
  # Your existing services
  web:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"

  app:
    image: your-app:latest
    ports:
      - "8080:8080"

  # Add ftagent for DDoS detection
  ftagent:
    image: flowtriq/ftagent:latest
    network_mode: host
    restart: unless-stopped
    environment:
      - FTAGENT_DEPLOY_TOKEN=your-deploy-token-here
      - FTAGENT_NODE_NAME=production-web-01
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
    cap_add:
      - NET_ADMIN
      - NET_RAW

The key settings:

• network_mode: host is required. The agent needs to see all traffic hitting the host, not just traffic within Docker's bridge network. Without host networking, the agent only sees inter-container traffic.
• /proc and /sys mounts give the agent read-only access to kernel network counters. This is how it measures PPS, bandwidth, and protocol breakdown without inspecting individual packets.
• NET_ADMIN and NET_RAW capabilities allow the agent to read network statistics and, when mitigation is enabled, deploy iptables rules.

Configuration via Environment Variables

ftagent is configured entirely through environment variables when running in Docker:

environment:
  # Required
  - FTAGENT_DEPLOY_TOKEN=ft_abc123...

  # Node identification
  - FTAGENT_NODE_NAME=web-prod-01
  - FTAGENT_NODE_GROUP=production

  # Service ports (comma-separated)
  - FTAGENT_SERVICE_PORTS=80/tcp,443/tcp,8080/tcp

  # Mitigation settings
  - FTAGENT_AUTO_MITIGATE=true
  - FTAGENT_FIREWALL_CHAIN=DOCKER-USER

  # Alert routing
  - FTAGENT_WEBHOOK_URL=https://hooks.slack.com/...
  - FTAGENT_ALERT_SEVERITY=medium

The FTAGENT_FIREWALL_CHAIN=DOCKER-USER setting is important for Docker environments. It tells the agent to insert mitigation rules in the DOCKER-USER chain, which is the correct chain for filtering traffic destined for Docker containers. Standard INPUT chain rules do not affect container traffic.

Production docker-compose.yml

A more complete example with logging, health checks, and persistent data:

version: "3.8"

services:
  ftagent:
    image: flowtriq/ftagent:latest
    container_name: ftagent
    network_mode: host
    restart: unless-stopped
    environment:
      - FTAGENT_DEPLOY_TOKEN=${FTAGENT_TOKEN}
      - FTAGENT_NODE_NAME=${HOSTNAME}
      - FTAGENT_SERVICE_PORTS=80/tcp,443/tcp,3306/tcp
      - FTAGENT_AUTO_MITIGATE=true
      - FTAGENT_FIREWALL_CHAIN=DOCKER-USER
      - FTAGENT_PCAP_ENABLED=true
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - ftagent-data:/var/lib/ftagent
    cap_add:
      - NET_ADMIN
      - NET_RAW
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "ftagent", "--health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  ftagent-data:

The ftagent-data volume persists baseline data and PCAP captures across container restarts. Without it, the agent rebuilds its baseline from scratch on every restart (takes about 5 minutes).

Multi-Service Stacks

For stacks with multiple exposed services, configure service ports for all of them:

# Web application + database + cache + monitoring
FTAGENT_SERVICE_PORTS=80/tcp,443/tcp,3306/tcp,6379/tcp,9090/tcp

The agent monitors all these ports as legitimate service traffic and builds separate baselines for each. An attack targeting port 3306 (MySQL) triggers detection even if web traffic on port 443 is normal.

Deploying Across Multiple Hosts

If you run Docker Compose on multiple servers (not a Swarm or K8s cluster, just separate Docker hosts), add the ftagent service to each host's compose file. Each host reports to the Flowtriq dashboard as a separate node, giving you per-host visibility.

For Docker Swarm or Kubernetes, see the Kubernetes DaemonSet guide for the recommended deployment pattern.

Monitoring and Prometheus

ftagent exposes Prometheus metrics on port 9101 by default. Since the container runs with host networking, these metrics are accessible at http://host-ip:9101/metrics. Add it to your Prometheus scrape config:

# prometheus.yml
scrape_configs:
  - job_name: 'ftagent'
    static_configs:
      - targets: ['localhost:9101']

Available metrics include ftagent_pps_total, ftagent_bps_total, ftagent_incidents_total, and per-protocol breakdowns. See the Prometheus metrics guide for the full list.

FAQ

Can I run ftagent without host networking?

Not recommended. Without network_mode: host, the agent only sees traffic on the Docker bridge network. It cannot monitor traffic hitting the host's external interface, which is where DDoS attacks arrive.

Does ftagent interfere with other containers?

No. The agent reads kernel counters passively and does not modify container networking. During mitigation, it adds rules to the DOCKER-USER chain, which Docker already uses for external-to-container traffic filtering.

What is the container image size?

The ftagent Docker image is under 50MB. It is based on Alpine Linux with the Python runtime and the ftagent package.

Back to Blog

Related Articles