NetBox Automatic Import Tool

Overview

The NetBox Automatic Import Tool provides an easy-to-use solution for importing and maintaining network device information in NetBox. This automated system ensures your NetBox database stays synchronized with the actual state of your network infrastructure through a containerized, API-driven architecture.

Architecture

The project consists of three main Docker containers working together:

• Controller - Web UI and API interface for configuration management

  • Stores NetBox connection details (URL, API key)
  • Manages global and device-specific credentials
  • Orchestrates the data collection and synchronization workflow

• Data Miner - Short-lived container for device data collection

  • Connects to network devices using provided credentials
  • Retrieves current device configuration and state information
  • Supports multiple vendors and management platforms

• Data Pusher - Short-lived container for NetBox synchronization

  • Processes collected device data
  • Updates NetBox device records with latest information
  • Respects device-specific tags and settings

Architecture design

Features

• Multi-vendor Support - Fortinet, Cisco, and Juniper devices
• Flexible Authentication - Global or per-device credentials
• Tag-based Control - Fine-grained control over import behavior
• Configuration Backup - Optional full config backup to NetBox
• Comprehensive Testing - Code quality, security scanning, unit and E2E tests
• CI/CD Integration - Automated testing and vulnerability scanning

Installation

# Step 1: Clone the repository
git clone https://github.com/ThaseG/netbox-automatic-import.git

# Step 2: Navigate to project directory
cd netbox-automatic-import

# Step 3: Start the services
docker-compose up

Usage

Initial Setup

1. Connect to Controller via web UI or API
2. Configure NetBox Connection
   • Set NetBox URL
   • Provide API key with appropriate permissions
3. Configure Credentials (optional)
   • Set global credentials for device access
   • Add device-specific credentials as needed

Device Import

1. Click Pull in the Controller UI
2. Review the list of devices matching criteria
3. Verify device prerequisites are met
4. Execute import operation

Device Configuration

Naming convention documentation for tags and other components, together with other documentation is stored her.

Prerequisites

Each device must meet the following requirements:

• Primary IP Address - Device must have:

  • At least one interface configured
  • An IP address associated with that interface
  • Primary IP set on the device object

• Vendor Information - Device must have:

  • Manufacturer selected (Fortinet, Cisco, Juniper)
  • Platform specified (fortigate, fortiwifi, ios-xr, ios-xe, nx-os, junos)

Technology Stack

• Containerization: Docker, Docker Compose
• Programming Languages: Python, Bash
• Container Images: Custom Dockerfiles for each component
• Scripting: Bash entrypoints for container orchestration

Quality Assurance

The project implements comprehensive testing and quality controls:

• Code Quality Pipeline - Enforces Python coding standards (python-lint)
• Dependency Management - Dependabot for automated dependency updates
• Security Scanning - Trivy vulnerability scanning for all container images
• Unit Testing - Validates individual function correctness
• End-to-End Testing - Verifies complete workflow integration
• Manual QA - Quality assurance testing and bug fixing

Roadmap

Major Versions

Version	Description
v1.*	Fortinet support - FortiGate/FortiWifi devices (direct and via FortiManager)
v2.*	Cisco support - IOS-XR/IOS-XE/NX-OS devices (direct, ACI, and DNA Center)
v3.*	Juniper support - JunOS devices (direct access)
v4.*	Push-via-diode capability for air-gapped environments
v5.*	Controller webUI

Minor Version Milestones

Version will be released only if all of these steps are covered:

• Component, naming, tags, etc. documentation is updated
• Controller container with API, webUI(once done) and JSON data model updated
• Per-device and global credential support is tested
• Device-Miner container image can be build
• Device-Miner is working
• Data-Pusher container can be build
• Tag-based automation logic implementation is tested and Data-Pusher is working
• Python-lint code quality testing
• Dependabot, security scanning, and unit testing
• Test plans for End-to-end testing in CI/CD pipeline is updated, tested and working
• Manual QA and production-readiness bug fixes

Contributing

Contributions are welcome! Please ensure all code passes:

• Code quality checks (python-lint)
• Security scans (Trivy, Dependabot)
• Unit tests
• End-to-end tests