Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
118 lines (95 loc) · 5.51 KB

ARCHITECTURE.md

File metadata and controls

118 lines (95 loc) · 5.51 KB

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
Loading

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
Loading

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