LLCForge network tooling — self-hosted, Rust, no SaaS. Pathology · Event Horizon · Catchment · Notary · Herald · Vigil
BGP route monitor for your own routers and BMP feeds. Learns the AS paths and origins your prefixes normally use, then alerts on any deviation.
English · Türkçe
Public route collectors only see what reaches them, minutes late and from a handful of vantage points. Your own routers see every path, every upstream and every attribute change the moment it happens. Pathology turns that full-fidelity view into a learned baseline and tells you when reality stops matching it.
Real output of pathology --config pathology.example.toml replay tests/fixtures/demo.bmp.bin on sample data that uses documentation address ranges and private ASNs (long lines shortened).
Collectors
- BMP collector (RFC 7854) on TCP
0.0.0.0:11019: Initiation, Peer Up/Down, Route Monitoring, Statistics and Termination. Only routers inallowed_peersmay connect; a reconnecting router replaces its old session. - BMP Loc-RIB (RFC 9069): the router's own best paths (peer type 3) are tracked as
loc-ribof that router. Adj-RIB-Out messages (RFC 8671 O-flag) are ignored. - Passive BGP listener for routers without BMP: a receive-only session (OPEN with 4-byte AS, MP IPv4/IPv6 unicast and ADD-PATH receive, KEEPALIVEs, hold timer). Pathology never sends an UPDATE. Only configured peer addresses with the configured ASN are accepted.
- BGP decoding: IPv4 and MP-BGP IPv4/IPv6 unicast NLRI,
ORIGIN,AS_PATH(4-byte, sets, confederations),AS4_PATHmerging for 2-byte speakers (RFC 6793), ADD-PATH path identifiers (RFC 7911) negotiated from the BMP Peer Up OPENs or the BGP OPEN exchange,COMMUNITIESandLARGE_COMMUNITY(RFC 8092). OPEN capabilities including RFC 9072 extended optional parameters. - Defensive parsing: every length field is bounds-checked, messages are size-capped before allocation, no
unsafe(#![forbid(unsafe_code)]). A malformed message closes only that session.
Detection (typed findings, severities info / warning / critical)
new_origin(also any origin outsideexpected_origins),new_upstream,path_change,more_specific,withdrawn.prepend_change(same path with different prepending) andpath_length_change(length differs from every baseline length bypath_length_deltaor more).community_change: a standard or large community the watched prefix never carried before.route_leak: valley-free violation (RFC 7908) checked against a CAIDAas-relrelationship file, with your own ASN as the receiver.upstream_lost: the prefix is no longer reachable via a first-hop upstream it used; resolved automatically when the upstream returns.session_down(BMP router feed, BMP peer, passive BGP session; resolved when it comes back) andpeer_flap(N downs inside a window).- RPKI state on every finding through Notary (
valid,invalid,not_found, plusstale): optional, cached, time-boxed; a missing Notary never blocks an alert. - Baseline-based findings are downgraded to
infowhile the baseline is learning;expected_originsviolations never are.
Baseline
- Per watched prefix: weighted histograms of origins, upstreams, full paths, path lengths and communities in
<data_dir>/baseline.json(atomic temp-file + rename; version 1 files load unchanged). - Decay: with
baseline.half_lifethe weights halve every half-life and keys below 0.125 are forgotten, so paths unused for long stop counting as known. - MRT import:
pathology import-mrtseeds the baseline from TABLE_DUMP_V2 RIB dumps (including RFC 8050 ADD-PATH subtypes) and BGP4MP / BGP4MP_ET update files;.gzis read directly.
Route API and web UI (read-only, default 127.0.0.1:8180)
GET /v1/routes?prefix=<p>&since=<rfc3339>&limit=<n>: persisted announce/withdraw history (prefix and more-specifics), retention-bounded.GET /v1/prefixes/<p>/paths: the current best path per router/peer.GET /v1/origins?asn=<n>: prefixes currently originated by that AS as seen by your routers.GET /: embedded web UI (no CDN, no external requests) with a per-prefix AS path graph, current paths and recent events.- Optional bearer token, security headers (strict CSP,
nosniff,DENYframing), concurrency limit, request timeout, no request bodies.
Operations (shared llcforge-beacon kit)
- Alerts in the
llcforge.alert.v1schema to stdout, webhook (HMAC-signed), Telegram, Slack, Discord, Microsoft Teams, e-mail (SMTP), PagerDuty, Opsgenie and syslog; per-sink severity / kind / resource filters, retries with backoff, rate limits. - Crash-safe persistent alert queue with redelivery, deduplication by stable alert id, resolved alerts.
- Silences / maintenance windows:
pathology silence add|list|removeand/v1/silences. /healthz,/readyzand/metrics(Pathology and alert-pipeline metrics) on the management listener; Grafana dashboard and Prometheus rules indeploy/.- Configuration reload on
SIGHUP(Unix), on config file change (all OSes) orPOST /v1/reload. - Text or JSON logging;
pathology service install|uninstall|run(Windows service; systemd / launchd units for Linux / macOS). - Offline replay:
pathology replay <file>runs a raw BMP capture through the detector without a router.
Pathology vs. Vigil: both catch hijacks, but from opposite ends. Pathology is deep monitoring from your own infrastructure (BMP / BGP sessions): full paths, upstreams, communities, learned baselines. Vigil is fast, shallow detection from public feeds (RIPE RIS, RouteViews): it only asks "who is originating my prefix right now?" and needs no router access. Run Pathology for path-level insight inside your network; run Vigil to see what the rest of the Internet sees. They complement each other and do not duplicate work.
Status: pre-release. Configuration keys and CLI flags may change before 1.0.
Requirements: a recent stable Rust toolchain, 1.88 or newer (rustup.rs). No system libraries are needed (TLS uses rustls). Builds and runs on Linux, macOS and Windows.
git clone https://github.com/LLCForge/Pathology.git
cd Pathology
cargo build --release
# Try it without a router: replay the bundled demo capture
./target/release/pathology --config pathology.example.toml replay tests/fixtures/demo.bmp.bin
# Real deployment: copy the example, edit routers and prefixes, then run
cp pathology.example.toml pathology.toml
./target/release/pathology --config pathology.toml check
./target/release/pathology --config pathology.toml runPoint your router's BMP station at the host on port 11019, or configure a BGP neighbor towards the passive listener. Then open http://127.0.0.1:8180/ for the web UI.
Minimal pathology.toml (documentation addresses; see pathology.example.toml for every key):
[collector.bmp]
listen = "0.0.0.0:11019"
allowed_peers = ["192.0.2.1", "192.0.2.2"] # only these routers may connect
[[watch]]
prefix = "198.51.100.0/24"
expected_origins = [64500]
[[alerts.sink]]
type = "telegram"
bot_token_env = "TELEGRAM_BOT_TOKEN"
chat_id = -1001234567890
min_severity = "warning"
[metrics]
listen = "127.0.0.1:9419"Passive BGP instead of (or next to) BMP:
[collector.bgp]
listen = "0.0.0.0:179"
local_asn = 64496
router_id = "192.0.2.254"
[[collector.bgp.peer]]
address = "192.0.2.3"
asn = 64503Secrets (bot tokens, webhook secrets, API tokens) are always read from environment variables named by the *_env keys, never from the config file. Durations accept s, m, h and d suffixes.
Upgrading from the first release: the old
[alerts] min_severity / webhook / telegramkeys are replaced by[[alerts.sink]]entries (with a per-sinkmin_severity);pathology checkreports the offending key.storage.data_dirnow defaults to the platform data directory.
| Platform | Package | Service |
|---|---|---|
| Debian / Ubuntu | .deb from the release page (cargo deb) |
sudo systemctl enable --now pathology (unit installed, not enabled) |
| RHEL / Fedora | .rpm from the release page (cargo generate-rpm) |
same systemd unit |
| macOS | brew install with packaging/homebrew/pathology.rb |
launchd: packaging/launchd/net.llcforge.pathology.plist |
| Windows | scoop install with packaging/scoop/pathology.json or the winget manifests in packaging/winget |
pathology --config C:\ProgramData\LLCForge\pathology\pathology.toml service install (Administrator) |
| Docker | docker compose up -d (docker-compose.yml, distroless, non-root) |
container |
| Kubernetes | helm install pathology deploy/helm/pathology |
Deployment + PVC |
- Linux: the packaged unit runs with
DynamicUser=yesand state in/var/lib/pathology($STATE_DIRECTORY). Put secrets in/etc/pathology/pathology.env(mode 0600).systemctl reload pathologysendsSIGHUP(configuration reload). For a passive BGP listener on port 179 addAmbientCapabilities=CAP_NET_BIND_SERVICEandCapabilityBoundingSet=CAP_NET_BIND_SERVICEin a drop-in, or listen on a port above 1023. - macOS:
pathology service installprints the launchd steps. Binding port 179 works unprivileged on macOS 10.14 and later. - Windows:
service installregisters a Windows service that runspathology service run --config <path>;service uninstallremoves it. Data lives in%ProgramData%\LLCForge\pathology. Port 179 needs no special privilege; allow the listener in Windows Defender Firewall. - Docker / Helm: set the management listener and
api.listento0.0.0.0inside the container; probes use/healthzand/readyzon port 9419. The chart exposes BMP (11019) and the API (8180).
Grafana dashboard: deploy/grafana/pathology-dashboard.json; alert rules: deploy/prometheus/pathology-rules.yml.
pathology [--config <FILE>] [run] run collectors, detector, API and alerting (default)
pathology [--config <FILE>] check validate config and every referenced secret, then exit
pathology [--config <FILE>] replay <FILE> [--all] replay a raw BMP capture offline (--all: include info)
pathology [--config <FILE>] import-mrt <FILE>... seed the baseline from MRT dumps (.gz accepted)
pathology [--config <FILE>] silence add|list|remove
pathology [--config <FILE>] service install|uninstall|run
pathology --version
--config defaults to pathology.toml. Replay uses the watch list and detection settings from the config but always starts from an empty in-memory baseline, uses the router timestamps from the capture as its clock, and never sends alerts or writes state. A capture is the raw TCP byte stream a router sends to its BMP station, for example recorded with nc -l 11019 > capture.bin. Stop the service before import-mrt: it rewrites baseline.json. bzip2 dumps (RouteViews) must be decompressed first (bunzip2 -k).
Example output of the demo replay:
2026-03-16T09:00:00Z WARNING path_change 198.51.100.0/24 via 192.0.2.1 (AS64501): AS path 64501 64511 64500 never seen in baseline
2026-03-16T09:05:00Z WARNING new_upstream 198.51.100.0/24 via 192.0.2.3 (AS64503): first-hop upstream AS64503 never seen in baseline (path 64503 64500)
2026-03-16T09:12:00Z CRITICAL more_specific 198.51.100.128/25 via 192.0.2.1 (AS64501): more-specific of watched 198.51.100.0/24 announced, origin AS64510 (path 64501 64510)
2026-03-16T09:12:05Z CRITICAL new_origin 198.51.100.0/24 via 192.0.2.2 (AS64502): origin AS64510 is not in expected_origins [64500] (path 64502 64510)
2026-03-16T09:20:00Z WARNING withdrawn 2001:db8:100::/48 via 192.0.2.1 (AS64501): watched prefix withdrawn by this peer
2026-03-16T09:20:00Z WARNING upstream_lost 2001:db8:100::/48 via 192.0.2.1 (AS64501): no longer reachable via upstream AS64501
2026-03-16T09:25:00Z CRITICAL new_origin 2001:db8:100::/48 via 192.0.2.1 (AS64501): origin AS64509 never seen in baseline (path 64501 64509)
2026-03-16T09:25:00Z RESOLVED upstream_lost 2001:db8:100::/48 via 192.0.2.1 (AS64501): reachable via upstream AS64501 again
2026-03-16T09:30:00Z WARNING upstream_lost 198.51.100.0/24 via 192.0.2.3 (AS64503): no longer reachable via upstream AS64503
2026-03-16T09:30:00Z WARNING session_down peer 192.0.2.3: peer down (BMP reason 4)
replayed 24 BMP messages: 3 critical, 6 warning, 4 info, 1 session events (10 shown, min_severity=warning)
Route API (add -H "Authorization: Bearer $PATHOLOGY_API_TOKEN" when api.token_env is set):
curl -s 'http://127.0.0.1:8180/v1/prefixes/198.51.100.0/24/paths'
curl -s 'http://127.0.0.1:8180/v1/routes?prefix=198.51.100.0/24&since=2026-03-16T09:00:00Z&limit=50'
curl -s 'http://127.0.0.1:8180/v1/origins?asn=64500'/v1/routes returns events oldest first: those at or after since (first limit), or the latest limit events without since (limit defaults to 100, maximum 1000). /v1/prefixes/<p>/paths picks, per router and peer, the shortest AS path (ADD-PATH peers send several). Management endpoints: curl -s http://127.0.0.1:9419/metrics, /healthz, /readyz.
Everything listed under Features is implemented and tested. Known gaps:
- TCP-MD5 (RFC 2385) on the passive BGP listener is not supported; configure the session without a password (or protect it with ACLs / GTSM on the router).
- The passive listener only accepts sessions (it never connects out) and resolves a connection collision by replacing the older session instead of RFC 4271 collision detection.
- A malformed UPDATE resets the session; RFC 7606 treat-as-withdraw is not implemented.
- Route leak detection is only as accurate as the relationship file; ASPA (draft-ietf-sidrops-aspa-verification) is not used here (see Notary).
- MRT: legacy
TABLE_DUMP(v1),RIB_GENERICand bzip2 input are not read directly. - BMP Route Mirroring messages are not decoded; Adj-RIB-Out monitoring is skipped.
- Interoperability has been tested with synthetic BMP / BGP / MRT data and the in-repo encoders, not yet against every router vendor.
See ARCHITECTURE.md for components, data flow, trust boundaries and failure modes.
- Vigil: Real-time origin hijack detection over public RIPE RIS and RouteViews feeds. Flags the moment someone else announces your prefix.
- Notary: RPKI Route Origin Validation checker. Pathology attaches its verdict to every finding; Notary can read your announced prefixes from Pathology's
/v1/origins. - Catchment: anycast catchment monitor; on a catchment shift it fetches path changes from Pathology's
/v1/routes. - Event Horizon: Automated RTBH in Rust. On DDoS detection it announces the victim prefix as a blackhole and sends the BGP community upstream.
Issues and pull requests are welcome. Read CONTRIBUTING.md and the Code of Conduct first. Found a vulnerability? Do not open a public issue; follow SECURITY.md.
Pathology is free and open-source software released under the MIT License. See NOTICE for attributions.