A high-performance Go-based reverse proxy with advanced security features, designed to transparently intercept and filter HTTP/HTTPS traffic with dynamic rule-based filtering and minimal disruption.
It features an (optional) control panel for easy management, configuration, and monitoring. The control panel will allow for realtime and centralized management of multiple FlowGuard instances in addition to providing access to GeoIP databases and AbuseIPDB IP lists.
Important
FlowGuard is intended for use by experienced system administrators and security professionals. Improper configuration may lead to service disruption. Always test configurations in a safe environment before deploying to production.
Caution
FlowGuard is a new project in acive development and may have undiscovered bugs or security vulnerabilities. Use at your own risk and always keep software up to date.
- Transparent Traffic Interception: Redirects traffic from ports 80 and 443 to proxy ports using iptables
- HTTPS Decryption: Dynamically loads and manages SSL certificates for transparent HTTPS inspection
- Automatic Certificate Management: Monitors and reloads certificates from the filesystem for seamless rotation
- Graceful Shutdown: Automatically removes iptables rules on shutdown to restore original traffic flow
- Dynamic Rule-Based Filtering: Flexible rule engine with conditions for path, domain, IP, ASN, user-agent, headers, ipset, and iplist matching
- IP Database Integration: ASN and geolocation lookups using configurable IP databases (MaxMind format)
- IP List System: Built-in high-performance in-memory IP lists with automatic URL refresh (10M+ lookups/sec)
- IPSet Integration: Direct integration with Linux ipset for kernel-level IP blocking
- Trusted Proxy Support: Properly handles X-Forwarded-For headers from configurable trusted proxies
- Real Client IP Detection: Extracts actual client IPs through proxy chains for accurate filtering
- Hot Configuration Reload: Automatic configuration file monitoring and reloading without restart
- Structured Logging: Sink-based logging to files, Axiom, Loki, or OpenObserve with hot-reload support
- Efficient connection handling: Minimal overhead with optimized middleware chain
- Certificate caching: Automatic refresh for seamless rotation
- Network interface binding: Support for multi-homed systems
- Smart caching: ETag-aware HTTP caching for external resources with stale-while-revalidate
- Regex optimization: Compiled pattern caching for rule matching
- Go 1.25 or later
- Linux system with iptables support
- Root/sudo access for port redirection
- ipset installed for IP filtering (optional)
# Clone the repository
git clone https://github.com/chieftools/flowguard.git
cd flowguard
# Build for current platform
go build -o flowguard .curl -sS https://pkg.flowguard.network/install.sh | sudo bash# Add FlowGuard repository
curl -sS https://pkg.flowguard.network/gpg.key | gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/flowguard.gpg
echo "deb https://pkg.flowguard.network/deb stable main" | sudo tee /etc/apt/sources.list.d/flowguard.list
# Update package list and install
sudo apt update
sudo apt install flowguard
# Setup initial configuration (optional - use FlowGuard control panel or create manually)
flowguard setup fgsvr_...
# Alternatively create the /etc/flowguard/config.json manually
# Ensure certificates are properly detected
flowguard certificates
# Start the FlowGuard service
sudo systemctl start flowguard
# Enable FlowGuard to start on boot
sudo systemctl enable flowguard# Add FlowGuard repository
sudo tee /etc/yum.repos.d/flowguard.repo << 'EOF'
[flowguard]
name=FlowGuard Repository
baseurl=https://pkg.flowguard.network/rpm/stable/x86_64
enabled=1
gpgcheck=1
gpgkey=https://pkg.flowguard.network/gpg.key
EOF
# Install FlowGuard
sudo yum install flowguard
# Setup initial configuration (optional - use FlowGuard control panel or create manually)
flowguard setup fgsvr_...
# Start the FlowGuard service
sudo systemctl start flowguard
# Enable FlowGuard to start on boot
sudo systemctl enable flowguard# Debian/Ubuntu
sudo apt update
sudo apt install --only-upgrade flowguard
# RHEL/CentOS/Rocky/Alma
sudo yum check-update --disablerepo=* --enablerepo=flowguard
sudo yum update flowguardSince FlowGuard operates as a reverse proxy, backend servers must be configured correctly to see the original client IPs. This typically involves setting up the backend to trust the proxy and extract the real client IP from headers like X-Forwarded-For.
This is an example of how this can be done in NGINX, replacing <public v4 address> and <public v6 address> with the actual public IP addresses of your server:
Remember to add all public IPs assigned to your server if you are using FlowGuard in it's default configuration where it will intercept traffic on all public IPs assigned to the server.
real_ip_header X-Forwarded-For;
real_ip_recursive on;
set_real_ip_from <public v4 address>;
set_real_ip_from <public v6 address>;A script that can generate this for you:
NGINX_CONF=/etc/nginx/conf.d/flowguard.conf
echo "real_ip_header X-Forwarded-For;" > $NGINX_CONF
echo "real_ip_recursive on;" >> $NGINX_CONF
echo "set_real_ip_from "`curl -sS ipv4.chief.tools`";" >> $NGINX_CONF
echo "set_real_ip_from "`curl -sS ipv6.chief.tools`";" >> $NGINX_CONF
cat $NGINX_CONF
service nginx configtest
# service nginx reloadThe proxy expects combined certificate files (cert + key) in the specified certificate path. Files should be named by hostname and contain both the certificate chain and private key.
Certificate files are:
- Loaded on-demand when first requested
- Cached in memory for performance
- Automatically refreshed periodically to support rotation
- Validated on load to ensure proper format
{
"proxy": {
"transparent_mode": true,
"tproxy_mark": 1,
"tproxy_routing_table": 100
}
}- Linux kernel 2.6.28+ with TPROXY support
- CAP_NET_ADMIN capability (already required for iptables)
- Modern iptables with TPROXY target
TPROXY only works when the proxy and backend are on different machines. For same-machine deployments, use standard mode (simpler, same result).
FlowGuard provides structured logging with multiple simultaneous destinations (sinks). Each sink can be independently configured and supports hot-reload.
- File: Local file logging
- Axiom: Axiom analytics platform
- Loki: Grafana Loki with JSON flattening
- OpenObserve: OpenObserve with automatic field flattening
{
"logging": {
"sinks": {
"local_log": {
"type": "file",
"path": "/var/log/flowguard/main.log"
},
"axiom": {
"type": "axiom",
"token": "xaat-your-token",
"dataset": "flowguard-production"
},
"loki": {
"type": "loki",
"url": "http://loki:3100/loki/api/v1/push",
"labels": {
"job": "flowguard",
"environment": "production"
}
},
"openobserve": {
"type": "openobserve",
"url": "https://observe.example.com",
"organization": "my-org",
"stream": "flowguard",
"username": "admin@example.com",
"password": "api-token"
}
},
"header_whitelist": ["cf-", "sec-ch-", "user-agent"]
}
}Each log entry includes:
- Request details (method, URL, headers, TLS info)
- Client information (IP, country, ASN)
- Rule matching results (which rule matched, action taken)
- Response details (status, timing, headers)
- Host metadata (server ID, hostname, version)
Sinks are only restarted when their specific configuration changes. Adding, removing, or modifying one sink doesn't affect others.
FlowGuard uses a JSON configuration file for advanced filtering rules. The configuration supports:
- Rules: Define matching conditions and associated actions
- Actions: Specify what to do when rules match:
log: Log request and continue processing (can be overridden by later rules)allow: Allow request and stop rule processingblock: Block request with custom status/messagerate_limit: Rate limit requests based on defined thresholds
- IP Database: Configure IP geolocation database source and refresh interval
- Trusted Proxies: Configure trusted proxy networks for proper client IP detection
- IP Lists: Configure in-memory IP lists for high-performance matching
- Logging: Configure structured logging sinks (file, Axiom, Loki, OpenObserve)
The repository includes a config.schema.json file that provides:
- IDE Autocomplete: IntelliSense support in VS Code, IntelliJ, and other modern IDEs
- Validation: Real-time error checking as you edit
- Documentation: Inline descriptions for all properties
To use the schema, add this line to your config.json:
{
"$schema": "https://raw.githubusercontent.com/chieftools/flowguard-proxy/main/config.schema.json"
}Example configuration structure:
{
"rules": {
"log-suspicious-agents": {
"action": "log-action",
"conditions": {
"matches": [
{
"type": "agent",
"match": "contains",
"value": "bot"
}
]
}
},
"block-malicious-agents": {
"action": "block-403",
"conditions": {
"operator": "OR",
"matches": [
{
"type": "agent",
"match": "contains",
"value": "scanner"
}
]
}
}
},
"actions": {
"log-action": {
"action": "log"
},
"block-403": {
"action": "block",
"status": 403,
"message": "Forbidden"
}
},
"ip_database": {
"url": "https://example.com/ipinfo.mmdb",
"refresh_interval_seconds": 86400
},
"trusted_proxies": {
"ipnets": [
"https://www.cloudflare.com/ips-v4",
"https://www.cloudflare.com/ips-v6",
"192.168.1.0/24"
],
"refresh_interval_seconds": 43200
}
}Rules support complex conditions with logical operators:
- Operators:
AND,OR,NOT - Match Types:
path: URL path matchingdomain: Host header matchinguser-agent: User-Agent header matchingheader: Arbitrary header matchingip: Client IP matchingasn: Autonomous System Number matchingipset: Linux ipset membership checking (external tool required)iplist: In-memory IP list matching (built-in, no dependencies)
- Match Operations:
equals,contains,starts-with,ends-with,regex,in,not-in,exists,missing
FlowGuard includes a built-in high-performance IP list system using radix trees for 10M+ lookups/second. Lists are loaded from URLs or files and automatically refreshed.
Configuration:
{
"ip_lists": {
"blocklist": {
"url": "https://example.com/blocklist.txt",
"refresh_interval_seconds": 3600
},
"local_allowlist": {
"path": "/etc/flowguard/allowlist.txt"
}
}
}List Format: One IP or CIDR per line (supports both IPv4 and IPv6):
192.168.1.1
10.0.0.0/24
2001:db8::/32
Rule Usage:
{
"type": "iplist",
"match": "in",
"value": "blocklist"
}Testing:
# Show list stats (load time, memory usage, entry count)
flowguard iplist blocklist
# Check if IP is in list
flowguard iplist blocklist contains 192.168.1.1For existing IPSet infrastructure, create and populate lists before starting:
# Create IPv4 blocklist
sudo ipset create abuseipdb_v4 hash:net
# Create IPv6 blocklist
sudo ipset create abuseipdb_v6 hash:net family inet6
# Add IPs to blocklist
sudo ipset add abuseipdb_v4 192.168.1.100
sudo ipset add abuseipdb_v6 2001:db8::1Note: IP Lists (iplist type) are recommended for new deployments due to easier management, automatic updates, and unified IPv4/IPv6 support. Use IPSet (ipset type) only if you have existing IPSet infrastructure.
The proxy uses a flexible rule engine defined in the configuration file. Rules can be updated without restarting the service by modifying the configuration file - FlowGuard automatically detects and reloads changes.
- Main: Entry point, command-line parsing, signal handling
- Proxy Manager: Coordinates proxy servers, iptables/TPROXY rules, and graceful shutdown
- HTTP/HTTPS Servers: Handle incoming requests and forward to backends
- Certificate Manager: Dynamic SSL certificate loading and management
- Configuration Manager: Hot-reload configuration with rule management
- Cache System: Caching layer for external data fetches with ETag support
- IP List Manager: High-performance radix tree-based IP list matching
- Logger Manager: Sink-based structured logging with hot-reload
- Middleware Chain:
- Rules Engine: Dynamic rule-based filtering with complex conditions
- IP Lookup: ASN and geolocation database integration
- Client IP extraction from trusted proxy chains
- Original traffic to ports 80/443 is redirected via iptables to proxy ports
- Proxy receives connection and extracts real client IP through trusted proxy chains
- For HTTPS, appropriate certificate is loaded/retrieved from cache
- Rules engine evaluates all configured rules against the request
- Request is either logged, blocked, or allowed based on rule evaluation
- Valid requests are forwarded to original destination
- Response is returned to client through proxy with appropriate headers
go test ./...If you discover a security vulnerability within this project, please report it privately via GitHub: https://github.com/chieftools/flowguard-proxy/security/advisories/new. All security vulnerabilities will be swiftly addressed. There is no bug bounty program at this time.
FlowGuard Proxy is open-source software licensed under the Apache License 2.0. This means you are free to use, modify, and distribute the software for both commercial and non-commercial purposes. See the LICENSE file for details.