Skip to content

FEATURES.md

Latest commit

 

History

History
278 lines (201 loc) · 10 KB

FEATURES.md

File metadata and controls

278 lines (201 loc) · 10 KB
Raw

Features

Synapse's capabilities are organised around three NDR phases: detect, block, and inspect.

Detect

JA4+ Fingerprinting

Synapse captures TLS, TCP, HTTP, and latency fingerprints that uniquely identify client software, bots, and attack tooling — independently of IP address. Fingerprints persist across VPN/proxy changes and can be used for active blocking, allow-listing, or streaming to a SIEM.

Fingerprint Available In Description
JA4 Proxy TLS ClientHello fingerprint
JA4H Proxy HTTP request header fingerprint
JA4T Both TCP SYN fingerprint (client)
JA4TS Both TCP SYN-ACK fingerprint (server response)
JA4L Both Client-to-server latency / distance estimate
JA4LS Both Server-to-client latency / distance estimate
JA4S Proxy TLS ServerHello fingerprint
JA4X Proxy X.509 certificate fingerprint

In proxy mode, Synapse forwards all collected fingerprints to origin servers via X-JA4* headers (enable with proxy.fingerprints.forward: true in the v2 upstreams config — was forward_fingerprints: true under config: in v1).

To stream fingerprint events to your own tooling, use the EventBridge: eventbridge-api.md.

IDS — Intrusion Detection

Network-level intrusion detection via thalamus-ids, available in both modes. Detects attack patterns at the packet level and emits IDS alert events to the Gen0Sec API and EventBridge.

BPF Statistics & Dropped IP Tracking

Real-time kernel-level counters exposed via the terminal TUI and logging:

  • Total packets processed / dropped
  • Per-IP drop counts (tracked in a kernel LRU map)
  • IPv4 and IPv6 ban/recently-banned hit counters
  • TCP fingerprint block counters

Block

eBPF / XDP Firewall

The XDP firewall is the first enforcement layer. It runs in kernel space and makes drop/pass decisions before the packet reaches userspace, giving near-zero latency at high packet rates.

Multi-backend automatic fallback:

XDP/eBPF  →  nftables  →  iptables  →  userland

Synapse selects the highest-capability backend available on the system. If XDP is unavailable (older kernel, unsupported NIC driver), it falls back to nftables, then iptables, then a userland filter — always with the same rule set. What differs at each level is where enforcement happens and which features are available:

XDP nftables iptables Userland
Drop before socket buffer ✅ ❌ ❌ ❌
BPF stats & per-IP counters ✅ ❌ ❌ ❌
Kernel TCP fingerprinting ✅ ❌ ❌ ❌
IDS active blocking ✅ ✅ ✅ ❌
Agent mode enforcement ✅ ✅ ✅ ❌

→ Full backend reference, requirements, diagnostics, and Windows path: FIREWALL.md

Access rules (allow/block lists):

  • Up to 4,194,304 IPv4 and 1,048,576 IPv6 CIDR entries per map
  • Rules stored in a BPF LPM Trie for O(1) longest-prefix-match lookup
  • CIDR coalescing: adjacent and contained prefixes are merged automatically before loading (e.g. 1,000 adjacent /24s → one /14), typically reducing rule count by 30–60%
  • Dynamically updated from the Gen0Sec API on config reload; zero-downtime diff-and-patch
  • Separate allow-list (permit even if in block list) and block-list semantics
  • IPv4 and IPv6 rule sets managed independently

Firewall mode can be forced via config:

firewall:
  mode: "auto"     # auto | xdp | nftables | iptables | none

Threat Intelligence

  • Gen0Sec Smart Lists — automatically updated lists of known bad IPs, ASNs, and CIDRs
  • Threat MMDB — local offline database for IP reputation scoring (auto-refreshed every 5 min)
  • GeoIP MMDB — country, ASN, and city-level geolocation (proxy mode: also used at HTTP level)
  • HTTP-level threat scoring (proxy mode) — threat score applied per request; configurable threshold for blocking, CAPTCHA, or logging
platform:
  threat:
    url: "https://download.gen0sec.com/v1"
    path: "/var/lib/synapse"
    refresh_secs: 300

WAF — Wirefilter Expressions

Expression-based request filtering using the Cloudflare Wirefilter syntax. Available in proxy mode only.

  • Filter by request method, path, headers, body content, JA4+ fingerprints, GeoIP, threat score
  • Actions: block, allow, captcha, log
  • Expressions managed centrally via Gen0Sec API
  • WAF rules hot-reload on config update

Example expressions:

# Block a specific fingerprint
http.ja4 eq "t13d1516h2_8daaf6152771_b186095e22b6"

# Challenge traffic from a high-threat-score country
ip.geoip.country eq "XX" and ip.threat_score > 60

# Block POST without content-type
http.request.method eq "POST" and not http.request.headers["content-type"][*] matches ".*"

Rate Limiting

Per-rule and per-path rate limits, configurable in proxy mode via upstreams config. Limits apply per client IP.

version: 2
hosts:
  example.com:
    tls:
      terminate:
        acme:
          challenge_type: http-01
    paths:
      "/api":
        upstream: backend:8080
        rate_limit: 100   # requests per minute

Global rate limit:

version: 2
proxy:
  global_rate_limit: 500

CAPTCHA Protection

Challenge suspicious requests before allowing them through. Proxy mode only.

Supported providers: hCaptcha, reCAPTCHA, Cloudflare Turnstile

proxy:
  captcha:
    provider: "turnstile"
    site_key: "your-site-key"
    secret_key: "your-secret-key"
    jwt_secret: "your-jwt-secret"
    token_ttl: 7200      # seconds a solved CAPTCHA is valid
    cache_ttl: 300       # seconds to cache verification result

CAPTCHA tokens are cached in Redis to avoid re-challenging the same client on every request.

Inspect (Proxy mode)

TLS Management

  • ACME / Let's Encrypt — automatic certificate provisioning and renewal
    • HTTP-01 challenge (default)
    • DNS-01 challenge (automatic for wildcard domains)
  • Custom certificates — bring your own PEM files
  • HTTPS enforcement — automatic HTTP → HTTPS upgrade
  • Expiry monitoring — automatic renewal; manual trigger via internal API
  • Redis storage — certificates stored in Redis for clustering
proxy:
  acme:
    enabled: true
    email: "admin@example.com"
    storage_type: "redis"   # or "file"
    development: false      # set true to use Let's Encrypt staging

Certificate management endpoints (via internal services server):

GET  /cert/expiration         — all certificates status
GET  /cert/expiration/:domain — specific certificate
POST /cert/renew/:domain      — trigger manual renewal

Content Scanning

Real-time malware detection on request bodies using ClamAV.

  • Scans multipart/form-data uploads and POST/PUT bodies
  • Configurable file size limit
  • Wirefilter expression to define when to scan
  • Skip specific file extensions
proxy:
  content_scanning:
    enabled: true
    clamav_server: "localhost:3310"
    max_file_size: 10485760   # 10 MB
    scan_expression: 'http.request.method eq "POST"'
    skip_extensions: [".jpg", ".png", ".gif"]

Upstreams & Load Balancing

Forward requests to backends with weighted load balancing and service discovery.

  • Providers: file, Consul, Kubernetes
  • Schema: v2 (recommended) or v1 (legacy) — auto-detected by version: field
  • TLS modes (v2): terminate with static cert, terminate with ACME, or passthrough (raw TCP routing by SNI, no L7)
  • Wildcard SNI passthrough (v2): route *.internal.example.com to a backend without terminating TLS
  • LB methods: round_robin, random, least_request, weighted_round_robin, consistent
  • Health checks (v2): TCP or HTTP, with consecutive-failure / consecutive-success thresholds
  • Layered config (v2): headers and timeouts merge global → host → route
  • Single-upstream sugar (v2): upstream: host:port for the common case
  • Hot-reload — update upstreams.yaml without restarting
  • Per-path config — different upstreams, rate limits, headers, timeouts per URL path
  • Sticky sessions — consistent hashing for session affinity
  • JA4+ header forwarding — pass fingerprints to origin via X-JA4* headers

See ../config/upstreams.yaml for a full v2 configuration example with commented stanzas covering each capability.

Observe

Terminal TUI

Real-time ratatui dashboard showing live fingerprints, traffic, threats, and blocking events. Works in both modes.

# Embedded (runs inside the synapse process)
synapse -c config.yaml --terminal

# Standalone (connects to a running synapse via EventBridge socket)
synapse --mode terminal --socket /var/run/synapse-events.sock

EventBridge

Stream JA4+ fingerprint events and connection metadata to your SIEM, custom tooling, or the synapse-tui TUI client over a Unix socket (Linux/macOS) or TCP (Windows).

Event socket (streaming):
  Linux/macOS: /var/run/synapse-events.sock
  Windows:     127.0.0.1:19199

Control socket (query-response):
  Linux/macOS: /var/run/synapse-control.sock
  Windows:     127.0.0.1:19198

Event types: PacketEvent (TCP/TLS fingerprint + GeoIP + threat score + blocking decision), HttpEvent (HTTP-level fingerprint + WAF result).

The control socket provides a POST /query HTTP API — send {"src_ip":"…","src_port":N} and get back a FingerprintQueryResult with all JA4+ fingerprints captured for that connection. Results are cached for 10 minutes. On Linux query the socket directly from application middleware; on Windows use TCP (127.0.0.1:19198).

Full API: eventbridge-api.md

Logging

Backend Platform Config
Rotating file (error.log, app.log, access.log) All logging.file_logging_enabled: true
Syslog Linux logging.syslog.enabled: true
ETW (Event Tracing for Windows) Windows logging.etw.enabled: true

Log files are automatically rotated and gzip-compressed. Default location: /var/log/synapse/.