Configuration Reference

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

1. Command Line Arguments - override specific settings via CLI flags
2. Environment Variables - e.g. export API_KEY="your-key"
3. YAML Configuration File - via config.yaml

:::warning Environment variable prefix The AX_ (and AX_ARXIGNIS_) environment-variable prefix is deprecated. Use the unprefixed variable names (e.g. API_KEY, not AX_API_KEY). The old prefixes still work but log a deprecation warning and will be removed in a future release. :::

Operating Modes

mode: "agent"  # or "proxy"

• agent (default) - Access rules, fingerprinting, IDS, and monitoring only. The reverse proxy (pingora) is disabled.
• proxy - Full reverse proxy functionality plus everything in agent mode.

Terminal Mode (TUI)

Synapse ships a real-time ratatui terminal UI that displays live JA4+ fingerprints, traffic, and threat data. Works on Linux and Windows.

# Embedded: TUI runs in the same process as the agent/proxy
synapse --mode agent --terminal

# Standalone: attach to a running daemon over its unix socket (Linux only)
synapse --terminal

YAML Configuration

Basic Example

mode: "agent"

network:
  iface: "auto"          # auto-attach physical uplinks only
  ip_version: "auto"     # processes both IPv4 and IPv6

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

platform:
  api_key: "your-api-key"
  base_url: "https://api.gen0sec.com/v1"
  telemetry_sending_enabled: true

logging:
  level: "info"

Feature Toggles

Feature	YAML Path	Environment Variable	Default
Packet Capture	capture.enabled	CAPTURE_MODE	true
Inline IDS (Thalamus)	ids.enabled	—	true
ML Classifier	classifier.enabled	—	false
Threat Intelligence	platform.threat.enabled	—	true
GeoIP	platform.geoip.enabled	—	true
Telemetry Sending (API)	platform.telemetry_sending_enabled	LOG_SENDING_ENABLED	true
Unified Fingerprint Log	logging.fingerprint_log.enabled	—	true
File Logging	logging.file_logging_enabled	LOGGING_FILE_ENABLED	true
Syslog (Linux)	logging.syslog.enabled	LOGGING_SYSLOG_ENABLED	false
ETW (Windows)	logging.etw.enabled	LOGGING_ETW_ENABLED	false
Windows Event Log	logging.windows_event_log.enabled	LOGGING_WINDOWS_EVENT_LOG_ENABLED	false
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	true
Internal Services	proxy.internal_services.enabled	INTERNAL_SERVICES_ENABLED	true
PROXY Protocol	proxy.protocol.enabled	PROXY_PROTOCOL_ENABLED	false
HTTP/2 cleartext (h2c)	proxy.h2c	—	true

:::info telemetry_sending_enabled (renamed) The platform log/telemetry toggle is now platform.telemetry_sending_enabled (formerly log_sending_enabled). Its environment override remains LOG_SENDING_ENABLED. :::

Core Sections

Network

network:
  # "auto" attaches XDP ONLY to physical UP uplink interfaces. Loopback and
  # CNI/virtual/tunnel devices (veth*, lxc*, cilium*, docker*, bridges,
  # vxlan/tunnels, etc.) are excluded, so it never clobbers a CNI datapath
  # (e.g. Cilium) on Kubernetes nodes. bond*/VLAN uplinks (eth0.100) are kept.
  iface: "auto"

  # Explicit list overrides `iface`; entries are attached as-is (bypasses the
  # "auto" filtering above — use this to opt in to a virtual interface).
  ifaces: []

  # "auto" (default) processes both IPv4 and IPv6.
  ip_version: "auto"

Packet Capture

Controls the backend used for JA4+ fingerprint packet capture.

capture:
  enabled: true

  # Backend:
  #   auto            — Auto-detect: XDP > af_packet_recv > pfring (default)
  #   xdp             — eBPF/XDP BPF map polling (highest performance)
  #   af_packet       — AF_PACKET TPACKET_V3 mmap ring buffer (zero-copy)
  #   af_packet_recv  — AF_PACKET plain recvfrom() (works on all kernels,
  #                      including 4.19 where TPACKET_V3 poll() is broken)
  #   pfring          — PF_RING zero-copy (requires pf_ring.ko + libpfring,
  #                      build with --features pfring-capture)
  mode: auto

  # interface: auto      # "auto" = all interfaces; or a specific iface
  snaplen: 65535         # max bytes per packet (af_packet/af_packet_recv/pfring)
  filter: "tcp"          # tcpdump-syntax BPF filter (af_packet, pfring)

  af_packet:             # only used when mode: af_packet
    block_size: 4194304  # ring block size (power of 2, default 4MB)
    block_count: 4       # number of blocks; total ring = block_size * block_count
    block_timeout_ms: 100
    promiscuous: true

  pfring:                # only used when mode: pfring
    zero_copy: true
    # cluster_id: 1      # multi-queue NIC load balancing (optional)

Environment overrides: CAPTURE_MODE, CAPTURE_SNAPLEN, CAPTURE_FILTER, PFRING_ZERO_COPY, PFRING_CLUSTER_ID.

Firewall

firewall:
  # auto: XDP > nftables > iptables > none
  # xdp / nftables / iptables: force a backend
  # none: disable kernel firewall, userland enforcement only
  mode: "auto"

Inline IDS (Thalamus)

Synapse embeds the Thalamus IDS engine for inline, signature-based detection on captured traffic.

ids:
  enabled: true
  capture_mode: xdp
  rule_paths:
    - "/etc/synapse/rules/*.rules"
  address_vars: {}            # Suricata-style address variable definitions
  port_vars: {}               # Suricata-style port variable definitions
  snaplen: 512
  poll_timeout_ms: 100
  flow_timeout_secs: 120
  max_flows: 200000
  cleanup_interval_secs: 30
  stats_log_interval_secs: 5
  enforce_block: true         # drop matching flows (false = alert only)

:::note Rule loading Thalamus loads one rule per line — there is no \ line-continuation. A rule split across multiple lines silently loads as zero rules. Validate offline before deploying. :::

ML Classifier

Optional ONNX-based JA4+ fingerprint classification (ships with the -ml package variant).

classifier:
  enabled: false
  model_path: ""        # path to the ONNX model file
  cache_size: 10000     # max cached predictions (0 = no cache)
  threshold: 0.5        # malicious probability threshold (0.0–1.0)

Platform

platform:
  api_key: ""
  base_url: "https://api.gen0sec.com/v1"

  # Send access logs / telemetry to the platform (formerly log_sending_enabled)
  telemetry_sending_enabled: true

  # WARNING: may capture PII, tokens, or API responses in logs
  include_response_body: false
  max_body_size: 1048576   # bytes; do not raise above the Basic plan maximum

  # Threat intelligence MMDB
  threat:
    enabled: true
    url: "https://download.gen0sec.com/v1"
    path: "/var/lib/synapse"
    headers: null
    refresh_secs: 300        # 5 minutes

  # GeoIP MMDB — ships with the IPinfo Lite bundle (single combined DB with
  # both country + ASN). Synapse auto-detects the IPinfo schema, so the DB
  # configured under `country` serves both country and ASN lookups; `asn`
  # and `city` are unused and their refresh workers don't run.
  geoip:
    enabled: true
    country:
      url: "https://github.com/gen0sec/geoip-databases/raw/download/ipinfo_lite.mmdb"
      path: "/var/lib/synapse/ipinfo_lite.mmdb"
      headers: null
    asn:   { url: "", path: "", headers: null }   # unused with IPinfo Lite
    city:  { url: "", path: "", headers: null }   # unused with IPinfo Lite
    refresh_secs: 28800       # 8 hours

:::info GeoIP changed to IPinfo Lite Synapse now defaults to a single combined IPinfo Lite database (ipinfo_lite.mmdb) instead of the split MaxMind GeoLite2 country/ASN/city files. To switch back to GeoLite2, point country/asn at the respective GeoLite2-*.mmdb URLs. :::

Logging

logging:
  level: "info"                       # error, warn, info, debug, trace
  file_logging_enabled: true
  log_directory: "/var/log/synapse"   # Windows: C:\ProgramData\Gen0Sec\Synapse\logs
  max_log_size: 104857600             # 100MB
  log_file_count: 10                  # rotated files are gzip-compressed

  # Syslog (Linux/Unix only; ignored on Windows)
  syslog:
    enabled: false
    facility: "daemon"
    identifier: "synapse"
    levels:                           # per-log-type priority
      error: "err"
      app: "info"
      access: "info"                  # proxy mode only

  # Event Tracing for Windows — Windows equivalent of syslog.
  # Events emit to ETW provider "Gen0Sec.Synapse".
  etw:
    enabled: false

  # Classic Windows Event Log (Event Viewer → Windows Logs → Application)
  windows_event_log:
    enabled: false
    source: "Synapse"

  # Unified per-connection fingerprint/BPF event log (agent mode).
  fingerprint_log:
    enabled: true
    # file: /var/log/synapse/fingerprints.log   # default: {log_directory}/fingerprints.log

:::warning Per-type fingerprint logging is deprecated The six per-type sections — bpf_stats, tcp_fingerprint, ssh_fingerprint, latency_fingerprint, tls_fingerprint, and http_fingerprint — are superseded by fingerprint_log (a.k.a. eventbridge_log), which emits every fingerprint/BPF event through one unified JSON log. They now ship disabled and will be removed in a future release. Use fingerprint_log. :::

When file_logging_enabled is true, Synapse writes (and rotates/compresses) error.log, app.log, and — in proxy mode — access.log (JSON).

Daemon / Service

Linux runs as a Unix daemon; Windows registers with the Service Control Manager (synapse --service install / sc start synapse; sc control synapse paramchange triggers a config reload).

daemon:
  enabled: true
  pid_file: "/var/run/synapse.pid"          # Linux only
  working_directory: "/var/lib/synapse"
  user: root                                 # Linux only
  group: root                                # Linux only
  chown_pid_file: true                       # Linux only

  # Sockets used by standalone terminal clients
  # event_socket:   "/var/run/synapse-events.sock"   # Windows: TCP, e.g. 127.0.0.1:19199
  # control_socket: "/var/run/synapse-control.sock"

Proxy (proxy mode)

proxy:
  address_http: "0.0.0.0:80"
  address_tls: "0.0.0.0:443"
  certificates: "/etc/synapse/certs"     # cert files: {NAME}.crt, {NAME}.key
  tls_grade: "medium"                    # high, medium, unsafe
  default_certificate: "default"         # fallback cert (file stem)

  # Enable HTTP/2 cleartext on the plaintext listener (gRPC over plaintext,
  # --http2-prior-knowledge clients).
  h2c: true

  # Allow proxying HTTP CONNECT (tunneling/WebSocket upgrades). When false,
  # CONNECT is rejected with 405.
  allow_connect_method_proxying: false

  # Max requests per connection before closing (frees per-connection memory).
  # null = no limit (default).
  keepalive_request_limit: null

  redis:
    url: "redis://127.0.0.1:6379/0"
    prefix: "g0s:synapse"
    # ssl:
    #   ca_cert_path: "/path/to/ca.crt"
    #   client_cert_path: "/path/to/client.crt"   # optional, mutual TLS
    #   client_key_path: "/path/to/client.key"    # optional, mutual TLS
    #   insecure: false

  upstream:
    conf: "/etc/synapse/upstreams.yaml"
    healthcheck:
      method: "HEAD"     # HEAD, GET, POST
      interval: 2        # seconds

  protocol:
    enabled: true
    timeout_ms: 1000

  captcha:
    site_key: null
    secret_key: null
    jwt_secret: null     # openssl rand -base64 48
    provider: "hcaptcha" # hcaptcha, recaptcha, turnstile, prosopo
    token_ttl: 7200
    cache_ttl: 300

  acme:
    enabled: true
    port: 9180           # binds to 127.0.0.1 only
    email: null
    storage_type: null   # "file" or "redis" (defaults by whether redis is set)
    storage_path: "/var/lib/synapse/acme"
    development: false    # true = Let's Encrypt staging
    redis_url: null       # overrides global redis.url for ACME storage

  content_scanning:
    enabled: false
    clamav_server: "localhost:3310"
    max_file_size: 10485760    # 10MB
    scan_content_types:
      - "text/html"
      - "application/x-www-form-urlencoded"
      - "multipart/form-data"
      - "application/json"
      - "text/plain"
    skip_extensions: []
    # Wirefilter expression deciding when to scan (default: POST/PUT)
    scan_expression: "http.request.method eq \"POST\" or http.request.method eq \"PUT\""

  internal_services:
    enabled: true        # auto-disabled in agent mode
    port: 9180
    bind_ip: "127.0.0.1"

Environment Variables

# Application mode & runtime
export MODE="agent"                       # or "proxy"
export MULTI_THREAD="false"               # enable multi-threaded runtime
export WORKER_THREADS="4"                 # worker threads when MULTI_THREAD=true

# Redis
export REDIS_URL="redis://127.0.0.1:6379/0"
export REDIS_PREFIX="g0s:synapse"
export REDIS_SSL_CA_CERT_PATH="..."
export REDIS_SSL_CLIENT_CERT_PATH="..."
export REDIS_SSL_CLIENT_KEY_PATH="..."
export REDIS_SSL_INSECURE="false"

# Network & capture
export NETWORK_IFACE="auto"
export NETWORK_IFACES="eth0,eth1"
export NETWORK_IP_VERSION="auto"
export CAPTURE_MODE="auto"                # xdp, af_packet, af_packet_recv, pfring
export CAPTURE_SNAPLEN="65535"
export CAPTURE_FILTER="tcp"
export PFRING_ZERO_COPY="true"
export PFRING_CLUSTER_ID="1"
export FIREWALL_MODE="auto"

# Gen0Sec Platform
export API_KEY="your-api-key"
export BASE_URL="https://api.gen0sec.com/v1"
export LOG_SENDING_ENABLED="true"         # platform.telemetry_sending_enabled

# Logging
export LOGGING_LEVEL="info"
export LOGGING_FILE_ENABLED="true"
export LOGGING_DIRECTORY="/var/log/synapse"
export LOGGING_MAX_FILE_SIZE="104857600"
export LOGGING_FILE_COUNT="10"
export LOGGING_SYSLOG_ENABLED="false"     # Linux
export LOGGING_SYSLOG_FACILITY="daemon"
export LOGGING_SYSLOG_IDENTIFIER="synapse"
export LOGGING_ETW_ENABLED="false"        # Windows
export LOGGING_WINDOWS_EVENT_LOG_ENABLED="false"   # Windows
export LOGGING_WINDOWS_EVENT_LOG_SOURCE="Synapse"

# Content scanning
export CONTENT_SCANNING_ENABLED="true"
export CLAMAV_SERVER="localhost:3310"
export CONTENT_MAX_FILE_SIZE="10485760"
export CONTENT_SCAN_CONTENT_TYPES="application/json,multipart/form-data"
export CONTENT_SKIP_EXTENSIONS="jpg,png"
export CONTENT_SCAN_EXPRESSION='http.request.method eq "POST"'

# CAPTCHA
export CAPTCHA_SITE_KEY="your-site-key"
export CAPTCHA_SECRET_KEY="your-secret-key"
export CAPTCHA_JWT_SECRET="your-jwt-secret"
export CAPTCHA_PROVIDER="hcaptcha"        # hcaptcha, recaptcha, turnstile, prosopo
export CAPTCHA_TOKEN_TTL="7200"
export CAPTCHA_CACHE_TTL="300"

# Internal services & PROXY protocol
export INTERNAL_SERVICES_ENABLED="true"
export INTERNAL_SERVICES_PORT="9180"
export INTERNAL_SERVICES_BIND_IP="127.0.0.1"
export PROXY_PROTOCOL_ENABLED="true"
export PROXY_PROTOCOL_TIMEOUT="1000"

# Daemon
export DAEMON_ENABLED="true"
export DAEMON_PID_FILE="/var/run/synapse.pid"
export DAEMON_WORKING_DIRECTORY="/var/lib/synapse"
export DAEMON_USER="root"
export DAEMON_GROUP="root"
export DAEMON_CHOWN_PID_FILE="true"

Upstreams Configuration

Synapse supports advanced upstream routing via a separate configuration file with hot-reloading. Supports multiple service discovery providers: file, Consul, and Kubernetes.

File Provider

provider: "file"
config:
  https_proxy_enabled: false
  sticky_sessions: true
  global_rate_limit: 100
  global_request_headers:
    - "X-Proxy-From:Synapse"
  global_response_headers:
    - "Access-Control-Allow-Origin:*"

internal_paths:
  "/cgi-bin/captcha/verify":
    rate_limit: 200
    servers:
      - "127.0.0.1:9180"

upstreams:
  example.com:
    certificate: "example.com"
    acme:
      challenge_type: "dns-01"  # or "http-01" (default)
      email: "[email protected]"
      wildcard: true
    paths:
      "/":
        rate_limit: 200
        force_https: true
        ssl_enabled: true
        request_headers:
          - "Host: api.example.com"
        connection_timeout: 30
        read_timeout: 120
        write_timeout: 30
        idle_timeout: 60
        servers:
          - "127.0.0.1:8000"
          - address: "127.0.0.1:8001"
            weight: 3
          - address: "127.0.0.1:8002"
            weight: 2

Kubernetes Provider

provider: "kubernetes"
config:
  sticky_sessions: true
  global_rate_limit: 300

kubernetes:
  servers:
    - "https://k8s-api.example.com:6443"
  tokenpath: "/var/run/secrets/kubernetes.io/serviceaccount/token"
  services:
    - upstream: "http://my-service.default.svc.cluster.local:8080"
      hostname: "api.example.com"
      path: "/"
      rate_limit: 500

Consul Provider

provider: "consul"
config:
  sticky_sessions: true
  global_rate_limit: 200

consul:
  servers:
    - "consul1.example.com:8500"
    - "consul2.example.com:8500"
  token: "your-consul-token"
  services:
    - upstream: "http://service-name.service.consul:8080"
      hostname: "api.example.com"
      path: "/"
      rate_limit: 500

SIGHUP Configuration Reload

Synapse supports runtime configuration reload via SIGHUP signal (Windows: sc control synapse paramchange):

kill -HUP $(cat /var/run/synapse.pid)

Hot-reloadable Settings

Setting	Config Path	Notes
Log level	logging.level	Switches log verbosity instantly
Telemetry sending	platform.telemetry_sending_enabled	Enable/disable API log sending
API key	platform.api_key	Update platform credentials
Base URL	platform.base_url	Change API endpoint
Include response body	platform.include_response_body	Toggle body capture in access logs
Max body size	platform.max_body_size	Adjust body size limit for logs
Upstreams	proxy.upstream.conf	Re-reads upstreams YAML file
Security rules	Local file or API	Re-fetches access rules, WAF rules, and IDS rules
Threat / GeoIP MMDBs	platform.threat.*, platform.geoip.*	Re-downloads MMDB files

Settings That Require Restart

Setting	Config Path	Reason
Listen addresses	proxy.address_http, proxy.address_tls	Port bindings set at startup
Network interface	network.iface, network.ifaces	XDP attached at startup
Firewall mode	firewall.mode	BPF programs loaded at startup
Capture backend	capture.*	Capture ring/sockets set up at startup
Inline IDS	ids.* (except rule files)	Engine/capture initialized at startup
Classifier	classifier.*	ONNX model loaded at startup
Runtime threads	multi_thread, worker_threads	Tokio runtime created at startup
Daemon settings	daemon.*	Process daemonization is one-time
Redis connection	proxy.redis.*	Connection pool created at startup
CAPTCHA config	proxy.captcha.*	Provider initialized once
Content scanning	proxy.content_scanning.*	Scanner initialized once
Certificate paths	proxy.certificates	Loaded at startup
ACME settings	proxy.acme.*	ACME manager created at startup
Internal services	proxy.internal_services.*	Server bound at startup
Fingerprint log	logging.fingerprint_log.*	Appender built at startup
File / syslog / Windows logging	logging.file_logging_enabled, logging.syslog.*, logging.etw.*, logging.windows_event_log.*	Appenders built at startup
IP version	network.ip_version	BPF filter compiled at startup
PROXY protocol	proxy.protocol.*	Listener configured at startup

Internal Services Endpoints

When proxy.internal_services.enabled is true, the following endpoints are available:

Endpoint	Method	Purpose
/health	GET	Health check
/cgi-bin/captcha/verify	POST	CAPTCHA verification
/.well-known/acme-challenge/*	GET	ACME HTTP-01 challenges
/cert/expiration	GET	Check all certificate expiration status
/cert/expiration/:domain	GET	Check specific certificate status
/cert/renew/:domain	POST	Manually trigger certificate renewal

Next Steps

• Daemon Mode - Run as a background service
• JA4+ Fingerprinting - Complete fingerprinting suite
• Testing Guide - Validate your configuration