LLCForge network tooling — self-hosted, Rust, no SaaS. Pathology · Event Horizon · Catchment · Notary · Herald · Vigil
Real-time origin hijack detection over public route collector feeds: RIPE RIS Live, the RouteViews BMP stream and MRT archives. Flags the moment someone else announces your prefix.
English · Türkçe
If another AS starts originating your prefix, or a more-specific of it, traffic from part of the Internet goes to them instead of you. You cannot see this from your own routers because the bad route never reaches you. Vigil watches hundreds of public BGP peers in real time and alerts within seconds of the first announcement, with zero access to your network required.
Real output of vigil --config vigil.example.toml replay examples/ris-sample.jsonl on sample data that uses documentation address ranges and private ASNs (2 of 6 alerts shown).
Feeds (any combination; all pure Rust, no system libraries)
- RIPE RIS Live over WebSocket (rustls). Vigil subscribes server-side to each watched prefix and its more-specifics and follows watch-list changes on the open session.
- RouteViews BMP stream over Kafka (
rskafka+bgpkit-parser): OpenBMP raw BMP messages, topics selected by glob (routeviews.amsix.*.bmp_raw).vigil kafka-topicslists what your globs match. - MRT update files via the BGPKIT broker (RouteViews and RIS collectors, minutes of delay), downloaded only from allow-listed archive hosts.
- Historical replay of the RIS MRT archive for a date range (
vigil replay-mrt --collector rrc00 --from … --to …) or of local MRT files, and of saved RIS Live JSON.
Detection
- Exact-prefix origin hijacks, sub-prefix hijacks (beyond
max_length, whatever origin they claim), MOAS, AS_SET origins (flagged, not guessed). - Squatting: announcements of registered but unannounced (
dormant = true) space. - Expected upstreams: a route whose neighbour of the origin is not in
upstreamsis reported (simple leak detection). - Scrubbing providers: a built-in, documented, overridable list of DDoS mitigation ASNs (see below); their announcements of your space become a
scrubbing_originwarning instead of a critical hijack (or no alert, or a normal hijack). - Time-boxed
[[exception]]entries, longest-prefix matching over IPv4 and IPv6. - Watch by ASN:
[[asn]]fetches the prefixes your AS originates from RIPEstat and refreshes them. - Event Horizon blackholes: polls Event Horizon's
GET /v1/blackholes, subscribes the /32 and /128 routes, and alerts when a blackhole is not visible at any RIS peer after a grace period. Your own RTBH more-specifics are not reported as sub-prefix hijacks. - Visibility: share of RIS full-feed peers that carry each watched prefix (RIPEstat routing-status, adjusted live by peer withdrawals);
visibility_lossalert belowmin_ratio, Prometheus gauge andGET /v1/visibility.
Alerts and operations (shared llcforge-beacon kit)
- Aggregation (peers, collectors, first seen) and dedup; resolution with the same alert id once the route has been gone for
resolve_after_secs. - Incident timeline (
vigil incidents,GET /v1/incidents), persisted. - Enrichment: RPKI state from Notary and AS names + country (local CSV, then RIPEstat, cached); each lookup is time-boxed and never delays an alert.
- Sinks: stdout, webhook (HMAC-signed), Telegram, Slack, Discord, Teams, e-mail, PagerDuty, Opsgenie, syslog; per-sink filters give per-prefix-group recipients (
resources = ["core/*"]). Persistent queue, silences (vigil silence add|list|removeand API),/healthz/readyz, JSON or text logs, config reload (SIGHUP, file change,POST /v1/reload),vigil service install|uninstall|run. - Prometheus metrics, Grafana dashboard and alerting rules in
deploy/. - No router access, no BGP session, no credentials to your network.
Vigil vs. Pathology: both catch hijacks, but from opposite ends. Vigil is fast, shallow detection from public feeds (RIPE RIS, RouteViews): it checks prefix, origin and the neighbour of the origin, needs no router access and is the first to see a hijack that never reaches your network. Pathology is deep monitoring from your own infrastructure (BMP / BGP): full AS paths, communities and learned baselines. Use Vigil for the outside view, Pathology for the inside view.
Cross-tool contracts: Vigil serves GET /v1/visibility?prefix=<p> → {"prefix","peers_seeing","peers_total","ratio","as_of"}; it calls Notary GET /v1/validity (field state, falling back to older field names; stale: true is shown as (stale)) and Event Horizon GET /v1/blackholes. Every call is optional, time-boxed and never delays an alert.
Release archives, packages and images are built by .github/workflows/release.yml for Linux (x86_64/aarch64, glibc and musl), macOS (Intel and Apple silicon) and Windows (x86_64 and ARM64).
- Linux, deb/rpm:
sudo apt install ./vigil_*.deborsudo dnf install ./vigil-*.rpm. The package installs/usr/bin/vigil,/etc/vigil/vigil.tomland the hardened systemd unit (not enabled). Put secrets in/etc/vigil/vigil.env(mode 0600), thensudo systemctl enable --now vigil.systemctl reload vigilreloads the configuration. - macOS, Homebrew:
brew install llcforge/tap/vigil; run under launchd withbrew services start vigilor the plist inpackaging/launchd. - Windows:
scoop install vigil(bucket manifest inpackaging/scoop) orwinget install LLCForge.Vigil; install the Windows service from an elevated PowerShell withpackaging/windows/install-service.ps1, orvigil service install --config C:\ProgramData\LLCForge\vigil\vigil.toml. - Docker:
docker compose up -dwithdocker-compose.yml(read-only root, no capabilities,/datavolume). Set[health] listen = "0.0.0.0:9184"in the mounted config so the published port works. - Kubernetes:
helm install vigil deploy/helm/vigil(config invalues.yaml, probes on/healthzand/readyz, optional ServiceMonitor). - From source: a stable Rust toolchain (1.88+),
cargo build --release. No system libraries on Linux, macOS or Windows.
Vigil needs no special privileges on any OS: it only opens outbound TCP connections (443 to RIS Live / RIPEstat / BGPKIT, 80 to the RouteViews archive, 9092 to the RouteViews Kafka brokers) and its own management listener.
Status: pre-release. Configuration keys and CLI flags may change before 1.0.
git clone https://github.com/LLCForge/Vigil.git
cd Vigil
cargo build --release
cp vigil.example.toml vigil.toml # then edit prefixes and origins
./target/release/vigil --config vigil.toml check-config
./target/release/vigil --config vigil.toml runTry it offline first, with the bundled samples (documentation prefixes and ASNs):
./target/release/vigil --config vigil.example.toml replay examples/ris-sample.jsonl
./target/release/vigil --config vigil.example.toml replay examples/ris-squat.jsonlUsage: vigil [OPTIONS] <COMMAND>
Commands:
run Watch the configured feeds and send alerts until stopped
check-config Validate the configuration (and required environment variables) and exit
replay Run saved RIS Live messages (JSON lines) through the detector offline
replay-mrt Replay MRT update files: local files, or a RIS archive date range
incidents Show the incident timeline recorded by `vigil run`
kafka-topics List Kafka topics matched by [feeds.routeviews_kafka]
silence Manage silences (maintenance windows)
service Install, uninstall or run as a system service
help Print this message or the help of the given subcommand(s)
Options:
-c, --config <CONFIG> Path to the TOML configuration file [default: vigil.toml]
-h, --help Print help
-V, --version Print version
run stops cleanly on Ctrl+C or SIGTERM, flushing pending alerts first. replay and replay-mrt use message timestamps as their clock, print alerts to stdout and never send to sinks. replay-mrt --collector rrc00 --from 2026-11-01T00:00:00Z --to 2026-11-01T06:00:00Z downloads the 5-minute RIS update files of that range (at most 7 days) and skips missing ones. Logs go to stderr.
Full example: vigil.example.toml. Addresses and ASNs are documentation values; replace them with your own. Unknown keys are rejected and the whole file is validated at startup. Secrets are never in the file, only the names of environment variables (*_env).
[feeds]
ris_live = true
feed_down_grace_secs = 120
[feeds.routeviews_kafka] # optional
brokers = ["stream.routeviews.org:9092"]
topics = ["routeviews.amsix.*.bmp_raw"]
[feeds.bgpkit] # optional
collectors = ["route-views2", "rrc00"]
[detection]
aggregation_window_secs = 10
dedup_secs = 3600
resolve_after_secs = 600
scrubbing = "warn" # warn | allow | off
[[prefix]]
prefix = "198.51.100.0/24"
origins = [64500]
max_length = 24
upstreams = [64496, 64497] # optional expected neighbours of the origin
group = "core" # alert resource "core/198.51.100.0/24"
[[prefix]]
prefix = "192.0.2.0/24"
dormant = true # registered, never announced: squatting
[[asn]] # optional: watch all prefixes of an AS
asn = 64500
[[exception]]
origin = 64505
prefix = "198.51.100.0/24"
until = "2030-01-01T00:00:00Z"
[enrich.notary]
url = "http://127.0.0.1:8323"
[enrich.asnames] # RIPEstat as-overview + rir-stats-country
file = "/etc/vigil/asnames.csv" # optional "asn,name,country" lines, consulted first
[visibility]
enabled = true
min_ratio = 0.5
[event_horizon]
url = "http://127.0.0.1:8080"
token_env = "EVENT_HORIZON_TOKEN"
[[alerts.sink]]
type = "telegram"
bot_token_env = "VIGIL_TELEGRAM_TOKEN"
chat_id = -1001234567890
resources = ["core/*"] # this chat only gets the "core" group
[[alerts.sink]]
type = "syslog"
transport = "udp"
address = "127.0.0.1:514"
[log]
format = "json"
[health]
listen = "127.0.0.1:9184" # /metrics, /healthz, /readyz, /v1/*Without any [[alerts.sink]], alerts go to stdout as before. The pre-0.2 [alerts] stdout/telegram/webhook keys are rejected with a pointer to the new [[alerts.sink]] form; [metrics] listen is still accepted as an alias of [health] listen.
| Kind | Severity | Fires when |
|---|---|---|
origin_hijack |
critical | A watched prefix (or more-specific within max_length) is announced by an origin not in origins and not excepted. |
sub_prefix_hijack |
critical | A more-specific beyond max_length is announced, by any origin (except your own Event Horizon blackholes). |
squatting |
critical | Dormant space is announced. |
moas |
warning | Two or more origins announce the same prefix at once and one of them is not allowed. |
ambiguous_origin |
warning | The AS path ends in an AS_SET. |
scrubbing_origin |
warning | A known scrubbing provider originates your prefix (scrubbing = "warn"). |
unexpected_upstream |
warning | The neighbour of a legitimate origin is not in upstreams. |
visibility_loss |
warning | Fewer than min_ratio of RIS full-feed peers see the prefix. |
blackhole_not_visible |
warning | An Event Horizon blackhole is not seen by any RIS peer after grace_secs. |
feed_down |
warning | A feed has been unreachable longer than feed_down_grace_secs. |
Every alert has a stable id (vigil:<kind>:<prefix>:<origin>); when the condition clears, the same id is sent again with resolved = true.
Holder names checked against RIPEstat as-overview on 2026-11-13. Override with detection.scrubbing_asns.
| ASN | Provider |
|---|---|
| AS13335 | Cloudflare (Magic Transit) |
| AS19551 | Imperva / Incapsula |
| AS19905 | Vercara (UltraDDoS Protect) |
| AS32787 | Akamai Prolexic |
| AS55002 | F5 Silverline (Defense.Net) |
Verified on 2026-11-13: stream.routeviews.org:9092 answers Kafka metadata requests without authentication, topics follow routeviews.<collector>.<peer-asn>.bmp_raw (the routeviews.amsix.*.bmp_raw glob matched 139 topics), and records are OpenBMP v1.7 headers with raw BMP messages, decoded by Vigil without errors (about 20,000 records per 40 s on that glob). Sources: the topic scheme as described by the BGPStream maintainers and the bgpkit-parser RouteViews Kafka example; RouteViews itself documents the stream only in presentations. TLS and SASL are not used by that endpoint and are not implemented; compressed record batches are supported with gzip and snappy only (no lz4/zstd, to stay free of C libraries).
- Kafka TLS/SASL and lz4/zstd record batches (not needed for the public RouteViews endpoint today).
- BMP Peer Down handling: today a route stays "current" until it is withdrawn or replaced, so an incident whose only carrier peer goes down is resolved late.
- Visibility counts RIS peers only (RIPEstat routing-status); RouteViews peers are not part of the ratio.
See ARCHITECTURE.md for components, data flow, trust boundaries and failure modes.
- Pathology: BGP route monitor for your own routers and BMP feeds.
- Event Horizon: DDoS detection and RTBH; Vigil checks its blackholes from the outside.
- Notary: RPKI Route Origin Validation checker; Vigil adds its verdict to alerts.
- Herald: Certificate Transparency log monitor.
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.
Vigil is free and open-source software released under the MIT License. See NOTICE for attributions.