DDAM

DDAM mitigates DDoS attacks by monitoring NetFlow data in an Elasticsearch cluster (configured separately). It calculates per-IP throughput and announces temporary blackhole routes via BGP when traffic exceeds a set threshold. Blackhole duration will increase exponentially (up to 24h by default) for repeat attacks to the same IP address.

Example

Example Docker Compose configuration. Replace

• <UPSTREAM-BGP-NEIGHBOR-IP> with the upstream BGP neighbor IP,
• <HOST-IP> with the Docker host public IP,
• <AS-NUMBER> with your AS number,
• <PEER-AS-NUMBER> with the upstream BGP neighbor AS number,
• <PEER-BLACKHOLE-COMMUNITY> with the upstream blackhole community,
• <ELASTICSEARCH-URL> with the address of an Elasticsearch server NetFlow data is collected into.

docker-compose.yml:

services:
  init-ddam-volume-permissions:
    image: "alikov/ddam"
    volumes:
      - "ddam-config:/etc/ddam"
      - "ddam-data:/var/lib/ddam"
      - "ddam-run:/run/exabgp"
    mem_limit: "32mb"
    read_only: true
    security_opt:
      - "no-new-privileges=true"
    user: root
    entrypoint: sh
    command:
      - -euc
      - 'chown -R nobody:root /etc/ddam /var/lib/ddam /run/exabgp'
    network_mode: none
  init-ddam-cidr-blocks:
    image: "alikov/ddam"
    volumes:
      - "ddam-config:/etc/ddam"
    mem_limit: "512mb"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges=true"
    networks:
      backend:
        ipv4_address: "10.17.0.5"
    entrypoint: /opt/ddam/bin/get-as-cidr-blocks
    command:
      - --output-file
      - /etc/ddam/cidr-blocks.json
      - "<AS-NUMBER>"
    depends_on:
      init-ddam-volume-permissions:
        condition: service_completed_successfully
  init-ddam-exabgp-conf:
    image: "alikov/ddam"
    volumes:
      - "ddam-config:/etc/ddam"
      - "./neighbors.json:/etc/ddam/neighbors.json:ro"
    mem_limit: "128mb"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges=true"
    network_mode: none
    entrypoint: /opt/ddam/bin/make-exabgp-conf
    command:
      - --neighbors-config-file
      - /etc/ddam/neighbors.json
      - --output-file
      - /etc/ddam/exabgp.conf
    depends_on:
      init-ddam-volume-permissions:
        condition: service_completed_successfully
  init-ddam-migrate:
    image: "alikov/ddam"
    environment:
      - DDAM_DB_FILE=/var/lib/ddam/ddam.db
    volumes:
      - "ddam-data:/var/lib/ddam"
    mem_limit: "128mb"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges=true"
    network_mode: none
    entrypoint: /opt/ddam/bin/ddam
    command:
      - migrate
    depends_on:
      init-ddam-volume-permissions:
        condition: service_completed_successfully
  ddam:
    image: "alikov/ddam"
    environment:
      - DDAM_ES_ADDRESS=<ELASTICSEARCH-URL>
      - DDAM_DB_FILE=/var/lib/ddam/ddam.db
      - DDAM_NEIGHBORS_CONFIG_FILE=/etc/ddam/neighbors.json
      - DDAM_CIDR_BLOCKS_FILE=/etc/ddam/cidr-blocks.json
      - DDAM_DDOS_THRESHOLD_MBPS=1000
      - DDAM_EXPORTER_PORT=9998
      - exabgp.api.cli=true
      - exabgp.tcp.bind=0.0.0.0
      - exabgp.tcp.port=1790
    volumes:
      - "ddam-config:/etc/ddam"
      - "ddam-data:/var/lib/ddam"
      - "ddam-run:/run/exabgp"
      - "./neighbors.json:/etc/ddam/neighbors.json:ro"
    mem_limit: "1024mb"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges=true"
    ports:
      - "9998:9998"
      - "179:1790"
    networks:
      backend:
        ipv4_address: "10.17.0.6"
    healthcheck:
      test:
        - CMD-SHELL
        - "/usr/bin/timeout 2 /usr/bin/nc -z 127.0.0.1 1790 || exit 1"
      interval: 30s
      timeout: 2s
      retries: 5
    command:
      - /opt/ddam/bin/exabgp
      - /etc/ddam/exabgp.conf
    restart: always
    depends_on:
      init-ddam-cidr-blocks:
        condition: service_completed_successfully
      init-ddam-exabgp-conf:
        condition: service_completed_successfully
      init-ddam-migrate:
        condition: service_completed_successfully
networks:
  backend:
    ipam:
      driver: default
      config:
        - subnet: "10.17.0.0/27"
          ip_range: "10.17.0.16/28"
volumes:
  ddam-config:
  ddam-data:
  ddam-run:

neighbors.json:

{
  "<UPSTREAM-BGP-NEIGHBOR-IP>": {
    "description": "ddam-test-neighbor",
    "connect": 179,
    "local-address": "10.17.0.6",
    "router-id": "<HOST-IP>",
    "local-as": <AS-NUMBER>,
    "peer-as": <PEER-AS-NUMBER>,
    "communities": ["<PEER-BLACKHOLE-COMMUNITY>"]
  }
}

Environment variables

Prometheus metrics

Developing

See DEVELOPING.md for local development setup instructions.

Diagram icon attribution

• Dot icons created by Bharat Icons - Flaticon,
• Network device icons created by SBTS2018 - Flaticon,
• Wind icons created by Freepik - Flaticon,
• Cloud icons created by kosonicon - Flaticon,
• Smtp icons created by Three musketeers - Flaticon.