FlowGuard Lite Documentation

🛡️ Welcome to the FlowGuard Lite documentation site.

FlowGuard Lite is experimental alpha software, primarily tested on one UniFi home network.

[!WARNING]

FlowGuard Lite is an early-stage project and may contain bugs.

All security detections are experimental heuristics, not guaranteed indicators of compromise.

It does not replace an IDS, SIEM, or SOC, and should not be considered a guarantee of attack detection.

Additional integrations have varying and limited levels of validation.

It acts as a lightweight flow collector and correlates router/firewall telemetry (NetFlow, IPFIX, sFlow, or passive capture) with optional Suricata IDS events to build device-centric behavioral baselines and explain anomalies. UniFi gateways may expose IPFIX, SIEM/syslog, SNMP, or only internal Traffic Flows depending on model and firmware; those paths are documented separately.

Feature Validation Status

The features in this repository are divided into three validation tiers:

Category	Features Included
Tested in real use by the author	* NetFlow/IPFIX Ingestion (from UniFi Gateway) * Docker Compose Deployment * SQLite daily shards (storage & retention) * Home network environment
Implemented with limited validation	* sFlow Ingestion (collector listener & decoder) * Passive Network Capture (via SPAN/Mirror port) * Suricata IDS Integration (correlating `eve.json` records) * DuckDB Storage Engine (for query acceleration) * DDoS/Volumetric Heuristics (BPS, PPS, FPS thresholds) * Slack & Telegram Webhook notifications
Experimental or unverified	* UniFi Syslog/SIEM Ingest (highly experimental and secondary; note that NetFlow/IPFIX is the primary and best tested source) * SNMP Auxiliary Metrics (future/optional tracking only)

📖 Table of Contents

Getting Started

Installation Guide - Learn how to deploy FlowGuard Lite using Docker Compose or host-native binaries.
Passive Network Capture - Opt-in libpcap deployment, minimum Linux capabilities, filters, and verification.
Configuration Reference - Complete schema details for config.yaml and environment variables.

Exporter Setup Guides

Configure your routers and firewalls to export supported telemetry:

Ubiquiti UniFi Gateways - IPFIX when available, SIEM/syslog Activity Logging ingest, passive capture fallback.
MikroTik RouterOS
OPNsense & pfSense Firewalls

Core Features

Anomaly Detection & Risk Heuristics - Deep dive into statistical baselines, DDoS thresholds, and device risk indexing.
Overview Dashboard - Default visibility dashboard, event timeline, risk distribution, and network operations panels.
Operator Workflows & UI Architecture - Target operator workflows, page model, Risk Index explanation requirements, and UI implementation order.
Integrations & Webhooks - How to set up Suricata ingestion, configure Slack/Telegram/webhook notifications, and export firewall rule templates.

Reference & Development

System Architecture - Internal design, collector worker pools, memory aggregation, and sharded storage engines.
Frontend Architecture - Vite module boundaries, feature-first structure, and UI refactor rules.
REST API Reference - Endpoints, request/response models, and example payloads.
Performance Baselines - Standard metrics, publishable profiles, N100 hardware targets, and pass/fail thresholds.
Capacity & Performance Guide - Ingestion limits, tested hardware profiles, overload mechanics, and router-specific tradeoffs.

Benchmark and Quality Gates

The benchmark suite is part of the validation gate. Use these commands to reproduce the preliminary performance estimates:

make benchmark-smoke
make benchmark-run
make docker-benchmark-run
make benchmark-matrix
make pre-release-gate

What they cover:

Command	Purpose
`make benchmark-smoke`	Fast regression check for processing rate and parser performance.
`make benchmark-run`	Native benchmark report generation under `benchmark-results/`.
`make docker-benchmark-run`	Containerized 2 GB benchmark profile.
`make benchmark-matrix`	Docker benchmark profiles for 2 GB, 4 GB, and 8 GB memory limits.
`make pre-release-gate`	Backend Go tests, frontend build/lint, Cypress smoke, benchmark smoke, and whitespace checks.

Preliminary capacity numbers are documented in the Capacity & Performance Guide.