# lopes/netbox-scanner architecture

> Architecture diagram of the GitHub repository lopes/netbox-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lopes/netbox-scanner
- Repository: https://github.com/lopes/netbox-scanner

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1
    subgraph "Layer 1: CLI & Config"
        CLIEntrypoint["CLI Entrypoint"]:::cliColor
        ConfigLoader["Configuration Loader"]:::configColor
    end

    %% Layer 2
    subgraph "Layer 2: Module Dispatcher"
        ModuleDispatcher["Module Dispatcher"]:::dispatcherColor
    end

    %% Layer 3
    subgraph "Layer 3: Source Modules"
        NmapModule["Nmap Module"]:::moduleColor
        PrimeModule["Prime Module"]:::moduleColor
        NetxmsModule["NetXMS Module"]:::moduleColor
    end

    %% Layer 4
    subgraph "Layer 4: Core Synchronizer"
        CoreSync["Core Synchronizer"]:::syncColor
    end

    %% Layer 5
    subgraph "Layer 5: NetBox Client"
        NetboxClient["NetBox Client"]:::clientColor
    end

    %% Layer 6
    subgraph "Layer 6: External Systems"
        FS["File System"]:::externalColor
        PrimeServer["Cisco Prime Server"]:::externalColor
        NetxmsServer["NetXMS Server"]:::externalColor
        NetboxServer["NetBox Server"]:::externalColor
    end

    %% Connections
    CLIEntrypoint -->|"load config"| ConfigLoader
    CLIEntrypoint -->|"dispatch module"| ModuleDispatcher

    ModuleDispatcher -->|"run()"| NmapModule
    ModuleDispatcher -->|"run()"| PrimeModule
    ModuleDispatcher -->|"run()"| NetxmsModule

    NmapModule -->|"XML files"| FS
    PrimeModule -->|"REST API call"| PrimeServer
    NetxmsModule -->|"REST API call"| NetxmsServer

    NmapModule -->|"(IP,desc) list"| CoreSync
    PrimeModule -->|"(IP,desc) list"| CoreSync
    NetxmsModule -->|"(IP,desc) list"| CoreSync

    CoreSync -->|"create/update hosts"| NetboxClient
    CoreSync -->|"fetch by tag (if cleanup)"| NetboxClient

    NetboxClient -->|"REST API"| NetboxServer

    %% Click Events
    click CLIEntrypoint "https://github.com/lopes/netbox-scanner/blob/master/netbox-scanner.py"
    click ConfigLoader "https://github.com/lopes/netbox-scanner/blob/master/netbox-scanner.conf"
    click ModuleDispatcher "https://github.com/lopes/netbox-scanner/blob/master/netbox-scanner.py"
    click ModuleDispatcher "https://github.com/lopes/netbox-scanner/blob/master/nbs/__init__.py"
    click NmapModule "https://github.com/lopes/netbox-scanner/blob/master/nbs/nmap.py"
    click PrimeModule "https://github.com/lopes/netbox-scanner/blob/master/nbs/prime.py"
    click NetxmsModule "https://github.com/lopes/netbox-scanner/blob/master/nbs/netxms.py"
    click CoreSync "https://github.com/lopes/netbox-scanner/blob/master/netbox-scanner.py"
    click NetboxClient "https://github.com/lopes/netbox-scanner/blob/master/requirements.txt"

    %% Styles
    classDef cliColor fill:#E3F2FD,stroke:#2196F3,stroke-width:2px;
    classDef configColor fill:#FFF8E1,stroke:#FFC107,stroke-width:2px;
    classDef dispatcherColor fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px;
    classDef moduleColor fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px;
    classDef syncColor fill:#FBE9E7,stroke:#FF5722,stroke-width:2px;
    classDef clientColor fill:#E0F7FA,stroke:#00BCD4,stroke-width:2px;
    classDef externalColor fill:#FFFFFF,stroke:#9E9E9E,stroke-dasharray: 5 5,stroke-width:2px;
```
