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

ExaBGP

Install ExaBGP on your border router or a dedicated route server
Configure ExaBGP with an HTTP API listener (default port 5000)
In Flowtriq, go to Dashboard → Mitigation → BGP Adapters
Click Add Adapter, select type ExaBGP
Enter the endpoint URL (e.g. http://10.0.0.1:5000) and optional auth token
Configure the BGP neighbor IP and max prefix length safety limit
Select capabilities (FlowSpec, RTBH, rate-limiting)
Click Test to verify connectivity

GoBGP

Install GoBGP and configure the gRPC/REST API
In Flowtriq, add a new adapter with type GoBGP
Enter the API endpoint URL and auth token
GoBGP supports the same FlowSpec and RTBH capabilities as ExaBGP

Cloudflare (Magic Transit)

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
Cloudflare adapter supports blackhole (prefix advertisement) intent

Webhook

Set up an HTTP endpoint that accepts POST requests with JSON body
Add a new adapter with type Webhook
Enter the endpoint URL, auth token, and optional custom headers
Webhook receives structured JSON with rule details, intent, target, and action (announce/withdraw)

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: Events from lib/notifications.php are queued in mitigation_event_queue with priority scores
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 cron job cron/mitigation-lifecycle.php runs every minute and handles:

Queue processing: Processes up to 100 pending events per cycle
TTL expiry: Withdraws rules that have exceeded their TTL
Retry: Re-attempts failed announcements with exponential backoff
Cleanup: Removes stale queue entries and expired rate-limit records

Cron required: Add this to your crontab: * * * * * php /var/www/flowtriq.com/html/cron/mitigation-lifecycle.php

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