nbpull 0.3.0

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

🔍 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

Command	Description
nbpull setup	Interactive setup wizard
nbpull prefixes	List IPAM prefixes
nbpull ip-addresses	List IP addresses
nbpull vlans	List VLANs
nbpull vrfs	List VRFs
nbpull aggregates	List IPAM aggregates (top-level space by RIR)
nbpull sites	List DCIM sites
nbpull devices	List DCIM devices
nbpull tenants	List tenancy tenants
nbpull rfc1918	Inventory Global VRF RFC 1918 prefixes with mapping status
nbpull location-report	Location-to-IP report — mapped prefixes with PRD and general columns
nbpull batch-prefixes	Query multiple prefixes from a TOML file

Common Flags

Flag	Description
--status	Filter by status (active, reserved, deprecated, container)
--vrf	Filter by VRF name
--tenant	Filter by tenant name
--site	Filter by site name
--tag	Filter by tag slug
--search / -s	Free-text search
--limit / -l	Max results (default: 50)
--format / -f	Output format: table (default), json (writes to file), or csv
--output / -o	JSON output file path (prompts with default if omitted)
--verbose / -v	Enable debug logging

See the full command reference for all options.

⚙️ Configuration

Set these in .env or as environment variables:

Variable	Required	Default	Description
NETBOX_URL	✅	—	NetBox instance URL
NETBOX_TOKEN	✅	—	API token (read-only recommended)
NETBOX_PAGE_SIZE	❌	100	Results per API page
NETBOX_TIMEOUT	❌	30	Request timeout (seconds)
NETBOX_VERIFY_SSL	❌	true	Verify SSL certificates

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