IP Address Management (IPAM)

NitroNet's IPAM module provides centralized tracking and management of IP addresses, subnets, and VLANs across your network. It automatically discovers devices from flow data and integrates with NetBox, your device inventory, and manual entry.

Overview

The IPAM system maintains three core tables:

Table	Description
`ipam_prefixes`	Subnets / CIDR blocks — your address plan
`ipam_addresses`	Individual IP address assignments
`ipam_vlans`	VLAN definitions

IP addresses are discovered automatically from multiple sources and correlated against configured prefixes. The prefix table is the source of truth — configure your subnets here first, then addresses discovered from flows, devices, and NetBox are automatically assigned to the correct prefix.

Data Sources

Source	Badge	How it works
`flow`	🌊 cyan	Discovered automatically from NetFlow/IPFIX data via MAC address
`device`	📡 blue	Synced from the devices table (`mgmt_ip` field)
`netbox`	🔗 purple	Imported from NetBox IPAM via API sync
`manual`	✏️ green	Manually added through the UI
`csv_import`	—	Imported via CSV file or REST API

Device Classification

When IPs are discovered from flow data, the device type is automatically classified using the OUI vendor name from the MAC address and observed application protocols:

Type	Detection Logic
`network`	Cisco, Juniper, Arista, Calix, Fortinet, Palo Alto OUI
`server`	Intel Corporate OUI + SSH/SNMP/NetFlow protocols observed
`workstation`	Apple, Dell, HP, Lenovo OUI
`voip`	Grandstream, Polycom, Yealink OUI
`iot`	Gaoshengda, Espressif, Tuya OUI (cheap WiFi chipsets)
`unknown`	Unrecognized OUI

IP Addresses Tab

The main table shows all discovered and configured IP addresses with filtering and sorting.

Filters

Filter	Options
Search	Free text — matches IP, hostname, MAC, vendor, owner, description
Type	All / Workstation / Server / Network / IoT / VoIP / Unknown
Source	All / Flow / Manual / NetBox / Device
Prefix	All / specific subnet dropdown (auto-populated)
Sort	Subnet (default) / IP Address / Last Seen / Device Type

Actions

🔍 Explore — opens IP Explorer modal with full context including flow history and open incidents
✏️ Edit — edit hostname, owner, device type, description, status
🗑 Delete — only available for manually created entries
⬇ CSV — exports current filtered view to CSV, sorted by subnet then IP
↻ Refresh — manually refresh the table
+ Add IP — manually add an IP address

IP Explorer

Click any IP address to open the Explorer modal showing:

Full address details (MAC, vendor, hostname, owner, prefix, site, device)
Top 10 flows in the last 24 hours (peer IP, application, bytes, last seen)
Open incidents that reference this IP address

Prefixes Tab

Manage your subnet address plan. Prefixes are the source of truth — add your CIDRs here and IP addresses will automatically be assigned to the correct prefix.

Adding a Prefix

Click + Add Prefix and fill in:

Field	Required	Description
CIDR	✓	e.g. `192.168.100.0/24`
Name		Human-readable name e.g. "Management Network"
Site		Assign to a site from the dropdown
Role		management / transit / access / server / loopback / dmz
VRF		Virtual routing domain (default: Global)
Status		active / reserved / deprecated

When a prefix is created, any existing IP addresses that fall within the CIDR are immediately assigned to it — no manual sync required.

Expandable Prefix Rows

Click any prefix row to expand it and see all IP addresses in that subnet inline. Each expanded row shows:

IP address with link to IP Explorer
Hostname / owner
MAC address and vendor
Device type
Source and status
Last seen timestamp

Utilization Bar

Each prefix shows a utilization bar: discovered addresses / total usable addresses. Colors:

🟢 Green — below 70%
🟡 Amber — 70–89%
🔴 Red — 90%+

VLANs Tab

Manage VLAN definitions. VLANs can be added manually, imported from NetBox, or used as reference data for prefix assignment.

Field	Description
VLAN ID	1–4094
Name	Descriptive name
Site	Optional site assignment
Description	Free text
Status	active / deprecated

Sync Operations

Sync Flows

Queries flows_all in ClickHouse for the last 24 hours, extracts unique private IP + MAC combinations, and upserts into ipam_addresses. Only RFC1918 addresses are imported:

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
100.64.0.0/10 (CGNAT)

Multicast (224.x.x.x, 239.x.x.x) and broadcast (255.x.x.x) are excluded.

Sync Devices

Pulls all devices from the devices table that have a mgmt_ip set and upserts them into ipam_addresses with source = 'device'. Device type is mapped from the device_type field:

device_type contains	IPAM device_type
Cisco, Juniper, Arista, Aruba, FortiGate, Palo Alto	`network`
Linux Server, Windows Server	`server`
probe	`network`
vpc	skipped

NetBox IPAM Sync

Available in Settings → Integrations → NetBox → IPAM Sync. Imports from three NetBox IPAM endpoints:

NetBox endpoint	Imported to
`/api/ipam/prefixes/`	`ipam_prefixes`
`/api/ipam/ip-addresses/`	`ipam_addresses`
`/api/ipam/vlans/`	`ipam_vlans`

Existing records are updated on conflict. NetBox is the authoritative source for source = 'netbox' records.

CSV Import

From the UI

Navigate to IPAM → Import tab and either drag-and-drop or click to upload a .csv file.

A preview of the first 5 rows is shown before importing. Click Download Template to get a pre-filled example CSV.

CSV Format

address,prefix,hostname,dns_name,mac_address,owner,device_type,description,status,vrf
0.1.1,10.0.1.0/24,router1,router1.corp.com,aa:bb:cc:dd:ee:01,NetOps,network,Core router,active,Global
0.1.10,10.0.1.0/24,server1,server1.corp.com,aa:bb:cc:dd:ee:02,IT,server,Web server,active,Global
168.100.50,192.168.100.0/24,printer1,,aa:bb:cc:dd:ee:04,Facilities,iot,HP LaserJet,active,Global

Column	Required	Description
`address`	✓	IPv4 address
`prefix`		CIDR — auto-created if not exists
`hostname`		Device hostname
`dns_name`		Fully qualified domain name
`mac_address`		Format: `aa:bb:cc:dd:ee:ff`
`owner`		Owner or team name
`device_type`		`workstation` \| `server` \| `network` \| `iot` \| `voip` \| `unknown`
`description`		Free text notes
`status`		`active` \| `reserved` \| `dhcp` \| `deprecated` (default: `active`)
`vrf`		VRF name (default: `Global`)

Import behavior:

Existing IPs are updated, not duplicated
If prefix is specified and doesn't exist, it is auto-created
After import, all addresses are automatically assigned to matching prefixes
Errors on individual rows are reported but don't stop the import

REST API

All endpoints require authentication:

Authorization: Bearer YOUR_API_TOKEN

Endpoints

Addresses

Method	Endpoint	Description
`GET`	`/api/ipam/addresses`	List addresses with filters
`GET`	`/api/ipam/addresses/:ip`	Single IP detail with flow context
`POST`	`/api/ipam/addresses`	Create address
`PATCH`	`/api/ipam/addresses/:id`	Update address
`DELETE`	`/api/ipam/addresses/:id`	Delete (manual only)

GET /api/ipam/addresses query params:

Param	Description
`search`	Free text search
`prefix_id`	Filter by prefix ID
`device_type`	Filter by device type
`source`	Filter by source
`status`	Filter by status
`site_id`	Filter by site
`sort`	`subnet` \| `address` \| `last_seen` \| `type`
`limit`	Page size (default: 100)
`offset`	Pagination offset

Prefixes

Method	Endpoint	Description
`GET`	`/api/ipam/prefixes`	List prefixes
`POST`	`/api/ipam/prefixes`	Create prefix
`PATCH`	`/api/ipam/prefixes/:id`	Update prefix
`DELETE`	`/api/ipam/prefixes/:id`	Delete prefix

VLANs

Method	Endpoint	Description
`GET`	`/api/ipam/vlans`	List VLANs
`POST`	`/api/ipam/vlans`	Create VLAN
`DELETE`	`/api/ipam/vlans/:id`	Delete VLAN

Sync

Method	Endpoint	Description
`POST`	`/api/ipam/sync/flows`	Discover IPs from flow data
`POST`	`/api/ipam/sync/devices`	Sync from devices table
`POST`	`/api/ipam/netbox/sync`	Sync from NetBox IPAM

Import

Method	Endpoint	Description
`POST`	`/api/ipam/import/api`	Bulk import JSON records
`POST`	`/api/ipam/import/csv`	Import CSV as request body
`GET`	`/api/ipam/import/template`	Download CSV template

Summary

Method	Endpoint	Description
`GET`	`/api/ipam/summary`	Counts by source, type, activity

Bulk Import via API

curl -X POST https://YOUR-WHITEOWL/api/ipam/import/api \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "address": "10.0.1.1",
        "hostname": "router1",
        "prefix": "10.0.1.0/24",
        "owner": "NetOps",
        "device_type": "network"
      },
      {
        "address": "10.0.1.10",
        "hostname": "server1",
        "mac_address": "aa:bb:cc:dd:ee:ff",
        "owner": "IT"
      }
    ]
  }'

Response:

{
  "success": true,
  "total": 2,
  "inserted": 2,
  "updated": 0,
  "prefixes_created": 1,
  "errors": []
}

CSV Import via API

curl -X POST https://YOUR-WHITEOWL/api/ipam/import/csv \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/csv" \
  --data-binary @my-addresses.csv

Database Schema

-- Subnets / prefixes
CREATE TABLE ipam_prefixes (
    id          SERIAL PRIMARY KEY,
    prefix      CIDR NOT NULL,
    name        VARCHAR(255),
    description TEXT,
    site_id     INTEGER REFERENCES sites(id),
    vlan_id     INTEGER,
    vrf         VARCHAR(100) DEFAULT 'Global',
    role        VARCHAR(50),   -- management|transit|access|server|loopback|dmz
    status      VARCHAR(20)  DEFAULT 'active',
    source      VARCHAR(20)  DEFAULT 'manual',
    netbox_id   INTEGER,
    created_at  TIMESTAMPTZ  DEFAULT NOW(),
    updated_at  TIMESTAMPTZ  DEFAULT NOW(),
    UNIQUE(prefix, vrf)
);

-- Individual IP assignments
CREATE TABLE ipam_addresses (
    id          SERIAL PRIMARY KEY,
    address     INET NOT NULL UNIQUE,
    prefix_id   INTEGER REFERENCES ipam_prefixes(id),
    device_id   INTEGER REFERENCES devices(id),
    mac_address VARCHAR(17),
    hostname    VARCHAR(255),
    dns_name    VARCHAR(255),
    vendor      VARCHAR(255),
    device_type VARCHAR(50),
    description TEXT,
    owner       VARCHAR(255),
    status      VARCHAR(20)  DEFAULT 'active',
    source      VARCHAR(20)  DEFAULT 'discovered',
    netbox_id   INTEGER,
    first_seen  TIMESTAMPTZ,
    last_seen   TIMESTAMPTZ,
    created_at  TIMESTAMPTZ  DEFAULT NOW(),
    updated_at  TIMESTAMPTZ  DEFAULT NOW()
);

-- VLANs
CREATE TABLE ipam_vlans (
    id          SERIAL PRIMARY KEY,
    vlan_id     INTEGER NOT NULL,
    name        VARCHAR(255),
    site_id     INTEGER REFERENCES sites(id),
    description TEXT,
    status      VARCHAR(20) DEFAULT 'active',
    netbox_id   INTEGER,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(vlan_id, site_id)
);

Prefix Assignment Logic

When an IP address is discovered or imported, it is automatically assigned to a prefix using PostgreSQL's << (contained within) operator:

UPDATE ipam_addresses a
SET prefix_id = p.id
FROM ipam_prefixes p
WHERE a.address << p.prefix
  AND (a.prefix_id IS NULL OR a.prefix_id != p.id)

This runs:

After every flow sync
After every device sync
Immediately when a new prefix is created
After every CSV/API import

This means you can add prefixes at any time and existing addresses will be automatically assigned on the next operation — no manual re-sync required.

Planned Enhancements

DHCP integration — parse DHCP ACK messages from syslog to track dynamic leases in real time
Prefix → flow tags sync — IPAM becomes the source of truth for flow tag CIDRs, replacing the separate flow tag management UI
DNS reverse lookup — auto-populate hostname from PTR records using the existing DNS resolver
Subnet utilization alerts — alert when a prefix exceeds 80% utilization
IPv6 support — extend prefix and address tables for IPv6 CIDR management
Parent/child prefix hierarchy — 10.0.0.0/8 → 10.0.1.0/24 tree view

Overview​

Data Sources​

Device Classification​

IP Addresses Tab​

Filters​

Actions​

IP Explorer​

Prefixes Tab​

Adding a Prefix​

Expandable Prefix Rows​

Utilization Bar​

VLANs Tab​

Sync Operations​

Sync Flows​

Sync Devices​

NetBox IPAM Sync​

CSV Import​

From the UI​

CSV Format​

REST API​

Endpoints​

Addresses​

Prefixes​

VLANs​

Sync​

Import​

Summary​

Bulk Import via API​

CSV Import via API​

Database Schema​

Prefix Assignment Logic​

Planned Enhancements​