How lopes/netbox-scanner works
Project Type and Purpose
• This is a command-line utility (Python 3.7+) for synchronizing host records into a NetBox instance.
• It reads IP data from various “modules” (plugins) – e.g. Nmap XML exports, Cisco Prime API, NetXMS API – and then creates/updates/deletes host (/32) entries in NetBox via the pynetbox client.
File Structure Analysis
• Top level:
• netbox-scanner.py – the CLI entrypoint
• netbox-scanner.conf – sample configuration
• requirements.txt – Python dependencies
• samples/ – example XML files and scripts
• tests/ – unit tests and environment-var wrapper
• nbs/ directory: each file (nmap.py, prime.py, netxms.py, prime.md, etc.) is a module implementing a class with a run() method returning a list of (IP, description) tuples.
• Tests exercise each module plus core NetBox sync logic.
Key Architecture Insights from README
• Core orchestration is in netbox-scanner.py; modules are dynamically imported from nbs/.
• Configuration defines which module to run, path or API credentials, tags, cleanup option.
• After data retrieval, a garbage-collector step (if enabled) deletes stale entries by tag.
Main Components
a. CLI Entrypoint
• Parses arguments, loads config, chooses module
b. Configuration Loader
• Reads ~/.netbox-scanner.conf or /opt/netbox/netbox-scanner.conf and environment variables
c. Module Dispatcher
• Dynamically imports the chosen class from nbs/ and calls its run()
d. Source Modules (Plugins)
• Nmap Module – reads XML files from filesystem
• Prime Module – REST API calls to Cisco Prime
• NetXMS Module – REST/Cookie API calls to NetXMS
• (Future modules follow same pattern)
e. Core Synchronizer
• Receives list of (IP,desc), deduplicates, applies tags
• Calls NetBox client to create/update hosts
• Optionally runs Garbage Collector
f. NetBox Client
• Uses pynetbox to communicate with NetBox’s REST API
g. External Systems
• File System (Nmap XML directory)
• Cisco Prime server
• NetXMS server
• NetBox server
Component Interactions and Data Flow
• CLI Entrypoint → Configuration Loader
• Configuration → Module Dispatcher
• Module Dispatcher → Selected Module.run() → returns host list
• Core Synchronizer ← host list
• Core Synchronizer → NetBox Client → NetBox API (create/update)
• If cleanup=yes: Core Synchronizer → NetBox Client (fetch by tag) → compare lists → delete stale hosts
• Modules → External Systems (read files or call APIs)
Architectural Patterns and Principles
• Plugin/Extension Architecture: each scanner is a drop-in module under nbs/
• Layered Separation: CLI / config / modules / sync logic / API client
• Single Responsibility: modules only retrieve data; core only syncs to NetBox
Technologies and Frameworks
• Python 3.7+
• pynetbox (NetBox REST client)
• requests, xml parsing (for Prime, NetXMS, Nmap modules)