🔍 nbpull

Read-only CLI tool to pull IPAM data from NetBox.

🔒 Safety guarantee: nbpull only reads data from NetBox. No POST / PUT / PATCH / DELETE requests are ever made. The HTTP client is hardcoded to GET-only — this invariant is enforced by code structure and verified by tests.

🌐 NetBox compatibility: Tested against NetBox Cloud v4.4.10. Compatible with NetBox v3.x+ (legacy site field) and v4.2+ (generic scope relation). The Prefix model transparently handles both via the resolved_site property.

✨ Features

• 📡 Prefixes — list and filter IPAM prefixes
• 🖥️ IP Addresses — query IP address allocations
• 🏷️ VLANs — browse VLAN assignments
• 🔀 VRFs — inspect VRF instances
• 📊 Aggregates — list top-level IP space by RIR
• 🏢 Sites — browse DCIM sites
• 🖧 Devices — query DCIM devices
• 🏛️ Tenants — list tenancy tenants
• 🌐 RFC 1918 — inventory Global VRF RFC 1918 prefixes with mapping status
• 📦 Batch queries — check many prefixes at once from a TOML file
• 🎨 Rich table output (default), JSON saved to a file (--format json), or CSV (--format csv)
• 🔎 Filter by status, VRF, tenant, site, tag, or free-text search
• ⚡ Async HTTP with automatic pagination
• 🔒 Strict typing (mypy strict mode + Pydantic v2)

📦 Installation

With uv (recommended)

uv tool install nbpull

With pipx

pipx install nbpull

With pip

pip install nbpull

From source

git clone https://github.com/Champion2005/nbpull.git
cd nbpull
make install   # uses uv sync

🚀 Quick Start

# 1. Run the interactive setup wizard
nbpull setup

# Or configure manually:
export NETBOX_URL=https://netbox.example.com
export NETBOX_TOKEN=your_read_only_token
# Or: cp .env.example .env && edit .env

# 2. Pull data
nbpull prefixes
nbpull prefixes --status active --vrf Production
nbpull ip-addresses --prefix 10.0.0.0/24
nbpull vlans --site DC1
nbpull vrfs --tenant Ops
nbpull aggregates --rir ARIN
nbpull sites --status active
nbpull devices --role "Core Router"
nbpull tenants
nbpull rfc1918
nbpull batch-prefixes --file my_prefixes.toml --status-only

📋 Commands

Common Flags

See the full command reference for all options.

⚙️ Configuration

Set these in .env or as environment variables:

See docs/configuration.md for details on token setup and SSL options.

📦 Batch Queries

Create a TOML file to query multiple prefixes in one run:

prefixes = [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
]

[filters]
# status = "active"
# vrf = "Production"

nbpull batch-prefixes --file prefixes.toml --status-only

📐 Architecture

src/netbox_data_puller/
├── cli.py          # Typer commands + filtering + JSON file output
├── client.py       # Async GET-only NetBox API client
├── config.py       # Pydantic Settings (.env)
├── formatters.py   # Rich table renderers
└── models/         # Pydantic models per resource
    ├── __init__.py
    ├── common.py   # Shared field types / base classes
    ├── aggregate.py
    ├── device.py
    ├── ip_address.py
    ├── prefix.py
    ├── site.py
    ├── tenant.py
    ├── vlan.py
    └── vrf.py

See docs/architecture.md for a full breakdown.

🛠️ Development

Prerequisites

• Python 3.13+
• uv — fast Python package manager

Setup

git clone https://github.com/Champion2005/nbpull.git
cd nbpull
make install    # Install dependencies

Commands

make all        # format → lint → typecheck → test
make test       # unit tests (no network)
make lint       # ruff linter
make format     # auto-format with ruff
make typecheck  # mypy strict mode
make test-integration  # hits real NetBox API

Running Tests

Unit tests use mocked HTTP responses and require no network access:

make test

Integration tests require NETBOX_URL and NETBOX_TOKEN:

make test-integration

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.

📝 Changelog

See CHANGELOG.md for a history of changes.

📄 License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

🙏 Acknowledgements

• NetBox — the leading open-source IPAM/DCIM platform
• Typer — CLI framework
• Rich — beautiful terminal formatting
• httpx — async HTTP client
• Pydantic — data validation