Network Flow Monitoring

uControl Insight can passively observe network traffic by ingesting NetFlow / IPFIX records exported from your network devices. Flow data powers the topology graph (COMMUNICATES_WITH relationships), the Impact Analysis and Asset Runbook context, and the AI Flow-Anomaly Detection feature.

What you get

• Who-talks-to-who visibility — uControl mines the flow stream every 5 minutes and adds COMMUNICATES_WITH edges to the topology graph. Recent flow peers show up alongside structural relationships.

• Flow-volume context on the Asset detail page (per-peer bytes/packets/ports over the last 24h).

• Better AI impact / runbook — the AI sees real traffic patterns when narrating what depends on an asset.

• Flow-Anomaly Detection — if AI is enabled, an hourly job flags new conversations not seen in the previous 7 days on watched service ports.

Discovering assets from flow

Passive flow is no longer just an overlay on assets you've already scanned. When uControl sees traffic to or from an IP that isn't yet in the inventory, it materialises a new asset directly from the flow record — with no active scan. Flow-materialised assets are attributed to a synthetic FLOW run, so you can tell them apart from scan-discovered assets in the Runs list. This includes OT / ICS endpoints seen only in flow, which often sit on segments an active scanner can't (or shouldn't) reach.

Flow-derived assets and traffic also feed:

• Dark-space / shadow-IP detection — IPs that are active on the network but were never scanned, and don't fall inside any known target range, are surfaced as shadow IPs.

• Self-Seed target proposals — active subnets observed in flow are proposed as new discovery targets, so you can bring them under managed scanning.

Where you see it

• Sidebar → Dashboard → Flows — live counts of incoming flow records, top talkers, top destinations.

• Topology map — COMMUNICATES_WITH edges appear once enough flow has been ingested (default refresh: every 5 minutes).

• Asset detail — a "New flow peers" card lazy-loads any open flow anomalies, and the AI Impact / Runbook modals reference flow peers by display name.

Prerequisites

• One or more flow exporters sending NetFlow v5/v9 or IPFIX over UDP to the uControl server. Common sources: Cisco/Juniper/Arista switches and routers, Fortinet/Palo Alto firewalls, VMware NSX, sFlow exporters via a converter.

• Network reachability on UDP 2055 (NetFlow) and/or UDP 4739 (IPFIX) from the exporters to the uControl host.

• Sufficient disk space — flow data writes to the partitioned flow_raw table by quarter. Plan ~1–5 GiB per million flows; rule of thumb: a busy enterprise generates a few hundred million flows per quarter.

How to enable

Step 1 — Configure your exporters

On each network device, point its NetFlow / IPFIX export at the uControl server. The exact syntax depends on the device; common examples:

! Cisco IOS NetFlow v9 flow exporter UCONTROL destination 192.0.2.10 transport udp 2055 export-protocol netflow-v9 template data timeout 60

! Cisco IOS IPFIX (Flexible NetFlow) flow exporter UCONTROL-IPFIX destination 192.0.2.10 transport udp 4739 export-protocol ipfix

Step 2 — Confirm uControl is listening

By default, each worker binds its NetFlow / IPFIX collection ports at startup. To verify on the worker host:

ss -ulnp | grep -E '2055|4739'

If you don't see both ports, note that the flow collection (listener) ports are configured per worker on the Worker Settings page — not on the control-plane Settings tab:

1. Sidebar → Workers → select the worker → Worker Settings.

2. Confirm the NetFlow port (2055) and IPFIX port (4739) that the worker listens on — change them only if you have a port conflict with another service on that host.

3. If you change a port, restart the worker (sudo systemctl restart ucontrolinsight) for the new listener to bind.

The control-plane Settings → Discovery & Flow tab covers the other flow options — batching, COMMUNICATES_WITH sync, and startup backfill (see Step 3) — but the collector listener ports themselves live on Worker Settings.

Step 3 — Tune (optional)

On the control-plane Settings → Discovery & Flow tab:

• Batch size (default 1000): how many records are inserted per database transaction. Increase on busy networks (up to 5000); decrease if you see write-pressure spikes.

• Batch interval (ms) (default 100): how often the batch writer drains the queue. Lowering improves real-time visibility; raising reduces DB load.

• Sync COMMUNICATES_WITH relationships (default on): turn off if you don't want flow peers showing up on the topology map.

• Backfill historical asset IDs on startup (default on): when uControl starts, it walks the last N hours of flow_raw and fills in any rows missing src/dst asset IDs. This is mostly relevant after an upgrade from a pre-UIP-135 build.

How to verify it's working

1. Wait 1–2 minutes after enabling exporters.

2. Sidebar → Dashboard → Flows: the "Flow records (last 1 minute)" count should be > 0.

3. On any asset that's actively talking to the network, the asset detail page should show network connections in its mini-topology and (if AI is enabled) its Impact Analysis modal should list flow peers.

4. Wait an hour and check the asset detail "New flow peers" card — it'll be empty on the first run while a baseline is being established, then will start surfacing real anomalies as the detector compares fresh traffic against the rolling 7-day baseline.

Disk usage and retention

The flow_raw table is partitioned by quarter. To manage size:

• Monitor with df -h /var/lib/mysql (or your data directory).

• Drop old quarter partitions periodically: ALTER TABLE flow_raw DROP PARTITION p_2025_q4;

• Reduce the busy-port sampling rate at the exporter side if a quarter's table is growing too fast.

Troubleshooting

• No flow records arriving — check tcpdump -i any 'udp port 2055 or udp port 4739' on the uControl host. If you see packets but nothing in uControl, look in the catalina log for "FlowUdpServer listening".

• InnoDB "table is full" errors in the log — almost always disk-full, not a database tuning issue. Check df -h /var/lib/mysql.

• No COMMUNICATES_WITH edges on the topology — check that the "Sync COMMUNICATES_WITH relationships" toggle is on in Settings → Discovery & Flow, and that you've waited at least 5 minutes since the first flow arrived.