flowsimulator-go

flowsimulator-go is an Enterprise Flow Simulation Platform for building, testing, demonstrating, and load-testing flow collectors.

Instead of emitting random NetFlow tuples, it models realistic enterprise activity: sites, users, servers, applications, services, public destinations, and ordered sessions. The result is reproducible flow telemetry exported as standard NetFlow v5, NetFlow v9, IPFIX, or sFlow v5.

Scenario Engine
  -> Enterprise Model
  -> Protocol-neutral FlowRecord
  -> NetFlow v5 / NetFlow v9 / IPFIX / sFlow v5
  -> Standards-based Flow Collector

Why flowsimulator-go?

Question	Classic flow generator	flowsimulator-go
What is generated?	Random endpoints, ports, counters	Enterprise sessions with topology, personas, applications, and services
Why does it exist?	Parser smoke tests	Collector development, regression, load tests, demos, and observability datasets
How realistic is traffic?	Usually flat and stateless	Ordered chains such as DNS-before-HTTPS, logon, backup, monitoring, scans, and exfiltration
How repeatable is it?	Often seedable, but low semantic value	Named YAML scenarios with deterministic seeds and stable model inputs
How broad is protocol output?	Often one protocol shape	One protocol-neutral core, four wire protocols
How noisy is security data?	Often attack-heavy or synthetic-only	Mostly normal enterprise traffic with low-weight security scenarios
Does it invent vendor fields?	Sometimes	No. Vendor fields require source-backed registry entries

What It Is For

• Developing and regressing NetFlow, IPFIX, and sFlow collectors.
• Producing realistic datasets for observability labs and demos.
• Running controlled load tests with deterministic traffic.
• Exercising parser, normalization, enrichment, storage, and dashboard paths.
• Generating normal enterprise traffic with optional low-volume security signals.

flowcollector-go is the primary development and regression platform for this project. Because flowsimulator-go emits standards-based wire protocols, it can also send telemetry to other NetFlow, IPFIX, and sFlow collectors. That is protocol interoperability, not certified vendor compatibility.

Features

• Protocol-neutral simulation core with NetFlow v5, NetFlow v9, IPFIX, and sFlow v5 UDP export.
• Enterprise topology, persona, application, service, address-pool, and exporter models.
• Ordered session chains for web, directory, DHCP, file, database, backup, monitoring, cloud, and security scenarios.
• Reproducible runs through fixed seeds and named YAML configs.
• GeoIP/ASN-capable public communication examples.
• No payload generation, PCAP replay, malformed packet fuzzing, or invented vendor fields.

Ordered Sessions In Practice

Session templates turn a single traffic intent into an ordered chain of protocol-neutral flow records. The built-in windows-login template is a good example: one session produces six FlowRecords in order, shaped by the interactive-tcp behaviour profile.

The full list of built-in templates - from https-web and backup-transfer to DHCP lease lifecycles and security patterns such as beaconing, dns-tunnel, and lateral-movement - is documented in the Session Template Library.

DHCPv4 Telemetry

The enterprise model includes flow-level DHCPv4 lifecycle telemetry for Discover, Offer, Request, ACK, Renew, Rebind, Release, Inform, and rare NAK sequences. Client messages use UDP 68 -> 67; server replies use UDP 67 -> 68. Initial Discover and Request traffic is modeled as broadcast to 255.255.255.255, with DHCP represented through ordered session templates and normal application, service, persona, scenario, and address-pool selection.

The continuous flowcollector-go lab config includes low-weight DHCP lifecycle traffic so DHCP is visible in permanent simulations without dominating normal enterprise activity.

Install

Requirements: Go 1.22 or newer, plus a collector listening on UDP.

git clone https://forgejo.sabolowitsch.org/StefanSA/flowsimulator-go.git
cd flowsimulator-go
go test ./...
go build -o bin/flowsimulator-go ./cmd/flowsimulator-go

Docker can be used for a local image build:

docker build -t flowsimulator-go:local .
docker run --rm flowsimulator-go:local version

No go install command is documented for v0.1.3 because the module path is not prepared as a public install path.

Quickstart

Validate and send five seconds of NetFlow v5 to the target configured in the example file:

go run ./cmd/flowsimulator-go validate -c configs/examples/minimal-netflow5.yaml
go run ./cmd/flowsimulator-go run -c configs/examples/minimal-netflow5.yaml --duration 5s

Check the simulator while it is running:

curl http://127.0.0.1:9098/status

Other minimal protocol examples:

Protocol	Config	Typical UDP port
NetFlow v5	configs/examples/minimal-netflow5.yaml	2055
NetFlow v9	configs/examples/minimal-netflow9.yaml	2055
IPFIX	configs/examples/minimal-ipfix.yaml	4739
sFlow v5	configs/examples/minimal-sflow5.yaml	6343

Override a collector target when needed:

go run ./cmd/flowsimulator-go run -c configs/examples/minimal-ipfix.yaml --target 127.0.0.1:4739 --duration 30s

Continuous Simulation

flowsimulator-go can run continuously until SIGTERM or SIGINT. Use a config with global.duration: 0s, or run without a positive --duration.

This turns the simulator into a long-running source of realistic enterprise telemetry for permanent observability labs, collector burn-in, load tests, and long-term regression datasets. The included configs/lab/flowcollector-go/continuous-enterprise.yaml profile exercises all four supported protocols while keeping normal enterprise behavior dominant.

CLI

go run ./cmd/flowsimulator-go validate -c configs/examples/minimal-netflow5.yaml
go run ./cmd/flowsimulator-go run -c configs/examples/minimal-netflow5.yaml
go run ./cmd/flowsimulator-go validate-registry -c configs/examples/enterprise-lab.yaml
go run ./cmd/flowsimulator-go validate-templates -c configs/examples/minimal-ipfix.yaml
go run ./cmd/flowsimulator-go export-hosts -c configs/examples/hosts-csv.yaml -o dist/hosts.csv
go run ./cmd/flowsimulator-go list-ie
go run ./cmd/flowsimulator-go list-templates
go run ./cmd/flowsimulator-go version

Useful run flags:

--target 127.0.0.1:2055
--protocol netflow5|netflow9|ipfix|sflow5
--rate 100
--duration 5s
--seed 12345
--metrics-listen :9098

Configuration And Labs

Configuration is YAML-first. Start with configs/examples/minimal-*.yaml, then move to enterprise examples under configs/examples/ or collector regression configs under configs/lab/flowcollector-go/.

The optional Observability Lab workflow describes how to run the simulator against flowcollector-go, downstream storage, and dashboard-style inspection. It is intentionally documented without local paths, private infrastructure, credentials, or host-specific details.

Start with:

• Integration Test Strategy
• Integration Matrix
• flowcollector-go integration notes
• Observability Lab integration notes

Canonical hosts.csv Export

Generated environments can optionally define a bounded host inventory and export it as the authoritative private-IP hostname map for flowcollector-go.

Configure hosts with a domain plus explicit groups and/or entries, then run:

go run ./cmd/flowsimulator-go export-hosts -c configs/examples/hosts-csv.yaml -o dist/hosts.csv

The file is written with Go's RFC4180 CSV writer, uses the header ip,hostname, contains one row per IPv4 or IPv6 address, sorts rows by IP address, and rejects duplicate IPs. Group hostnames are rendered as canonical FQDNs by appending hosts.domain; explicit entries may provide IPv4, IPv6, or both.

Example output:

ip,hostname
10.10.10.11,client-001.lab.example.local
10.10.10.12,client-002.lab.example.local
10.20.10.5,srv-db01.lab.example.local
10.20.10.50,dual-stack-01.lab.example.local
2001:db8:20::50,dual-stack-01.lab.example.local

v0.1.3 Scope And Limits

v0.1.3 is a patch release over v0.1.2 for DHCPv4 enterprise telemetry and runtime timestamp correctness. Functional scope remains the four supported UDP exporters, protocol-neutral simulation, enterprise traffic models, deterministic examples, continuous simulation, canonical hosts.csv export, CI, Docker build, and publish-surface checks.

Known limits:

• No application payloads, PCAP replay, or malformed packet fuzzing.
• IPv6 remains a roadmap item.
• Built-in public service pools are representative test prefixes, not complete provider IP databases.
• Vendor fields require source-backed registry entries before implementation.
• Richer NAT, MPLS, VXLAN, SD-WAN, WLAN, and vendor records remain planned.
• Collector-specific behavior beyond flowcollector-go requires separate validation.

Documentation

• Strategy and scenarios: Flow Simulation Strategy, Scenario Model, Enterprise Scenarios
• Models: Application Model, Service Model, Session Template Library, Address Pools
• Public and security traffic: Public Traffic Model, GeoIP/ASN Strategy, Security Scenarios
• Protocols and exporters: Exporter Profiles, Protocol Coverage Plan, flowcollector-go Compatibility Matrix
• Integration: Integration Test Strategy, Integration Matrix
• Vendor planning: Vendor Extension Plan, Vendor Roadmap