NetBox Scanner

A Dockerized network scanner that discovers hosts with Nmap and imports them into NetBox as IP address records.

How it works

1. Scanner (scan.py) — performs an Nmap sweep of configured networks and writes results to output/network.txt.
2. NetBox Importer (ipscan-v2.py) — scans networks directly with Nmap, resolves hostnames via DNS, then creates or updates IP address records in NetBox. IPs not found during the scan are marked as offline.

Networks to scan can come from the environment variable NETWORKS, from NetBox IPAM prefixes, or both — controlled by SCAN_SOURCE.

Requirements

• Docker and Docker Compose

Setup

1. Copy the example environment file and fill in your values:

cp .env.example .env

2. Edit .env:

NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_token_here
SSL_VERIFY=false

SCAN_SOURCE=env
NETWORKS=192.168.1.0/24,192.168.2.0/24

NETBOX_PREFIX_STATUS=active
TENANT=Your Tenant Name

3. Build the image:

docker compose build

Usage

Run the NetBox importer

Scans all configured networks and imports results into NetBox:

docker compose up netbox-importer

Run the standalone scanner

Scans networks and writes results to ./output/network.txt:

docker compose up scanner

Run both services

docker compose up scanner netbox-importer

Configuration

All configuration is done via environment variables. Copy .env.example to .env and set the values there.

NetBox importer (ipscan-v2.py)

Variable	Default	Description
NETBOX_URL	—	NetBox instance URL
NETBOX_TOKEN	—	NetBox API token
SSL_VERIFY	false	Set to true to verify SSL certificates
SCAN_SOURCE	env	Where to get networks: env, netbox, or mixed
NETWORKS	—	Comma-separated CIDR networks (used when SCAN_SOURCE=env or mixed)
NETBOX_PREFIX_STATUS	(all)	Filter NetBox prefixes by status, e.g. active, reserved (used when SCAN_SOURCE=netbox or mixed)
TENANT	—	NetBox tenant name to assign to imported IPs

SCAN_SOURCE values:

• env — scan only networks from NETWORKS
• netbox — scan only prefixes fetched from NetBox IPAM
• mixed — combine both sources

Scanner service (scan.py)

Variable	Default	Description
OUTPUT_PATH	/app/output/network.txt	Path inside the container to write results

Scan behaviour

• Port range scanned: 1–32768 (TCP)
• Timing template: -T4 (aggressive)
• Per-host timeout: 2 minutes
• Up to 5 networks and 5 hosts are processed in parallel (thread pool)
• Hosts that were previously in NetBox but not found in the current scan are set to status offline

Output format (network.txt)

192.168.1.1 up 22 80 443
192.168.1.2 down

Project structure

.
├── ipscan-v2.py        # NetBox importer script
├── scan.py             # Standalone Nmap scanner
├── Dockerfile          # Python 3.14-slim + Nmap + Tini
├── docker-compose.yml  # Defines scanner and netbox-importer services
├── requirements.txt    # python-nmap, pynetbox, requests
├── .env                # Local environment config (gitignored)
└── .env.example        # Template — safe to commit

Dependencies

Package	Version
python-nmap	0.7.1
pynetbox	7.4.1
requests	2.32.3