Architecture

How Synapse Works

Synapse operates in two deployment modes — Agent (transparent) and Proxy (inline) — that share the same eBPF/XDP kernel enforcement layer. The mode determines what happens after the kernel makes its drop/pass decision.

Agent Mode — Transparent

flowchart TD
    inet([Internet / North-South])
    ew([Internal Services / East-West])
    blocked[XDP DROP / Blocked]
    backend[Backend Upstream]

    subgraph kernel[eBPF XDP Kernel Layer]
        acl[Access Rules<br/>4M IPv4 / 1M IPv6]
        fp[JA4+ Fingerprinting<br/>JA4T · JA4TS · JA4L · JA4LS]
        ti[Threat Intel and IDS<br/>GeoIP / IP Reputation]
    end

    subgraph agent[Agent Mode - Transparent]
        passthru[Pass-through / zero overhead]
        enforce[XDP DROP / nftables / iptables]
        eb[EventBridge / SIEM / Unix socket]
    end

    inet --> acl
    ew --> ti
    acl -->|drop| blocked
    fp --> passthru
    passthru --> backend
    backend --> ew

Proxy Mode — Inline

flowchart TD
    inet([Internet / North-South])
    ew([Internal Services / East-West])
    blocked[XDP DROP / Blocked]
    backend[Backend Upstream]

    subgraph kernel[eBPF XDP Kernel Layer]
        acl[Access Rules<br/>4M IPv4 / 1M IPv6]
        fp[JA4+ Fingerprinting<br/>JA4T · JA4TS · JA4L · JA4LS]
        ti[Threat Intel and IDS<br/>GeoIP / IP Reputation]
    end

    subgraph proxy[Proxy Mode - Inline]
        tls[1 · TLS Termination<br/>ACME / Custom certs]
        ja4[2 · Full JA4+ Suite<br/>JA4 · JA4H · JA4S · JA4X]
        waf[3 · WAF / Rate Limiting / CAPTCHA]
        scan[4 · Content Scanning / ClamAV]
        fwd[5 · Forward to Upstream]
    end

    inet --> acl
    ew --> ti
    acl -->|drop| blocked
    fp --> tls
    tls --> ja4
    ja4 --> waf
    waf --> scan
    scan --> fwd
    fwd --> backend

Agent mode — transparent

Synapse attaches to the network interface via XDP. Packets are inspected and fingerprinted in kernel space. Allowed traffic passes through to the original destination without modification — Synapse is invisible to the connection. Active blocking happens at kernel speed via XDP_DROP, nftables, or iptables. JA4+ fingerprint events are streamed to SIEM tools or third-party applications via the EventBridge Unix socket.

Use for: east-west protection between internal services, deploying alongside an existing reverse proxy or load balancer, Windows environments, or anywhere you want enforcement without being in the data path.

Proxy mode — inline

Traffic is terminated at Synapse. TLS is decrypted, the full JA4+ suite is available (including application-layer fingerprints JA4, JA4H, JA4S, JA4X that require reading the TLS handshake), and the request passes through WAF rules, rate limiting, CAPTCHA, and optional content scanning before being forwarded to the upstream. This is the only mode that can inspect or modify HTTP/HTTPS payloads.

Use for: perimeter ingress (north-south), applications that need WAF/CAPTCHA/TLS termination, or full L7 visibility.

---

Component map

Component	Description
XDP / eBPF Kernel Filter	First line: kernel-space packet drop before userspace sees the packet
Access Rules Engine	LPM Trie for 4M IPv4 / 1M IPv6 CIDR rules with CIDR coalescing
JA4+ Fingerprint Engine	Full suite: JA4, JA4H, JA4T, JA4TS, JA4L, JA4LS, JA4S, JA4X
Threat Intelligence	Gen0Sec API + Threat MMDB (auto-updated) + IP reputation scoring
GeoIP Manager	Country, ASN, and city-level lookups via MMDB (auto-updated)
IDS	Network intrusion detection (thalamus-ids), both modes
Multi-Backend Firewall	XDP → nftables → iptables → userland automatic fallback
BPF Statistics Collector	Kernel-level packet counters, per-IP drop tracking
TCP Fingerprint Collector	SYN packet extraction and analysis
EventBridge	Fingerprint event streaming over Unix/TCP socket to SIEM or TUI
HTTP/TLS Server	Proxy mode: HTTP + HTTPS ingress
TLS / ACME Manager	Automatic Let's Encrypt (HTTP-01 and DNS-01), custom certs, expiry monitoring
Reverse Proxy	Request forwarding to upstreams via Pingora
Upstream Manager	File, Consul, Kubernetes service discovery; weighted load balancing; hot-reload
WAF (Wirefilter)	Expression-based request filtering and blocking
Rate Limiter	Per-rule, per-path request rate enforcement
CAPTCHA Engine	hCaptcha, reCAPTCHA, Cloudflare Turnstile challenge/verify
Content Scanner	ClamAV malware detection on request bodies
Internal Services Server	ACME HTTP-01, CAPTCHA verify, cert management endpoints
Redis Cache	Certificates, threat intel, CAPTCHA tokens, content scan results
Terminal TUI	ratatui real-time dashboard: fingerprints, traffic, threats
Event Queue	Batched delivery of logs, stats, fingerprint events to Gen0Sec API
File / Syslog / ETW Logger	Rotating files, Linux syslog, Windows Event Tracing
Windows Service	SCM integration: install, uninstall, start, stop, config reload

Performance

• Ultra-low latency — XDP drops happen in kernel space before the packet ever reaches userspace
• High throughput — Rust async runtime (Tokio) with worker threads matching CPU core count
• Memory efficient — LPM Trie with BPF_F_NO_PREALLOC; only allocated entries use memory
• Zero-downtime reloads — upstream config, access rules, and WAF expressions hot-reload without restarting