LLCForge network tooling — self-hosted, Rust, no SaaS. Pathology · Event Horizon · Catchment · Notary · Herald · Vigil
RPKI Route Origin Validation checker. Tells you whether your prefixes are RPKI-valid and watches third-party ASes.
English · Türkçe
More and more networks drop RPKI-invalid routes. A ROA with the wrong maxLength or a forgotten origin ASN quietly makes your prefix unreachable from half the Internet. Notary keeps a local, always-fresh copy of the validated ROA payloads and answers "is this route valid?" for your prefixes and for any AS you care about, before your customers notice.
Real output of notary check --file examples/routes.txt --vrps examples/vrps.json on sample data that uses documentation address ranges and private ASNs.
- VRP sources: an RTR client for your own validator (Routinator, rpki-client + StayRTR, FORT) over plain TCP, TLS (rustls, optional mutual TLS) or SSH (subsystem
rpki-rtr, pinned host key), or a JSON export ({"roas":[...], "aspas":[...]}) from a file orhttp(s)://URL. - RTR client: versions 0 (RFC 6810), 1 (RFC 8210) and 2 (draft-ietf-sidrops-8210bis, ASPA) with automatic step-down; Reset / Serial Query, incremental updates, Serial Notify, Cache Reset, End of Data timers, Error Reports. Strict per-PDU length checks, 64 KiB PDU cap.
- Route Origin Validation per RFC 6811:
Valid,Invalid(wrong_origin/max_length_exceeded),NotFound; every covering VRP is listed and explained. AS0 ROAs never match. - ASPA path verification (draft-ietf-sidrops-aspa-verification, upstream and downstream) with ASPA records from RTR v2 or JSON
aspas. - SLURM (RFC 8416) local filters and assertions, re-applied on every update and on config reload.
- ROA expiry warnings from rpki-client JSON
expiresor RoutinatorjsonextchainValidityfor every watched route. - ROA suggester (
notary suggest): minimal ROAs, maxLength = prefix length, for what an AS announces today. - maxLength audit (
notary audit, RFC 9319): VRPs that authorise prefixes the AS does not announce, with exact replacements. - IRR consistency (
notary irr): route/route6 objects from the RIPE DB REST API or any IRR whois server compared with ROAs. - Validator diff (
notary diff): two VRP sources side by side (JSON vs RTR, two caches, ...). - Bulk checks from a file or stdin, text or JSON Lines.
- VRP change history: every applied update is diffed and appended to a rotated JSON Lines log, queryable by prefix, ASN and time (
notary history,GET /v1/history). - Prefix sources for
[[watch_as]]: RIPEstat, your own routers via Pathology/v1/origins, and the bgp.tools table dump (union, last good list kept per source). - Daemon (
notary run): persistent watch state (no re-alerts after a restart, changes during downtime are caught), alerts through the shared llcforge-beacon dispatcher (Telegram, webhook with HMAC, Slack, Discord, Teams, e-mail, PagerDuty, Opsgenie, syslog, stdout) with a crash-safe queue, silences, dedup;/healthz/readyz; config reload on SIGHUP, file change orPOST /v1/reload; Windows service, systemd and launchd. - HTTP API and web UI on
127.0.0.1:8323: single and batch validity, status, history, ASPA, Prometheus/metrics, and an embedded prefix-search page. Optional bearer token.
Notary answers "should this origin exist?" from cryptographic data. Vigil and Pathology answer "does this origin exist right now?" from live routing data. They call Notary's /v1/validity to annotate every finding with its RPKI state, and Notary calls Pathology's /v1/origins to watch exactly what your routers originate.
Notary is a single static binary for Linux, macOS and Windows (x86_64 and aarch64). Release archives, packages and container images are produced by .github/workflows/release.yml.
Linux (deb / rpm + systemd)
sudo apt install ./notary_<version>_amd64.deb # or: sudo dnf install ./notary-<version>.x86_64.rpm
sudoedit /etc/notary/notary.toml # point [vrp] at your validator
echo 'NOTARY_TELEGRAM_TOKEN=...' | sudo tee /etc/notary/notary.env >/dev/null
sudo systemctl enable --now notary # unit: packaging/systemd/notary.service
sudo systemctl reload notary # SIGHUP: reload the configurationThe unit runs with DynamicUser=yes, StateDirectory=notary (/var/lib/notary) and a strict sandbox. notary service install prints the same steps.
macOS (Homebrew + launchd)
brew install llcforge/tap/notary # formula from the release's package-manifests archive
sudo install -m 0644 packaging/launchd/net.llcforge.notary.plist /Library/LaunchDaemons/
sudo launchctl bootstrap system /Library/LaunchDaemons/net.llcforge.notary.plistWindows (scoop / winget + service)
# Rendered scoop / winget manifests ship in notary-<version>-package-manifests.tar.gz
scoop install .\notary.json
# or, once the manifest is in winget-pkgs: winget install LLCForge.Notary
# Elevated PowerShell, from the release zip:
.\install-service.ps1 -Config .\notary.example.toml -EnvFile .\notary.envThe service runs as LocalService with its data in %ProgramData%\LLCForge\notary; see packaging/windows/README.md. notary service install|uninstall|run manages it directly.
Docker
docker compose up -d # docker-compose.yml: read-only rootfs, no capabilities, /data volumeThe image is distroless, non-root, and runs notary run --config /etc/notary/notary.toml. Inside a container set [api] listen = "0.0.0.0:8323" and publish the port deliberately.
Helm
helm install notary deploy/helm/notary --set-file config=notary.tomlProbes use /healthz and /readyz on port 8323; a ServiceMonitor, Grafana dashboard (deploy/grafana/notary-dashboard.json) and Prometheus rules (deploy/prometheus/notary-rules.yml) are included.
From source
git clone https://github.com/LLCForge/Notary.git && cd Notary
cargo build --release # Rust 1.89+, no C toolchain or OpenSSL needed
./target/release/notary check 198.51.100.0/24 AS64500 --vrps examples/vrps.jsonnotary check 198.51.100.0/24 AS64500 --vrps examples/vrps.json
notary check 192.0.2.0/24 64500 --rtr 192.0.2.10:3323
notary check 192.0.2.0/24 64500 --rtr tls://rpki.example.net --tls-ca-file ca.pem
notary check 192.0.2.0/24 64500 --rtr ssh://rtr@rpki.example.net \
--ssh-key-file ~/.ssh/rtr_ed25519 --ssh-host-key SHA256:AbCd...
notary check 2001:db8:1000::/36 AS64503 --vrps examples/vrps.json --json
notary check --file examples/routes.txt --vrps examples/vrps.json --slurm examples/slurm.json
bgp-export | notary check --file - --rtr 192.0.2.10:3323 --json # JSON LinesExit status: 0 Valid, 2 Invalid, 3 NotFound, 1 error. Bulk mode: 2 if any route is Invalid, else 3 if any is NotFound, 1 on unreadable lines. Example:
Route 198.51.100.0/24 origin AS64500
Source examples/vrps.json (6 VRPs)
Result INVALID (wrong origin)
Covering VRPs (2):
198.51.100.0/24 max /24 AS64501 origin mismatch
198.51.100.0/24 max /26 AS64502 origin mismatch
No covering VRP lists this origin AS. Networks that drop RPKI-invalid routes will reject it.
notary suggest AS64500 --vrps vrps.json # minimal ROAs for today's announcements
notary suggest AS64500 --prefixes-from http://127.0.0.1:8180 # your routers' view (Pathology)
notary audit AS64500 --rtr 192.0.2.10:3323 # RFC 9319 loose maxLength
notary irr AS64500 --vrps vrps.json # RIPE DB route objects vs ROAs
notary irr AS64500 --vrps vrps.json --irr whois://whois.radb.net
notary aspa "64511 64500" --vrps examples/vrps.json # neighbor first, origin last
notary aspa "64520 64510 64500" --direction downstream --rtr 192.0.2.10:3323 --rtr-version 2
notary diff vrps.json rtr://192.0.2.10:3323 # compare two validators
notary history --asn AS64500 --since 2026-01-01T00:00:00Z--prefixes-from takes ripestat (default), bgptools (needs --user-agent "<you> - <contact>", as bgp.tools requires) or a Pathology base URL (token from PATHOLOGY_API_TOKEN). audit, irr and diff exit 2 when they find something.
cp notary.example.toml notary.toml # then edit
notary run --config notary.toml
notary --log-format json run --config notary.toml
notary silence add --resource "192.0.2.0/24*" --duration 2h -m "ROA migration"Every key is documented in notary.example.toml. The important ones:
[vrp]
rtr = "tls://rpki.example.net" # host:port, tls://host[:port], ssh://user@host[:port]; or json = "..."
rtr_max_version = 2 # 2 = ASPA; steps down automatically
slurm = ["/etc/notary/slurm.json"]
expiry_warn_days = 7
[vrp.transport]
tls_ca_file = "/etc/notary/rtr-ca.pem"
# ssh_key_file / ssh_password_env / ssh_host_key = "SHA256:..."
[[watch]]
prefix = "198.51.100.0/24"
origin = 64500
[[watch_as]]
asn = 64501 # every prefix this AS originates
[prefix_sources]
ripestat = true
pathology_url = "http://127.0.0.1:8180"
[api]
listen = "127.0.0.1:8323"
token_env = "NOTARY_API_TOKEN" # optional bearer token for /v1/*
[[alerts.sink]]
type = "telegram"
bot_token_env = "NOTARY_TELEGRAM_TOKEN"
chat_id = -1001234567890Secrets are only ever names of environment variables. The pre-0.2 keys [alerts] webhook_url_env / telegram_token_env / telegram_chat_id still work and are translated into sinks (with a deprecation warning); a plain-http:// webhook to a non-loopback host now needs an explicit [[alerts.sink]] type = "webhook" with allow_http = true.
Alerts (tool = "notary"): state_change (resource "<prefix> AS<origin>", resolved when the route becomes Valid), roa_expiring, vrp_stale (resolved when fresh), vrp_empty_rejected. A watched route seen for the first time alerts only if it is Invalid. Watch state, VRP history, the alert queue and silences live in the data directory, so a restart neither repeats alerts nor misses a change that happened while Notary was down.
Reload (systemctl reload notary, a config file change, or POST /v1/reload with the admin token) applies alert sinks, SLURM, the watch list and prefix sources in place; the VRP source and API listener need a restart.
curl 'http://127.0.0.1:8323/v1/validity?prefix=198.51.100.0/24&asn=AS64500'
curl -X POST http://127.0.0.1:8323/v1/validity -H 'Content-Type: application/json' \
-d '{"routes":[{"prefix":"192.0.2.0/24","asn":64500},{"prefix":"198.51.100.0/24","asn":"AS64500"}]}'{"covering":[{"asn":64501,"max_length":24,"prefix":"198.51.100.0/24"},{"asn":64502,"max_length":26,"prefix":"198.51.100.0/24"}],"origin":64500,"prefix":"198.51.100.0/24","reason":"wrong_origin","stale":false,"state":"invalid"}| Endpoint | Returns |
|---|---|
GET /v1/validity?prefix=..&asn=.. |
state (valid / invalid / not_found), reason, covering, stale; 400 bad input, 503 before the first VRP set |
POST /v1/validity |
{"routes":[{"prefix","asn"}]} → {"results":[...]} in request order (bad entries carry error); at most max_batch (10000) routes, 4 MiB body |
GET /v1/status |
Source, VRP / ASPA counts, RTR serial / session / version, last update, stale, SLURM, last error |
GET /v1/history?prefix=&asn=&since=&limit= |
VRP change events, newest first |
GET /v1/aspa?path=64511+64500&direction=upstream |
ASPA verification with per-hop outcomes |
GET /healthz, GET /readyz |
Liveness; readiness = VRP data loaded and fresh |
GET /metrics |
notary_* and llcforge_beacon_* Prometheus metrics |
GET / |
Web UI: prefix search, covering VRPs, VRP history |
/v1/silences, POST /v1/reload |
Mounted only when their admin tokens are configured |
With [api] token_env set, every /v1/* route needs Authorization: Bearer <token>; the web UI has a token field that keeps the token in page memory only.
Measured with notary bench (release build, defaults: 600,000 IPv4 + 200,000 IPv6 synthetic VRPs, 2,000,000 routes, one thread) on an Intel Core Ultra 7 255HX laptop with 32 GB RAM, Windows 11. Two consecutive runs while other builds were running on the same machine:
| Step | Run 1 | Run 2 |
|---|---|---|
| Build the trie index (800,000 VRPs) | 466 ms | 422 ms |
| Validate a route (RFC 6811, covering VRPs collected and sorted) | 1,076,415 routes/s (929 ns) | 565,744 routes/s (1,768 ns) |
| Parse a JSON export (55.6 MiB) | 114.4 MiB/s | 90.4 MiB/s |
| Decode RTR prefix PDUs | 43.0 M PDUs/s | 35.3 M PDUs/s |
Run notary bench (or notary bench --vrps <your export>) to measure your own hardware; the second run shows how much a busy host costs.
Everything is pure Rust (rustls / ring, russh); no OpenSSL or C toolchain is needed on any OS. Notary needs no special privileges anywhere: it opens outbound TCP connections and one listening socket. SSH keys must be Ed25519 or ECDSA: RSA support is compiled out because the rsa crate carries an unfixed timing advisory (RUSTSEC-2023-0071). On Windows, configuration reload happens on file change or POST /v1/reload (there is no SIGHUP).
- ASPA over RTR v2 follows draft-ietf-sidrops-8210bis and is tested against an in-process cache; it has not yet been tested against a production cache speaking version 2.
- The bgp.tools source is implemented against the documented
table.jsonlformat (CIDR / ASN / Hits) and tested with fixtures; it was not exercised live in CI because bgp.tools asks for a personal contact in the User-Agent. - VRP history itemises changes only while the daemon runs; the first set after a start is recorded as a
baselinecount, so changes during downtime appear in watch alerts but not as itemised history. notary aspaverifies a given AS_PATH; the neighbor-AS and AS_SET pre-checks of the draft are the router's job and are only applied to the path you pass in.- The API has no per-connection header timeout; keep it on loopback or behind a reverse proxy if you expose it.
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.
- Pathology: 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.
- Herald: Certificate Transparency log monitor. Sends a Telegram alert the second a new TLS certificate is issued for your domains.
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.
Notary is free and open-source software released under the MIT License. See NOTICE for attributions.