GitHub

Quickstart

This walks you from nothing to a running, dry-run Kapkan instance that detects attacks against a test prefix. There is no build step — Kapkan ships as a single prebuilt, signed binary — and nothing here can announce a route, because dry-run is the default.

iWhat you need

A Linux host (amd64 or arm64). To see real detections you need a router exporting flow telemetry — NetFlow, IPFIX or sFlow (records of who is sending traffic to whom; see the glossary). With no router and a source checkout, you can still confirm detection works by running the test suite — see the last section. You only need a Go toolchain if you go that route, or if you build from source instead of downloading.

1. Install Kapkan

Pick whichever fits your host — every release ships prebuilt and signed for linux amd64/arm64, so you never compile anything.

iUse the latest release — replace v1.0.0

Before you copy-paste, replace v1.0.0 in every command below with the newest tag from the releases page (copying v1.0.0 verbatim will 404 if it is not the current release), and amd64 with arm64 on ARM hosts. Archive and package names drop the leading v (e.g. kapkan_1.0.0_linux_amd64.tar.gz).

Debian / Ubuntu (.deb)

VER=v1.0.0
curl -fLO "https://github.com/fornex/kapkan/releases/download/$VER/kapkan_${VER#v}_linux_amd64.deb"
sudo apt install "./kapkan_${VER#v}_linux_amd64.deb"

The package installs the binary to /usr/local/bin/kapkan, creates an unprivileged kapkan user, lays out /etc/kapkan with a dry-run config.yaml, and installs the hardened systemd unit — left stopped so you can review the config first. The Production deployment page covers the service from there. RHEL / Fedora is the same with the .rpm: sudo dnf install ./kapkan_<ver>_linux_amd64.rpm.

Tarball (any distro)

VER=v1.0.0
curl -fLO "https://github.com/fornex/kapkan/releases/download/$VER/kapkan_${VER#v}_linux_amd64.tar.gz"
tar xzf "kapkan_${VER#v}_linux_amd64.tar.gz"

That unpacks the kapkan binary plus a deploy/ directory (the systemd unit, an example config, and update.sh). The rest of this page uses the tarball. Before running it in production it is worth verifying the download — the cosign signature and SHA-256.

2. Run in dry-run

From the unpacked tarball, start Kapkan with the bundled example config and human-readable logs:

./kapkan -config deploy/config.example.yaml -log-format text

It runs in the foreground and prints logs to your terminal; press Ctrl-C to stop it cleanly.

-config points at the YAML config and -log-format text switches logs from the default structured JSON to a human-readable form — see the CLI reference for every flag and its accepted values.

In dry-run, Kapkan needs no special privileges and can run as a normal user. (Going live binds BGP to port 179, which needs root or the CAP_NET_BIND_SERVICE capability — the shipped systemd unit handles this; see Production deployment.)

The bundled deploy/config.example.yaml has dry_run: true, test protected networks of 203.0.113.0/24 and 2001:db8::/32, a protected_whitelist, and listens for sFlow on :6343 and NetFlow/IPFIX on :2055. Because dry-run is on, Kapkan records would-be blackholes but never announces a route.

iInstalled the package?

If you installed the .deb/.rpm, the same daemon runs as a service against /etc/kapkan/config.yaml instead — sudo systemctl start kapkan, then journalctl -u kapkan -f. See Production deployment.

3. Point your exporters at Kapkan

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

ProtocolDefault port
sFlow v5:6343
NetFlow v5/v9 + IPFIX:2055

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. Optional: no router? Validate detection from source

iThis is a developer path, not the binary path

This step does not use the prebuilt binary you downloaded above. It runs Kapkan's test suite, so it needs a source checkout and a Go toolchain. If you only have the .deb/.rpm/tarball and no router yet, skip this — point a router at the listen ports (step 3) when you have one. The synthetic-attack tooling (pkg/flowgen) is a test-suite package, not a command the shipped binary exposes.

What this proves: Kapkan detects an attack and would have blacklisted the victim — all without sending anything to a real router, since dry-run only records the would-be block (a virtual ban — a blackhole route Kapkan exposes through the API but never announces).

The test sends a fake NTP-amplification flood at a dry-run instance over a real UDP socket and checks the attack shows up in the API, with a virtual ban that later auto-expires by its TTL. Run it from a source checkout:

git clone https://github.com/fornex/kapkan && cd kapkan/engine
go test ./internal/app -run TestEndToEndNTPAmplification -v

Next steps