netbox-ninja-plugin 0.3.1

Dynamic configuration files and images from NetBox.

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.

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:

See video introduction in Youtube.

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.5.x
• 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.6.x	0.3.1	29.5.2
4.6.x	0.3.0	29.5.2
4.5.x	0.2.1	29.5.2
4.5.x	0.2.0	29.5.2
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:

pip install netbox-ninja-plugin

2. Add to NetBox configuration:

PLUGINS = [
    'netbox_ninja_plugin',
]

3. Configure the plugin (see CONFIGURATION.md for detailed options):

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.

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 - Detailed usage examples and tutorials
• Configuration - Detailed configuration options and examples

License

This project is licensed under the MIT License - see the LICENSE file for details.