Netbox Assurance

NetBox Assurance

Your knowledge of NetBox Assurance may be outdated. Deviation types, data source configuration, and API behavior evolve between releases. Prefer retrieval over pre-trained knowledge.

Retrieval Sources

NetBox Assurance detects drift between your intended network state (what NetBox says should exist) and the actual network state (what's really out there). It surfaces differences as deviations that you review and resolve through the NetBox UI.

When to Use This Skill

• Configuring or troubleshooting Assurance deviation workflows
• Understanding drift types and how to resolve them
• Setting up data sources that feed actual network state
• Integrating Assurance with Discovery and Diode
• Building operational workflows around deviation triage

Quick Reference

Deviation States

Actions

All actions support bulk operations on multiple deviations.

Drift Types

Topology drift (relationship mismatches like device→wrong site) and configuration drift (running config vs intended) are future capabilities.

Architecture

Assurance follows a three-stage pipeline:

1. INGESTION          2. ANALYSIS              3. RESOLUTION
   ─────────            ────────                 ──────────
   Actual state    →    Compare actual     →     Review deviations
   collected from       vs intended              and take action
   network              (NetBox) state           (apply/ignore)

Data sources feed actual network state into the system:

• Discovery agents — automated SNMP/API-based network scanning
• Controller integrations — VMware vCenter, Cisco Catalyst Center, HPE Mist, etc.
• Diode SDK — custom Python/Go integrations for any data source

The analysis engine compares ingested data against NetBox and produces deviations with field-level change details (before/after values for each differing attribute).

Data Sources

Assurance requires at least one data source providing actual network state. See references/data-sources.md for detailed setup.

Discovery Agents (Recommended Starting Point)

The Orb Agent from NetBox Discovery actively scans your network and feeds results directly into Assurance. This is the most common path for getting started.

See the netbox-discovery skill for agent configuration.

Controller Integrations

Pre-built integrations with infrastructure controllers (VMware vCenter, Cisco Catalyst Center, HPE Mist, etc.) pull state from management platforms.

Diode SDK (Custom Integrations)

For data sources without built-in support, use the Diode SDK (Python or Go) to push entity data programmatically.

See the netbox-diode skill for SDK usage patterns.

Deviation Lifecycle

See references/deviation-lifecycle.md for the complete state machine.

Typical Workflow

1. Data ingested — network data arrives from a data source → deviation enters Queued
2. Analysis runs — system compares against NetBox → deviation moves to Open (or No Changes)
3. Operator reviews — examines field-level changes in the UI
4. Action taken:
   • Apply → NetBox updated, deviation marked Applied
   • Ignore → deviation dismissed, marked Ignored
   • Rediff → re-analyzed against current NetBox state (useful after manual NetBox edits)

Resolution Patterns

UI Workflow

Navigation

Assurance adds an Assurance section to the NetBox navigation with these views:

Reviewing a Deviation

1. Navigate to Assurance → Active Deviations
2. Click a deviation to open the detail view
3. Overview tab — source, object type, state, timestamps
4. Changes tab — field-level before/after comparison
5. Take action: Apply, Ignore, or Rediff

Bulk Operations

Select multiple deviations from any list view to perform bulk actions:

• Bulk Rediff — re-analyze all selected against current NetBox state
• Bulk Ignore — dismiss all selected
• Bulk Apply — accept all selected changes into NetBox

Filtering

Deviation lists support filtering by:

• State — Open, Applied, Failed, Ignored, etc.
• Object type — e.g., devices, interfaces, IP addresses
• Deviation type — classification of the drift
• Data source — which integration produced it
• Time range — when the data was ingested

Deviation Types

Deviations are classified by type, combining the action needed with the object type:

• Create types — object needs to be added to NetBox (inventory drift)
• Update types — object exists but attributes differ (attribute drift)

Each deviation type aggregates a count of matching deviations, making the Deviation Types view useful for understanding drift patterns at a glance.

What Gets Compared

Any entity type flowing through the ingestion pipeline can be compared. Common types:

• Devices (dcim.device)
• Interfaces (dcim.interface)
• Sites (dcim.site)
• Device types (dcim.devicetype)
• IP addresses (ipam.ipaddress)
• Prefixes (ipam.prefix)

The system is extensible — it compares whatever entity types the data sources provide.

Integration Patterns

See references/integration-patterns.md for detailed integration guidance.

With NetBox Discovery

Discovery agents provide the "actual state" side of the comparison:

Network Devices → Orb Agent (Discovery) → Assurance → Deviations → NetBox

Discovery and Assurance are tightly coupled — Discovery collects, Assurance compares and remediates.

With Diode SDK

The Diode SDK is the programmatic ingestion path for custom integrations:

Custom Script → Diode SDK (Python/Go) → Assurance → Deviations → NetBox

With NetBox Branching

Deviations can be scoped to NetBox branches, allowing you to:

• Review drift against a specific branch's state
• Apply changes to a branch rather than the main database
• Use branches as a staging area for deviation resolution

Day 1 / Day 1.5 / Day 2 Patterns

Permissions

Assurance defines two permission levels:

Assign these through NetBox's standard user/group permission system.

Prerequisites

• NetBox Cloud or NetBox Enterprise with Assurance enabled (on Enterprise, your license file determines whether Assurance services are installed; on Cloud it's a licensed add-on). The Assurance plugin supports NetBox 4.4.10 through 4.6.x (current plugin line v1.5.x).
• At least one configured data source
• Network connectivity between data sources and the Assurance service

Assurance is an optional, licensed add-on for NetBox Cloud and NetBox Enterprise — it is not part of open-source NetBox Community.

Troubleshooting

No Deviations Appearing

1. Verify data sources are active and sending data
2. Check that Discovery agents are running and collecting (see netbox-discovery)
3. Confirm ingestion is working (data should flow through to analysis)
4. Allow time — analysis is asynchronous and may take minutes

Too Many False Positives

• Review which object types and fields are generating noise
• Use Ignore for known acceptable discrepancies
• Consider whether data source configuration needs tuning (e.g., SNMP community strings, API credentials)

Failed Deviations

• Check the error details in the deviation detail view
• Common causes: permission issues writing to NetBox, validation errors, dependency ordering
• After fixing the root cause, use Rediff to re-analyze

Performance with Large Networks

• Use filtering to narrow deviation views (by state, object type, time range)
• Address deviations incrementally — start with one object type or site
• Bulk operations help process large batches efficiently

Anti-Patterns and Limitations

1. Assurance compares what data sources provide — if a data source doesn't collect a field, Assurance can't detect drift on it
2. Ordering matters for applies — some deviations depend on others (e.g., you must create a site before assigning a device to it). The system handles dependency ordering, but complex chains may need manual intervention
3. Stale inventory detection is limited — detecting objects that should be removed from NetBox (because they no longer exist on the network) depends on observation timestamps and is an evolving capability
4. Not a real-time system — there is inherent latency between network changes, discovery, analysis, and deviation availability
5. Branch scoping — when using branches, ensure you're reviewing deviations against the correct branch context

References

Related Skills

• netbox-discovery — Orb Agent configuration for network scanning
• netbox-diode — Diode SDK for programmatic data ingestion
• netbox-branching — Branch-aware workflows