netbox-assurance
NetBox Assurance drift detection and deviation management. Use when working with network state comparison, deviation review/remediation, data source configuration, or understanding how intended vs actual network state is reconciled in NetBox Cloud and Enterprise.
netboxlabs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add netboxlabs/skills --skill netbox-assuranceAbout this skill
name: netbox-assurance description: > NetBox Assurance drift detection and deviation management. Use when working with network state comparison, deviation review/remediation, data source configuration, or understanding how intended vs actual network state is reconciled in NetBox Cloud and Enterprise. license: Apache-2.0
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
| Source | URL / Method | Use for |
|---|---|---|
| Assurance docs | https://netboxlabs.com/docs/assurance/ | Overview, getting started, UI workflows |
| NetBox Platform MCP | If configured — query deviations, data sources | Live drift status |
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
| State | Meaning |
|---|---|
| Queued | Ingested data awaiting analysis |
| Open | Drift detected, ready for review |
| Applied | Change accepted and pushed to NetBox |
| Ignored | Dismissed by operator |
| Failed | Apply attempted but errored |
| No Changes | Analysis found no differences |
| Errored | Processing error during analysis |
Actions
| Action | What It Does | Available From |
|---|---|---|
| Apply | Accept deviation, update NetBox to match actual state | Open, Failed |
| Ignore | Dismiss deviation permanently | Open |
| Rediff | Re-analyze against current NetBox state | Open, Applied, Failed |
| Reopen | Bring back an ignored deviation | Ignored |
All actions support bulk operations on multiple deviations.
Drift Types
| Type | Description | Example |
|---|---|---|
| Attribute drift | Object exists in both places but properties differ | Device serial number changed |
| Inventory drift (additive) | Object discovered on network but missing from NetBox | New interface found on device |
| Inventory drift (stale) | Object in NetBox but not recently observed on network | Decommissioned device still in NetBox |
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
- Data ingested — network data arrives from a data source → deviation enters Queued
- Analysis runs — system compares against NetBox → deviation moves to Open (or No Changes)
- Operator reviews — examines field-level changes in the UI
- 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
| Scenario | Recommended Action |
|---|---|
| Legitimate change detected (e.g., new interface added) | Apply — update NetBox |
| Known discrepancy you don't want to track | Ignore — dismiss it |
| You manually updated NetBox already | Rediff — re-analyze to confirm |
| Previously ignored but situation changed | Reopen → then Apply or Rediff |
| Apply failed due to transient error | Fix the issue, then Rediff or retry Apply |
UI Workflow
Navigation
Assurance adds an Assurance section to the NetBox navigation with these views:
| View | Purpose |
|---|---|
| Deviation Types | Browse deviation categories with counts |
| Active Deviations | Unresolved deviations needing |