{"id":34246507,"url":"https://github.com/gen0sec/synapse","last_synced_at":"2026-02-17T13:11:49.928Z","repository":{"id":318771462,"uuid":"1067776336","full_name":"gen0sec/synapse","owner":"gen0sec","description":"XDR with eBPF-powered firewall and proxy. Protect your Linux servers.","archived":false,"fork":false,"pushed_at":"2026-02-13T11:51:53.000Z","size":12183,"stargazers_count":76,"open_issues_count":15,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-13T20:35:19.101Z","etag":null,"topics":["access-rules","adr","arxignis","ebpf","firewall","gen0sec","ja3-fingerprint","ja4","ja4-fingerprint","ja4h","ja4t","rate-limiting","runtime","ssl-fingerprint","threat-intelligence","waf","webserver","xdr"],"latest_commit_sha":null,"homepage":"https://gen0sec.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gen0sec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T11:25:27.000Z","updated_at":"2026-02-12T05:52:37.000Z","dependencies_parsed_at":"2025-10-15T13:50:26.542Z","dependency_job_id":"c6054bdb-86ea-4007-be07-78ee1e4c121c","html_url":"https://github.com/gen0sec/synapse","commit_stats":null,"previous_names":["arxignis/moat","gen0sec/synapse"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/gen0sec/synapse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gen0sec%2Fsynapse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gen0sec%2Fsynapse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gen0sec%2Fsynapse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gen0sec%2Fsynapse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gen0sec","download_url":"https://codeload.github.com/gen0sec/synapse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gen0sec%2Fsynapse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29545322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T13:00:00.370Z","status":"ssl_error","status_checked_at":"2026-02-17T12:57:14.072Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-rules","adr","arxignis","ebpf","firewall","gen0sec","ja3-fingerprint","ja4","ja4-fingerprint","ja4h","ja4t","rate-limiting","runtime","ssl-fingerprint","threat-intelligence","waf","webserver","xdr"],"created_at":"2025-12-16T07:08:16.494Z","updated_at":"2026-02-17T13:11:49.920Z","avatar_url":"https://github.com/gen0sec.png","language":"Rust","funding_links":[],"categories":["Projects Related to eBPF"],"sub_categories":["Security"],"readme":"![Gen0Sec logo](./images/logo.svg)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gen0sec/synapse/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-ELv2-green\" alt=\"License - Elastic 2.0\"\u003e\u003c/a\u003e \u0026nbsp;\n  \u003ca href=\"https://github.com/gen0sec/synapse/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/gen0sec/synapse.svg?label=Release\" alt=\"Release\"\u003e\u003c/a\u003e \u0026nbsp;\n  \u003cimg alt=\"GitHub Downloads (all assets, all releases)\" src=\"https://img.shields.io/github/downloads/gen0sec/synapse/total\"\u003e \u0026nbsp;\n  \u003ca href=\"https://docs.gen0sec.com/\"\u003e\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/gen0sec-documentation-page?style=flat\u0026link=https%3A%2F%2Fdocs.gen0sec.com%2F\"\u003e\u003c/a\u003e \u0026nbsp;\n  \u003ca href=\"https://discord.gg/jzsW5Q6s9q\"\u003e\u003cimg src=\"https://img.shields.io/discord/1377189913849757726?label=Discord\" alt=\"Discord\"\u003e\u003c/a\u003e \u0026nbsp;\n  \u003ca href=\"https://x.com/gen0sec\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/gen0sec?style=flat\" alt=\"X (formerly Twitter) Follow\" /\u003e \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/jzsW5Q6s9q\"\u003e\u003cimg src=\"https://img.shields.io/badge/Join%20Us%20on-Discord-5865F2?logo=discord\u0026logoColor=white\" alt=\"Join us on Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://arxignis.substack.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Substack-FF6719?logo=substack\u0026logoColor=fff\" alt=\"Substack\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Overview\n\nSynapse is a high-performance reverse proxy and firewall built with Rust, featuring:\n\n- **XDP-based packet filtering** for ultra-low latency protection at kernel level\n- **Multi-backend firewall** with automatic fallback (XDP \u003e nftables \u003e iptables \u003e userland)\n- **Dynamic access rules** with automatic updates from Gen0Sec API\n- **JA4+ fingerprinting** complete suite: JA4, JA4H, JA4T, JA4L, JA4S, JA4X\n- **Automatic TLS certificate management** with ACME/Let's Encrypt (HTTP-01 and DNS-01)\n- **Threat intelligence integration** with Gen0Sec API and Threat MMDB\n- **Content scanning** with ClamAV integration for malware detection\n- **Advanced upstream routing** with service discovery (file, Consul, Kubernetes)\n- **Weighted load balancing** with hot-reloadable configuration\n\n\u003e **Linux only.** Requires kernel 4.18+ with XDP/BPF support.\n\n## Quick Start\n\n```bash\n# Ubuntu install\ncurl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh\n```\n\n```bash\n# Run with config file\nsynapse -c /etc/synapse/config.yaml\n\n# Set mode via environment variable (default: agent)\nexport MODE=\"proxy\"  # or \"agent\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore installation methods\u003c/strong\u003e\u003c/summary\u003e\n\n### Ansible\n\n```bash\ngit clone https://github.com/gen0sec/synapse.git\ncd synapse/moat/ansible\ncp hosts.example hosts\n# Edit hosts and add your server details\nansible-playbook playbook.yml -e gen0sec_api_token=your_key_here\n```\n\nFeatures: Debian/Ubuntu + RedHat/CentOS/Fedora, optional ClamAV/Redis/Fail2Ban. [More details.](./ansible/README.md)\n\n### Kubernetes\n\n```bash\nhelm repo add gen0sec https://helm.gen0sec.com\nhelm install synapse-stack\n```\n\n[More details.](./docs/OPERATOR_README.md)\n\n### Killercoda Playground\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key \u003cYOUR_API_KEY\u003e\n```\n\n### Docker\n\n```bash\n# Required capabilities\n--cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN\n```\n\n\u003c/details\u003e\n\n## Modes\n\nSynapse runs in two modes: **Agent** (default) and **Proxy**.\n\n| Feature | Proxy | Agent |\n|---------|:-----:|:-----:|\n| **HTTP/HTTPS Reverse Proxy** | ✅ | ❌ |\n| **TLS \u0026 ACME Certificates** | ✅ | ❌ |\n| **Upstreams \u0026 Load Balancing** | ✅ | ❌ |\n| **WAF, Rate Limiting, CAPTCHA** | ✅ | ❌ |\n| **Content Scanning (ClamAV)** | ✅ | ❌ |\n| **XDP Firewall \u0026 Access Rules** | ✅ | ✅ |\n| **Threat Intelligence \u0026 GeoIP** | ✅ | ✅ |\n| **JA4+ Fingerprinting** | ✅ Full | ✅ Network-level |\n| **BPF Stats \u0026 TCP Fingerprinting** | ✅ | ✅ |\n| **File/Syslog Logging** | ✅ | ✅ |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDetailed feature comparison\u003c/strong\u003e\u003c/summary\u003e\n\n| Feature | Proxy Mode | Agent Mode |\n|---------|-------------------|------------|\n| **HTTP/HTTPS Reverse Proxy** | ✅ Full support | ❌ Not available |\n| **TLS Certificate Management** | ✅ ACME \u0026 custom certificates | ❌ Not available |\n| **Upstreams \u0026 Load Balancing** | ✅ File, Consul, Kubernetes | ❌ Not available |\n| **Hot-reloadable Upstreams** | ✅ Zero-downtime updates | ❌ Not available |\n| **XDP Packet Filtering** | ✅ Kernel-level filtering | ✅ Kernel-level filtering |\n| **Multi-Backend Firewall** | ✅ XDP/nftables/iptables/userland | ✅ XDP/nftables/iptables/userland |\n| **Access Rules Enforcement** | ✅ IP allow/block lists | ✅ IP allow/block lists |\n| **Dynamic Access Rules** | ✅ Auto-updates from Gen0Sec API | ✅ Auto-updates from Gen0Sec API |\n| **BPF Statistics Collection** | ✅ Packet processing metrics (XDP only) | ✅ Packet processing metrics (XDP only) |\n| **TCP Fingerprinting** | ✅ SYN packet analysis | ✅ SYN packet analysis |\n| **JA4+ Fingerprinting** | ✅ JA4, JA4H, JA4T, JA4L, JA4S, JA4X | ✅ JA4T, JA4L (network-level) |\n| **Wirefilter Expressions (WAF)** | ✅ Advanced request filtering | ❌ Not available |\n| **Rate Limiting** | ✅ Per-rule rate limits | ❌ Not available |\n| **Content Scanning (ClamAV)** | ✅ Malware detection | ❌ Not available |\n| **CAPTCHA Protection** | ✅ hCaptcha, reCAPTCHA, Turnstile | ❌ Not available |\n| **Threat Intelligence** | ✅ Real-time MMDB + HTTP-level | ✅ Smart Lists (network-level) |\n| **GeoIP Databases** | ✅ Country, ASN, City lookups | ⚠️ Via Smart Lists only |\n| **Internal Services Server** | ✅ ACME, CAPTCHA endpoints | ❌ Not available |\n| **Redis Caching** | ✅ Certificates, threat intel, validation | ❌ Not available |\n| **Access Log Sending** | ✅ To Gen0Sec API | ❌ Not available |\n| **File/Syslog Logging** | ✅ Rotating logs | ✅ Rotating logs |\n| **Multiple Network Interfaces** | ✅ High availability setups | ✅ High availability setups |\n| **Multi-threaded Runtime** | ✅ Default | ⚠️ Single-threaded default |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAgent mode (default)\u003c/strong\u003e\u003c/summary\u003e\n\nStandalone agent focused on access rules enforcement without HTTP/HTTPS proxy. Ideal for network-level protection where you don't need request proxying.\n\n```yaml\nmode: \"agent\"  # default, can be omitted\n```\n\n```bash\n# Set via environment variable\nexport MODE=\"agent\"\n```\n\nUse cases:\n- Network-level firewall protection without proxying\n- Access rules enforcement at the edge\n- Kernel-level IP blocking without HTTP overhead\n- Integration with existing reverse proxies or load balancers\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProxy mode\u003c/strong\u003e\u003c/summary\u003e\n\nFull-featured reverse proxy with HTTP/HTTPS support, forwarding requests to upstream servers while applying access rules and threat intelligence at the kernel level.\n\n```yaml\nmode: \"proxy\"\n\nproxy:\n  address_http: \"0.0.0.0:80\"\n  address_tls: \"0.0.0.0:443\"\n  upstream:\n    conf: \"/etc/synapse/upstreams.yaml\"\n```\n\n```bash\n# Set via environment variable\nexport MODE=\"proxy\"\n```\n\n\u003c/details\u003e\n\n## Configuration\n\nSynapse supports three configuration methods (highest to lowest priority):\n\n1. **YAML Configuration File** - via `config.yaml` ([example](./config_example.yaml))\n2. **Command Line Arguments** - override specific settings via CLI flags\n3. **Environment Variables** - `export API_KEY=\"your-key\"`\n\n### CLI Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-c`, `--config \u003cPATH\u003e` | Path to configuration file (YAML) | - |\n| `--security-rules-config \u003cPATH\u003e` | Security rules file (fallback without API key) | `security_rules.yaml` |\n| `-i`, `--iface \u003cNAME\u003e` | Network interface for XDP | `eth0` |\n| `--ifaces \u003cLIST\u003e` | Additional interfaces (comma-separated, overrides `--iface`) | - |\n| `--log-level \u003cLEVEL\u003e` | Log level (error, warn, info, debug, trace) | `info` |\n| `--disable-xdp` | Disable XDP packet filtering | `false` |\n| `--redis-url \u003cURL\u003e` | Redis connection URL | `redis://127.0.0.1/0` |\n| `--redis-prefix \u003cPREFIX\u003e` | Redis namespace prefix | `ax:synapse` |\n| `--captcha-site-key \u003cKEY\u003e` | CAPTCHA site key | - |\n| `--captcha-secret-key \u003cKEY\u003e` | CAPTCHA secret key | - |\n| `--captcha-jwt-secret \u003cKEY\u003e` | JWT secret for CAPTCHA tokens | - |\n| `--captcha-provider \u003cPROVIDER\u003e` | CAPTCHA provider (hcaptcha, recaptcha, turnstile) | - |\n| `--captcha-token-ttl \u003cSECS\u003e` | CAPTCHA token TTL | `7200` |\n| `--captcha-cache-ttl \u003cSECS\u003e` | CAPTCHA cache TTL | `300` |\n| `--proxy-protocol-enabled` | Enable PROXY protocol | `false` |\n| `--proxy-protocol-timeout \u003cMS\u003e` | PROXY protocol timeout | `1000` |\n| `-d`, `--daemon` | Run as daemon | `false` |\n| `--daemon-pid-file \u003cPATH\u003e` | PID file path | `/var/run/synapse.pid` |\n| `--daemon-working-dir \u003cPATH\u003e` | Daemon working directory | `/` |\n| `--daemon-stdout \u003cPATH\u003e` | Daemon stdout log | `/var/log/synapse.out` |\n| `--daemon-stderr \u003cPATH\u003e` | Daemon stderr log | `/var/log/synapse.err` |\n| `--daemon-user \u003cUSER\u003e` | Run daemon as user | - |\n| `--daemon-group \u003cGROUP\u003e` | Run daemon as group | - |\n| `--clear-certificate \u003cDOMAIN\u003e` | Clear certificate from filesystem and Redis | - |\n\n### Feature Toggles\n\n| Feature | YAML Path | Environment Variable | Default |\n|---------|-----------|---------------------|---------|\n| **BPF Statistics** | `logging.bpf_stats.enabled` | `BPF_STATS_ENABLED` | `true` |\n| **TCP Fingerprinting** | `logging.tcp_fingerprint.enabled` | `TCP_FINGERPRINT_ENABLED` | `true` |\n| **Content Scanning** | `proxy.content_scanning.enabled` | `CONTENT_SCANNING_ENABLED` | `false` |\n| **CAPTCHA Protection** | (enabled when keys are set) | `CAPTCHA_SITE_KEY`, `CAPTCHA_SECRET_KEY` | disabled |\n| **ACME (Auto TLS)** | `proxy.acme.enabled` | `ACME_ENABLED` | `false` |\n| **Internal Services** | `proxy.internal_services.enabled` | `INTERNAL_SERVICES_ENABLED` | `true` |\n| **PROXY Protocol** | `proxy.protocol.enabled` | `PROXY_PROTOCOL_ENABLED` | `false` |\n| **File Logging** | `logging.file_logging_enabled` | `LOGGING_FILE_ENABLED` | `false` |\n| **Syslog** | `logging.syslog.enabled` | `LOGGING_SYSLOG_ENABLED` | `false` |\n| **Log Sending (API)** | `platform.log_sending_enabled` | `LOG_SENDING_ENABLED` | `true` |\n| **XDP Firewall** | `firewall.disable_xdp` | `FIREWALL_DISABLE_XDP` | `false` (XDP enabled) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEnvironment variables reference\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Application mode\nexport MODE=\"proxy\"  # or \"agent\"\n\n# Redis configuration\nexport REDIS_URL=\"redis://127.0.0.1/0\"\nexport REDIS_PREFIX=\"ax:synapse\"\n\n# Network configuration\nexport NETWORK_IFACE=\"eth0\"\nexport NETWORK_IFACES=\"eth0,eth1\"  # Multiple interfaces (comma-separated)\nexport NETWORK_IP_VERSION=\"both\"  # ipv4, ipv6, or both\nexport FIREWALL_MODE=\"auto\"  # auto, xdp, nftables, iptables, none\nexport FIREWALL_DISABLE_XDP=\"false\"\n\n# Gen0Sec Platform configuration\nexport API_KEY=\"your-api-key\"\nexport BASE_URL=\"https://api.gen0sec.com/v1\"\nexport LOG_SENDING_ENABLED=\"true\"\n\n# CAPTCHA configuration\nexport CAPTCHA_SITE_KEY=\"your-site-key\"\nexport CAPTCHA_SECRET_KEY=\"your-secret-key\"\nexport CAPTCHA_JWT_SECRET=\"your-jwt-secret\"\nexport CAPTCHA_PROVIDER=\"turnstile\"\nexport CAPTCHA_TOKEN_TTL=\"7200\"\nexport CAPTCHA_CACHE_TTL=\"300\"\n\n# Content scanning\nexport CONTENT_SCANNING_ENABLED=\"true\"\nexport CLAMAV_SERVER=\"localhost:3310\"\nexport CONTENT_MAX_FILE_SIZE=\"10485760\"\nexport CONTENT_SCAN_CONTENT_TYPES=\"text/html,application/x-www-form-urlencoded,multipart/form-data\"\nexport CONTENT_SKIP_EXTENSIONS=\".jpg,.png,.gif\"\nexport CONTENT_SCAN_EXPRESSION=\"http.request.method eq \\\"POST\\\" or http.request.method eq \\\"PUT\\\"\"\n\n# Internal services configuration\nexport INTERNAL_SERVICES_ENABLED=\"true\"\nexport INTERNAL_SERVICES_PORT=\"9180\"\nexport INTERNAL_SERVICES_BIND_IP=\"127.0.0.1\"\n\n# PROXY protocol configuration\nexport PROXY_PROTOCOL_ENABLED=\"true\"\nexport PROXY_PROTOCOL_TIMEOUT=\"1000\"\n\n# Daemon mode\nexport DAEMON_ENABLED=\"false\"\nexport DAEMON_PID_FILE=\"/var/run/synapse.pid\"\nexport DAEMON_WORKING_DIRECTORY=\"/\"\nexport DAEMON_USER=\"root\"\nexport DAEMON_GROUP=\"root\"\nexport DAEMON_CHOWN_PID_FILE=\"true\"\n\n# Logging\nexport LOGGING_LEVEL=\"info\"\nexport LOGGING_FILE_ENABLED=\"true\"\nexport LOGGING_DIRECTORY=\"/var/log/synapse\"\nexport LOGGING_MAX_FILE_SIZE=\"104857600\"\nexport LOGGING_FILE_COUNT=\"10\"\nexport LOGGING_SYSLOG_ENABLED=\"false\"\nexport LOGGING_SYSLOG_FACILITY=\"daemon\"\nexport LOGGING_SYSLOG_IDENTIFIER=\"synapse\"\n```\n\nFor a complete list, see [ENVIRONMNET_VARS.md](./docs/ENVIRONMNET_VARS.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFeature configuration examples\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBPF Statistics - Kernel-level packet processing statistics (requires XDP)\u003c/summary\u003e\n\n```yaml\nlogging:\n  bpf_stats:\n    enabled: true\n    log_interval_secs: 60\n    enable_dropped_ip_events: true\n    dropped_ip_events_interval_secs: 30\n```\n```bash\nBPF_STATS_ENABLED=true BPF_STATS_LOG_INTERVAL=60\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTCP Fingerprinting - TCP SYN packet fingerprints for behavioral analysis\u003c/summary\u003e\n\n```yaml\nlogging:\n  tcp_fingerprint:\n    enabled: true\n    log_interval_secs: 60\n    enable_fingerprint_events: true\n    fingerprint_events_interval_secs: 30\n    min_packet_count: 3\n    min_connection_duration_secs: 1\n```\n```bash\nTCP_FINGERPRINT_ENABLED=true TCP_FINGERPRINT_LOG_INTERVAL=60\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eContent Scanning - ClamAV-based malware detection\u003c/summary\u003e\n\n```yaml\nproxy:\n  content_scanning:\n    enabled: true\n    clamav_server: \"localhost:3310\"\n    max_file_size: 10485760  # 10MB\n```\n```bash\nCONTENT_SCANNING_ENABLED=true CLAMAV_SERVER=localhost:3310\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCAPTCHA Protection - hCaptcha, reCAPTCHA, or Turnstile\u003c/summary\u003e\n\n```yaml\nproxy:\n  captcha:\n    site_key: \"your-site-key\"\n    secret_key: \"your-secret-key\"\n    jwt_secret: \"your-jwt-secret\"\n    provider: \"turnstile\"  # hcaptcha, recaptcha, turnstile\n    token_ttl: 7200\n    cache_ttl: 300\n```\n```bash\nCAPTCHA_SITE_KEY=... CAPTCHA_SECRET_KEY=... CAPTCHA_PROVIDER=turnstile\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eACME (Auto TLS) - Automatic Let's Encrypt certificates\u003c/summary\u003e\n\n```yaml\nproxy:\n  acme:\n    enabled: true\n    port: 9180\n    email: \"admin@example.com\"\n    storage_path: \"/var/lib/synapse/acme\"\n    storage_type: \"redis\"  # or \"file\"\n    development: false\n```\n```bash\nACME_ENABLED=true ACME_EMAIL=admin@example.com ACME_STORAGE_TYPE=redis\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGeoIP Databases - Country, ASN, and city-level geolocation\u003c/summary\u003e\n\n```yaml\nproxy:\n  geoip:\n    refresh_secs: 28800  # 8 hours\n    country: { url: \"https://git.io/GeoLite2-Country.mmdb\", path: \"/var/lib/synapse\" }\n    asn: { url: \"https://git.io/GeoLite2-ASN.mmdb\", path: \"/var/lib/synapse\" }\n    city: { url: \"https://git.io/GeoLite2-City.mmdb\", path: \"/var/lib/synapse\" }\n```\n```bash\nGEOIP_COUNTRY_URL=... GEOIP_COUNTRY_PATH=/var/lib/synapse GEOIP_REFRESH_SECS=28800\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eThreat Intelligence - Threat MMDB for real-time protection\u003c/summary\u003e\n\n```yaml\nplatform:\n  threat:\n    url: \"https://download.gen0sec.com/v1\"\n    path: \"/var/lib/synapse\"\n    refresh_secs: 300  # 5 minutes\n```\n```bash\nTHREAT_MMDB_URL=https://download.gen0sec.com/v1 THREAT_MMDB_PATH=/var/lib/synapse\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFirewall \u0026 Network - Backend mode and interface configuration\u003c/summary\u003e\n\n```yaml\nfirewall:\n  mode: \"auto\"  # auto, xdp, nftables, iptables, none\n  disable_xdp: false\nnetwork:\n  iface: \"eth0\"\n  ifaces: [\"eth0\", \"eth1\"]  # overrides iface\n  ip_version: \"both\"  # ipv4, ipv6, both\n```\n```bash\nFIREWALL_MODE=auto NETWORK_IFACE=eth0 NETWORK_IP_VERSION=both\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLogging - File and syslog configuration\u003c/summary\u003e\n\n```yaml\nlogging:\n  level: \"info\"  # error, warn, info, debug, trace\n  file_logging_enabled: true\n  log_directory: \"/var/log/synapse\"\n  max_log_size: 104857600  # 100MB\n  log_file_count: 10\n  syslog:\n    enabled: false\n    facility: \"daemon\"\n    identifier: \"synapse\"\n```\n```bash\nLOGGING_LEVEL=info LOGGING_FILE_ENABLED=true LOGGING_DIRECTORY=/var/log/synapse\n```\n\nLog files created: `error.log`, `app.log`, `access.log` (with automatic rotation and gzip compression).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePlatform (Gen0Sec API) - API integration and log sending\u003c/summary\u003e\n\n```yaml\nplatform:\n  api_key: \"your-api-key\"\n  base_url: \"https://api.gen0sec.com/v1\"\n  log_sending_enabled: true\n  include_response_body: true\n  max_body_size: 1048576  # 1MB\n```\n```bash\nAPI_KEY=your-api-key LOG_SENDING_ENABLED=true\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInternal Services - CAPTCHA verification, ACME challenges server\u003c/summary\u003e\n\n```yaml\nproxy:\n  internal_services:\n    enabled: true\n    port: 9180\n    bind_ip: \"127.0.0.1\"\n```\n```bash\nINTERNAL_SERVICES_ENABLED=true INTERNAL_SERVICES_PORT=9180\n```\n\nEndpoints:\n- `GET /health` - Health check\n- `POST /cgi-bin/captcha/verify` - CAPTCHA verification\n- `GET /.well-known/acme-challenge/*` - ACME HTTP-01 challenges\n- `GET /cert/expiration` - Check all certificate expiration status\n- `GET /cert/expiration/:domain` - Check specific certificate status\n- `POST /cert/renew/:domain` - Manually trigger certificate renewal\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUpstreams configuration\u003c/strong\u003e\u003c/summary\u003e\n\nSynapse supports advanced upstream routing via a separate configuration file with hot-reloading. See [UPSTREAMS_CONFIG.md](./UPSTREAMS_CONFIG.md) for complete documentation.\n\nFeatures: multiple service discovery providers (file, Consul, Kubernetes), global configuration, internal paths, per-path rate limits/headers/timeouts, weighted load balancing, and zero-downtime updates.\n\n**Basic example (file provider):**\n\n```yaml\nprovider: \"file\"\nconfig:\n  https_proxy_enabled: false\n  sticky_sessions: true\n  global_rate_limit: 100\n  global_request_headers:\n    - \"X-Proxy-From:Synapse\"\n  global_response_headers:\n    - \"Access-Control-Allow-Origin:*\"\n\ninternal_paths:\n  \"/cgi-bin/captcha/verify\":\n    rate_limit: 200\n    servers:\n      - \"127.0.0.1:9180\"\n\nupstreams:\n  example.com:\n    certificate: \"example.com\"\n    acme:\n      challenge_type: \"dns-01\"  # or \"http-01\" (default)\n      email: \"admin@example.com\"\n      wildcard: true\n    paths:\n      \"/\":\n        rate_limit: 200\n        force_https: true\n        ssl_enabled: true\n        request_headers:\n          - \"Host: api.example.com\"\n        connection_timeout: 30\n        read_timeout: 120\n        write_timeout: 30\n        idle_timeout: 60\n        servers:\n          - \"127.0.0.1:8000\"\n          - address: \"127.0.0.1:8001\"\n            weight: 3\n          - address: \"127.0.0.1:8002\"\n            weight: 2\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eKubernetes service discovery\u003c/summary\u003e\n\n```yaml\nprovider: \"kubernetes\"\nconfig:\n  sticky_sessions: true\n  global_rate_limit: 300\n\nkubernetes:\n  servers:\n    - \"https://k8s-api.example.com:6443\"\n  tokenpath: \"/var/run/secrets/kubernetes.io/serviceaccount/token\"\n  services:\n    - upstream: \"http://my-service.default.svc.cluster.local:8080\"\n      hostname: \"api.example.com\"\n      path: \"/\"\n      rate_limit: 500\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eConsul service discovery\u003c/summary\u003e\n\n```yaml\nprovider: \"consul\"\nconfig:\n  sticky_sessions: true\n  global_rate_limit: 200\n\nconsul:\n  servers:\n    - \"consul1.example.com:8500\"\n    - \"consul2.example.com:8500\"\n  token: \"your-consul-token\"\n  services:\n    - upstream: \"http://service-name.service.consul:8080\"\n      hostname: \"api.example.com\"\n      path: \"/\"\n      rate_limit: 500\n```\n\u003c/details\u003e\n\nExample files: [file](./upstreams_example.yaml) | [kubernetes](./upstreams_example_kubernetes.yaml) | [consul](./upstreams_example_consul.yaml)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSIGHUP configuration reload\u003c/strong\u003e\u003c/summary\u003e\n\nSynapse supports runtime configuration reload via `SIGHUP` signal:\n\n```bash\nkill -HUP $(cat /var/run/synapse.pid)\n```\n\n**Hot-reloadable settings:**\n\n| Setting | Config Path | Notes |\n|---------|-------------|-------|\n| Log level | `logging.level` | Switches log verbosity instantly |\n| Log sending | `platform.log_sending_enabled` | Enable/disable API log sending |\n| API key | `platform.api_key` | Update platform credentials |\n| Base URL | `platform.base_url` | Change API endpoint |\n| Include response body | `platform.include_response_body` | Toggle body capture in access logs |\n| Max body size | `platform.max_body_size` | Adjust body size limit for logs |\n| Upstreams | `proxy.upstream.conf` | Re-reads upstreams YAML file |\n| Security rules | Local file or API | Re-fetches access rules and WAF rules |\n| GeoIP databases | `proxy.geoip.*` | Re-downloads MMDB files |\n\n**Settings that require restart:**\n\n| Setting | Config Path | Reason |\n|---------|-------------|--------|\n| Listen addresses | `proxy.address_http`, `proxy.address_tls` | Port bindings set at startup |\n| Network interface | `network.iface`, `network.ifaces` | XDP attached at startup |\n| Firewall mode | `firewall.mode`, `firewall.disable_xdp` | BPF programs loaded at startup |\n| Runtime threads | `multi_thread`, `worker_threads` | Tokio runtime created at startup |\n| Daemon settings | `daemon.*` | Process daemonization is one-time |\n| Redis connection | `proxy.redis.*` | Connection pool created at startup |\n| CAPTCHA config | `proxy.captcha.*` | Provider initialized once (write-once) |\n| Content scanning | `proxy.content_scanning.*` | Scanner initialized once (write-once) |\n| Certificate paths | `proxy.certificates` | Loaded at startup |\n| ACME settings | `proxy.acme.*` | ACME manager created at startup |\n| Internal services | `proxy.internal_services.*` | Server bound at startup |\n| BPF stats intervals | `logging.bpf_stats.*` | Task timers set at spawn time |\n| TCP fingerprint intervals | `logging.tcp_fingerprint.*` | Task timers set at spawn time |\n| File logging config | `logging.file_logging_enabled`, `logging.log_directory` | Log appenders built at startup |\n| Syslog config | `logging.syslog.*` | Syslog appender built at startup |\n| IP version | `network.ip_version` | BPF filter compiled at startup |\n| PROXY protocol | `proxy.protocol.*` | Listener configured at startup |\n\n\u003c/details\u003e\n\n## Features\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMulti-backend firewall\u003c/strong\u003e\u003c/summary\u003e\n\n- **Automatic fallback** - XDP/BPF \u003e nftables \u003e iptables \u003e userland\n- **Dynamic access rules** - Allow/block lists auto-updated from Gen0Sec API\n- **BPF map enforcement** - Rules enforced at kernel level via XDP\n- **IPv4/IPv6 dual-stack** - Separate rule sets, zero-downtime updates\n- **BPF statistics** - Packet counters, dropped IP tracking (XDP only)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eThreat intelligence\u003c/strong\u003e\u003c/summary\u003e\n\n- **IP reputation scoring** - Automatic scoring via Gen0Sec API\n- **Threat MMDB** - Local MaxMind database for offline lookups (auto-updated)\n- **GeoIP MMDB** - Country, ASN, and city-level geolocation (auto-updated)\n- **Bot detection** - Advanced detection and mitigation\n- **Redis caching** - Cached threat data for performance\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eJA4+ fingerprinting\u003c/strong\u003e\u003c/summary\u003e\n\n- **JA4** - TLS client fingerprinting from ClientHello\n- **JA4H** - HTTP header fingerprinting\n- **JA4T** - TCP fingerprinting from SYN packet options\n- **JA4L** - Latency fingerprinting from packet timing\n- **JA4S** - TLS server fingerprinting from ServerHello\n- **JA4X** - X.509 certificate fingerprinting\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWAF (Wirefilter expressions)\u003c/strong\u003e\u003c/summary\u003e\n\n- **Expression engine** - Filter by request method, path, headers, and more\n- **Actions** - Allow, block, or challenge based on expression matches\n- **Centralized management** - Expressions fetched from Gen0Sec API\n- **Content scanning triggers** - Define when to scan based on request characteristics\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTLS management\u003c/strong\u003e\u003c/summary\u003e\n\n- **ACME/Let's Encrypt** - Automatic certificates with HTTP-01 and DNS-01 challenges\n- **Wildcard detection** - Automatically uses DNS-01 for wildcard domains\n- **Custom certificates** - Bring your own TLS certificates\n- **HTTPS enforcement** - Force HTTPS with HTTP upgrade responses\n- **Expiration monitoring** - Automatic renewal and manual trigger via API\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContent scanning\u003c/strong\u003e\u003c/summary\u003e\n\n- **ClamAV integration** - Real-time malware detection\n- **Multipart/form scanning** - Scans uploads and form data\n- **Wirefilter triggers** - Advanced rules for when to scan\n- **Extension filtering** - Skip specific file extensions\n\n\u003c/details\u003e\n\n## Requirements\n\n| Requirement | Minimum | Recommended | Notes |\n|-------------|---------|-------------|-------|\n| **Kernel** | 4.18+ | 5.4+ | XDP support required |\n| **glibc** | 2.31+ | 2.35+ | For binary releases |\n| **Architecture** | x86_64 | x86_64, aarch64 | ARM64 supported |\n| **Memory** | 128 MB | 512 MB+ | Depends on traffic |\n| **Disk** | 100 MB | 500 MB+ | For logs and MMDB files |\n\n| Dependency | Required | Purpose |\n|------------|----------|---------|\n| **libbpf** | Yes | eBPF program loading |\n| **Redis** | Yes | Caching, certificate store |\n| **ClamAV** | Optional | Content scanning |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTested distributions\u003c/strong\u003e\u003c/summary\u003e\n\n| Distribution | Version | Status | Notes |\n|--------------|---------|--------|-------|\n| **Ubuntu** | 24.04 LTS | ✅ Tested | Recommended |\n| **Ubuntu** | 22.04 LTS | ✅ Tested | Fully supported |\n| **Ubuntu** | 20.04 LTS | ✅ Tested | All features, glibc 2.31 |\n| **Ubuntu** | 18.04 LTS | ✅ Tested | All features, kernel 4.15→5.4 HWE |\n| **Ubuntu** | 16.04 LTS | ⚠️ Limited | iptables backend only (no XDP) |\n| **Debian** | 12 (Bookworm) | ✅ Tested | Fully supported |\n| **Debian** | 11 (Bullseye) | ✅ Compatible | glibc 2.31 |\n| **RHEL/Rocky/Alma** | 9.x | ✅ Tested | Fully supported |\n| **RHEL/CentOS** | 8.x | ⚠️ Compatible | Kernel 4.18 |\n| **Fedora** | 39+ | ✅ Compatible | Latest kernel |\n| **Amazon Linux** | 2023 | ✅ Compatible | AWS optimized |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eKernel feature requirements\u003c/strong\u003e\u003c/summary\u003e\n\n| Feature | Required For | Check Command |\n|---------|--------------|---------------|\n| **XDP** | Packet filtering | `grep XDP /boot/config-$(uname -r)` |\n| **BPF** | eBPF programs | `grep BPF /boot/config-$(uname -r)` |\n| **BTF** | BPF Type Format | `ls /sys/kernel/btf/vmlinux` |\n\n\u003c/details\u003e\n\n## Architecture\n\n- **Multi-Backend Firewall** - XDP/nftables/iptables/userland packet filtering\n- **HTTP/TLS Servers** - HTTP traffic handling and HTTPS connection management\n- **Internal Services Server** - Unified server for CAPTCHA, ACME, and certificate management\n- **Reverse Proxy** - Request forwarding to upstream services\n- **Upstreams Manager** - Routing with service discovery, weighted load balancing, and hot-reloading\n- **Threat Intelligence** - Gen0Sec API and Threat MMDB integration\n- **GeoIP Manager** - Country, ASN, and city-level geolocation via MMDB\n- **Access Rules Engine** - Dynamic IP allow/block lists with periodic API updates\n- **BPF Statistics Collector** - Kernel-level packet processing tracking\n- **TCP Fingerprint Collector** - SYN fingerprint extraction and analysis\n- **Fingerprint Engine** - Complete JA4+ suite (JA4, JA4H, JA4T, JA4L, JA4S, JA4X)\n- **CAPTCHA Engine** - Multi-provider CAPTCHA validation\n- **Content Scanner** - ClamAV malware detection\n- **ACME Manager** - HTTP-01 and DNS-01 certificate management\n- **File/Syslog Loggers** - Rotating file-based and centralized syslog logging\n- **Event Queue** - Unified batch processing for logs, statistics, and events\n- **Redis Cache** - Certificates, threat intel, CAPTCHA, and content scan results\n\n### Performance\n\n- **Ultra-low latency** - XDP filtering operates in kernel space\n- **High throughput** - Rust-based implementation with async I/O\n- **Memory efficient** - Minimal footprint with efficient caching\n- **Scalable** - Multiple network interfaces and concurrent connections\n\n## Thank you!\n[Cloudflare](https://github.com/cloudflare) for Pingora and Wirefilter\n[Aralaz](https://github.com/sadoyan/aralez) for Aralez\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgen0sec%2Fsynapse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgen0sec%2Fsynapse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgen0sec%2Fsynapse/lists"}