Skip to main content

NetBox Integration

Overview​

This integration allows importing data from NetBox into WhiteOwl:

  • Sites — Physical locations with coordinates
  • Devices — Network devices with IP addresses and site assignments
  • IP Prefixes — CIDR ranges converted to Flow Tags for traffic classification

Connecting to NetBox​

  1. Navigate to Settings → Integrations → expand the NetBox card
  2. Enter your NetBox API URL (e.g., https://netbox.example.com/api)
  3. Enter your API Token (create in NetBox → Admin → API Tokens)
  4. Click Test Connection to verify
  5. Click Save to store the configuration

Import Order​

For best results, import in this order:

  1. Sites first — Creates the site records needed for devices
  2. Devices second — Links devices to their sites
  3. IP Prefixes last — Creates flow tags for traffic classification and flow enrichment

Sites Import​

Maps NetBox Sites to WhiteOwl Sites.

Imported fields:

  • Name
  • Description
  • Latitude / Longitude
  • Physical address

Behavior: Existing sites (matched by name) are updated.

Devices Import​

Maps NetBox Devices to WhiteOwl Devices.

Requirements:

  • Site must already exist in WhiteOwl

Imported fields:

  • Name
  • Device type
  • Role
  • Primary IP (used as mgmt_ip and sampler_address)

Skipped devices:

  • Devices without a primary IP
  • Devices without a matching site in WhiteOwl

IP Prefixes → Flow Tags​

Converts NetBox IP Prefixes into WhiteOwl Flow Tags for traffic classification.

Tag Naming​

Tags are named by combining:

  • Site name
  • VRF name
  • Role
  • Tenant

Example: HQ Data Center - Production - Infrastructure

Import Options​

OptionDescription
DimensionCategory to assign the tag: site, environment, application, owner, or server
DirectionWhether the CIDR matches source IPs, destination IPs, or both
Create TagsIf unchecked, only creates rules for existing tags

Environment Variables​

Optional encryption key for API tokens:

INTEGRATION_SECRET=your-32-character-secret-key