NetBox
NetBox is a network management tool that documents and manages your network infrastructure. You can bring network and device data from NetBox into Brinqa to enhance your network security and provide a comprehensive view of your attack surface.
This document details the information you must provide for the connector to authenticate with NetBox and how to obtain that information from NetBox. See create a data integration for step-by-step instructions on setting up the integration.
Required connection settings
When setting up a data integration, select NetBox from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate NetBox with Brinqa:
-
Server URL: Your organization's NetBox server URL.
-
API token: The API token associated with the NetBox account, which must have permissions to log in to the API server and return data.
Generate a NetBox API token
For the NetBox connector to use the NetBox API, you must provide an API token. To generate a new token, follow these steps:
-
Log in to your organization's NetBox server.
-
Click your user profile in the upper-right corner of the page, and then click API Tokens.
-
Click Add a token and fill in the fields as shown below:
-
Key: Give your new token a key. If you don't provide a key, NetBox generates one automatically.
-
Write enabled: A NetBox API token can be used to perform all actions via the API that a user is permitted to do via the web UI. As Brinqa only requires read operations, uncheck this box to restrict API requests made with the token to read operations (GET) only.
-
Expires: Set an expiration date and time for the token.
-
Description: Provide a description for the token.
-
Allowed IPs: Specify any Internet Protocol (IP) v4 or v6 addresses allowed by the token. Leave this field blank if there are no restrictions.
-
-
Click Create.
A new API token appears on the API Tokens page. You can view this token later without restrictions, eliminating the need to save it immediately to a secure location. However, it is still important to protect the token and limit access to authorized personnel.
For additional information on managing API tokens for your NetBox account and API permissions, see NetBox documentation.
Additional settings
The NetBox connector contains additional options for specific configuration:
-
Set page size: The maximum number of records to get per API request. The default setting is 100. It is not recommended to go over 100.
-
Parallel requests: The maximum number of parallel API requests. The default setting is 4.
Types of data to retrieve
The NetBox connector can retrieve the following types of data from the NetBox API:
Table 1: Data retrieved from NetBox
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Cluster | No | Not mapped |
| Device | Yes | Device |
| Prefixes | Yes | Subnet |
| Virtual LAN | No | Not mapped |
| Virtual Machine | Yes | Host |
The NetBox connector does not currently support operation options for the types of data it retrieves.
For detailed steps on how to view the data retrieved from NetBox in the Brinqa Platform, see How to view your data.
Attribute mappings
Click the tabs below to view the mappings between the source and the Brinqa data model attributes.
- Device
- Prefixes
- Virtual Machine
Table 2: Device attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| airflow | Local variable |
| asset_tag | tags |
| categories | categories |
| cluster.id | Local variable |
| comments | Local variable |
| created | firstSeen |
| description | description |
| device_role.id | Local variable |
| device_role.name | Local variable |
| device_type.id | Local variable |
| device_type.name | Local variable |
| display | Local variable |
| face | Local variable |
| id | uid |
| last_updated | lastSeen, sourceLastModified |
| location.id | Local variable |
| location.name | Local variable |
| name | name |
| parent_device | Local variable |
| platform.id | Local variable |
| platform.name | Local variable |
| position | Local variable |
| primary_ip | ipAddresses, publicIpAddresses, privateIpAddresses |
| primary_ip4 | ipAddresses, publicIpAddresses, privateIpAddresses |
| primary_ip6 | ipAddresses, publicIpAddresses, privateIpAddresses |
| rack.id | Local variable |
| rack.name | Local variable |
| serial | serialNumber |
| site.id | Local variable |
| site.name | Local variable |
| status.value | status, statusCategory |
| tags | tags |
| tenant.id | Local variable |
| tenant.name | Local variable |
| url | Local variable |
| vc_position | Local variable |
| vc_priority | Local variable |
| virtual_chassis.id | Local variable |
| virtual_chassis.name | Local variable |
Table 3: Prefixes attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| _depth | Local variable |
| categories | categories |
| children | Local variable |
| comments | Local variable |
| created | firstSeen |
| description | description |
| display | name |
| family.label | Local variable |
| id | uid |
| is_pool | Local variable |
| last_updated | lastSeen, sourceLastModified |
| mark_utilized | Local variable |
| prefix | Local variable |
| role.id | Local variable |
| role.name | Local variable |
| site.id | Local variable |
| site.name | Local variable |
| status.value | status, statusCategory |
| tags | tags |
| tenant.id | Local variable |
| tenant.name | Local variable |
| url | Local variable |
| vrf.id | Local variable |
| vrf.name | Local variable |
| vlan.id | Local variable |
| vlan.name | Local variable |
Table 4: Virtual Machine attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| categories | categories |
| cluster.id | Local variable |
| cluster.name | Local variable |
| comments | Local variable |
| created | firstSeen |
| description | description |
| device.id | Local variable |
| device.name | Local variable |
| disk | Local variable |
| display | Local variable |
| id | uid |
| last_updated | lastSeen, sourceLastModified |
| memory | Local variable |
| name | hostNames, name |
| platform.id | Local variable |
| platform.name | Local variable |
| primary_ip | ipAddresses, publicIpAddresses, privateIpAddresses |
| primary_ip4 | ipAddresses, publicIpAddresses, privateIpAddresses |
| primary_ip6 | ipAddresses, publicIpAddresses, privateIpAddresses |
| role.id | Local variable |
| role.name | Local variable |
| site.id | Local variable |
| site.name | Local variable |
| status.value | status, statusCategory |
| tags | tags |
| tenant.id | Local variable |
| tenant.name | Local variable |
| url | Local variable |
| vcpus | Local variable |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
APIs
The NetBox connector uses the NetBox REST API. Specifically, it uses the following endpoints:
Table 5: NetBox API Endpoints
| Connector Object | API Endpoints |
|---|---|
| Cluster | GET /api/virtualization/clusters/ |
| Device | GET /api/dcim/devices |
| Prefixes | GET /api/ipam/prefixes |
| Virtual LAN | GET /api/ipam/vlans |
| Virtual Machine | GET /api/virtualization/virtual-machines |
You can view the NetBox REST API documentation by navigating to https://YourNetBoxInstance/api/docs/. For more information, see NetBox documentation.
Changelog
The NetBox connector has undergone the following changes:
3.0.0
- Initial Integration+ release.