Metadata-Version: 2.4
Name: netbox-history
Version: 0.1.1
Summary: Search NetBox changelog snapshots by field value, including deleted objects
Author-email: Avery Abbott <averyhabbott@yahoo.com>
Maintainer-email: Avery Abbott <averyhabbott@yahoo.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/averyhabbott/netbox-history
Project-URL: Source, https://github.com/averyhabbott/netbox-history
Project-URL: Issues, https://github.com/averyhabbott/netbox-history/issues
Project-URL: Changelog, https://github.com/averyhabbott/netbox-history/blob/main/CHANGELOG.md
Keywords: netbox,netbox-plugin,changelog,history,audit
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# netbox-history

A NetBox plugin that searches changelog snapshots by field value — including
data from objects that have since been **deleted**.

When a NetBox object is deleted, its data disappears from the primary tables but
lives on in `core.ObjectChange` as serialized JSON in `prechange_data` /
`postchange_data`. NetBox's built-in changelog UI only filters by object type
and primary key — not by arbitrary field values inside the snapshot. This plugin
adds a UI search view and a REST API over those snapshots.

It adds **no database models and requires no migrations** — it is a pure
search-and-display layer over `core.ObjectChange`.

## Requirements

- NetBox >= 4.5.0 (tested through the 4.6.x line)
- Python >= 3.12

## Installation

```bash
pip install -e .
```

Add the plugin to your NetBox `configuration.py`:

```python
PLUGINS = ['netbox_history']
```

Restart NetBox. No migrations are required.

## Usage

### UI

Navigate to **Plugins → History → History Search**. Choose an object type and
field, enter a value, pick a match mode (Contains / Exact), and optionally a
date range. Results show the searched field's before/after values alongside the
standard changelog columns.

### REST API

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/plugins/history/models/` | List searchable models |
| `GET` | `/api/plugins/history/models/<model>/` | Field structure for a model (case-insensitive) |
| `POST` | `/api/plugins/history/search/` | Execute a changelog search |

Example search request:

```json
{
  "model": "IPAddress",
  "query": {"field": "dns_name", "match_type": "partial", "search_text": "myhost"},
  "max_results": 100,
  "search_history_days": 30
}
```

## Adding searchable models

Edit [`netbox_history/registry.py`](netbox_history/registry.py) and add an entry
to `SEARCHABLE_FIELDS`, keyed by `"<app_label>.<model_name>"`. Include only
simple string/choice fields that appear as direct keys in the JSON snapshot
(foreign-key fields serialize as integer IDs and are not useful to search).

## License

This project is licensed under the GNU General Public License v3.0 or later
(GPL-3.0-or-later). See the [LICENSE](LICENSE) file for the full text.
