Metadata-Version: 2.4
Name: netbox-ninja-plugin
Version: 0.1.15
Summary: Dynamic configuration files and images from NetBox.
License: MIT
License-File: LICENSE
Author: Veikko Pankakoski
Author-email: veikko@rautanen.io
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: lxml (>=5.0,<7.0)
Requires-Dist: requests (>=2.32.2,<3.0.0)
Project-URL: Documentation, https://github.com/rautanen-io/netbox-ninja-plugin
Project-URL: Homepage, https://rautanen.io
Project-URL: Repository, https://github.com/rautanen-io/netbox-ninja-plugin
Description-Content-Type: text/markdown

# Netbox Ninja Plugin

<img src="images/ninja-logo.svg" width="100">

[![Development Status](https://img.shields.io/badge/status-beta-yellow.svg)](https://github.com/rautanen-io/netbox-ninja-plugin)

A NetBox plugin for generating dynamic text files and images using Jinja2 templates.

## Overview

Netbox Ninja Plugin enables dynamic content generation in NetBox through Jinja2 templates. It supports both text file generation and SVG image creation from draw.io XML templates, seamlessly integrating with NetBox's data model.

```mermaid
graph LR
    DATA[Any data in Netbox] --> TEMPLATE[Ninja template]
    TEMPLATE --> DRAWIO[Drawio file]
    DRAWIO[Drawio file] --> SVG[SVG image]
    TEMPLATE --> JSON[JSON file]
    TEMPLATE --> TEXT[Generic text]
    SVG --> NBUI[Netbox UI]
    JSON --> NBUI[Netbox UI]
    TEXT --> NBUI[Netbox UI]
    SVG --> API[Netbox API]
    JSON --> API[Netbox API]
    TEXT --> API[Netbox API]
```
Output files can be seen via Netbox UI and accessed via API.

Example of automatically generated network diagram:

<img src="images/network-diagram-example.jpeg">

See video introduction in [Youtube](https://youtu.be/yTFBYkSDgWY?si=YAkBmPFcv_doXWgH).

> **Note**: This plugin is currently in beta. While it's functional, some features are still under development and the API may change in future releases.

## Use cases
Netbox Ninja Plugin can be used to generate **always up-to-date** outputs for many use cases including (but not limited to) following:
- Network diagrams
- Any other visualization of any Netbox data
- Configuration files for others systems to fetch from Netbox
- Any other text based output for any purpose

## Key Features

- Dynamic text file generation using Jinja2 templates
- Template-based SVG image generation from draw.io XML format
- Direct integration with NetBox's data model
- REST API endpoints for template management
- Support for object-specific template rendering
  - Show output in Ninja tab in chosen Netbox object view (i.e. Site)
  - Tempalate rendered per object (i.e for each Site)
- Per-template dropdown filters on Ninja tab templates (object type + string filters)

## Requirements

- NetBox v4.0.11 - v4.4.10
- [drawio-export-api](https://github.com/rautanen-io/drawio-export-api) Docker container. Optional, required for SVG images that need to be fetched through REST API.

## Compatibility

Plugin versions listed below have been tested with its corresponding NetBox version.

| NetBox Version   | Plugin Version | draw.io / diagrams.net version |
|:----------------:|:--------------:|:-------------------------------:
|  4.4.0 - 4.4.10  |     0.1.15     |            29.5.2              |
|  4.4.0 - 4.4.10  |     0.1.14     |            29.5.2              |
|  4.4.0 - 4.4.7   |     0.1.13     |            27.1.0              |
|  4.2.3 - 4.3.7   |     0.1.12     |            27.1.0              |
|  4.2.3 - 4.3.7   |     0.1.11     |            27.1.0              |
|  4.2.3 - 4.3.6   |     0.1.10     |            27.1.0              |
|  4.0.11 - 4.3.2  |     0.1.9      |            27.1.0              |


## Test Ninja in Codespaces

The quickest way to test Ninja is using GitHub Codespaces:

1. Click the "Code" button on the repository and select "Create codespace on main"
2. Once your Codespace is ready, run `make demo_environment` in the terminal
3. Access the development environment at http://localhost:8000 with credentials admin/admin

## Quick Start

1. Install the plugin:
```bash
pip install netbox-ninja-plugin
```

2. Add to NetBox configuration:
```python
PLUGINS = [
    'netbox_ninja_plugin',
]
```

3. Configure the plugin (see [CONFIGURATION.md](CONFIGURATION.md) for detailed options):
```python
PLUGINS_CONFIG = {
    "netbox_ninja_plugin": {
        "target_models": {
            "dcim": ["device", "interface", "site", "region"],
            "ipam": ["prefix"],
        },
        "jinja_model_querysets": {
            "dcim": ["device", "interface", "site", "region"],
            "ipam": ["prefix"],
        },
        "filter_variable_prefix": "filter_",
        "drawio_export_api": {
            "enabled": True,
            "url": "https://drawio-export-api:443/svg",
            "token": "your-token",
            "pem_file_path": "/path/to/drawio_export_api.pem",
            "verify_tls": True,
            "timeout": 60,
        },
        "top_level_menu": False,
    }
}
```

## Usage

### Template Creation

1. Navigate to NetBox's Ninja Templates section
2. Create a new template with:
   - Name: Template identifier
   - Output type: Text or Draw.io format
   - Object types: NetBox objects to associate with the template
   - Object type filters: Adds dropdown filters on the Ninja tab for templates (based on selected object types)
   - String filters: Adds dropdowns on the Ninja tab for reusable string filter options
   - Template code: Your Jinja2 template

### Template Variables

- Access NetBox objects using object queries, e.g. `{{ sites.first() }}` or `{{ regions.get(slug='region1') }}`
- For object-specific templates, use `{{ target_object }}` to reference the current object
- Ninja tab dropdown filter selections are exposed to templates as Jinja variables.
  - Variable names use `filter_variable_prefix` (default: `filter_`), e.g. `{{ filter_sites }}`.
  - Object type filter variables receive a queryset of the selected objects (or `None` when no selection is made).
  - String filter variables receive a list of the selected option values (or `None` when nothing is selected).
- Filter selections persist via query parameters while the page is open, and each template card has its own scoped reset.

For detailed examples and use cases, see [EXAMPLES.md](EXAMPLES.md).

## Security Note

The plugin currently doesn't enforce object-level permissions in templates. Exercise caution when exposing data through templates, as users may access data beyond their normal permissions.

## Documentation

- [Examples](EXAMPLES.md) - Detailed usage examples and tutorials
- [Configuration](CONFIGURATION.md) - Detailed configuration options and examples

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

