NetBox
The NetBox integration reads a NetBox instance through the NetBox REST API. It runs on an Integrator inside your network.
It is read-only. The integration never creates, changes or deletes anything in NetBox.
NetBox documents what the network is meant to look like. CyberOptix CTEM Platform reads it as that: the networks, hosts, devices and interfaces it reports come from NetBox's records, not from observing the network, and every record belongs to the NetBox instance that holds it.
What it collects
| Sync | Collects |
|---|---|
| Host discovery | Every IP address with its DNS name, the device or virtual machine and interface it is assigned to, and that interface's MAC; deprecated addresses are skipped |
| Network discovery | Every device with its manufacturer, model, serial, platform and primary address; every device interface with its MAC, VLAN, speed, state and assigned addresses; every prefix with its VRF, VLAN and site; deprecated prefixes are skipped |
The NetBox instance itself appears under Attack Surface > Network Devices, with its version. The devices NetBox documents appear beside it, managed by it, and the prefixes appear as its networks. Virtual machines are read only to name the addresses assigned to them; they are not reported as compute.
A VLAN with no prefix is not a network and is not reported.
Create a read-only API token
A token has the permissions of the user it belongs to, and can be limited further.
-
Under Admin > Authentication > Users, add a user for the integration (for example
inventory) with Staff status and Superuser status both off. -
Under Admin > Authentication > Permissions, add a permission with View as its only action, for the object types the syncs read:
- IPAM: prefix, VLAN, IP address, VRF
- DCIM: device, device type, manufacturer, interface, platform, site
- Virtualization: virtual machine
Assign it to the user.
-
Sign in as that user and, under the user's profile, open API Tokens and add a token. Turn Write enabled off. Copy the key: NetBox shows it once.
The token can also be created under Admin > Authentication > API Tokens. With Write enabled off, the token cannot change anything even if the user later gains other permissions.
Connect it
- Under Integrations, add NetBox with the NetBox URL (for example
https://netbox.example.net, including any base path NetBox is served under) and the API token. - In the integration's settings, assign the Integrator that can reach NetBox over HTTPS.
- Enable the syncs you want.
A NetBox that serves a self-signed certificate is trusted on first use: the first connection records the certificate's fingerprint, and later connections must present the same certificate. After replacing it, clear the pinned fingerprint in the integration's settings.
A token NetBox rejects fails the sync with an error. It does not report an empty instance.