Deployment Modes

Synapse runs in two mutually exclusive modes. Both share the same eBPF/XDP kernel enforcement layer — the difference is what happens after the kernel decides to pass a packet.

See ARCHITECTURE.md for a full data-flow diagram.

---

Agent mode — transparent (default)

Synapse attaches to the network interface and observes all traffic at the kernel level without being in the data path. Traffic flows directly to its destination; Synapse enforces blocking via XDP_DROP, nftables, or iptables without touching passing packets.

When to choose agent mode:

• You already have a reverse proxy or load balancer and want network-level protection around it
• You need east-west protection between internal services
• You want kernel-speed blocking without proxying overhead
• Running on Windows (proxy mode is not available on Windows)
• You want to stream JA4+ fingerprint events to your own SIEM or tooling via the EventBridge

mode: "agent"  # default — can be omitted

export MODE="agent"

Use cases:

• Network-level firewall at the edge of a Kubernetes cluster
• East-west enforcement between microservices
• Kernel-level IP/CIDR/fingerprint blocking alongside Nginx, HAProxy, Caddy
• Windows Server endpoint protection

---

Proxy mode — inline

Traffic terminates at Synapse. TLS is decrypted, the full JA4+ fingerprint suite is available (including application-layer types that require reading the HTTP request and TLS handshake), and requests pass through WAF, rate limiting, CAPTCHA, and optional content scanning before being forwarded to the upstream. This is the only mode that can inspect or block based on HTTP headers, bodies, or URL paths.

When to choose proxy mode:

• You need WAF rules, rate limiting per URL path, or CAPTCHA challenges
• You want automatic TLS certificate management (ACME / Let's Encrypt)
• You need malware scanning on uploaded content
• You want JA4 (TLS ClientHello) and JA4H (HTTP header) fingerprints in addition to TCP-level JA4T/JA4TS

mode: "proxy"

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

export MODE="proxy"

---

Feature comparison

Feature	Proxy	Agent
XDP Firewall & Access Rules	✅	✅
CIDR Coalescing (up to 4M rules)	✅	✅
IDS / Intrusion Detection	✅	✅
Threat Intelligence & GeoIP	✅	✅
JA4T · JA4TS · JA4L · JA4LS (TCP/IP level)	✅	✅
BPF Stats & TCP Fingerprinting	✅	✅
Event Sending (Fingerprint + IDS)	✅	✅
Terminal TUI (ratatui)	✅	✅
File / Syslog / ETW Logging	✅	✅
Windows Support	⚠️ Agent features only	✅
Windows Service (SCM)	✅	✅
HTTP/HTTPS Reverse Proxy	✅	❌
TLS & ACME Certificates	✅	❌
Upstreams & Load Balancing	✅	❌
JA4 · JA4H · JA4S · JA4X (application level)	✅	❌
WAF (Wirefilter expressions)	✅	❌
Rate Limiting	✅	❌
CAPTCHA Protection	✅	❌
Content Scanning (ClamAV)	✅	❌
HTTP Access Log Sending	✅	❌

Detailed comparison

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	✅ IP allow/block (4M IPv4 / 1M IPv6)	✅ IP allow/block (4M IPv4 / 1M IPv6)
CIDR Coalescing	✅ Auto-merge before BPF load	✅ Auto-merge before BPF load
Dynamic Access Rules	✅ Auto-updates from Gen0Sec API	✅ Auto-updates from Gen0Sec API
IDS / Intrusion Detection	✅ thalamus-ids, network-level	✅ thalamus-ids, network-level
BPF Statistics Collection	✅ Packet counters (XDP only)	✅ Packet counters (XDP only)
TCP Fingerprinting	✅ SYN packet analysis	✅ SYN packet analysis
JA4+ (TCP/IP level)	✅ JA4T, JA4TS, JA4L, JA4LS	✅ JA4T, JA4TS, JA4L, JA4LS
JA4+ (application level)	✅ JA4, JA4H, JA4S, JA4X	❌ Requires TLS termination
Fingerprint Header Forwarding	✅ 11 X-JA4* headers to origin	❌ Not available
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	✅ Certs, threat intel, CAPTCHA	❌ Not available
HTTP Access Log Sending	✅ To Gen0Sec API	❌ Not available
Event Sending (Fingerprint + IDS)	✅ To Gen0Sec API	✅ To Gen0Sec API
Terminal TUI	✅ Embedded + standalone	✅ Embedded + standalone
File/Syslog Logging	✅ Rotating logs (Linux: syslog)	✅ Rotating logs (Linux: syslog)
ETW Logging	✅ Windows only	✅ Windows only
Windows Service (SCM)	✅ install/uninstall/start/stop	✅ install/uninstall/start/stop
Windows eBPF/XDP	✅ Via eBPF for Windows	✅ Via eBPF for Windows
Multiple Network Interfaces	✅ High availability setups	✅ High availability setups
Multi-threaded Runtime	✅ Default	⚠️ Single-threaded default
Windows	⚠️ Agent features only	✅ Full support

---

Choosing a mode

Do you need to terminate TLS or inspect HTTP?
  YES → Proxy mode
  NO  ↓

Do you already have a reverse proxy (Nginx, Caddy, HAProxy)?
  YES → Agent mode  (protect around/alongside it)
  NO  ↓

Are you on Windows?
  YES → Agent mode  (proxy mode not available)
  NO  ↓

Do you need WAF, rate limiting, or CAPTCHA?
  YES → Proxy mode
  NO  → Agent mode  (lighter, no traffic-path overhead)