https://github.com/lance0/prefixd
BGP FlowSpec policy daemon for automated DDoS mitigation
https://github.com/lance0/prefixd
bgp ddos ddos-mitigation fastnetmon flowspec gobgp netops network-automation rust
Last synced: 2 months ago
JSON representation
BGP FlowSpec policy daemon for automated DDoS mitigation
- Host: GitHub
- URL: https://github.com/lance0/prefixd
- Owner: lance0
- License: mit
- Created: 2026-01-16T15:13:44.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T01:10:18.000Z (3 months ago)
- Last Synced: 2026-03-20T06:16:29.807Z (3 months ago)
- Topics: bgp, ddos, ddos-mitigation, fastnetmon, flowspec, gobgp, netops, network-automation, rust
- Language: Rust
- Homepage: https://prefixd.io
- Size: 2.09 MB
- Stars: 72
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# prefixd
[](https://github.com/lance0/prefixd/actions/workflows/ci.yml)
[](https://www.rust-lang.org)
[](LICENSE)
**prefixd** is a BGP FlowSpec policy daemon for automated DDoS mitigation. It receives attack signals from detectors, applies policy-driven playbooks, and announces FlowSpec rules to routers via GoBGP.
---
## Why prefixd?
You have detectors (FastNetMon, Kentik, Prometheus alerts) that know when you're under attack. You have routers (Juniper, Arista, Cisco) that can filter traffic at line rate with FlowSpec. But there's a gap:
| Problem | Without prefixd | With prefixd |
|---------|-----------------|--------------|
| **Detector → Router** | Manual CLI or fragile scripts | Automated policy engine |
| **Response time** | Minutes (operator intervention) | Seconds (API-driven) |
| **Safety** | Easy to fat-finger, no guardrails | Quotas, safelist, /32-only, TTLs |
| **Visibility** | Scattered logs, no audit trail | Dashboard, metrics, audit log |
| **Expiry** | Forget to remove rules | Auto-expire via TTL |
**Key idea:** Detectors signal intent, prefixd decides policy. No detector ever speaks BGP directly.
```
Detector ──► prefixd ──► GoBGP ──► Routers
│
├── Policy Engine (playbooks)
├── Guardrails (quotas, safelist)
└── Reconciliation (auto-expire)
```
---
## Quick Start
### 1. Clone and configure
```bash
git clone https://github.com/lance0/prefixd.git
cd prefixd
```
### 2. Start the stack
```bash
docker compose up -d
```
This starts 7 services:
| Service | Purpose | Ports |
|---------|---------|-------|
| **nginx** | Reverse proxy (single entrypoint) | 80 |
| **prefixd** | Policy daemon | internal |
| **dashboard** | Web UI | internal |
| **gobgp** | BGP route server | 179 (BGP) |
| **postgres** | State storage | 5432 |
| **prometheus** | Metrics storage | 9091 |
| **grafana** | Monitoring dashboards | 3001 |
### 3. Verify it's running
```bash
# Check all services are healthy
docker compose ps
# Test the API
curl http://localhost/v1/health
# {"status":"ok","version":"0.14.0","auth_mode":"none"}
```
### 4. Create an admin account
```bash
docker compose exec prefixd prefixdctl operators create \
--username admin --role admin
# Enter password when prompted
```
### 5. Open the dashboard
```bash
open http://localhost
```
Login with the admin credentials you just created.
### Troubleshooting
```bash
# View prefixd logs
docker compose logs prefixd
# View GoBGP logs
docker compose logs gobgp
# Restart everything
docker compose restart
```
**Common issues:**
- Port 80 in use → Stop local web server or change nginx port in docker-compose.yml
- Port 5432 in use → Stop local PostgreSQL or change port in docker-compose.yml
- Port 179 in use → Another BGP daemon is running
- "connection refused" → Wait a few seconds for services to start
---
## Next Steps
Once you have prefixd running locally:
### 1. Configure your inventory
Edit `configs/inventory.yaml` to map your IP space to customers:
```yaml
customers:
- customer_id: acme
name: "ACME Corp"
prefixes:
- "203.0.113.0/24"
services:
- service_id: dns
assets:
- ip: "203.0.113.10"
allowed_ports:
udp: [53]
```
### 2. Define playbooks
Edit `configs/playbooks.yaml` to set response policies:
```yaml
playbooks:
- name: udp_flood
match:
vector: udp_flood
steps:
- action: police
rate_bps: 10000000 # 10 Mbps
ttl_seconds: 120
- action: discard # Escalate if attack persists
ttl_seconds: 300
```
### 3. Connect a detector
Point your detector at prefixd's API. Three integration paths:
**Generic events API** (any detector):
```bash
curl -X POST http://localhost/v1/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PREFIXD_API_TOKEN" \
-d '{
"timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
"source": "fastnetmon",
"victim_ip": "203.0.113.10",
"vector": "udp_flood",
"bps": 5000000000
}'
```
**Native adapters** (zero-config signal translation):
- **Alertmanager** → `POST /v1/signals/alertmanager` — maps labels/annotations to events
- **FastNetMon** → `POST /v1/signals/fastnetmon` — accepts native JSON payload
With [multi-signal correlation](docs/configuration.md#correlation) enabled, events from multiple detectors targeting the same IP are grouped and corroborated before triggering mitigation.
See [FastNetMon Integration](docs/detectors/fastnetmon.md) for a complete setup guide.
### 4. Peer with your routers
Configure GoBGP neighbors in `configs/gobgp.conf` and set up FlowSpec import policies on your routers. See [Router Setup](docs/deployment.md#router-configuration).
---
## Features
| Category | What it does |
|----------|--------------|
| **Signal Ingestion** | HTTP API + native Alertmanager and FastNetMon webhook adapters |
| **Multi-Signal Correlation** | Time-windowed grouping of events from multiple detectors with source weighting and corroboration |
| **Policy Engine** | YAML playbooks define per-vector responses with escalation |
| **Guardrails** | Quotas, safelist, /32-only enforcement, mandatory TTLs |
| **BGP FlowSpec** | Announces via GoBGP (traffic-rate, discard actions) |
| **Reconciliation** | Auto-expires mitigations, repairs RIB drift every 30s |
| **Dashboard** | Real-time web UI with WebSocket updates and toast notifications |
| **Manual Mitigation** | "Mitigate Now" form for operator-initiated events |
| **Authentication** | Three roles (admin, operator, viewer) with mode-aware auth (`none`, `bearer`, `credentials`, `mtls`) |
| **Observability** | Prometheus metrics, Grafana dashboards, structured logs, audit trail |
| **CLI** | `prefixdctl` for status, mitigations, safelist, config reload |
---
## How It Works
1. **Detector sends event** → `POST /v1/events`, `/v1/signals/alertmanager`, or `/v1/signals/fastnetmon`
2. **Inventory lookup** → Find customer/service owning the IP
3. **Signal correlation** → Group related signals by (victim_ip, vector), check corroboration
4. **Playbook match** → Determine action (police/discard) based on vector
5. **Guardrails check** → Validate quotas, safelist, prefix length
6. **FlowSpec announce** → Send rule to GoBGP via gRPC
7. **Router enforcement** → Traffic filtered at line rate
8. **Auto-expiry** → Rule withdrawn when TTL expires
**Fail-open design:** If prefixd dies, mitigations auto-expire. No permanent rules, no stuck state.
---
## Documentation
| Topic | Link |
|-------|------|
| Full deployment guide | [docs/deployment.md](docs/deployment.md) |
| Configuration reference | [docs/configuration.md](docs/configuration.md) |
| API reference | [docs/api.md](docs/api.md) |
| CLI reference | [docs/cli.md](docs/cli.md) |
| Router setup | [docs/deployment.md#router-configuration](docs/deployment.md#router-configuration) |
| Grafana dashboards | [docs/grafana.md](docs/grafana.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
---
## Supported Routers
FlowSpec (RFC 5575, RFC 8955) is supported by:
| Vendor | Platform | Notes |
|--------|----------|-------|
| Juniper | MX, PTX, SRX | Full FlowSpec support |
| Arista | 7xxx | EOS 4.20+ |
| Cisco | IOS-XR | ASR 9000, NCS |
| Nokia | SR OS | 19.x+ |
---
## Requirements
- **Docker** (recommended) or Rust 1.85+ for building from source
- **PostgreSQL 14+** for state storage
- **GoBGP** is included in Docker Compose
---
## Upgrading
Database migrations run automatically on startup. See **[docs/upgrading.md](docs/upgrading.md)** for version-specific notes.
> **v0.12.0 breaking change:** Offset-based pagination (`?offset=N`) has been removed from all list endpoints. Use cursor-based pagination instead (`?cursor=&limit=N`). If you have scripts or integrations using `--offset` or `?offset=`, they must be updated. See [ADR 016](docs/adr/016-cursor-pagination.md) for rationale and [upgrading.md](docs/upgrading.md) for migration examples.
---
## Project Status
Current version: **v0.14.0**
- Core functionality stable and tested
- Real-time dashboard with WebSocket updates, toast notifications, and mitigation detail views
- Full operator workflow: manual mitigation, withdraw, safelist management, config browsing
- API may change before v1.0
- See [ROADMAP.md](ROADMAP.md) for planned features
---
## Community
- **Issues:** [GitHub Issues](https://github.com/lance0/prefixd/issues)
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
- **Architecture Decision Records:** [docs/adr/](docs/adr/) (19 ADRs)
---
## License
MIT - See [LICENSE](LICENSE)