Overview

Synapse is a high-performance reverse proxy and firewall built with Rust, featuring:

XDP-based packet filtering for ultra-low latency protection at kernel level
Multi-backend firewall with automatic fallback (XDP > nftables > iptables > userland)
Dynamic access rules with automatic updates from Gen0Sec API
JA4+ fingerprinting complete suite: JA4, JA4H, JA4T, JA4L, JA4S, JA4X
Automatic TLS certificate management with ACME/Let's Encrypt (HTTP-01 and DNS-01)
Threat intelligence integration with Gen0Sec API and Threat MMDB
Content scanning with ClamAV integration for malware detection
Advanced upstream routing with service discovery (file, Consul, Kubernetes)
Weighted load balancing with hot-reloadable configuration

Linux only. Requires kernel 4.18+ with XDP/BPF support.

Quick Start

# Ubuntu install
curl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh

# Run with config file
synapse -c /etc/synapse/config.yaml

# Set mode via environment variable (default: agent)
export MODE="proxy"  # or "agent"

<details> <summary>More installation methods</summary>

Ansible

git clone https://github.com/gen0sec/synapse.git
cd synapse/moat/ansible
cp hosts.example hosts
# Edit hosts and add your server details
ansible-playbook playbook.yml -e gen0sec_api_token=your_key_here

Features: Debian/Ubuntu + RedHat/CentOS/Fedora, optional ClamAV/Redis/Fail2Ban. More details.

Kubernetes

helm repo add gen0sec https://helm.gen0sec.com
helm install synapse-stack

More details.

Killercoda Playground

curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key <YOUR_API_KEY>

Docker

# Required capabilities
--cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN

</details>

Modes

Synapse runs in two modes: Agent (default) and Proxy.

| Feature | Proxy | Agent | |---------|:-----:|:-----:| | HTTP/HTTPS Reverse Proxy | ✅ | ❌ | | TLS & ACME Certificates | ✅ | ❌ | | Upstreams & Load Balancing | ✅ | ❌ | | WAF, Rate Limiting, CAPTCHA | ✅ | ❌ | | Content Scanning (ClamAV) | ✅ | ❌ | | XDP Firewall & Access Rules | ✅ | ✅ | | Threat Intelligence & GeoIP | ✅ | ✅ | | JA4+ Fingerprinting | ✅ Full | ✅ Network-level | | BPF Stats & TCP Fingerprinting | ✅ | ✅ | | File/Syslog Logging | ✅ | ✅ |

<details> <summary>Detailed feature comparison</summary>

| Feature | Proxy Mode | Agent Mode | |---------|-------------------|------------| | HTTP/HTTPS Reverse Proxy | ✅ Full support | ❌ Not available | | TLS Certificate Management | ✅ ACME & custom certificates | ❌ Not available | | Upstreams & Load Balancing | ✅ File, Consul, Kubernetes | ❌ Not available | | Hot-reloadable Upstreams | ✅ Zero-downtime updates | ❌ Not available | | XDP Packet Filtering | ✅ Kernel-level filtering | ✅ Kernel-level filtering | | Multi-Backend Firewall | ✅ XDP/nftables/iptables/userland | ✅ XDP/nftables/iptables/userland | | Access Rules Enforcement | ✅ IP allow/block lists | ✅ IP allow/block lists | | Dynamic Access Rules | ✅ Auto-updates from Gen0Sec API | ✅ Auto-updates from Gen0Sec API | | BPF Statistics Collection | ✅ Packet processing metrics (XDP only) | ✅ Packet processing metrics (XDP only) | | TCP Fingerprinting | ✅ SYN packet analysis | ✅ SYN packet analysis | | JA4+ Fingerprinting | ✅ JA4, JA4H, JA4T, JA4L, JA4S, JA4X | ✅ JA4T, JA4L (network-level) | | Wirefilter Expressions (WAF) | ✅ Advanced request filtering | ❌ Not available | | Rate Limiting | ✅ Per-rule rate limits | ❌ Not available | | Content Scanning (ClamAV) | ✅ Malware detection | ❌ Not available | | CAPTCHA Protection | ✅ hCaptcha, reCAPTCHA, Turnstile | ❌ Not available | | Threat Intelligence | ✅ Real-time MMDB + HTTP-level | ✅ Smart Lists (network-level) | | GeoIP Databases | ✅ Country, ASN, City lookups | ⚠️ Via Smart Lists only | | Internal Services Server | ✅ ACME, CAPTCHA endpoints | ❌ Not available | | Redis Caching | ✅ Certificates, threat intel, validation | ❌ Not available | | Access Log Sending | ✅ To Gen0Sec API | ❌ Not available | | File/Syslog Logging | ✅ Rotating logs | ✅ Rotating logs | | Multiple Network Interfaces | ✅ High availability setups | ✅ High availability setups | | Multi-threaded Runtime | ✅ Default | ⚠️ Single-threaded default |

</details> <details> <summary>Agent mode (default)</summary>

Standalone agent focused on access rules enforcement without HTTP/HTTPS proxy. Ideal for network-level protection where you don't need request proxying.

mode: "agent"  # default, can be omitted

# Set via environment variable
export MODE="agent"

Use cases:

Network-level firewall protection without proxying
Access rules enforcement at the edge
Kernel-level IP blocking without HTTP overhead
Integration with existing reverse proxies or load balancers

</details> <details> <summary>Proxy mode</summary>

Full-featured reverse proxy with HTTP/HTTPS support, forwarding requests to upstream servers while applying access rules and threat intelligence at the kernel level.

mode: "proxy"

proxy:
  address_http: "0.0.0.0:80"
  address_tls: "0.0.0.0:443"
  upstream:
    conf: "/etc/synapse/upstreams.yaml"

# Set via environment variable
export MODE="proxy"

</details>

Configuration

Synapse supports three configuration methods (highest to lowest priority):

YAML Configuration File - via config.yaml (example)
Command Line Arguments - override specific settings via CLI flags
Environment Variables - export API_KEY="your-key"

CLI Options

| Flag | Description | Default | |------|-------------|---------| | -c, --config <PATH> | Path to configuration file (YAML) | - | | --security-rules-config <PATH> | Security rules file (fallback without API key) | security_rules.yaml | | -i, --iface <NAME> | Network interface for XDP | eth0 | | --ifaces <LIST> | Additional interfaces (comma-separated, overrides --iface) | - | | --log-level <LEVEL> | Log level (error, warn, info, debug, trace) | info | | --disable-xdp | Disable XDP packet filtering | false | | --redis-url <URL> | Redis connection URL | redis://127.0.0.1/0 | | --redis-prefix <PREFIX> | Redis namespace prefix | ax:synapse | | --captcha-site-key <KEY> | CAPTCHA site key | - | | --captcha-secret-key <KEY> | CAPTCHA secret key | - | | --captcha-jwt-secret <KEY> | JWT secret for CAPTCHA tokens | - | | --captcha-provider <PROVIDER> | CAPTCHA provider (hcaptcha, recaptcha, turnstile) | - | | --captcha-token-ttl <SECS> | CAPTCHA token TTL | 7200 | | --captcha-cache-ttl <SECS> | CAPTCHA cache TTL | 300 | | --proxy-protocol-enabled | Enable PROXY protocol | false | | --proxy-protocol-timeout <MS> | PROXY protocol timeout | 1000 | | -d, --daemon | Run as daemon | false | | --daemon-pid-file <PATH> | PID file path | /var/run/synapse.pid | | --daemon-working-dir <PATH> | Daemon working directory | / | | --daemon-stdout <PATH> | Daemon stdout log | /var/log/synapse.out | | --daemon-stderr <PATH> | Daemon stderr log | /var/log/synapse.err | | --daemon-user <USER> | Run daemon as user | - | | --daemon-group <GROUP> | Run daemon as group | - | | --clear-certificate <DOMAIN> | Clear certificate from filesystem and Redis | - |

Feature Toggles

| Feature | YAML Path | Environment Variable | Default | |---------|-----------|---------------------|---------| | BPF Statistics | logging.bpf_stats.enabled | BPF_STATS_ENABLED | true | | TCP Fingerprinting | logging.tcp_fingerprint.enabled | TCP_FINGERPRINT_ENABLED | true | | Content Scanning | proxy.content_scanning.enabled | CONTENT_SCANNING_ENABLED | false | | CAPTCHA Protection | (enabled when keys are set) | CAPTCHA_SITE_KEY, CAPTCHA_SECRET_KEY | disabled | | ACME (Auto TLS) | proxy.acme.enabled | ACME_ENABLED | false | | Internal Services | proxy.internal_services.enabled | INTERNAL_SERVICES_ENABLED | true | | PROXY Protocol | proxy.protocol.enabled | PROXY_PROTOCOL_ENABLED | false | | File Logging | logging.file_logging_enabled | LOGGING_FILE_ENABLED | false | | Syslog | logging.syslog.enabled | `LOGGING_S

Synapse

Install / Use

README