Dolly-Sensor

Dolly-Sensor is a real-time DDoS detection and mitigation system written in Go. It ingests sFlow samples from your network devices, profiles traffic behavior, and — when an attack is confirmed — automatically announces BGP Flowspec / RTBH rules through GoBGP to block the threat at your edge.

How It Works

Every sampled packet passes through a detection pipeline, ordered from cheapest to most expensive:

1. Blocklist — instant drop if the source IP matches a configured blocklist.
2. TrustScore — behavioral reputation per source IP (based on SYN/ACK handshake success). Known flooders are rejected before consuming further resources.
3. Stateful TCP validation — flags out-of-state TCP packets (e.g. ACKs without handshake, SYN floods).
4. Protocol filters — application-level inspection for FTP (ports 20/21) and SSH: malformed commands, brute force, rate limits.

When a filter triggers, the sensor executes mitigation: an RTBH (/32) or Flowspec rule is announced to your routers via GoBGP, and automatically withdrawn after the configured duration (default: 60s).

Key Features

• Sharded engine — stats are partitioned across CPU cores (default: 64 shards) to process hundreds of thousands of PPS.
• Live dashboard — global PPS/Mbps overview, per-IP traffic profiles (protocols, TCP flags, TTL distribution, top talkers), alert feed, and a packet inspector with filtering.
• Automated BGP mitigation — RTBH and Flowspec announcements with auto-withdrawal to keep the routing table clean.
• TrustScore reputation — rewards legitimate clients and penalizes attackers based on historical behavior.
• Z-score anomaly detection — statistical baselines to detect volume deviations.
• File-based blocklists — load lists from blocklists/ and reload them from the dashboard without restarting.
• No dependencies — single Go binary; GoBGP is only required for automated mitigation.

Quick Start

Prerequisites: Go 1.22+ (GoBGP if you plan to use automated mitigation).

git clone https://github.com/lilsheepyy/Dolly-Sensor.git
cd Dolly-Sensor

# Create your config from the template
cp rename-me.config.json config.json
$EDITOR config.json

# Build and run
go build -o dolly-sensor main.go
./dolly-sensor

Then point your router's sFlow exporter at the sensor (UDP 6343 by default) and open the dashboard at http://YOUR_IP:8080.

Configuration

Key options in config.json:

Section	Option	Description
sflow.collector	ip, udpport	Address the sFlow collector binds to (default 0.0.0.0:6343).
http.listen		Dashboard/API listen address (default 0.0.0.0:8080).
local.owned_cidrs		CIDR ranges you protect; traffic to these is analyzed.
local.trusted_ips		Sources exempt from detection.
performance.shards		Number of store shards (tune to your CPU cores).
detection	sensitivity, network_type	Detection aggressiveness and traffic profile.
bgp	enabled, peer_ip, peer_as, community	GoBGP session parameters for mitigation.
mitigation	blocklist_path, auto_block	Blocklist files and automatic blocking.
protocols_tuning	ftp, ftp_data	Per-protocol PPS limits and block durations.
trust_tuning	min_score_for_exemption	TrustScore threshold for filter exemption.

Dashboard & API

The web dashboard exposes a JSON API under /api/:

Endpoint	Purpose
/api/stats, /api/packets	Global stats and recent sampled packets.
/api/profiles, /api/profile-detail	Per-IP traffic profiles and deep-dive detail.
/api/global-summary	Network-wide load and active alerts.
/api/reputation/all	TrustScore reputations for all sources.
/api/mitigation/status	Active BGP announcements and blocklist state.
/api/blocklist/add, /api/mitigation/reload	Manage blocklists at runtime.

Project Layout

main.go            Entry point
app/               Bootstrap and wiring
config/            Configuration loading and validation
sflow/             sFlow collector and datagram parsing
packet/            Packet/event models and protocol mappings
store/             Sharded packet store and statistics
analyzer/          Detection pipeline and z-score analysis
stateful/          TCP state validation
basefilters/       Protocol filters (FTP, SSH)
trustscore/        Behavioral reputation engine
profiler/          Persistent per-IP profiles and snapshots
mitigation/        BGP manager (GoBGP) and blocklist engine
dashboard/, web/   HTTP API and frontend

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Commit your changes and push the branch.
4. Open a pull request.

License

Distributed under the MIT License. See LICENSE for details.