NetBox CMDB

Community Platform

runZero integrates with NetBox configuration management database (CMDB) using the NetBox REST API to enrich your asset inventory.

NetBox limitations

runZero explicitly supports NetBox version 4. Older versions (3.x) may be compatible, but are not specifically tested or supported.

Since NetBox data entry is free-form, the runZero integration may not be a good fit for your organization, and we strongly recommend testing this integration in a Project first before configuring it for a production Organization.

The NetBox integration will import Devices and Virtual Machines, as well as their associated resources.

The NetBox integration will NOT create entities for anything other than Devices and Virtual Machines.

The Device and Virtual Machine records are imported as runZero assets with the following fields:

Device or Virtual Machine
- ID in the form of device.<ID> or vm.<ID>
- Name
- FirstSeenTS and LastSeenTS
- Serial
- AssetTag (Device only)
- Interfaces
  - IP addresses for PrimaryIP / PrimaryIP4 / Primary IP6 / OOB IP
  - Additional IP addresses using the ip<index>.field syntax
  - NAT Inside and NAT Outside addresses
  - MAC Addresses (if entered in NetBox)
  - CreatedTS and UpdatedTS
  - ID, DNSName, Name, Comments, and Description
  - Module Name, MTU, Speed (Device only)
  - Tagged and Untagged VLANs
  - Custom Fields
- Prefixes
  - VLAN and CIDR
  - ID, Comments, and Description
  - Role Name
  - Custom Fields
- Location
  - ID and Name
  - Latitude and Longitude
  - Chained Location Path
  - Custom Fields
- Rack
  - ID and Name
  - Position and Rack Face
- Status
- Manufacturer
  - ID, Name, and Model
  - Comments, Description, and Part Number
  - Custom Fields
- Device Role
  - ID, Name, Description
  - Custom Fields
- Platform
  - ID & Name
  - Custom Fields
- Site
  - ID, Name, Description, Comments
  - Facility, Physical Address, Shipping Address
  - Region, Group
  - Custom Fields
- Virtual Chassis
  - ID, Name, Comments, and Description
  - Master ID and Master Name
  - VC Position and Priority
- Interface Count
- Inventory Item Count
- Custom Fields

The following top-level attributes are rollups across all sub-fields:

Addrs
Names
MACs
VLANs

NetBox asset matching

runZero will use the Name, IP Address, and MAC Addresses to match NetBox Devices and Virtual Machines to runZero assets. If there isn’t a direct match, runZero will create a new asset record, unless the “Exclude unknown assets” option is enabled. Since NetBox data is typically static and network assets tend to change over time, there is a good chance that many assets will not match. MAC Addresses are the most reliable way to correlate these, but many organizations do not fill out the MAC Address fields in NetBox.

NetBox asset fingerprinting

runZero will use the mfg.name as the hardware vendor and mfg.model as the hardware model for Devices. runZero will report Virtual Machine vendors by matching the Cluster Type field to a known list of common hypervisors (Xen, VMware, Proxmox, etc.). The platform.name field, with and without the mfg.name field as a prefix will be used to find an operating system match.

The NetBox operating system data in platform.name will be treated as low-confidence relative to agent-based sources like EDRs and CMDB.

The NetBox hardware values will be treated similarly, with live agent-based sources taking priority.

Getting started

To set up the NetBox integration, you will need:

A NetBox instance in the cloud or that is reachable by one of your runZero Explorers.
An administrative account in the NetBox instance.

Step 1: Create a NetBox API key

Sign in to your NetBox portal.
Click on your name in the upper right and select API Tokens from the drop-down.
Click Add a Token and define a new token with no expiration and without Write permissions.
Give this new key a name and copy the secret value.

Step 2: Add the NetBox credential to runZero

Go to the Credentials page in runZero and click Add Credential.
Provide a name for the credential, like NetBox CMDB.
Choose NetBox API Key from the list of credential types.
Provide the following information:
- Name - Give this credential a unique name (ex:NetBox)
- NetBox URL - The URL for your NetBox portal.
- NetBox API key - The API key created in step 1.
Save the credential.

You’re now ready to set up and activate the connection to bring in data from NetBox.

Step 3: Configure the NetBox integration as a connector task

A connection requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new NetBox-only assets are created.

We strongly recommend testing NetBox in a a new Project first before applying this to your production Organization. Create a new Project.
Activate a connection to NetBox. You can access all available third-party connections from the integrations page, your inventory, or the tasks page.
Choose the credential you added earlier. If you don’t see the credential listed, make sure the credential has access to the organization or project you are currently in.
Enter a name for the task, like NetBox sync.
Leave the default settings to create a one-off sync task.
Under Task configuration, choose the site you want to add your assets to. NetBox assets that do not match existing assets will use this site by default.
If you want to exclude assets that have not been scanned by runZero from your integration import, switch the Exclude unknown assets toggle to Yes.
Activate the connection when you are done. The task will run. You can always check the Tasks page to track the status.

Step 4: View NetBox assets

After a successful sync, you can go to your inventory to view your NetBox assets. These assets will have a NetBox icon listed in the Source column.

To filter by NetBox assets, consider running the following queries:

View all NetBox assets:
```
 source:netbox
```

Click into each asset to see its individual attributes. runZero will show you the attributes returned by the NetBox API.

Review the new NetBox assets and confirm that the NetBox-sourced asset count is roughly in-line with your overall inventory and the total in NetBox itself

If there are far fewer NetBox-sourced assets in runZero, you may want to avoid the final step until NetBox is updated with better correlation data.

Step 5: Enable Unknown Assets in Recurring Sync

Configure a new recurring NetBox task, with Exclude unknown assets disabled. This will create new assets for anything in NetBox that runZero can’t correlate to in your asset inventory. If this process creates significant duplicates, delete all assets matching the filter source_count:1 AND source:netbox, and re-enable the Exclude unknown assets option in your recurring task until the NetBox records have better correlation data (MAC addresses, hostnames, etc.).

Troubleshooting

If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.

Why is the NetBox integration unable to connect?

Are you getting any data from the NetBox integration?
- Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
- In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly.
If the NetBox integration is unable to connect be sure to check the task log for errors. Some common errors include:
- 500 - server error, unable to connect to the URL
- 404 - hitting an unknown URL on the server
- 401 - not authorized, likely a credential issue
- 403 - access denied, likely a credential issue
Verify you are running the integration task from an Explorer with access to the NetBox host if it is on-premises.

Updated April 9, 2025

Previous: Miradore MDM Next: Qualys VMDR