Horizon

High-performance infrastructure intelligence tool

Horizon provides instant, offline access to IP-to-ASN mappings, network metadata, and geospatial infrastructure data. Query data centers, internet exchanges, and network facilities near any location—all from a single binary with sub-microsecond lookup times.

Features

• Instant IP Lookups — Resolve any IPv4 to ASN, organization, and country in ~32 nanoseconds
• ASN Intelligence — Query ASN metadata including name, type, and organization
• Spatial Search — Find data centers and IXPs near any coordinates
• Fully Offline — No API keys, no rate limits, no network calls
• Multiple Outputs — Human-readable, JSON, or CSV
• Interactive TUI — Terminal UI for exploration
• Tiny Footprint — ~11MB database, single static binary

Quick Start

# Clone and build
git clone https://github.com/copyleftdev/horizon.git
cd horizon

# Install (copies binary to ~/.local/bin, database to ~/.horizon/)
make install

# Verify installation
hz --version

Usage

IP Lookup

# Human-readable output
$ hz lookup 8.8.8.8

IP: 8.8.8.8
├─ Range: 8.8.8.0 - 8.8.8.255
├─ ASN: AS15169
├─ Name: Google LLC
└─ Country: US

# JSON output for scripting
$ hz -f json lookup 8.8.8.8
{
  "ip": "8.8.8.8",
  "range_start": "8.8.8.0",
  "range_end": "8.8.8.255",
  "asn": 15169,
  "asn_name": "Google LLC",
  "country": "US"
}

ASN Lookup

$ hz lookup AS13335

ASN: AS13335
├─ Name: Cloudflare, Inc.
├─ Country: US
├─ Type: Content
└─ Org ID: 12345

Spatial Search

# Find infrastructure near coordinates
$ hz scan --coords 37.7749,-122.4194 -r 20

  HORIZON SCAN
  Location: 37.7749, -122.4194
  Radius: 20 miles

    #  TYPE  DISTANCE  NAME                                      CITY
  ────────────────────────────────────────────────────────────────────────────────
    1  FAC     0.7mi  The Mission Street Center                 San Francisco
    2  FAC     1.4mi  TelePacific                               San Francisco
    3  FAC     1.6mi  274 Brannan Street                        San Francisco

# Auto-detect location via IP geolocation
$ hz scan --here -r 50

Database Info

$ hz info

Horizon Database
├─ Path: /home/user/.horizon/horizon.db
├─ Size: 11262628 bytes
│
├─ IP Ranges:    439,972
├─ ASNs:          77,598
├─ Organizations: 30,044
├─ Facilities:     7,070
└─ Geo Index:      5,212

Interactive TUI

$ hz tui

Launch an interactive terminal interface for exploring the database.

Controls:

• Tab — Switch panels
• Enter — Execute search
• / — Focus search
• ? — Help
• q — Quit

Installation

From Source (Recommended)

git clone https://github.com/copyleftdev/horizon.git
cd horizon
make install

This installs:

• hz binary to ~/.local/bin/
• Database to ~/.horizon/horizon.db

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Manual Build

cargo build --release
./target/release/hz --help

Performance

Horizon is designed for speed. All lookups use memory-mapped binary search with zero allocations in hot paths.

Operation	Time	Notes
IP Lookup	~32 ns	Binary search over 440K ranges
ASN Lookup	~22 ns	Binary search over 78K ASNs
Spatial Query (20mi)	~60 µs	Morton curve + distance filter

Run benchmarks yourself:

cargo bench

Data Sources

The bundled database is built from public sources:

• IPtoASN — IP to ASN mappings
• PeeringDB — Network and facility data
• BGP.Tools — ASN metadata

Updating the Database

To rebuild with fresh data:

cd scripts/data_pipeline
pip install -r ../requirements.txt
python download_datasets.py
python transform.py
make install-db  # from horizon/ directory

Project Structure

horizon/
├── src/
│   ├── main.rs       # CLI entry point
│   ├── lib.rs        # Library exports
│   ├── db/           # Database engine (memory-mapped)
│   ├── geo/          # Haversine, Morton encoding
│   ├── query/        # Query result types
│   ├── error.rs      # Error types
│   └── tui/          # Terminal UI
├── benches/          # Criterion benchmarks
├── tests/            # Integration tests
├── data/             # Bundled database
└── scripts/          # Installation scripts

Output Formats

Format	Flag	Use Case
Human	-f human (default)	Interactive use
JSON	-f json	Scripting, pipelines
CSV	-f csv	Spreadsheets, data analysis

Environment Variables

Variable	Description	Default
HORIZON_DB	Path to database file	~/.horizon/horizon.db
NO_COLOR	Disable colored output	unset

Contributing

Contributions welcome! Please:

1. Run cargo fmt before committing
2. Ensure cargo clippy passes
3. Add tests for new functionality
4. Run cargo test to verify

License

MIT License. See LICENSE for details.

Acknowledgments

Built with:

• clap — CLI parsing
• ratatui — Terminal UI
• memmap2 — Memory-mapped I/O
• serde — Serialization

Data from:

• IPtoASN
• PeeringDB
• BGP.Tools