English | Türkçe
Documentation: GitHub Wiki
NetBox plugin 0.2.13 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
| Plugin | NetBox | Python | Status |
|---|---|---|---|
| 0.2.x | 4.4.x | 3.10-3.12 | Target range; automated testing pending |
| 0.2.x | 4.5.x | 3.10-3.12 | Target range; automated testing pending |
| 0.2.x | 4.6.x | 3.10-3.12 | Tested & Verified (NetBox Community v4.6.8) |
These are target ranges and verified environments. See COMPATIBILITY.md for the evidence matrix.
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.
Supports NetBox 4.4, 4.5, and 4.6 on Python 3.10+.
Activate your NetBox virtual environment and install the plugin from PyPI:
source /opt/netbox/venv/bin/activate
pip install netbox-ip-historyAdd 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
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,
}
}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-rqFor NetBox Docker:
docker compose restart netboxThe plugin will be available under /plugins/ip-history/ and directly accessible from NetBox IP Address (ipam.ipaddress) detail pages.
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.
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/.
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_historyRepeat 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.
Adapters are independent registry entries. The support matrix at /plugins/ip-history/sources/support/ is generated from declarations and inspection results:
| Source | Level | Notes |
|---|---|---|
| GestioIP, phpIPAM | EXPORT | CSV/JSON inventory/history normalization |
| RackTables, NIPAP, TeemIP, Microsoft IPAM, Ralph | EXPORT | Use reviewed exports or read-only source views |
| GLPI, Device42, Infoblox, BlueCat, Micetro, EfficientIP | EXPERIMENTAL | File/API capability is source-version dependent and must be inspected |
| SolarWinds, ManageEngine, Nautobot | EXPERIMENTAL | Inventory/observation data; do not equate discovery with assignment |
| Another NetBox instance | EXPERIMENTAL | REST/export contract; source ObjectChange provenance is retained when retrieved |
| Generic SQL / Other IPAM | EXPERIMENTAL / EXPORT | Administrator-defined mappings; read-only SQL only |
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.
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.
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.ipaddressdetail 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.
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.
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.
Bugs and feature requests: GitHub Issues. General questions: GitHub Discussions. Security reports: SECURITY.md and GitHub Security Advisories.
See CONTRIBUTING.md, SECURITY.md, and LICENSE. This project is licensed under Apache-2.0.
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.