Skip to content

bgpkit/monocle

BranchesTags

Repository files navigation

Monocle

Rust Crates.io Docs.rs License

See through all Border Gateway Protocol (BGP) data with a monocle.

Table of Contents

Install

Using cargo

cargo install monocle

Using homebrew on macOS

brew install monocle

Using cargo-binstall

Install cargo-binstall first:

cargo install cargo-binstall

Then install monocle using cargo binstall

cargo binstall monocle

Using Docker

Pull the pre-built image or build locally:

# Build the image locally
docker build -t bgpkit/monocle:latest .

# Or use docker compose
docker compose build

Run monocle commands:

# Show help
docker run --rm bgpkit/monocle:latest

# Run a command (e.g., inspect an ASN)
docker run --rm bgpkit/monocle:latest inspect 13335

# Run with persistent data directory
docker run --rm -v monocle-data:/data bgpkit/monocle:latest inspect 13335

# Start the WebSocket server
docker run --rm -p 8080:8080 -v monocle-data:/data bgpkit/monocle:latest server --address 0.0.0.0 --port 8080

# Using docker compose for server mode
docker compose up -d

Library Usage

Monocle can also be used as a library in your Rust projects. Add it to your Cargo.toml:

[dependencies]
# Full library with CLI argument support (default)
monocle = "1.0"

# Minimal database access only
monocle = { version = "1.0", default-features = false, features = ["database"] }

# BGP operations without CLI overhead
monocle = { version = "1.0", default-features = false, features = ["lens-bgpkit"] }

# Full functionality without CLI
monocle = { version = "1.0", default-features = false, features = ["lens-full"] }

Feature Tiers

Monocle's features are organized in tiers for minimal dependency footprint:

Feature Description Key Dependencies
database SQLite operations only rusqlite, oneio, ipnet, chrono
lens-core Standalone lenses (TimeLens) chrono-humanize, dateparser
lens-bgpkit BGP-related lenses bgpkit-*, rayon, tabled
lens-full All lenses including InspectLens All above
cli (default) Full CLI binary with server axum, tokio, tower-http

Architecture

The library is organized into the following core modules:

  • database: All database functionality

    • core: Connection management and schema definitions
    • session: One-time storage for search results
    • monocle: Main monocle database with ASInfo, AS2Rel, RPKI, and Pfx2as caching

  • lens: High-level business logic (reusable across CLI, API, GUI)

    • time: Time parsing and formatting lens (lens-core)
    • country: Country code/name lookup lens (lens-bgpkit)
    • ip: IP information lookup lens (lens-bgpkit)
    • parse: MRT file parsing lens with progress tracking (lens-bgpkit)
    • search: BGP message search lens with progress tracking (lens-bgpkit)
    • rpki: RPKI validation and data lens (lens-bgpkit)
    • pfx2as: Prefix-to-AS mapping types (lens-bgpkit)
    • as2rel: AS-level relationships lens (lens-bgpkit)
    • inspect: Unified AS/prefix inspection lens (lens-full)

  • server: WebSocket API server (cli feature)

For detailed architecture documentation, see ARCHITECTURE.md.

Example: Using Lenses

use monocle::database::MonocleDatabase;
use monocle::lens::inspect::{InspectLens, InspectQueryOptions};

fn main() -> anyhow::Result<()> {
    // Open the monocle database
    let db = MonocleDatabase::open_in_dir("~/.monocle")?;
    
    // Create a lens
    let lens = InspectLens::new(&db);
    
    // Query AS information
    let options = InspectQueryOptions::default();
    let results = lens.query_asn(13335, &options)?;
    
    println!("AS{}: {}", results.asn, results.name.unwrap_or_default());
    
    Ok(())
}

Example: Parse MRT Files with Progress

use monocle::lens::parse::{ParseLens, ParseFilters, ParseProgress};
use std::sync::Arc;

fn main() -> anyhow::Result<()> {
    let lens = ParseLens::new();
    let filters = ParseFilters::default();
    
    // Define a progress callback
    let callback = Arc::new(|progress: ParseProgress| {
        match progress {
            ParseProgress::Started { file_path } => {
                eprintln!("Started parsing: {}", file_path);
            }
            ParseProgress::Update { messages_processed, rate, .. } => {
                eprintln!("Processed {} messages ({:.0} msg/s)", 
                    messages_processed, rate.unwrap_or(0.0));
            }
            ParseProgress::Completed { total_messages, duration_secs, .. } => {
                eprintln!("Completed: {} messages in {:.2}s", total_messages, duration_secs);
            }
        }
    });
    
    // Parse with progress tracking
    let elems = lens.parse_with_progress(
        &filters, 
        "path/to/file.mrt", 
        Some(callback)
    )?;
    
    for elem in elems {
        println!("{:?}", elem);
    }
    
    Ok(())
}

Usage

Subcommands:

  • parse: parse individual MRT files
  • search: search for matching messages from all available public MRT files
  • server: start a WebSocket server for programmatic access
  • inspect: unified AS and prefix information lookup
  • country: utility to look up country name and code
  • time: utility to convert time between unix timestamp and RFC3339 string
  • as2rel: AS-level relationship lookup between ASNs
  • pfx2as: prefix-to-ASN mapping lookup with RPKI validation
  • rpki: RPKI validation and ROA/ASPA listing
  • ip: IP information lookup
  • config: configuration display and database management (refresh, backup, sources)

Global Options

All commands support the following global options:

  • --format <FORMAT>: Output format (table, markdown, json, json-pretty, json-line, psv)
  • --json: Shortcut for --format json-pretty
  • --debug: Print debug information

Top-level help menu:

➜  ~ monocle                      
A commandline application to search, parse, and process BGP information in public sources.


Usage: monocle [OPTIONS] <COMMAND>

Commands:
  parse    Parse individual MRT files given a file path, local or remote
  search   Search BGP messages from all available public MRT files
  server   Start the WebSocket server (ws://<address>:<port>/ws, health: http://<address>:<port>/health)
  inspect  Unified AS and prefix information lookup
  country  Country name and code lookup utilities
  time     Time conversion utilities
  rpki     RPKI utilities
  ip       IP information lookup
  as2rel   AS-level relationship lookup between ASNs
  config   Show monocle configuration, data paths, and database management
  help     Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>  configuration file path, by default $HOME/.monocle.toml is used
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help
  -V, --version          Print version

monocle parse

Parsing a single MRT file given a local path or a remote URL.

➜  monocle parse --help
Parse individual MRT files given a file path, local or remote

Usage: monocle parse [OPTIONS] <FILE>

Arguments:
  <FILE>  File path to a MRT file, local or remote

Options:
      --debug                    Print debug information
      --format <FORMAT>          Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json                     Output as JSON objects (shortcut for --format json-pretty)
  -M, --mrt-path <MRT_PATH>      MRT output file path
  -o, --origin-asn <ORIGIN_ASN>  Filter by origin AS Number
  -p, --prefix <PREFIX>          Filter by network prefix
  -s, --include-super            Include super-prefix when filtering
  -S, --include-sub              Include sub-prefix when filtering
  -j, --peer-ip <PEER_IP>        Filter by peer IP address
  -J, --peer-asn <PEER_ASN>      Filter by peer ASN
  -m, --elem-type <ELEM_TYPE>    Filter by elem type: announce (a) or withdraw (w)
  -t, --start-ts <START_TS>      Filter by start unix timestamp inclusive
  -T, --end-ts <END_TS>          Filter by end unix timestamp inclusive
  -h, --help                     Print help

Example: parse a remote MRT file and show only announcements for a specific prefix:

➜  monocle parse https://data.ris.ripe.net/rrc00/2024.01/updates.20240101.0000.gz \
    -p 1.1.1.0/24 -m a | head -5
┌──────────┬─────────────────────┬───────────────────────────┬──────────┬────────────┬───────────────────────────────────────────┬────────┬─────────────┬───────────────────────────┬────────────┬─────┬─────────────┬────────┬──────────┬─────────┬──────────────────┬─────────┬────────────┬───────────┐
│ type     │ timestamp           │ peer_ip                   │ peer_asn │ prefix     │ as_path                                   │ origin │ origin_asns │ next_hop                  │ local_pref │ med │ communities │ atomic │ aggr_asn │ aggr_ip │ only_to_customer │ unknown │ deprecated │ collector │
├──────────┼─────────────────────┼───────────────────────────┼──────────┼────────────┼───────────────────────────────────────────┼────────┼─────────────┼───────────────────────────┼────────────┼─────┼─────────────┼────────┼──────────┼─────────┼──────────────────┼─────────┼────────────┼───────────┤
│ announce │ 2024-01-01 00:00:44 │ 2001:7f8:4::9d85:1        │ 40325    │ 1.1.1.0/24 │ 40325 13335                               │ IGP    │ 13335       │ 2001:7f8:4::9d85:1        │            │     │             │ false  │          │         │                  │         │            │           │
│ announce │ 2024-01-01 00:00:50 │ 2001:7f8:4::3:2e8b:1      │ 208571   │ 1.1.1.0/24 │ 208571 6939 13335                         │ IGP    │ 13335       │ 2001:7f8:4::3:2e8b:1      │            │     │             │ false  │          │         │                  │         │            │           │

Output Format

The output contains the following fields:

Field Description
type Message type: announce or withdraw
timestamp Message timestamp in UTC
peer_ip IP address of the BGP peer
peer_asn ASN of the BGP peer
prefix Network prefix being announced/withdrawn
as_path AS path (space-separated)
origin Origin type: IGP, EGP, or INCOMPLETE
origin_asns Origin AS number(s)
next_hop Next hop IP address
local_pref Local preference value
med Multi-exit discriminator
communities BGP communities
atomic Atomic aggregate flag
aggr_asn Aggregator ASN
aggr_ip Aggregator IP
only_to_customer OTC attribute (RFC 9234)
unknown Unknown attributes
deprecated Deprecated attributes
collector Collector name (for search results)

JSON output example:

{
  "type": "announce",
  "timestamp": "2024-01-01T00:00:44Z",
  "peer_ip": "2001:7f8:4::9d85:1",
  "peer_asn": 40325,
  "prefix": "1.1.1.0/24",
  "as_path": "40325 13335",
  "origin": "IGP",
  "origin_asns": [13335],
  "next_hop": "2001:7f8:4::9d85:1",
  "local_pref": null,
  "med": null,
  "communities": [],
  "atomic": false,
  "aggr_asn": null,
  "aggr_ip": null,
  "only_to_customer": null,
  "unknown": null,
  "deprecated": null,
  "collector": null
}

monocle search

Search for BGP messages from all available public MRT files using BGPKIT Broker.

➜  monocle search --help
Search BGP messages from all available public MRT files

Usage: monocle search [OPTIONS] --start-ts <START_TS> --end-ts <END_TS>

Options:
      --debug                        Print debug information
      --format <FORMAT>              Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json                         Output as JSON objects (shortcut for --format json-pretty)
  -t, --start-ts <START_TS>          Start timestamp (RFC3339 or Unix)
  -T, --end-ts <END_TS>              End timestamp (RFC3339 or Unix)
  -c, --collector <COLLECTOR>        Filter by collector name
      --project <PROJECT>            Filter by project (riperis, routeviews)
  -d, --dump-type <DUMP_TYPE>        Dump type: updates or rib [default: updates]
  -o, --origin-asn <ORIGIN_ASN>      Filter by origin AS Number
  -p, --prefix <PREFIX>              Filter by network prefix
  -s, --include-super                Include super-prefix when filtering
  -S, --include-sub                  Include sub-prefix when filtering
  -j, --peer-ip <PEER_IP>            Filter by peer IP address
  -J, --peer-asn <PEER_ASN>          Filter by peer ASN
  -m, --elem-type <ELEM_TYPE>        Filter by elem type: announce (a) or withdraw (w)
      --as-path <AS_PATH>            Filter by AS path regex
      --broker-files                 Show broker file list only (don't parse)
  -h, --help                         Print help

Example: search for BGP announcements for a prefix during a specific time window:

➜  monocle search -t 2024-01-01T00:00:00Z -T 2024-01-01T00:01:00Z \
    -c rrc00 -p 1.1.1.0/24 -m a

Use --broker-files to see the list of MRT files that would be queried without actually parsing them:

➜  monocle search -t 2024-01-01T00:00:00Z -T 2024-01-01T01:00:00Z \
    -c rrc00 --broker-files

monocle time

Parse and convert time strings between various formats.

➜  monocle time --help
Time conversion utilities

Usage: monocle time [OPTIONS] [TIMES]...

Arguments:
  [TIMES]...  Time strings to parse (Unix timestamp, RFC3339, or human-readable)

Options:
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help

Examples:

➜  monocle time 1704067200
┌────────────┬──────────────────────┬─────────────────────────────────────┐
│ unix       │ rfc3339              │ human                               │
├────────────┼──────────────────────┼─────────────────────────────────────┤
│ 1704067200 │ 2024-01-01T00:00:00Z │ Mon, Jan 1, 2024 at 12:00:00 AM UTC │
└────────────┴──────────────────────┴─────────────────────────────────────┘

➜  monocle time "2024-01-01T00:00:00Z"
┌────────────┬──────────────────────┬─────────────────────────────────────┐
│ unix       │ rfc3339              │ human                               │
├────────────┼──────────────────────┼─────────────────────────────────────┤
│ 1704067200 │ 2024-01-01T00:00:00Z │ Mon, Jan 1, 2024 at 12:00:00 AM UTC │
└────────────┴──────────────────────┴─────────────────────────────────────┘

➜  monocle time "yesterday" "last week"

monocle inspect

Unified AS and prefix information lookup. Replaces the former whois and pfx2as commands.

By default, inspect shows all available information for ASN and prefix queries, including:

  • Basic: AS name, country, organization, and PeeringDB info (website, IRR AS-SET)
  • Prefixes: Announced prefixes with RPKI validation status
  • Connectivity: AS relationships (upstreams, peers, downstreams)
  • RPKI: ROAs and ASPA records

When querying multiple ASNs, a glance table is automatically shown first, providing a quick overview of all queried ASNs before the detailed per-ASN information.

➜  monocle inspect --help
Unified AS and prefix information lookup

Usage: monocle inspect [OPTIONS] [QUERY]...

Arguments:
  [QUERY]...  One or more queries: ASN (13335, AS13335), prefix (1.1.1.0/24), IP (1.1.1.1), or name (cloudflare)

Options:
  -a, --asn                Force treat queries as ASNs
      --debug              Print debug information
  -p, --prefix             Force treat queries as prefixes
      --format <FORMAT>    Output format: table (default), markdown, json, json-pretty, json-line, psv
  -n, --name               Force treat queries as name search
  -c, --country <COUNTRY>  Search by country code (e.g., US, DE)
      --json               Output as JSON objects (shortcut for --format json-pretty)
      --show <SECTION>     Select data sections to display (can be repeated). Available: basic, prefixes, connectivity, rpki, all
      --full               Show all data sections with no limits
      --full-roas          Show all RPKI ROAs (default: top 10)
      --full-prefixes      Show all prefixes (default: top 10)
      --full-connectivity  Show all neighbors (default: top 5 per category)
      --limit <N>          Limit search results (default: 20)
  -u, --update             Force refresh the asinfo database
  -h, --help               Print help

Examples:

# Look up AS by number (shows all information by default)
➜  monocle inspect 13335
Query: 13335 (type: asn)
─── Basic Information ───
ASN:     AS13335
Name:    CLOUDFLARENET
Country: US
Org:     Cloudflare, Inc.
Org ID:  CLOUD14-ARIN
Website: https://www.cloudflare.com
AS-SET:     AS13335:AS-CLOUDFLARE

─── Announced Prefixes ───
Total: 5526 (2409 IPv4, 3117 IPv6)
RPKI Validation: valid 5071 (91.8%), invalid 1 (0.0%), unknown 454 (8.2%)
╭─────────────────────┬────────────╮
│ Prefix              │ Validation │
├─────────────────────┼────────────┤
│ 103.186.74.0/24     │ unknown    │
│ ...                 │ ...        │
╰─────────────────────┴────────────╯
(showing 10 of 5526 prefixes, use --full-prefixes to show all)

─── Connectivity ───
...
(results truncated, use --full-connectivity to show all)

─── RPKI ───
ROAs: 4420 total (2754 IPv4, 1666 IPv6)
...
(ROA list truncated, use --full-roas to show all)

# Query multiple ASNs (glance table shown first)
➜  monocle inspect 13335 15169
─── Glance ───
╭─────────┬───────────────┬─────────┬──────────────────╮
│ ASN     │ Name          │ Country │ Org              │
├─────────┼───────────────┼─────────┼──────────────────┤
│ AS13335 │ CLOUDFLARENET │ US      │ Cloudflare, Inc. │
│ AS15169 │ GOOGLE        │ US      │ Google LLC       │
╰─────────┴───────────────┴─────────┴──────────────────╯

════════════════════════════════════════════════════════════════════════════════

Query: 13335 (type: asn)
─── Basic Information ───
...

# Search by name
➜  monocle inspect -n cloudflare
Query: cloudflare (type: name)

─── Search Results ───
Found: 5 matches
╭────────┬────────────────────────────┬─────────╮
│ ASN    │ Name                       │ Country │
├────────┼────────────────────────────┼─────────┤
│ 13335  │ CLOUDFLARENET              │ US      │
│ ...    │ ...                        │ ...     │
╰────────┴────────────────────────────┴─────────╯

# Look up prefix
➜  monocle inspect 1.1.1.0/24
Query: 1.1.1.0/24 (type: prefix)

─── Announced Prefix ───
╭────────────────┬────────────┬─────────┬────────────╮
│ Matched Prefix │ Match Type │ ASN     │ Validation │
├────────────────┼────────────┼─────────┼────────────┤
│ 1.1.1.0/24     │ exact      │ AS13335 │ valid      │
╰────────────────┴────────────┴─────────┴────────────╯

─── Covering ROAs ───
╭────────────┬────────────┬────────────┬───────╮
│ Prefix     │ Max Length │ Origin ASN │ TA    │
├────────────┼────────────┼────────────┼───────┤
│ 1.1.1.0/24 │ 24         │ AS13335    │ APNIC │
╰────────────┴────────────┴────────────┴───────╯

# Show only basic information
➜  monocle inspect 13335 --show basic

monocle country

Look up country names and codes.

➜  monocle country --help
Country name and code lookup utilities

Usage: monocle country [OPTIONS] <QUERY>

Arguments:
  <QUERY>  Country code (2-letter) or name to search

Options:
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help

Examples:

➜  monocle country US
┌──────┬───────────────┐
│ code │ name          │
├──────┼───────────────┤
│ US   │ United States │
└──────┴───────────────┘

➜  monocle country germany
┌──────┬─────────┐
│ code │ name    │
├──────┼─────────┤
│ DE   │ Germany │
└──────┴─────────┘

monocle as2rel

Look up AS-level relationships between ASNs using BGPKIT's AS relationship data.

➜  monocle as2rel --help
AS-level relationship lookup between ASNs

Usage: monocle as2rel [OPTIONS] <ASNS>...

Arguments:
  <ASNS>...  One or more ASNs to query relationships for
             - Single ASN: shows all relationships for that ASN
             - Two ASNs: shows the relationship between them
             - Multiple ASNs: shows relationships for all pairs (asn1 < asn2)

Options:
      --debug                Print debug information
      --format <FORMAT>      Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json                 Output as JSON objects (shortcut for --format json-pretty)
      --update               Force update the local database
      --no-explain           Hide the explanation text in table output
      --sort-by-asn          Sort results by ASN2 ascending (default: sort by connected % descending)
      --show-name            Show organization name for ASN2 (truncated to 20 chars)
      --show-full-name       Show full organization name without truncation
      --min-visibility <PCT> Minimum visibility percentage (0-100) to include in results
      --single-homed         Only show ASNs that are single-homed to the queried ASN
      --is-upstream          Only show relationships where the queried ASN is an upstream (provider)
      --is-downstream        Only show relationships where the queried ASN is a downstream (customer)
      --is-peer              Only show peer relationships
  -h, --help                 Print help

Output columns:

  • asn1 / asn2: The two ASNs being compared
  • connected: Percentage of peers that see any connection between the ASNs
  • peer: Percentage seeing pure peering relationship
  • as1_upstream: Percentage seeing ASN1 as upstream of ASN2
  • as2_upstream: Percentage seeing ASN2 as upstream of ASN1

Examples:

# Look up relationship between two ASNs
➜  monocle as2rel 13335 174
┌───────┬──────┬───────────┬───────┬─────────────┬─────────────┐
│ asn1  │ asn2 │ connected │ peer  │ as1_upstream│ as2_upstream│
├───────┼──────┼───────────┼───────┼─────────────┼─────────────┤
│ 13335 │ 174  │ 95.2%     │ 85.1% │ 2.3%        │ 7.8%        │
└───────┴──────┴───────────┴───────┴─────────────┴─────────────┘

# Show all relationships for an ASN with names
➜  monocle as2rel 13335 --show-name | head -10

# Find ASNs that are single-homed to AS2914 (NTT)
➜  monocle as2rel 2914 --single-homed --show-name

# Find single-homed ASNs with at least 10% visibility
➜  monocle as2rel 2914 --single-homed --min-visibility 10

# Show only downstream customers of an ASN
➜  monocle as2rel 2914 --is-upstream --show-name

# Show only upstream providers of an ASN
➜  monocle as2rel 13335 --is-downstream --show-name

# Show relationships among multiple ASNs (all pairs)
➜  monocle as2rel 174 2914 3356 --show-name

monocle pfx2as

Look up prefix-to-ASN mappings. Query by prefix to find origin ASNs, or by ASN to find announced prefixes. Results include RPKI validation status for each prefix-ASN pair.

➜  monocle pfx2as --help
Prefix-to-ASN mapping lookup

Query by prefix to find origin ASNs, or by ASN to find announced prefixes.
Includes RPKI validation status for each prefix-ASN pair.

Usage: monocle pfx2as [OPTIONS] <QUERY>

Arguments:
  <QUERY>  Query: an IP prefix (e.g., 1.1.1.0/24) or ASN (e.g., 13335, AS13335)

Options:
  -u, --update           Force update the local pfx2as database
      --include-sub      Include sub-prefixes (more specific) in results when querying by prefix
      --include-super    Include super-prefixes (less specific) in results when querying by prefix
      --show-name        Show AS name for each origin ASN
      --show-full-name   Show full AS name without truncation (default truncates to 20 chars)
  -l, --limit <N>        Limit the number of results (default: no limit)
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help

Examples:

# Look up a prefix - shows origin ASN and RPKI validation status
➜  monocle pfx2as 1.1.1.0/24
╭────────────┬────────────┬───────╮
│ prefix     │ origin_asn │ rpki  │
├────────────┼────────────┼───────┤
│ 1.1.1.0/24 │ 13335      │ valid │
╰────────────┴────────────┴───────╯

# Look up with AS name
➜  monocle pfx2as 1.1.1.0/24 --show-name
╭────────────┬────────────┬───────────────┬───────╮
│ prefix     │ origin_asn │ as_name       │ rpki  │
├────────────┼────────────┼───────────────┼───────┤
│ 1.1.1.0/24 │ 13335      │ CLOUDFLARENET │ valid │
╰────────────┴────────────┴───────────────┴───────╯

# Look up by ASN - shows all prefixes announced by the ASN
➜  monocle pfx2as 13335 --limit 5 --show-name
╭─────────────────────┬────────────┬───────────────┬───────────╮
│ prefix              │ origin_asn │ as_name       │ rpki      │
├─────────────────────┼────────────┼───────────────┼───────────┤
│ 172.69.7.0/24       │ 13335      │ CLOUDFLARENET │ valid     │
│ 2606:4700:839a::/48 │ 13335      │ CLOUDFLARENET │ valid     │
│ 8.36.218.0/24       │ 13335      │ CLOUDFLARENET │ not_found │
│ 2400:cb00:b8e6::/48 │ 13335      │ CLOUDFLARENET │ valid     │
│ 172.68.134.0/24     │ 13335      │ CLOUDFLARENET │ valid     │
╰─────────────────────┴────────────┴───────────────┴───────────╯

# Include sub-prefixes (more specific prefixes)
➜  monocle pfx2as 8.8.0.0/16 --include-sub --limit 5 --show-name
╭──────────────┬────────────┬────────────┬───────────╮
│ prefix       │ origin_asn │ as_name    │ rpki      │
├──────────────┼────────────┼────────────┼───────────┤
│ 8.0.0.0/12   │ 3356       │ LEVEL3     │ not_found │
│ 8.8.8.0/24   │ 15169      │ GOOGLE     │ valid     │
│ 8.8.249.0/24 │ 989        │ ANAXA3-ASN │ valid     │
│ 8.8.216.0/24 │ 13781      │ ENERGYNET  │ valid     │
│ 8.8.64.0/24  │ 3356       │ LEVEL3     │ not_found │
╰──────────────┴────────────┴────────────┴───────────╯

# Include super-prefixes (less specific prefixes)
➜  monocle pfx2as 1.1.1.0/24 --include-super

# JSON output
➜  monocle pfx2as 13335 --limit 3 --json
[
  {
    "prefix": "172.69.7.0/24",
    "origin_asn": 13335,
    "rpki": "valid"
  },
  {
    "prefix": "2606:4700:839a::/48",
    "origin_asn": 13335,
    "rpki": "valid"
  },
  {
    "prefix": "8.36.218.0/24",
    "origin_asn": 13335,
    "rpki": "not_found"
  }
]

monocle rpki

RPKI utilities for validation and listing ROAs/ASPAs.

Data sources:

➜  monocle rpki --help
RPKI utilities

Usage: monocle rpki [OPTIONS] <COMMAND>

Commands:
  validate  validate a prefix-asn pair using cached RPKI data
  roas      list ROAs from RPKI data (current or historical via bgpkit-commons)
  aspas     list ASPAs from RPKI data (current or historical via bgpkit-commons)
  help      Print this message or the help of the given subcommand(s)

Options:
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help

monocle rpki validate

Validate a prefix-ASN pair against cached RPKI data. Implements RFC 6811 validation logic:

  • Valid: Covering ROA exists with matching ASN and prefix length ≤ max_length
  • Invalid: Covering ROA exists but ASN doesn't match or prefix length exceeds max_length
  • NotFound: No covering ROA exists for the prefix
➜  monocle rpki validate --help
validate a prefix-asn pair using cached RPKI data

Usage: monocle rpki validate [OPTIONS] <RESOURCES>...

Arguments:
  <RESOURCES>...  Two resources: one prefix and one ASN (order does not matter)

Options:
  -r, --refresh  Force refresh the RPKI cache before validation
  -h, --help     Print help

Examples:

➜  monocle rpki validate 1.1.1.0/24 13335
┌────────────┬───────┬────────┬───────────────────────────────────┐
│ prefix     │ asn   │ status │ reason                            │
├────────────┼───────┼────────┼───────────────────────────────────┤
│ 1.1.1.0/24 │ 13335 │ Valid  │ Covered by ROA: 1.1.1.0/24-24     │
└────────────┴───────┴────────┴───────────────────────────────────┘

➜  monocle rpki validate 1.1.1.0/24 12345
┌────────────┬───────┬─────────┬────────────────────────────────────────────┐
│ prefix     │ asn   │ status  │ reason                                     │
├────────────┼───────┼─────────┼────────────────────────────────────────────┤
│ 1.1.1.0/24 │ 12345 │ Invalid │ ASN mismatch: ROA allows 13335, got 12345  │
└────────────┴───────┴─────────┴────────────────────────────────────────────┘

monocle rpki roas

List ROAs from RPKI data. Supports both current (cached from Cloudflare) and historical data.

➜  monocle rpki roas --help
list ROAs from RPKI data (current or historical via bgpkit-commons)

Usage: monocle rpki roas [OPTIONS] [RESOURCES]...

Arguments:
  [RESOURCES]...  Filter by resources (prefixes or ASNs, auto-detected)

Options:
      --date <DATE>            Load historical data for this date (YYYY-MM-DD)
      --source <SOURCE>        Historical data source: ripe, rpkiviews [default: ripe]
      --collector <COLLECTOR>  RPKIviews collector: soborost, massars, attn, kerfuffle [default: soborost]
  -r, --refresh                Force refresh the RPKI cache (only applies to current data)
  -h, --help                   Print help

Examples:

# List ROAs for an ASN (current data)
➜  monocle rpki roas 13335
┌───────┬─────────────────────┬────────────┐
│ asn   │ prefix              │ max_length │
├───────┼─────────────────────┼────────────┤
│ 13335 │ 1.0.0.0/24          │ 24         │
│ 13335 │ 1.1.1.0/24          │ 24         │
│ ...   │ ...                 │ ...        │
└───────┴─────────────────────┴────────────┘

# List ROAs for a prefix
➜  monocle rpki roas 1.1.1.0/24
┌───────┬────────────┬────────────┐
│ asn   │ prefix     │ max_length │
├───────┼────────────┼────────────┤
│ 13335 │ 1.1.1.0/24 │ 24         │
└───────┴────────────┴────────────┘

# Historical data from a specific date
➜  monocle rpki roas 13335 --date 2024-01-01 --source ripe

monocle rpki aspas

List ASPAs (Autonomous System Provider Authorizations) from RPKI data.

➜  monocle rpki aspas --help
list ASPAs from RPKI data (current or historical via bgpkit-commons)

Usage: monocle rpki aspas [OPTIONS]

Options:
      --customer <CUSTOMER>    Filter by customer ASN
      --provider <PROVIDER>    Filter by provider ASN
      --date <DATE>            Load historical data for this date (YYYY-MM-DD)
      --source <SOURCE>        Historical data source: ripe, rpkiviews [default: ripe]
      --collector <COLLECTOR>  RPKIviews collector: soborost, massars, attn, kerfuffle [default: soborost]
  -r, --refresh                Force refresh the RPKI cache (only applies to current data)
  -h, --help                   Print help

Examples:

# List all ASPAs
➜  monocle rpki aspas | head -10

# Filter by customer ASN
➜  monocle rpki aspas --customer 13335

# Filter by provider ASN
➜  monocle rpki aspas --provider 174

monocle ip

Look up information about IP addresses.

➜  monocle ip --help
IP information lookup

Usage: monocle ip [OPTIONS] [IP]

Arguments:
  [IP]  IP address to look up (omit to get your public IP)

Options:
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -h, --help             Print help

Examples:

# Look up a specific IP
➜  monocle ip 1.1.1.1
┌─────────────┬─────────────────────────────────────────────────┐
│ Field       │ Value                                           │
├─────────────┼─────────────────────────────────────────────────┤
│ ip          │ 1.1.1.1                                         │
│ asn         │ 13335                                           │
│ as_name     │ CLOUDFLARENET                                   │
│ country     │ AU                                              │
│ ...         │ ...                                             │
└─────────────┴─────────────────────────────────────────────────┘

# Get your public IP info
➜  monocle ip

monocle config

Show monocle configuration, data paths, and manage the database.

➜  monocle config --help
Show monocle configuration, data paths, and database management

Usage: monocle config [OPTIONS] [COMMAND]

Commands:
  db-refresh  Refresh data source(s)
  db-backup   Backup the database to a destination
  db-sources  List available data sources and their status
  help        Print this message or the help of the given subcommand(s)

Options:
      --debug            Print debug information
      --format <FORMAT>  Output format: table (default), markdown, json, json-pretty, json-line, psv
      --json             Output as JSON objects (shortcut for --format json-pretty)
  -v, --verbose          Show detailed information about all data files
  -h, --help             Print help

Examples:

# Show configuration and database status
➜  monocle config
Configuration:
  Config file: ~/.monocle.toml (not found, using defaults)
  Data directory: ~/.monocle

SQLite Database: ~/.monocle/monocle-data.sqlite3
  Size: 45.2 MB
  ASInfo: 120415 ASes
  AS2Rel: 1234567 relationships
  RPKI: 784188 ROAs, 388 ASPAs (updated 2 hours ago)
  Pfx2as: 1000000 prefixes

# Refresh all data sources
➜  monocle config db-refresh --all

# Refresh a specific source
➜  monocle config db-refresh asinfo
➜  monocle config db-refresh rpki

# Backup the database
➜  monocle config db-backup ~/monocle-backup.sqlite3

# List available data sources
➜  monocle config db-sources

monocle server

Start a WebSocket server for programmatic access to monocle functionality.

➜  monocle server --help
Start the WebSocket server

Usage: monocle server [OPTIONS]

Options:
  -a, --address <ADDRESS>  Bind address [default: 127.0.0.1]
  -p, --port <PORT>        Bind port [default: 8080]
  -h, --help               Print help

Endpoints:

  • WebSocket: ws://<address>:<port>/ws
  • Health check: http://<address>:<port>/health

Features:

  • JSON-RPC style request/response protocol
  • Streaming support with progress reporting for parse/search operations
  • Operation cancellation via op_id
  • DB-first policy: queries read from local SQLite cache

Available methods:

  • system.info, system.methods - Server introspection
  • time.parse - Time string parsing
  • ip.lookup, ip.public - IP information lookup
  • rpki.validate, rpki.roas, rpki.aspas - RPKI operations
  • as2rel.search, as2rel.relationship, as2rel.update - AS relationships
  • pfx2as.lookup - Prefix-to-ASN mapping
  • country.lookup - Country code/name lookup
  • inspect.query, inspect.refresh - Unified AS/prefix inspection
  • parse.start, parse.cancel - MRT file parsing (streaming)
  • search.start, search.cancel - BGP message search (streaming)
  • database.status, database.refresh - Database management

For detailed protocol specification, see src/server/README.md.

Example:

➜  monocle server
Starting WebSocket server on 127.0.0.1:8080
  WebSocket: ws://127.0.0.1:8080/ws
  Health: http://127.0.0.1:8080/health

➜  monocle server --address 0.0.0.0 --port 3000
Starting WebSocket server on 0.0.0.0:3000

Built with ❤️ by BGPKIT Team

https://bgpkit.com/logo.png

About

🧐 See through all BGP data with a monocle.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

139 stars

Watchers

4 watching

Forks

8 forks
Report repository

Releases 30

v1.0.2 Latest
Dec 19, 2025
+ 29 releases

Packages

No packages published

Contributors 5

Languages