National Cyber Warfare Foundation (NCWF)login

netbox-scanner for keeping NetBox IPAM data synchronized with live network sources


0 user ratings
2026-11-12 15:32:10
milo
Red Team (CNA)
"netbox-scanner

netbox-scanner pulls host data from nmap scans, Cisco Prime, and NetXMS and reconciles it into a NetBox IPAM database for authorized asset management and documentation.








Toollopes/netbox-scanner — Python utility that discovers IPv4 hosts and synchronizes them as /32 records into a NetBox IPAM instance
CategoryNetwork inventory synchronization and IPAM automation
Primary UseAutomating create/update/delete of /32 host records in NetBox from sources like nmap, Cisco Prime, and NetXMS
Safe UseIntended for authorized asset management of networks you own or administer, such as internal labs and documented enterprise environments; it is a documentation tool, not an attack tool
Telemetry NoteThe nmap module generates ordinary scan traffic against listed networks, and API modules authenticate to Cisco Prime and NetXMS with credentials from the config file; defenders will see host-discovery probes and authenticated API sessions in logs

netbox-scanner from lopes addresses a chronic problem in network documentation: the drift between what a NetBox IPAM database says exists and what actually answers on the wire. Rather than being a pure discovery engine, it positions itself as a synchronization layer that creates, updates, and deletes host records — strictly /32 entries — inside NetBox, fed either by live network scans or by other databases of record. The author candidly notes in the README that since version 2 the name is a misnomer, since the focus shifted to synchronizing disparate sources into NetBox, and that netbox-sync would be a more honest title. That transparency is useful for operators evaluating fit, because it tells you the tool's real value lies in reconciliation logic, not raw scanning.


Installation is deliberately old-school: you fetch the archive from GitHub, unpack it, create a python3 virtual environment with python3 -m venv venv, and install dependencies via pip install -r requirements.txt. The project targets Python 3.7+, which keeps it compatible with modest baseline infrastructure where NetBox instances commonly live. Configuration is file-based rather than flag-based: the shipped netbox-scanner.conf serves as a template, and the tool searches for a config first in the home directory as ~/.netbox-scanner.conf, then in /opt/netbox, and finally in the project root, taking the first match. That lookup order is worth remembering when debugging why a change isn't taking effect — a stale file earlier in the chain silently wins.


There is one operational gotcha that the README flags prominently and that will bite anyone running a modern NetBox: starting with NetBox v2.9.0, tag creation changed, so you must manually create a tag in the web UI corresponding to each module you intend to use — an nmap tag before running the nmap module, and so on. This matters because tags are the core of the tool's safety model. Every record netbox-scanner inserts is tagged, and the tool only manages records bearing its tags; manually created entries without those tags are never updated or deleted. This is a sensible integrity boundary that prevents automation from steamrolling curated human input, and it is the first thing an operator should verify before trusting a large sync run.


The tag mechanism also underpins garbage collection. If cleanup is set to yes in the configuration, then after synchronization the tool pulls all IP addresses in NetBox sharing the same tag, compares that list against the freshly synced dataset, and deletes anything present in NetBox but absent from the new source. In effect, the most recent sync becomes the authoritative truth for that tag's population. For an authorized environment this is a powerful way to retire stale records — workstations decommissioned, DHCP churn resolved — but it also means a partial or failed scan can silently vaporize inventory, so careful attention to source completeness before enabling cleanup is warranted.


Interaction with NetBox itself is handled through pynetbox, the widely used Python API client, and the author notes testing against NetBox v2.9.11. Modules are invoked from the command line as the sole accepted argument, e.g. python netbox-scanner.py nmap, and the quick start suggests populating networks.txt with one CIDR per line to observe behavior on a first run. When a source provides no description for a discovered host, the tool inserts whatever string is configured under the unknown parameter, which users can customize — a small but thoughtful touch that keeps output uniform rather than littering the IPAM with blanks.


Architecturally, version 2.0 moved the project to a module design that is cleanly documented. The main script is a thin layer: each source lives as a file inside the nbs directory, is imported by the core, and must return data as a two-dimensional array of (IP address, description) tuples — the README's example shows entries like ('10.0.1.1', 'Gateway'). This uniform contract is what makes the design extensible; any system that can be coerced into emitting pairs of addresses and descriptions can become a source. For teams with in-house CMDBs or homegrown monitoring, that is an inviting integration point.


The nmap module deserves clarification because it has changed character over time. Rather than requiring the operator to run nmap separately and parse output, discovery is now embedded in the tool itself, and notably the scan does not require root privileges because it only checks for hosts that are up — host discovery, not port enumeration. For authorized internal inventory this keeps the footprint light and avoids the privilege escalation questions that full nmap runs raise. It also defines the tool's ceiling: if you need service detection, you will be feeding NetBox from other tooling, not from this module.


Two enterprise-source modules round out the feature set, and both reveal the author's practical environment. The Prime module talks to Cisco Prime Infrastructure over its RESTful API — you point it at an endpoint shaped like https://prime.domain/webacs/api/v4/ with valid API credentials — and it was tested on Cisco Prime v3.4.0 against API v4. One nuance documented in the README: retrieving access point data requires elevated privileges on Prime's side, and must be explicitly requested via Prime().run(access_points=True). This is exactly the kind of permission subtlety that otherwise costs an afternoon of debugging.


The NetXMS module, contributed in part with API tips from Jarder Gonzalez, reads the full NetXMS object list and extracts IPv4 addresses while discarding loopbacks. The README is refreshingly frank about its limitations: the NetXMS API is poorly documented, does not paginate, and authenticates with cookies rather than tokens, so queries can take minutes on large datasets and may degrade the NetXMS server under load. An operator scheduling recurring syncs should treat this module as heavyweight and off-peak material, not something to hammer on a fifteen-minute cron.


Quality assurance is modest but present. A tests directory contains basic tests and a shell script to run them all, gated behind environment variables such as NETBOX_ADDRESS and NMAP_PATH — with the sensible guidance to export secrets in your shell rather than hardcoding passwords into the script. Extending the tool is also spelled out concretely: drop a new file like nbs/netxms.py, implement a class with a run method, wire a cmd_netxms function into netbox-scanner.py, and add matching entries to the argument parser and the main dispatch block. That is a low barrier for anyone comfortable with Python.


For security professionals, the legitimate home of netbox-scanner is asset management on networks you are authorized to administer: keeping an internal NetBox truthful for lab environments, enterprise IPAM hygiene, or preparing accurate scoping data ahead of an authorized assessment. The telemetry it generates is correspondingly benign but observable — host-discovery probes from the nmap module and authenticated API sessions against Prime and NetXMS will appear in network and application logs, which is worth knowing when a NOC asks why a NetBox-tagged record set changed overnight. The project carries an MIT license, sits at a modest but real community size, and its topics (ipam, netbox, nmap, cisco-prime, netxms) accurately describe a focused, single-purpose utility rather than a sprawling framework.



Official project repository for lopes/netbox-scanner.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.






Source: OffensiveSec
Source Link: https://www.offsecblog.com/2026/11/netbox-scanner-for-keeping-netbox-ipam.html


Comments
new comment
Nobody has commented yet. Will you be the first?
 
Forum
Red Team (CNA)



Copyright 2012 through 2026 - National Cyber Warfare Foundation - All rights reserved worldwide.