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 assets that cannot be merged into an existing asset” 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.

NetBox-to-runZero custom field mapping

The NetBox integration allows for users to map custom fields within NetBox to attributes within runZero. These mappings will override the mfg.name, mfg.model, and platform.name attributes as noted above.

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

The following runZero attributes are supported for custom field mapping:

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

Usage within the runZero CLI scanner

To use the custom field mapping functionality within the runZero CLI scanner, provide a JSON array with the following example structure as an argument, where in each array item the “key” represents the NetBox custom field name and the “value” represents the runZero attribute:

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

In this example, netboxHostnames is the NetBox custom field being mapped to the runZero hostnames attribute and netboxManufacturer is the NetBox custom field being mapped to the runZero manufacturer attribute.

Searchable time attributes

The NetBox integration will process all Date & time or Date NetBox attributes and create searchable attributes from them within runZero. For example, a NetBox attribute called “lastChecked” with a value of 2024-07-26T15:30:00Z will have a new attribute created from it called lastCheckedTS with a Unix epoch timestamp value of 1722017400.

Getting started

To set up the NetBox integration, you will need:

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

Step 1: Create a NetBox API key

  1. Sign in to your NetBox portal.
  2. Click on 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. 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.
    • Insecure - Set this to Yes if you want 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.
      • You may scan your NetBox instance with runZero in order to obtain the TLS thumbprint. The TLS fingerprints service attribute report lists all previously seen fingerprints.
      • If insecure is set to No and no thumbprints are provided:
        • With a self-signed certificate, the connection will fail 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.

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.

  1. We strongly recommend testing NetBox in a new Project first before applying this to your production Organization. Create a new Project.
  2. Activate a connection to NetBox. You can access all available third-party connections from the integrations page, your inventory, or the tasks page.
  3. 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.
  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 you want to add your assets to. NetBox assets that do not match existing assets will use this site by default.
  7. If you want to exclude assets that have not been scanned by runZero from your integration import, tick the Exclude assets that cannot be merged into an existing asset checkbox.
  8. 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:

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 assets that cannot be merged into an existing asset 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?

  1. 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.
  2. 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.
  3. 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
  4. Verify you are running the integration task from an Explorer with access to the NetBox host if it is on-premises.

Why aren’t my custom field mappings aren’t working properly?

  1. Ensure you are using the name of the custom field and not the label.
  2. Ensure the custom fields are applied to the correct types. The NetBox integration only supports the “Device” and “Virtual Machine” types within NetBox.
  3. If your hostnames are becoming malformed within runZero, ensure they are comma-separated if there are multiple hostnames within the custom field. Additionally, ensure there are no tab characters present within the custom field.
  4. All of the custom fields except for the first_seen_ts attribute must be the Text type within NetBox. first_seen_ts must be either a Date & time or Date type.
Updated
Previous: Miradore MDM Next: Qualys VMDR