Quickstart

This walks you from a fresh checkout to a running, dry-run Kapkan instance that detects attacks against a test prefix. Nothing here can announce a route — dry-run is the default.

1. Build the binary

make build

This produces a single static kapkan binary.

2. Run in dry-run

Start Kapkan with the bundled development config and human-readable logs:

make run-dev
# equivalent to:
./kapkan -config configs/dev.yaml -log-format text

The development config (configs/dev.yaml) has dry_run: true, a test protected network of 203.0.113.0/24, and listens for sFlow on :6343 and NetFlow/IPFIX on :2055.

3. Point your exporters at Kapkan

Configure your routers' flow exporters to send to Kapkan's listen ports:

NetFlow and IPFIX share the same UDP socket. At least one listener must be configured.

4. Watch it work

Kapkan serves its REST API and metrics on 127.0.0.1:8080 by default:

# Current mode, protected networks, thresholds, active attack/ban counts
curl -s localhost:8080/api/v1/status | jq

# Active attacks plus the last 100 that ended, with samples and classification
curl -s localhost:8080/api/v1/attacks | jq

# Prometheus metrics
curl -s localhost:8080/metrics | grep kapkan_

You can also open the embedded dashboard at http://localhost:8080 in a browser.

5. No router? Generate synthetic attacks

Kapkan ships with pkg/flowgen, which builds real NetFlow / sFlow wire-format datagrams — including amplification, SYN-flood and UDP-flood patterns. It is used throughout the test suite to validate detection end-to-end without touching a real router. The integration test in internal/app replays an NTP-amplification flood over a real UDP socket against a dry-run instance and asserts the attack and its (auto-expiring) virtual ban appear in the API.

Next steps

• Configuration reference — adapt the config to your network.
• Detection & thresholds — tune what counts as an attack.
• Going live — validate, then turn off dry-run.