BGP Mitigation Engine

Auto-deploy FlowSpec rules, RTBH blackhole routes, and rate-limiting announcements via BGP

BGP mitigation requires admin or owner role. It works alongside firewall rules and cloud scrubbing — all three can trigger on the same incident.

Overview

The BGP mitigation engine connects Flowtriq to your BGP speakers (ExaBGP, GoBGP) or upstream providers (Cloudflare, webhook). When an attack is detected, the engine automatically selects the right mitigation action and announces the corresponding BGP rule. Rules auto-expire after their TTL, and the engine handles retries, deduplication, and rate limiting.

Key Concepts

Concept	Description
Adapter	A BGP speaker or endpoint that receives mitigation commands (ExaBGP, GoBGP, Cloudflare, or webhook)
Intent	The type of mitigation: `rate_limit_src`, `drop_protocol`, `drop_udp_port`, `blackhole`
Escalation Level	Four levels: `local` (rate-limit), `flowspec` (drop), `rtbh` (blackhole), `scrubbing` (cloud divert)
Rule TTL	How long a rule stays active before auto-expiring (default: 300 seconds)
Cooldown	Minimum time between rules for the same target (default: 60 seconds)

Escalation Policy

The escalation policy determines which mitigation level is applied based on attack bandwidth. Thresholds are configurable per workspace.

Level	Default Threshold	Action
Local (Rate-Limit)	> 100 Mbps	FlowSpec rate-limiting rules throttle attack traffic
FlowSpec (Drop)	> 500 Mbps	FlowSpec drop rules filter specific protocols/ports
RTBH (Blackhole)	> 2 Gbps	RTBH announces target with community 65535:666
Cloud Scrubbing	> 5 Gbps	Diverts traffic to upstream scrubbing provider

To configure thresholds, go to Dashboard → Mitigation → Escalation tab.

Setting Up an Adapter

Direct API vs proxy: Some adapters (Cloudflare, GoBGP REST, Webhook) connect directly to an existing API. Others (ExaBGP, GoBGP CLI, BIRD 2, FRR) are CLI-based tools with no built-in HTTP API, so they need a lightweight HTTP proxy running alongside them. We provide a ready-to-use proxy script below.

ExaBGP (requires proxy)

ExaBGP is a CLI-based BGP speaker that reads commands from stdin. Flowtriq communicates over HTTP, so you need a small proxy that receives HTTP requests and pipes commands into ExaBGP.

1. Install ExaBGP and the proxy

# Install ExaBGP
pip3 install exabgp

# Install the proxy dependencies
pip3 install flask gunicorn

2. Create the proxy script

Save this as /opt/flowtriq-bgp-proxy/proxy.py:

#!/usr/bin/env python3
"""Flowtriq BGP proxy for ExaBGP / GoBGP CLI / BIRD 2 / FRR.
Receives HTTP POST from Flowtriq, executes the command locally."""

import subprocess, os, hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
AUTH_TOKEN = os.environ.get("PROXY_AUTH_TOKEN", "")

# --- ExaBGP: pipe commands to the ExaBGP process via its named pipe ---
EXABGP_PIPE = os.environ.get("EXABGP_PIPE", "/run/exabgp.cmd")

@app.route("/command", methods=["POST"])
def handle_command():
    # Verify auth token
    if AUTH_TOKEN:
        header = request.headers.get("Authorization", "")
        if header != f"Bearer {AUTH_TOKEN}":
            return jsonify({"error": "unauthorized"}), 401

    data = request.get_json(silent=True) or {}
    cmd = data.get("command", "").strip()
    if not cmd:
        return jsonify({"error": "missing command"}), 400

    # Write to ExaBGP named pipe
    try:
        with open(EXABGP_PIPE, "w") as f:
            f.write(cmd + "\n")
        return jsonify({"ok": True, "command": cmd})
    except Exception as e:
        return jsonify({"error": str(e)}), 500

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)

3. Run the proxy

# Set an auth token (use the same value in the Flowtriq adapter config)
export PROXY_AUTH_TOKEN="your-secret-token"

# Run with gunicorn (production)
gunicorn -b 127.0.0.1:5000 -w 2 proxy:app

# Or create a systemd service for persistence

4. Configure ExaBGP to peer with your router

Example exabgp.conf for RTBH peering with a MikroTik or Cisco router:

process http-api {
    run /bin/cat;            # ExaBGP reads commands from stdin
    encoder json;
}

neighbor 10.0.0.1 {         # Your router's IP
    router-id 10.0.0.2;     # This server's IP
    local-address 10.0.0.2;
    local-as 65001;
    peer-as 65001;           # iBGP (same AS)
    family {
        ipv4 unicast;
        ipv4 flow;           # Enable FlowSpec
    }

    api {
        processes [http-api];
    }
}

5. Add the adapter in Flowtriq

Go to Dashboard → Mitigation → BGP Adapters
Click Add Adapter, select type ExaBGP
Set the endpoint to http://127.0.0.1:5000 (if the proxy runs on the same VM)
Enter the same auth token you set in PROXY_AUTH_TOKEN
Set your blackhole next-hop (commonly 192.0.2.1) and BGP communities (e.g. 65535:666 for standard RTBH)
Click Test to verify

Flowtriq sends commands like:

# RTBH blackhole
announce route 203.0.113.5/32 next-hop 192.0.2.1 community [65535:666]

# FlowSpec drop UDP
announce flow route { match { destination 203.0.113.5/32; protocol 17; } then { discard; } }

# Withdraw (auto-expires after TTL)
withdraw route 203.0.113.5/32 next-hop 192.0.2.1

GoBGP

GoBGP supports two modes:

REST mode (v2.x): GoBGP has a built-in REST API. No proxy needed. Point the adapter endpoint directly at http://gobgp-host:8080.
CLI mode (v3+): GoBGP v3 removed the REST API. Use the same proxy script above but replace the ExaBGP pipe logic with subprocess.run(["gobgp"] + cmd.split()). Flowtriq sends gobgp global rib add ... commands.

BIRD 2 (requires proxy)

Uses the same proxy pattern as ExaBGP. The proxy should execute commands via birdc:

# In the proxy, replace the ExaBGP pipe with:
subprocess.run(["birdc"] + cmd.split(), capture_output=True, timeout=10)

Flowtriq sends BIRD route commands to the /birdc endpoint.

FRRouting (FRR) (requires proxy)

Same proxy pattern. The proxy should execute commands via vtysh:

# Proxy receives a list of commands and runs them through vtysh
subprocess.run(["vtysh", "-c", cmd], capture_output=True, timeout=10)

Flowtriq sends FRR sends structured vtysh commands to the /vtysh endpoint, including configure terminal, ip route ... Null0, and community configuration.

Cloudflare Magic Transit (direct API)

Connects directly to Cloudflare's API. No proxy needed.

Requires a Cloudflare account with Magic Transit enabled
Add a new adapter with type Cloudflare
Enter your API token (needs Account:IP Prefixes:Edit scope) and account ID
Flowtriq toggles prefix advertisement on/off via the Cloudflare API to divert traffic through their scrubbing network

Webhook (direct API)

The most flexible option. Flowtriq sends structured JSON to any HTTP endpoint you control. Use this to integrate with custom scripts, router APIs, or automation platforms.

Add a new adapter with type Webhook
Enter your endpoint URL and optional auth token

Flowtriq sends POST requests with this payload:

{
  "action": "announce",          // "announce" or "withdraw"
  "intent_type": "blackhole_ip",  // "blackhole_ip", "drop_tcp_syn", "rate_limit_udp", etc.
  "target_ip": "203.0.113.5",    // The IP being attacked
  "protocol": "any",             // "tcp", "udp", "icmp", or "any"
  "destination_port": null,       // Target port (null if not applicable)
  "rate_limit_bps": null,         // Rate limit in bps (for rate-limit intents)
  "escalation_level": "rtbh",     // "local", "flowspec", "rtbh", or "scrubbing"
  "timestamp": "2026-07-28T14:30:00+00:00"
}

Your endpoint should return HTTP 2xx on success. Failed deliveries are retried with exponential backoff.

Radware & F5 (direct API)

Connect directly to the Radware DefensePro or F5 BigIP management API. Enter the appliance URL and credentials in the adapter config. Flowtriq handles the multi-step API workflow (creating network objects, firewall rules, and committing) automatically.

Attack Type Mapping

The engine maps each classified attack type to specific mitigation intents:

Attack Family	Intent	Details
UDP Flood	`drop_protocol`	Drop all UDP to target
TCP SYN Flood	`rate_limit_src`	Rate-limit TCP to target
ICMP Flood	`drop_protocol`	Drop all ICMP to target
DNS Amplification	`drop_udp_port`	Drop UDP port 53
NTP Amplification	`drop_udp_port`	Drop UDP port 123
SSDP Amplification	`drop_udp_port`	Drop UDP port 1900
Memcached Amplification	`drop_udp_port`	Drop UDP port 11211
Unknown / High Volume	`rate_limit_src`	Conservative rate-limiting (only above 500 Mbps)

Event Pipeline

Attack events flow through the following stages before a BGP rule is announced:

Queue: Attack events are queued with priority scores based on severity and bandwidth
Aggregation: Events within the aggregation window (default 5s) targeting the same IP+protocol+port+family are collapsed
Validation: Target IP must be public IPv4 (private/reserved IPs rejected, /24 minimum prefix)
Intent Generation: Attack type determines the FlowSpec/RTBH intent
Escalation: Attack bandwidth determines whether intent is upgraded to a higher level
Deduplication: If an active rule already exists for this target+intent, the event is skipped
Rate Limiting: Sliding window ensures max N rules/minute per tenant (default: 30)
Cooldown: Same target cannot receive a new rule within the cooldown period (default: 60s)
Adapter Selection: Best adapter is scored by capability match and last test status
Announce: Rule is dispatched to the adapter with full payload logging

Lifecycle Management

The mitigation engine runs continuously in the background and handles:

Queue processing: Processes pending events within seconds of detection
TTL expiry: Automatically withdraws rules that have exceeded their TTL
Retry: Re-attempts failed announcements with exponential backoff
Cleanup: Removes expired rules and rate-limit records automatically

Lifecycle management is fully automated. No manual setup or scheduled jobs required on your side.

Manual Rules

Create rules manually from the Manual Rule tab in the dashboard. Specify:

Target IP (public IPv4 only)
Intent type (rate-limit, drop protocol, drop port, blackhole)
Protocol and port (for drop rules)
Rate limit value (for rate-limit intent)
TTL in seconds
Escalation level override
Specific adapter (or auto-select)

API Endpoints

The mitigation API is at /api/dash/mitigation:

Method	Action	Description
GET	`?action=rules`	List active mitigation rules
GET	`?action=history`	List rule history (last 100)
GET	`?action=adapters`	List configured adapters
GET	`?action=escalation`	Get escalation policy
GET	`?action=log`	Get activity log
GET	`?action=metrics`	Get mitigation metrics (active rules, queue depth, etc.)
POST	`?action=save_adapter`	Create or update an adapter (admin+)
POST	`?action=delete_adapter`	Delete an adapter (admin+)
POST	`?action=test_adapter`	Test adapter connectivity (admin+)
POST	`?action=save_escalation`	Save escalation policy (admin+)
POST	`?action=create_rule`	Create a manual rule (admin+)
POST	`?action=withdraw_rule`	Manually withdraw a rule (admin+)

Safety Guards

IPv4 only: IPv6 targets are rejected (roadmap)
No private IPs: RFC 1918, link-local, loopback, and reserved ranges are blocked
/24 minimum prefix: Prevents overly broad blackholes
Rate limiting: Configurable max rules per minute (default: 30)
Cooldown: Same target cannot receive a new rule within the cooldown period
Global cap: Maximum 200 active rules per tenant
Distributed locks: MySQL GET_LOCK() prevents duplicate announcements in multi-process deployments
Unknown attacks: Only mitigated above 500 Mbps with conservative rate-limiting