NetBox IP History

English | Türkçe

Documentation: GitHub Wiki

NetBox plugin 0.2.12 provides a canonical-IP timeline combining native NetBox core.ObjectChange records with immutable, plugin-owned GestioIP, phpIPAM, CSV, and JSON history. External records retain their source ID, source user, import job, timestamp, normalized scope, and complete raw_data snapshot.

License: Apache-2.0

Screenshots

IP Timeline & Lifecycle Search

Multi-Source IP Comparison

Historical Data Import (CSV / JSON / JSONL)

Import Jobs & Safe Rollback Management

Data Source Support Matrix

Compatibility

These are target ranges and verified environments. See COMPATIBILITY.md for the evidence matrix.

Dependencies

Additional mandatory Python dependencies: None beyond NetBox's runtime. NetBox supplies Django, PostgreSQL, and Redis requirements. External IPAM connectivity is optional and currently uses administrator-supplied file exports; vendor API/SQL clients are not bundled.

Compatibility and installation

Supports NetBox 4.4, 4.5, and 4.6 on Python 3.10+.

1. Installation

Standard NetBox (Virtual Environment)

Activate your NetBox virtual environment and install the plugin from PyPI:

source /opt/netbox/venv/bin/activate
pip install netbox-ip-history

NetBox Docker

Add netbox-ip-history to your plugin_requirements.txt:

netbox-ip-history

Note: To install directly from GitHub (e.g. latest development branch):

pip install --upgrade git+https://github.com/muratbulat/netbox-ip-history.git

2. Enable the Plugin

Add netbox_ip_history to PLUGINS in your /opt/netbox/netbox/netbox/configuration.py (or configuration/plugins.py for Docker):

PLUGINS = [
    "netbox_ip_history",
]

PLUGINS_CONFIG = {
    "netbox_ip_history": {
        # Enable or disable NetBox 4.x global search indexing for IP events and sources (default: True)
        "enable_global_search": True,
        # Enable or disable real-time tracking of native NetBox IP changes (default: True)
        "enable_native_event_tracking": True,
    }
}

3. Run Migrations & Collect Static Files

cd /opt/netbox
source /opt/netbox/venv/bin/activate
python netbox/manage.py migrate
python netbox/manage.py collectstatic --no-input
systemctl restart netbox
systemctl restart netbox-rq

For NetBox Docker:

docker compose restart netbox

The plugin will be available under /plugins/ip-history/ and directly accessible from NetBox IP Address (ipam.ipaddress) detail pages.

Configuration and security

All web views and API endpoints enforce strict Django model permissions with raise_exception=True (denying unauthenticated or unauthorized access with HTTP 403 Forbidden):

• view_historicalipevent: Access timeline search (/plugins/ip-history/), event details, multi-source comparison, and IP address page extension panels.
• add_historicalipevent: Access import data UI (/plugins/ip-history/import/).
• delete_historicalipevent: Execute safe rollback of import jobs (/plugins/ip-history/import-jobs/<pk>/rollback/).
• view_importjob: View import job audit logs and details (/plugins/ip-history/import-jobs/).
• view_importsource: View source matrix and adapter capabilities (/plugins/ip-history/sources/support/).

ImportSource records store source metadata, timezone, field mapping, support level, capabilities, and authority. Credentials, tokens, and passwords belong in PLUGINS_CONFIG or environment variables, never in database model records or logs.

Formats and workflow

GestioIP and phpIPAM adapters accept CSV/JSON exports and preserve unknown columns. phpIPAM JSON supports arrays and JSON Lines. Generic CSV supports UTF-8/BOM, delimiters, quoting, and source mappings stored on ImportSource; generic JSON supports arrays of objects and JSON Lines. Every upload creates an analyzed job; dry run is optional and performs no historical-event writes. The result and error details are visible under /plugins/ip-history/import-jobs/.

Management Commands

Large imports and native synchronization use CLI commands:

# Import external IPAM history (file export)
python netbox/manage.py import_ip_history --source gestioip --file /data/history.csv --history-only --dry-run
python netbox/manage.py import_ip_history --source phpipam --file /data/export.json --history-only

# Synchronize past native NetBox IP changes from core.ObjectChange into HistoricalIPEvent
python netbox/manage.py sync_netbox_ip_history --dry-run
python netbox/manage.py sync_netbox_ip_history

Repeat imports are idempotent through SHA-256 fingerprint deduplication. A permitted administrator can remove only events belonging to a selected job; native NetBox audit data and live inventory are never rolled back.

Supported source adapters

Adapters are independent registry entries. The support matrix at /plugins/ip-history/sources/support/ is generated from declarations and inspection results:

REST API Endpoints

NetBox REST API endpoints are available under /api/plugins/ip-history/ (secured by standard NetBox model permissions):

• GET /api/plugins/ip-history/events/: List and filter historical IP events.
• GET /api/plugins/ip-history/jobs/: List and monitor import jobs.
• GET /api/plugins/ip-history/sources/: List configured import source profiles.

Portable exchange format

Unsupported products can use the stable exchange format without a new adapter:

{
	"format": "netbox-ip-history",
	"version": 1,
	"source": {"type": "other", "name": "Legacy IPAM"},
	"records": [
		{"ip": "10.222.1.33", "timestamp": "2024-01-01T10:00:00+03:00", "owner_name": "APP01", "event_type": "assigned"}
	]
}

The same records may be supplied as JSON Lines for large migrations. Map source-native fields in the source profile; unknown fields remain in raw_data. Source scopes such as Infoblox network views, Device42 VRF groups, BlueCat configurations, and Micetro address spaces must be explicitly mapped to NetBox VRFs rather than merged by IP alone.

Timeline and features

Search /plugins/ip-history/?ip=10.222.1.33 or access the IP History menu directly from the NetBox sidebar. Scope is separated by VRF name/RD, and missing scope is shown as Global / Unknown. Native records are resolved from snapshots by canonical IP so deleted and recreated IP objects can share one timeline; historical owner/interface strings do not depend on live objects.

The plugin provides:

• Dedicated NetBox sidebar navigation menu (IP History) with sub-items for Timeline & Search, Source Comparison, Import Data, Import Jobs, and Source Matrix (without cluttering the generic Plugins menu).
• Direct NetBox IP Address integration: Action button and quick history widget panel on the NetBox ipam.ipaddress detail page (template_content.py).
• NetBox 4.x Global Search integration indexing IP addresses, hostnames, DNS names, and sources.
• Modern Bootstrap 5 UI with tabbed sub-navigation, stat summary metrics cards, colored event badges, and raw snapshot inspectors.

Project status

The core historical model, canonical-IP timeline, registry architecture, generic file workflow, and conservative provenance/rollback behavior are implemented. GestioIP, phpIPAM, generic CSV/JSON/JSONL, and portable exchange imports are the validated paths. Vendor modules are deliberately EXPORT or EXPERIMENTAL until tested against a specific product version; they do not invent API endpoints or audit support.

Development and testing

Install the plugin into a NetBox development environment, run python netbox/manage.py migrate, and execute python -m unittest discover -s tests -v. Build with python -m pip wheel . --no-deps --wheel-dir dist. New adapters should declare capabilities, return SourceInspection, normalize into the DTO contract, preserve raw_data, and add sanitized fixtures/tests.

Support

Bugs and feature requests: GitHub Issues. General questions: GitHub Discussions. Security reports: SECURITY.md and GitHub Security Advisories.

Contributing and license

See CONTRIBUTING.md, SECURITY.md, and LICENSE. This project is licensed under Apache-2.0.

Uninstall

Export required history, disable the plugin, run python netbox/manage.py migrate netbox_ip_history zero only after confirming retention requirements, remove the package, and restart NetBox services. Native NetBox tables are not modified by this plugin.