Experimental self-hosted NetFlow/IPFIX visibility and anomaly-detection

Configuration Reference Guide

GitHub

Configuration Reference Guide

FlowGuard Lite uses a single configuration file (config.yaml) to adjust ports, networks, storage parameters, and outbound integrations.

Behavioral detections that depend on local clock time use the process timezone. In Docker, set the standard TZ environment variable (for example Europe/Madrid) to match the monitored network.

Modeline & Autocomplete

To get live schema validation and autocompletion in IDEs like VS Code or GoLand, prepend the following line to your config.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/miquelbar/flowguard-lite/main/docs/config.schema.json

Configuration Schema

Below is a complete config.yaml reference containing default parameters:

# The web server port for the dashboard UI and JSON API
port: "8080"

# UDP listening port for incoming NetFlow (v5/v9) and IPFIX telemetry
netflow_port: 2055

# UDP listening port for incoming sFlow telemetry
sflow_port: 6343

# Optional local interface for passive packet-to-flow capture. Empty disables it.
capture_interface: ""

# Kernel BPF filter applied before passive packets enter FlowGuard
capture_bpf_filter: "ip or ip6"

# Enable only when traffic visibility requires promiscuous interface capture
capture_promiscuous: false

# Optional UniFi CyberSecure Activity Logging/SIEM syslog collector.
# Disabled by default. Use host port mapping if UniFi must send to 514/udp.
unifi_syslog_enabled: false
unifi_syslog_port: 5514
unifi_syslog_allowed_ips: []

# Directory where database shards, evidence, and logs will be written
storage_dir: "/data"

# Storage backend engine: "sqlite" (default shards) or "duckdb" (experimental single file analytics)
storage_backend: "sqlite"

# List of local CIDR subnets representing internal devices.
# FlowGuard Lite relies on this list to profile local vs. external IP addresses.
local_subnets:
  - "192.168.1.0/24"
  - "10.0.0.0/8"

# Log level verbosity: "debug", "info", "warn", or "error"
log_level: "info"

# Execution environment profile: "production" or "development"
environment: "production"

# Slack/Discord Incoming Webhook URL used by notification rules with channel target "slack"
slack_webhook_url: "https://example.com/slack-webhook"

# Generic JSON webhook URL used by notification rules with channel target "webhook"
webhook_url: "https://automation.example.local/flowguard-alerts"

# Legacy generic webhook formatter. New Slack routing uses slack_webhook_url directly.
webhook_format: "generic"

# Optional custom headers for generic webhook requests
webhook_headers: {}

# Telegram Bot API channel used by notification rules with channel target "telegram"
telegram_enabled: false
telegram_token: ""
telegram_chat_id: ""

# Flag tracking first-run wizard completion status
first_run_completed: true

# Local admin password hash generated by first-run access setup.
# Never place a plaintext password here.
admin_password_hash: ""

# Random session secret generated by first-run access setup
session_secret: ""

# Data retention in days for historical databases (pruned daily)
retention_days: 7

# Global alert noise controls
disabled_anomaly_types: []
muted_anomaly_subnets: []
notify_allowed_subnets: []
notify_suppressed_types: []

# Behavioral detector sensitivity
new_destination_min_history_buckets: 12
beacon_min_observations: 12
beacon_min_interval_seconds: 90
traffic_spike_min_packets: 2500
traffic_spike_min_bytes: 1048576

# Global Volumetric DDoS heuristic triggers (experimental)
ddos_threshold_pps: 5000
ddos_threshold_bps: 10485760
ddos_threshold_fps: 1000
syn_flood_threshold_pps: 1000
udp_flood_threshold_pps: 3000
icmp_flood_threshold_pps: 500

# Optional Suricata eve.json telemetry file path
suricata_eve_path: ""

Configuration Parameter Details

port

  • Type: String
  • Default: "8080"
  • Description: The port the HTTP server binds to. Provides both the SPA web dashboard and REST analytics endpoints.

netflow_port

  • Type: Integer
  • Default: 2055
  • Description: UDP port where the NetFlow/IPFIX worker pool listens. Set to 0 to disable the NetFlow collector.

sflow_port

  • Type: Integer
  • Default: 6343
  • Description: UDP port where the sFlow worker pool listens. Set to 0 to disable the sFlow collector.

unifi_syslog_enabled

  • Type: Boolean
  • Default: false
  • Description: Enables the dedicated UniFi CyberSecure Activity Logging/SIEM syslog collector. This is a separate protocol from NetFlow/IPFIX and must not use the NetFlow port. The collector parses bounded syslog messages, stores reduced retained UniFi evidence, and can create anomalies for high-confidence security detections and critical events. Note that this integration is experimental and has limited real-world utility.

unifi_syslog_port

  • Type: Integer
  • Default: 5514
  • Description: UDP app port reserved for UniFi SIEM/syslog ingest. Use an unprivileged app port by default; if UniFi requires destination port 514, map host 514/udp to the app port in Docker or with host firewall/NAT rules. Set to 0 only when unifi_syslog_enabled is false.

unifi_syslog_allowed_ips

  • Type: Array of strings
  • Default: []
  • Description: Optional allowlist of UniFi gateway sender IPs or CIDR ranges. Values are bounded and validated as IP addresses or CIDRs. Empty means any sender can reach the configured UDP port, so active deployments should prefer a gateway IP/CIDR allowlist and firewall rules.

capture_interface

  • Type: String
  • Default: "" (disabled)
  • Description: Local interface used for passive packet capture, such as eth0 or en0. When enabled, FlowGuard reduces TCP and UDP packets to bounded 5-tuple flow counters. It does not persist payload bytes or PCAP data. The process needs permission to open a packet capture device.

capture_bpf_filter

  • Type: String
  • Default: "ip or ip6"
  • Description: Berkeley Packet Filter applied by libpcap in the kernel. Invalid filters prevent capture startup. Use a restrictive filter where possible to reduce CPU load.

capture_promiscuous

  • Type: Boolean
  • Default: false
  • Description: Requests promiscuous mode from libpcap. Leave disabled unless the selected interface receives traffic addressed to other hosts and the deployment has explicitly granted the required raw-packet privileges.

These values are also available in Settings → Collectors Setup → Passive Network Capture. Saving capture changes persists them to the YAML configuration but does not re-open packet devices in the running process; restart the FlowGuard daemon after changing the interface, BPF filter, or promiscuous mode. The UI keeps capture disabled when the interface is empty and warns before enabling options that require raw-packet privileges.

storage_dir

  • Type: String
  • Default: "/data"
  • Description: Base folder on the host system where databases are stored. If running SQLite, shards are created daily under this path (e.g. /data/flowguard_2026-07-04.db).

storage_backend

  • Type: String
  • Allowed Values: "sqlite", "duckdb"
  • Default: "sqlite"
  • Description: Database engine. Choose sqlite for standard low-CPU homelab usage, or duckdb (experimental) for heavy multi-day analytical queries.

local_subnets

  • Type: Array of Strings
  • Description: CIDR definitions for internal address space. Traffic flowing within or originating from these networks is profiled to discover device behaviors and baselines.

slack_webhook_url

  • Type: String
  • Description: Slack Incoming Webhook or Discord Slack-compatible webhook URL. Notification rules with channel target slack dispatch formatted text payloads to this endpoint.

webhook_url

  • Type: String
  • Description: Generic outbound webhook destination URL. Notification rules with channel target webhook dispatch raw anomaly JSON to this endpoint.

webhook_format

  • Type: String
  • Allowed Values: "generic", "slack", "telegram"
  • Description: Legacy payload formatting value retained for compatibility. New routing uses slack_webhook_url for Slack/Discord, webhook_url for generic JSON, and Telegram bot settings for Telegram.

webhook_headers

  • Type: Object / map of strings
  • Default: {}
  • Description: Optional custom HTTP headers sent with outbound webhook requests. Use this for webhook authentication headers such as Authorization or X-Webhook-Token. Header values may contain secrets and are not written to logs.

telegram_enabled

  • Type: Boolean
  • Default: false
  • Description: Enables the Telegram Bot channel for notification rules that target telegram. The bot token and chat ID must also be configured.

telegram_token

  • Type: String
  • Default: ""
  • Description: Telegram Bot API token generated by BotFather. Treat it as a secret. If it is exposed, revoke it in BotFather and generate a replacement.

telegram_chat_id

  • Type: String
  • Default: ""
  • Description: Telegram destination chat ID. Send /start to the bot, then call https://api.telegram.org/bot<TOKEN>/getUpdates and copy message.chat.id. For groups/channels, add the bot first and use the group/channel chat.id, often a negative number.

first_run_completed

  • Type: Boolean
  • Description: Tracks whether setup has been completed. If set to false, the UI shows the step-by-step onboarding wizard.

admin_password_hash

  • Type: String
  • Default: ""
  • Description: PBKDF2-SHA256 hash for the local admin password. It is generated by the UI/API setup flow and must never contain a plaintext password.

session_secret

  • Type: String
  • Default: ""
  • Description: Random secret generated for session management. Treat it as sensitive configuration.

retention_days

  • Type: Integer
  • Default: 7
  • Allowed Range: 1 to 60
  • Description: Number of days to retain database flow events, aggregates, and evidence records before pruning them. Values above 60 are rejected to preserve bounded storage on small hardware.

disabled_anomaly_types

  • Type: Array of strings
  • Default: []
  • Description: Alert types that should not be created by behavioral/DDoS detectors. Use this only for globally unwanted detections; prefer notification rules or policies when evidence should still be stored.

muted_anomaly_subnets

  • Type: Array of CIDR strings
  • Default: []
  • Description: Source subnets for which behavioral/DDoS anomaly creation is skipped. This is useful for approved noisy VLANs such as lab, guest, or IoT networks. Empty means all local subnets are eligible.

notify_allowed_subnets

  • Type: Array of CIDR strings
  • Default: []
  • Description: Optional global notification allowlist. When set, Slack, Telegram, and generic webhook dispatch only occurs for anomalies whose source IP is inside one of these CIDRs. Anomalies outside the list remain stored.

notify_suppressed_types

  • Type: Array of strings
  • Default: []
  • Description: Alert types that are persisted but never dispatched to Slack, Telegram, or generic webhooks. Use this to keep evidence while avoiding real-time noise.

new_destination_min_history_buckets

  • Type: Integer
  • Default: 12
  • Allowed Range: 1 to 10080
  • Description: Number of retained one-minute source buckets required before NEW_DESTINATION and NEW_PORT detections become active for that source.

beacon_min_observations

  • Type: Integer
  • Default: 12
  • Allowed Range: 3 to 60
  • Description: Number of periodic observations required before BEACONING can alert.

beacon_min_interval_seconds

  • Type: Integer
  • Default: 90
  • Allowed Range: 1 to 86400
  • Description: Minimum interval between beacon observations. Raising it suppresses common one-minute cloud keepalives.

traffic_spike_min_packets

  • Type: Integer
  • Default: 2500
  • Description: Minimum packets per one-minute source bucket before packet-count TRAFFIC_SPIKE statistical checks can alert.

traffic_spike_min_bytes

  • Type: Integer
  • Default: 1048576
  • Description: Minimum bytes per one-minute source bucket before byte-volume TRAFFIC_SPIKE statistical checks can alert.

ddos_threshold_pps

  • Type: Integer
  • Default: 5000
  • Description: Volumetric packets-per-second threshold for triggering global DDoS alert signals.

ddos_threshold_bps

  • Type: Integer
  • Default: 10485760 (10 MB/s)
  • Description: Volumetric bytes-per-second threshold for triggering global DDoS alert signals.

ddos_threshold_fps

  • Type: Integer
  • Default: 1000
  • Description: Volumetric flow-records-per-second threshold for triggering global DDoS alert signals against a local victim.

syn_flood_threshold_pps

  • Type: Integer
  • Default: 1000
  • Description: Packets-per-second threshold for TCP SYN Flood anomaly detection.

udp_flood_threshold_pps

  • Type: Integer
  • Default: 3000
  • Description: Packets-per-second threshold for UDP Flood anomaly detection.

icmp_flood_threshold_pps

  • Type: Integer
  • Default: 500
  • Description: Packets-per-second threshold for ICMP Flood anomaly detection.

suricata_eve_path

  • Type: String
  • Default: ""
  • Description: Local file path to read Suricata eve.json alerts from.

Environment Variable Overrides

Any parameter can be overridden using environment variables prefixed with FLOWGUARD_. This is highly useful in Docker setups:

  • FLOWGUARD_PORT overrides port
  • FLOWGUARD_NETFLOW_PORT overrides netflow_port
  • FLOWGUARD_SFLOW_PORT overrides sflow_port
  • FLOWGUARD_CAPTURE_INTERFACE overrides capture_interface
  • FLOWGUARD_CAPTURE_BPF_FILTER overrides capture_bpf_filter
  • FLOWGUARD_CAPTURE_PROMISCUOUS overrides capture_promiscuous
  • FLOWGUARD_UNIFI_SYSLOG_ENABLED overrides unifi_syslog_enabled
  • FLOWGUARD_UNIFI_SYSLOG_PORT overrides unifi_syslog_port
  • FLOWGUARD_UNIFI_SYSLOG_ALLOWED_IPS overrides unifi_syslog_allowed_ips using comma-separated IPs/CIDRs
  • FLOWGUARD_STORAGE_DIR overrides storage_dir
  • FLOWGUARD_STORAGE_BACKEND overrides storage_backend
  • FLOWGUARD_LOG_LEVEL overrides log_level
  • FLOWGUARD_SLACK_WEBHOOK_URL overrides slack_webhook_url
  • FLOWGUARD_WEBHOOK_URL overrides webhook_url
  • FLOWGUARD_WEBHOOK_FORMAT overrides webhook_format
  • FLOWGUARD_WEBHOOK_HEADERS overrides webhook_headers using a JSON object, for example {"Authorization":"Bearer token"}
  • FLOWGUARD_TELEGRAM_ENABLED overrides telegram_enabled
  • FLOWGUARD_TELEGRAM_TOKEN overrides telegram_token
  • FLOWGUARD_TELEGRAM_CHAT_ID overrides telegram_chat_id
  • FLOWGUARD_ADMIN_PASSWORD_HASH overrides admin_password_hash
  • FLOWGUARD_SESSION_SECRET overrides session_secret
  • FLOWGUARD_RETENTION_DAYS overrides retention_days
  • FLOWGUARD_DDOS_THRESHOLD_PPS overrides ddos_threshold_pps
  • FLOWGUARD_DDOS_THRESHOLD_BPS overrides ddos_threshold_bps
  • FLOWGUARD_DDOS_THRESHOLD_FPS overrides ddos_threshold_fps
  • FLOWGUARD_DISABLED_ANOMALY_TYPES overrides disabled_anomaly_types
  • FLOWGUARD_MUTED_ANOMALY_SUBNETS overrides muted_anomaly_subnets
  • FLOWGUARD_NOTIFY_ALLOWED_SUBNETS overrides notify_allowed_subnets
  • FLOWGUARD_NOTIFY_SUPPRESSED_TYPES overrides notify_suppressed_types
  • FLOWGUARD_NEW_DESTINATION_MIN_HISTORY_BUCKETS overrides new_destination_min_history_buckets
  • FLOWGUARD_BEACON_MIN_OBSERVATIONS overrides beacon_min_observations
  • FLOWGUARD_BEACON_MIN_INTERVAL_SECONDS overrides beacon_min_interval_seconds
  • FLOWGUARD_TRAFFIC_SPIKE_MIN_PACKETS overrides traffic_spike_min_packets
  • FLOWGUARD_TRAFFIC_SPIKE_MIN_BYTES overrides traffic_spike_min_bytes
  • FLOWGUARD_SYN_FLOOD_THRESHOLD_PPS overrides syn_flood_threshold_pps
  • FLOWGUARD_UDP_FLOOD_THRESHOLD_PPS overrides udp_flood_threshold_pps
  • FLOWGUARD_ICMP_FLOOD_THRESHOLD_PPS overrides icmp_flood_threshold_pps
  • FLOWGUARD_SURICATA_EVE_PATH overrides suricata_eve_path