Skip to content

flowwler

A DDoS detection and mitigation daemon that ingests NetFlow v5/v9/IPFIX and sFlow v5 traffic data, detects attacks via configurable threshold escalation, and triggers BGP mitigations (blackhole, subnet-blackhole, FlowSpec) via an embedded GoBGP BGP server — no external daemon required.

flowwler is not a traffic analytics or network insight tool. It does not provide traffic visualisation, capacity planning, or historical flow analysis. For those use cases, run a dedicated tool such as Akvorado alongside flowwler — both consume the same NetFlow/sFlow data and are designed to complement each other.

Features

flowwler listens for NetFlow v5/v9/IPFIX and sFlow v5 on independent UDP sockets (all listeners default to [::], so IPv4 and IPv6 are handled identically) and aggregates traffic per destination IP in a sliding window with configurable depth and sampling-rate scaling. Duration-based normalization is intentionally left out — routers reset their byte/packet counters at each active-timeout export, so summing the buckets as they arrive is the correct behavior, not an approximation. Rate smoothing is asymmetric: a fast α=0.9 on the way up catches a sustained attack within seconds, a slow α=0.2 on the way down keeps a brief dip from triggering a premature withdrawal.

Each group and victim IP runs its own escalation state machine (Idle → Active → HoldDown → Idle) with configurable hold times and escalate-after timers; a level with no mitigation: block fires notifications only. The same aggregation extends to carpet-bomb attacks — match.subnet aggregates traffic across a whole prefix and escalates once at least min_victims (default 3) distinct victim IPs inside it are affected.

A triggered level can combine any of three BGP mitigation types: a host blackhole (/32//128), a subnet blackhole (auto-derives /24//48, with community and next-hop), or FlowSpec discard/rate-limit/redirect with dynamic top-N source-rule refresh and optional BGP community tagging (standard AS:VALUE or large ASN:Local1:Local2). More than one type can be active on the same level at once — for example, a subnet blackhole to steer traffic onto scrubbing infrastructure while FlowSpec filters it there. Per-group BGP route attributes (ASN for AS-PATH prepend, NO_EXPORT, NO_ADVERTISE) layer on top of any of these for downstream customer mitigations, and flows with no output interface are counted separately so mitigation effectiveness itself becomes a metric.

Subnets and whitelists don't have to be maintained by hand: per-group prefixes can be auto-discovered from IRR (AS-SET expansion via WHOIS) or NetBox IPAM and refreshed in the background every 12 hours, and the same sources — plus a static list or a plain URL fetch — can populate per-scope whitelists that exclude known-good source IPs from attack-rate calculations and FlowSpec target selection, configurable globally or per group.

Day-to-day operation runs through a REST API that covers escalation state, router liveness, group subnets, prefix sources, notification target health, active config, attack history, and per-target traffic visibility (current inbound/discard/outbound rates for every IP in a group, including below-threshold); the same API can manually trigger or withdraw mitigations — including stopping ones the escalation engine started — test notification targets on demand, and trigger a reload. A SIGHUP or POST /api/v1/reload re-parses config and reconciles BGP peers live, immediately withdrawing mitigations for any removed group, without needing a restart (only local_asn/router_id changes do). Every attack session and state-transition event is recorded to a SQLite-backed store with configurable retention (default 90 days) and exposed as Prometheus gauges/counters per router, per group (inbound and outbound), and per victim; attacks and mitigations are tracked as distinct but attack_id-linked records, since an attack is always logged even when its level is alert-only and never announces a route. Optional per-attack PCAP capture synthesizes one libpcap-format file per attack session from flow metadata into a configurable directory (manual ad-hoc captures are supported too), all downloadable via the REST API. Notifications fire on every escalation state change, with per-target health tracking and on-demand testing, to any combination of webhook, Slack, Telegram, PagerDuty, Pushover, Alertmanager, MS Teams, Jira, and Zammad. An anonymous telemetry ping to statistics.flowwler.net reports version, feature flags, and aggregate attack counts — no IP addresses or operator-identifying data — and can be turned off with telemetry.disabled: true. flowwler --version always reports version and build timestamp, plus remaining license time on demo binaries.

How it works

flowwler listens for NetFlow and sFlow datagrams, aggregates traffic per destination IP using a sliding window with asymmetric smoothing, and runs a per-victim state machine that escalates through configured levels when thresholds are exceeded. When a level triggers, it announces a BGP route - blackhole, subnet-blackhole, or FlowSpec - to the connected customer router via the embedded GoBGP server. No external BGP daemon or database required.

See How it works for a full description of the pipeline, escalation mechanics, FlowSpec source selection, router discard detection, and design rationale.

Requirements

  • A NetFlow v5/v9/IPFIX or sFlow v5 exporter (router, switch, or softflowd)
  • A customer/edge router that will accept blackhole and FlowSpec routes from flowwler, discard the traffic locally, and optionally propagate mitigation routes to upstream providers - GoBGP is embedded; no separate gobgpd process needed