NetBox CMDB

View as Markdown

Community Platform

runZero imports records from your NetBox configuration management database (CMDB) through the NetBox REST API to enrich your asset inventory.

NetBox limitations

runZero supports NetBox version 4. Older versions (3.x) may be compatible, but runZero does not test or support them.

NetBox data entry is free-form, so the integration may not be a good fit for your organization. We strongly recommend testing it in a Project before you configure it for a production Organization.

The integration imports Devices and Virtual Machines, along with their associated resources, but creates entities only for those two types.

Device and Virtual Machine records become runZero assets with these 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

These top-level attributes roll up values across all sub-fields:

  • Addrs
  • Names
  • MACs
  • VLANs

NetBox asset matching

runZero matches NetBox Devices and Virtual Machines to runZero assets by Name, IP Address, and MAC Addresses. Without a direct match, runZero creates a new asset record, unless you enable the “Exclude assets that cannot be merged into an existing asset” option. NetBox data is typically static while network assets tend to change over time, so there is a good chance that many assets will not match. MAC Addresses are the most reliable way to correlate them, but many organizations leave the MAC Address fields in NetBox empty.

NetBox asset fingerprinting

For Devices, runZero uses mfg.name as the hardware vendor and mfg.model as the hardware model. For Virtual Machines, runZero reports the vendor by matching the Cluster Type field against a list of common hypervisors (Xen, VMware, Proxmox, etc.). To find an operating system match, runZero tries the platform.name field both with and without mfg.name as a prefix.

runZero treats the NetBox operating system data in platform.name as low-confidence relative to agent-based sources like EDRs and CMDB.

NetBox hardware values get the same treatment, with live agent-based sources taking priority.

NetBox-to-runZero custom field mapping

You can map custom fields in NetBox to attributes in runZero. These mappings override the mfg.name, mfg.model, and platform.name attributes described above.

In the field mapping widget of the NetBox task configuration, the “NetBox field” inputs must be the name properties of the custom fields in NetBox.

You can map custom fields to these runZero attributes:

  • hostnames: The hostnames to apply to the asset in runZero. Separate multiple hostnames in the NetBox custom field with commas, and no hostname may contain tab characters. This custom field must be a Text type.
  • manufacturer: The manufacturer to apply to the asset in runZero. This custom field must be a Text type.
  • model: The model to apply to the asset in runZero. This custom field must be a Text type.
  • device_type: The type of device to apply to the asset in runZero. This custom field must be a Text type.
  • first_seen_ts: The “first seen time” to apply to the asset in runZero. This custom field must be either a Date & time or Date type.
  • os: The type of operating system to apply to the asset in runZero. This custom field must be a Text type.
  • os_version: The version of the operating system to apply to the asset in runZero. This custom field must be a Text type.

Usage within the runZero CLI scanner

To map custom fields with the runZero CLI scanner, pass a JSON array like this one as an argument. In each array item, the “key” is the NetBox custom field name and the “value” is the runZero attribute:

--netbox-field-mappings '[{"key":"netboxHostnames","value":"hostnames"},{"key":"netboxManufacturer","value":"manufacturer"}]'

This example maps the NetBox custom field netboxHostnames to the runZero hostnames attribute and the NetBox custom field netboxManufacturer to the runZero manufacturer attribute.

Searchable time attributes

The integration creates a searchable attribute in runZero from every Date & time or Date NetBox attribute. For example, a NetBox attribute called “lastChecked” with a value of 2024-07-26T15:30:00Z produces a new attribute called lastCheckedTS with a Unix epoch timestamp value of 1722017400.

Getting started

To set up the NetBox integration, you need:

  1. A NetBox instance in the cloud or reachable from one of your runZero Explorers.
  2. An administrative account in the NetBox instance.
  3. A v1 NetBox API key. runZero does not currently support v2 API keys, which carry the prefix nbt_.

Step 1: Create a NetBox API key

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

Step 2: Add the NetBox credential to runZero

  1. Go to the Credentials page in runZero and click Add Credential.
  2. Provide a name for the credential, like NetBox CMDB.
  3. Choose NetBox API Key from the list of credential types.
  4. Fill in these fields:
    • Name - A unique name for this credential (for example, NetBox)
    • NetBox URL - The URL for your NetBox portal.
    • NetBox API key - The API key from step 1.
    • Insecure - Set this to Yes to attempt authentication without a verified thumbprint.
    • NetBox thumbprints (optional) - A set of IP=SHA256:B64HASH or domain.tld=SHA256:B64HASH pairs to trust for authentication.
      • To get the TLS thumbprint, you may scan your NetBox instance with runZero. The TLS fingerprints service attribute report lists all previously seen fingerprints.
      • If insecure is set to No and you provide no thumbprints:
        • With a self-signed certificate, the connection fails because the certificate chain cannot be verified.
        • With a valid certificate from a public CA, the connection can work without thumbprints.
  5. Save the credential.

Step 3: Configure the NetBox integration as a connector task

A connection needs a schedule and a site. The schedule sets when the sync runs, and the site is where runZero creates any new NetBox-only assets.

  1. Create a new Project. We strongly recommend testing NetBox in a new Project before applying it to your production Organization.
  2. Activate a connection to NetBox. You can reach every available third-party connection from the integrations page, your inventory, or the tasks page.
  3. Choose the credential you added earlier. If it is not listed, check that the credential has access to the organization or project you are in.
  4. Enter a name for the task, like NetBox sync.
  5. Leave the default settings to create a one-off sync task.
  6. Under Task configuration, choose the site to add your assets to. NetBox assets that match no existing asset land in this site by default.
  7. To leave out assets that runZero has not scanned, tick the Exclude assets that cannot be merged into an existing asset checkbox.
  8. Activate the connection when you are done. The task runs, and the Tasks page tracks its status.

Step 4: View NetBox assets

After a successful sync, go to your inventory to view your NetBox assets. They show a NetBox icon in the Source column.

To filter to NetBox assets, run this query:

Click an asset to see its attributes. runZero shows the attributes returned by the NetBox API.

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

If runZero holds far fewer NetBox-sourced assets, you may want to skip 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 assets that cannot be merged into an existing asset disabled. runZero then creates new assets for anything in NetBox it can’t correlate to your asset inventory. If this 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 with this integration, the questions and answers below may help.

Why is the NetBox integration unable to connect?

  1. Check whether the NetBox integration is returning any data.
    • Query the inventory rather than the task details to review all the data available from this integration.
    • In some cases, an integration’s configuration limits how much data reaches the runZero console.
  2. Some integrations require specific actions that are easy to overlook. If you miss a step during setup, the integration may not work correctly. Review this page and follow the steps exactly.
  3. If the NetBox integration can’t connect, check the task log for errors. 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
  4. If NetBox is on-premises, verify that the integration task runs from an Explorer with access to the NetBox host.

Why aren’t my custom field mappings working properly?

  1. Use the name of the custom field, not the label.
  2. Apply the custom fields to the correct types. The NetBox integration supports only the “Device” and “Virtual Machine” types in NetBox.
  3. If hostnames arrive malformed in runZero, check that multiple hostnames in the custom field are comma-separated and that the field contains no tab characters.
  4. Every custom field except first_seen_ts must be the Text type in NetBox. first_seen_ts must be either a Date & time or Date type.
Updated