netbox-nsm 0.3.1

A NetBox plugin for documenting network security policy: rulebooks, zones, and NSM object links

netbox-nsm

Network Security Management for NetBox

Document zones, firewall rules, and object relationships — vendor-agnostic, inside your existing IPAM and DCIM inventory.

Full user guide · Using netbox-nsm · Architecture · Database · Changelog

Work in progress — not for production use.
netbox-nsm is a documentation plugin. It does not push rules to firewalls or replace Tufin, AlgoSec, or similar tools.

---

At a glance

Security Panel	Injected on every Prefix, IP, Device, VM, and Custom Object — assign zones, addresses, labels; see policy impact instantly
Rulebooks	Flexible column layout: zone-based, address-based, label-based, or mixed — side by side in one NetBox
Rules grid	Server-rendered rules table — Table / Group / Matrix views, filter query, cell display modes. See Rules grid.
Zone matrix	Source × destination heatmap on the Matrix tab
IP Analysis	Compare address resolution — Security Panel loupe (🔍) on analyzable objects; optional full page /plugins/netbox-nsm/ip-analysis/
Object Analyzer	@xyflow/react graph from any NetBox object to zones, links, and rulebooks

---

Why netbox-nsm?

Your network inventory already lives in NetBox. Security policy should live there too — not in spreadsheets or siloed tools.

• One source of truth — link a prefix to prod, a VM to an app zone, a device NIC to both
• Any object type — rule columns and Security Panel use TypeConfig; missing types? Create a Custom Object Type, then bind it in NSM
• Any vendor style — Palo Alto zones, AWS address groups, Illumio labels — each in its own Rulebook
• Bidirectional visibility — open a zone and see every prefix, VM, and rule that references it
• Audit-friendly — Journal and Changelog on rules, links, and configuration

---

Security Panel — the hub

The Security Panel is the core workflow for NSM. Once NSM types exist, any supported NetBox object can be linked to any allowed NSM object via + Assign — prefixes, interfaces, VMs, zones, services, … Rulebook references appear automatically when an NSM object is used in a rule column.

Inheritance (e.g. Inherit to IPAM children on a parent prefix) propagates macro zones to child prefixes and addresses without repeating + Assign on every object.

Macro vs. micro zones — different segmentation products on the same inventory:

Layer	Example	Purpose
Macro zone (product A)	prod, untrust on a prefix with IPAM inheritance	Site segment, trust boundary
Micro zone (product B)	app-payroll direct on a VM interface	Application tier within the macro segment

The same zone object linked on an interface is the same object used in rulebook columns (Source.Zones, Destination.Zones, …).

Zone untrust (Starter demo) — rulebook references + bidirectional service link

Assign Link — Direct, Inherit to IPAM children, or Inherit to group members

Service SNMP-Trap — reverse link to zone untrust after a bidirectional Direct assignment

Universal linking → · Security Panel deep dive →

Extend with your own object types

NSM is not limited to the seven built-in types (Zones, Addresses, …):

1. Need a new security object class? Define it in netbox-custom-objects (schema, fields, UI).
2. Register it in NSM — Security → Type Config → + Add: pick the ContentType, set matching class, panel slugs, display template, and which NetBox objects may link it (Linkable in panel).
3. Use everywhere — add the TypeConfig to Rulebook → Fields (rule columns + picker) and assign instances from any allowed host object via + Assign in the Security Panel.

Rule columns reference TypeConfig records, not hard-coded COT names — so custom and native NetBox types share the same pipeline once configured.

Full guide: extending NSM →

---

Screenshots

Starter demo environment (2026-06-07). Full walkthrough: Using netbox-nsm · Documentation home

Setup wizard — sections 1–4 complete, Starter demo	Custom Object Types — seven built-in nsm_* types
Type Config list — matching class, panel slugs, All types	Type Config edit — Zones, panel slugs, Linkable in panel
Rulebook list — Demo - Zone Matrix, Demo - Addresses	Rulebook detail — Fields hierarchy (Source / Destination / Service / Action)
Edit rulebook — metadata, Matrix tab, parent rulebook	Add field — container column under Source
Add field type — TypeConfig picker (Zones, Services, …)	Rulebook changelog — rule CRUD audit trail
Policy rules — Table view, zone/service pills, filter bar	Add rule — Demo - Zone Matrix, Source tab
Rule detail — trust-to-untrust, zone/service columns	Zone matrix — 4×4 grid, Permit / Deny cells
Zone untrust — rulebook references + service link	Assign Link — link type dropdown (Direct / IPAM / group)
Service SNMP-Trap — bidirectional zone link (reverse view)	Object Analyzer — zone dmz → Demo - Zone Matrix → rules

---

Quick start

1. Install

pip install netbox-nsm

# configuration.py
PLUGINS = [
    "netbox_custom_objects",   # required
    "netbox_nsm",
]

./manage.py migrate netbox_custom_objects --no-input
./manage.py migrate netbox_nsm --no-input

2. Setup wizard

Security → Configuration → Setup — run sections 1 → 2 → 3 in order:

#	Section	Action
1	Menu & panel title	Labels for sidebar and Security card
2	Custom Objects	Add all Custom Object Types (7 built-in COTs)
3	TypeConfig	Add all TypeConfigs (matching, panels, display)
4	Demo	Starter demo (recommended) — or Enterprise DC when the IP database is empty

3. First links

Open any Prefix → Security Panel → + Assign → pick a Zone.
Open the Zone object → see the reverse view (prefixes, VMs, matching rules).

4. First rulebook

Security → Rulebooks → + Add — or run the Starter demo from Setup (Section 4) for ready-made sample rulebooks.

---

Configuration

PLUGINS_CONFIG = {
    "netbox_nsm": {
        "top_level_menu": True,              # Security top-level menu
        "setup_menu": True,                  # Setup under Configuration
        "setup_allow_destructive_actions": True,  # Demo imports (disable in prod)
        "assignments_menu": False,           # Rulebook Assignments menu entry
        "menu_label": "Security",
        "panel_label": "Security",
    }
}

Restart NetBox after changes.

---

Feature map

Custom Object Types — zones, addresses, labels, services, actions, apps

Seven built-in types via Setup Section 2. Managed under Custom Objects → NSM.

Custom Object Types →

Type Config — matching class, display template, panel slugs

Links each ContentType to NSM (built-in COTs or your own Custom Object Types): matching class, display template, panel sections, and Linkable in panel. Required before a type can appear in Rulebook fields or + Assign.

Type Configs → · Extend with custom types →

Rulebooks & rules — flexible columns, All Rules view, rule editor

• All Rules (/rulebooks/0/) — read-only aggregate across all rulebooks
• Rulebook detail — configurable field hierarchy (zone-based, address-based, …)
• Rules tab — server-rendered table with Table / Group / Matrix views and filter query — Rules grid
• Add rule — Source / Destination / Service / Action tabs with object picker

 

Security Rulebooks →

Zone matrix — source × destination, directed / undirected

Corner filters (dmz OR mgmt), diagonal self-cells, axis limit 250 zones.

Zone Matrix →

IP Analysis — two-column IP resolution + CSV paths

Security Panel — loupe icon (address-analyzable objects only)

Opens the IP Analysis overlay (same API as /plugins/netbox-nsm/ip-analysis/). Compare prefix trees side by side and copy CSV paths from the tree.

IP Analysis →

Object Analyzer — explore links and rulebooks from any object

Security → Analysis → Object Analyzer

Pick Device, VM, IP, Prefix, or Zone → Analyse → expand the graph.

Object Analyzer →

---

REST API

Base path: /api/plugins/netbox-nsm/

Endpoint	Model
object-links/	ObjectLink
type-configs/	TypeConfig
rulebooks/	Rulebook
rules/	Rule
security-policy-assignments/	RulebookAssignment

Portable schema: POST /api/plugins/custom-objects/schema/apply/ with bundled nsm_portable_schema.json.

REST API reference →

---

Demo data

After Setup sections 1–3, use Section 4 (Demo) to load sample rulebooks. Requires setup_allow_destructive_actions: True in PLUGINS_CONFIG.

Starter demo (recommended)

The Starter demo is the primary entry point for exploring netbox-nsm. It runs synchronously in the browser (no RQ worker) and is always available at Security → Configuration → Setup → Demo → Create once section 3 is complete.

Created	Details
Prerequisites	Imports built-in Custom Object Types and TypeConfigs if missing; seeds default zones (trust, untrust, dmz, mgmt), actions (Permit, Deny), and services (HTTPS, SSH)
Demo - Zone Matrix	Zone-based rulebook with six example rules — use it for the Rules grid, grouping, and Zone matrix
Demo - Addresses	Address-based rulebook layout (zones + addresses in source/destination columns) — schema only, no pre-filled rules

Typical workflow: run Starter demo → open Security → Rulebooks → Demo - Zone Matrix → switch Table / Group / Matrix views → assign zones from any Prefix via the Security Panel.

Step-by-step matrix walkthrough: Demo - Zone Matrix example in the user guide.

Other demos

Demo	Availability
Enterprise DC	Visible in Setup; full DC scenario (DCIM + IPAM + 11 rulebooks, ~30–60 s). Disabled when IP addresses already exist
Scale test / Addresses demo	Not shown in the Setup UI — high-volume performance tests (~12k / ~6k rules, background RQ queue, ~1–2 min). CLI scripts under scripts/ if needed

---

Compatibility

NetBox	Plugin
4.5+	0.3.x

---

Third-party UI

Library	License	Used in
@xyflow/react 12	MIT	Object Analyzer (CDN via esm.sh)

Details: Third-party UI libraries

License

See LICENSE.