https://github.com/gen0sec/synapse
XDR with eBPF-powered firewall and proxy. Protect your Linux servers.
https://github.com/gen0sec/synapse
access-rules adr arxignis ebpf firewall gen0sec ja3-fingerprint ja4 ja4-fingerprint ja4h ja4t rate-limiting runtime ssl-fingerprint threat-intelligence waf webserver xdr
Last synced: 4 months ago
JSON representation
XDR with eBPF-powered firewall and proxy. Protect your Linux servers.
- Host: GitHub
- URL: https://github.com/gen0sec/synapse
- Owner: gen0sec
- License: other
- Created: 2025-10-01T11:25:27.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T11:51:53.000Z (4 months ago)
- Last Synced: 2026-02-13T20:35:19.101Z (4 months ago)
- 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
- Language: Rust
- Homepage: https://gen0sec.com
- Size: 11.6 MB
- Stars: 76
- Watchers: 1
- Forks: 8
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
- awesome-ebpf - Synapse - Extended detection and response (XDR) with eBPF-powered firewall and proxy, to protect your Linux servers. (Projects Related to eBPF / Security)
README
## Overview
Synapse is a high-performance reverse proxy and firewall built with Rust, featuring:
- **XDP-based packet filtering** for ultra-low latency protection at kernel level
- **Multi-backend firewall** with automatic fallback (XDP > nftables > iptables > userland)
- **Dynamic access rules** with automatic updates from Gen0Sec API
- **JA4+ fingerprinting** complete suite: JA4, JA4H, JA4T, JA4L, JA4S, JA4X
- **Automatic TLS certificate management** with ACME/Let's Encrypt (HTTP-01 and DNS-01)
- **Threat intelligence integration** with Gen0Sec API and Threat MMDB
- **Content scanning** with ClamAV integration for malware detection
- **Advanced upstream routing** with service discovery (file, Consul, Kubernetes)
- **Weighted load balancing** with hot-reloadable configuration
> **Linux only.** Requires kernel 4.18+ with XDP/BPF support.
## Quick Start
```bash
# Ubuntu install
curl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh
```
```bash
# Run with config file
synapse -c /etc/synapse/config.yaml
# Set mode via environment variable (default: agent)
export MODE="proxy" # or "agent"
```
More installation methods
### Ansible
```bash
git clone https://github.com/gen0sec/synapse.git
cd synapse/moat/ansible
cp hosts.example hosts
# Edit hosts and add your server details
ansible-playbook playbook.yml -e gen0sec_api_token=your_key_here
```
Features: Debian/Ubuntu + RedHat/CentOS/Fedora, optional ClamAV/Redis/Fail2Ban. [More details.](./ansible/README.md)
### Kubernetes
```bash
helm repo add gen0sec https://helm.gen0sec.com
helm install synapse-stack
```
[More details.](./docs/OPERATOR_README.md)
### Killercoda Playground
```bash
curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key
```
### Docker
```bash
# Required capabilities
--cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN
```
## Modes
Synapse runs in two modes: **Agent** (default) and **Proxy**.
| Feature | Proxy | Agent |
|---------|:-----:|:-----:|
| **HTTP/HTTPS Reverse Proxy** | ✅ | ❌ |
| **TLS & ACME Certificates** | ✅ | ❌ |
| **Upstreams & Load Balancing** | ✅ | ❌ |
| **WAF, Rate Limiting, CAPTCHA** | ✅ | ❌ |
| **Content Scanning (ClamAV)** | ✅ | ❌ |
| **XDP Firewall & Access Rules** | ✅ | ✅ |
| **Threat Intelligence & GeoIP** | ✅ | ✅ |
| **JA4+ Fingerprinting** | ✅ Full | ✅ Network-level |
| **BPF Stats & TCP Fingerprinting** | ✅ | ✅ |
| **File/Syslog Logging** | ✅ | ✅ |
Detailed feature comparison
| Feature | Proxy Mode | Agent Mode |
|---------|-------------------|------------|
| **HTTP/HTTPS Reverse Proxy** | ✅ Full support | ❌ Not available |
| **TLS Certificate Management** | ✅ ACME & custom certificates | ❌ Not available |
| **Upstreams & Load Balancing** | ✅ File, Consul, Kubernetes | ❌ Not available |
| **Hot-reloadable Upstreams** | ✅ Zero-downtime updates | ❌ Not available |
| **XDP Packet Filtering** | ✅ Kernel-level filtering | ✅ Kernel-level filtering |
| **Multi-Backend Firewall** | ✅ XDP/nftables/iptables/userland | ✅ XDP/nftables/iptables/userland |
| **Access Rules Enforcement** | ✅ IP allow/block lists | ✅ IP allow/block lists |
| **Dynamic Access Rules** | ✅ Auto-updates from Gen0Sec API | ✅ Auto-updates from Gen0Sec API |
| **BPF Statistics Collection** | ✅ Packet processing metrics (XDP only) | ✅ Packet processing metrics (XDP only) |
| **TCP Fingerprinting** | ✅ SYN packet analysis | ✅ SYN packet analysis |
| **JA4+ Fingerprinting** | ✅ JA4, JA4H, JA4T, JA4L, JA4S, JA4X | ✅ JA4T, JA4L (network-level) |
| **Wirefilter Expressions (WAF)** | ✅ Advanced request filtering | ❌ Not available |
| **Rate Limiting** | ✅ Per-rule rate limits | ❌ Not available |
| **Content Scanning (ClamAV)** | ✅ Malware detection | ❌ Not available |
| **CAPTCHA Protection** | ✅ hCaptcha, reCAPTCHA, Turnstile | ❌ Not available |
| **Threat Intelligence** | ✅ Real-time MMDB + HTTP-level | ✅ Smart Lists (network-level) |
| **GeoIP Databases** | ✅ Country, ASN, City lookups | ⚠️ Via Smart Lists only |
| **Internal Services Server** | ✅ ACME, CAPTCHA endpoints | ❌ Not available |
| **Redis Caching** | ✅ Certificates, threat intel, validation | ❌ Not available |
| **Access Log Sending** | ✅ To Gen0Sec API | ❌ Not available |
| **File/Syslog Logging** | ✅ Rotating logs | ✅ Rotating logs |
| **Multiple Network Interfaces** | ✅ High availability setups | ✅ High availability setups |
| **Multi-threaded Runtime** | ✅ Default | ⚠️ Single-threaded default |
Agent mode (default)
Standalone agent focused on access rules enforcement without HTTP/HTTPS proxy. Ideal for network-level protection where you don't need request proxying.
```yaml
mode: "agent" # default, can be omitted
```
```bash
# Set via environment variable
export MODE="agent"
```
Use cases:
- Network-level firewall protection without proxying
- Access rules enforcement at the edge
- Kernel-level IP blocking without HTTP overhead
- Integration with existing reverse proxies or load balancers
Proxy mode
Full-featured reverse proxy with HTTP/HTTPS support, forwarding requests to upstream servers while applying access rules and threat intelligence at the kernel level.
```yaml
mode: "proxy"
proxy:
address_http: "0.0.0.0:80"
address_tls: "0.0.0.0:443"
upstream:
conf: "/etc/synapse/upstreams.yaml"
```
```bash
# Set via environment variable
export MODE="proxy"
```
## Configuration
Synapse supports three configuration methods (highest to lowest priority):
1. **YAML Configuration File** - via `config.yaml` ([example](./config_example.yaml))
2. **Command Line Arguments** - override specific settings via CLI flags
3. **Environment Variables** - `export API_KEY="your-key"`
### CLI Options
| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config ` | Path to configuration file (YAML) | - |
| `--security-rules-config ` | Security rules file (fallback without API key) | `security_rules.yaml` |
| `-i`, `--iface ` | Network interface for XDP | `eth0` |
| `--ifaces ` | Additional interfaces (comma-separated, overrides `--iface`) | - |
| `--log-level ` | Log level (error, warn, info, debug, trace) | `info` |
| `--disable-xdp` | Disable XDP packet filtering | `false` |
| `--redis-url ` | Redis connection URL | `redis://127.0.0.1/0` |
| `--redis-prefix ` | Redis namespace prefix | `ax:synapse` |
| `--captcha-site-key ` | CAPTCHA site key | - |
| `--captcha-secret-key ` | CAPTCHA secret key | - |
| `--captcha-jwt-secret ` | JWT secret for CAPTCHA tokens | - |
| `--captcha-provider ` | CAPTCHA provider (hcaptcha, recaptcha, turnstile) | - |
| `--captcha-token-ttl ` | CAPTCHA token TTL | `7200` |
| `--captcha-cache-ttl ` | CAPTCHA cache TTL | `300` |
| `--proxy-protocol-enabled` | Enable PROXY protocol | `false` |
| `--proxy-protocol-timeout ` | PROXY protocol timeout | `1000` |
| `-d`, `--daemon` | Run as daemon | `false` |
| `--daemon-pid-file ` | PID file path | `/var/run/synapse.pid` |
| `--daemon-working-dir ` | Daemon working directory | `/` |
| `--daemon-stdout ` | Daemon stdout log | `/var/log/synapse.out` |
| `--daemon-stderr ` | Daemon stderr log | `/var/log/synapse.err` |
| `--daemon-user ` | Run daemon as user | - |
| `--daemon-group ` | Run daemon as group | - |
| `--clear-certificate ` | Clear certificate from filesystem and Redis | - |
### Feature Toggles
| Feature | YAML Path | Environment Variable | Default |
|---------|-----------|---------------------|---------|
| **BPF Statistics** | `logging.bpf_stats.enabled` | `BPF_STATS_ENABLED` | `true` |
| **TCP Fingerprinting** | `logging.tcp_fingerprint.enabled` | `TCP_FINGERPRINT_ENABLED` | `true` |
| **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` | `false` |
| **Internal Services** | `proxy.internal_services.enabled` | `INTERNAL_SERVICES_ENABLED` | `true` |
| **PROXY Protocol** | `proxy.protocol.enabled` | `PROXY_PROTOCOL_ENABLED` | `false` |
| **File Logging** | `logging.file_logging_enabled` | `LOGGING_FILE_ENABLED` | `false` |
| **Syslog** | `logging.syslog.enabled` | `LOGGING_SYSLOG_ENABLED` | `false` |
| **Log Sending (API)** | `platform.log_sending_enabled` | `LOG_SENDING_ENABLED` | `true` |
| **XDP Firewall** | `firewall.disable_xdp` | `FIREWALL_DISABLE_XDP` | `false` (XDP enabled) |
Environment variables reference
```bash
# Application mode
export MODE="proxy" # or "agent"
# Redis configuration
export REDIS_URL="redis://127.0.0.1/0"
export REDIS_PREFIX="ax:synapse"
# Network configuration
export NETWORK_IFACE="eth0"
export NETWORK_IFACES="eth0,eth1" # Multiple interfaces (comma-separated)
export NETWORK_IP_VERSION="both" # ipv4, ipv6, or both
export FIREWALL_MODE="auto" # auto, xdp, nftables, iptables, none
export FIREWALL_DISABLE_XDP="false"
# Gen0Sec Platform configuration
export API_KEY="your-api-key"
export BASE_URL="https://api.gen0sec.com/v1"
export LOG_SENDING_ENABLED="true"
# CAPTCHA configuration
export CAPTCHA_SITE_KEY="your-site-key"
export CAPTCHA_SECRET_KEY="your-secret-key"
export CAPTCHA_JWT_SECRET="your-jwt-secret"
export CAPTCHA_PROVIDER="turnstile"
export CAPTCHA_TOKEN_TTL="7200"
export CAPTCHA_CACHE_TTL="300"
# Content scanning
export CONTENT_SCANNING_ENABLED="true"
export CLAMAV_SERVER="localhost:3310"
export CONTENT_MAX_FILE_SIZE="10485760"
export CONTENT_SCAN_CONTENT_TYPES="text/html,application/x-www-form-urlencoded,multipart/form-data"
export CONTENT_SKIP_EXTENSIONS=".jpg,.png,.gif"
export CONTENT_SCAN_EXPRESSION="http.request.method eq \"POST\" or http.request.method eq \"PUT\""
# Internal services configuration
export INTERNAL_SERVICES_ENABLED="true"
export INTERNAL_SERVICES_PORT="9180"
export INTERNAL_SERVICES_BIND_IP="127.0.0.1"
# PROXY protocol configuration
export PROXY_PROTOCOL_ENABLED="true"
export PROXY_PROTOCOL_TIMEOUT="1000"
# Daemon mode
export DAEMON_ENABLED="false"
export DAEMON_PID_FILE="/var/run/synapse.pid"
export DAEMON_WORKING_DIRECTORY="/"
export DAEMON_USER="root"
export DAEMON_GROUP="root"
export DAEMON_CHOWN_PID_FILE="true"
# 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"
export LOGGING_SYSLOG_FACILITY="daemon"
export LOGGING_SYSLOG_IDENTIFIER="synapse"
```
For a complete list, see [ENVIRONMNET_VARS.md](./docs/ENVIRONMNET_VARS.md).
Feature configuration examples
BPF Statistics - Kernel-level packet processing statistics (requires XDP)
```yaml
logging:
bpf_stats:
enabled: true
log_interval_secs: 60
enable_dropped_ip_events: true
dropped_ip_events_interval_secs: 30
```
```bash
BPF_STATS_ENABLED=true BPF_STATS_LOG_INTERVAL=60
```
TCP Fingerprinting - TCP SYN packet fingerprints for behavioral analysis
```yaml
logging:
tcp_fingerprint:
enabled: true
log_interval_secs: 60
enable_fingerprint_events: true
fingerprint_events_interval_secs: 30
min_packet_count: 3
min_connection_duration_secs: 1
```
```bash
TCP_FINGERPRINT_ENABLED=true TCP_FINGERPRINT_LOG_INTERVAL=60
```
Content Scanning - ClamAV-based malware detection
```yaml
proxy:
content_scanning:
enabled: true
clamav_server: "localhost:3310"
max_file_size: 10485760 # 10MB
```
```bash
CONTENT_SCANNING_ENABLED=true CLAMAV_SERVER=localhost:3310
```
CAPTCHA Protection - hCaptcha, reCAPTCHA, or Turnstile
```yaml
proxy:
captcha:
site_key: "your-site-key"
secret_key: "your-secret-key"
jwt_secret: "your-jwt-secret"
provider: "turnstile" # hcaptcha, recaptcha, turnstile
token_ttl: 7200
cache_ttl: 300
```
```bash
CAPTCHA_SITE_KEY=... CAPTCHA_SECRET_KEY=... CAPTCHA_PROVIDER=turnstile
```
ACME (Auto TLS) - Automatic Let's Encrypt certificates
```yaml
proxy:
acme:
enabled: true
port: 9180
email: "admin@example.com"
storage_path: "/var/lib/synapse/acme"
storage_type: "redis" # or "file"
development: false
```
```bash
ACME_ENABLED=true ACME_EMAIL=admin@example.com ACME_STORAGE_TYPE=redis
```
GeoIP Databases - Country, ASN, and city-level geolocation
```yaml
proxy:
geoip:
refresh_secs: 28800 # 8 hours
country: { url: "https://git.io/GeoLite2-Country.mmdb", path: "/var/lib/synapse" }
asn: { url: "https://git.io/GeoLite2-ASN.mmdb", path: "/var/lib/synapse" }
city: { url: "https://git.io/GeoLite2-City.mmdb", path: "/var/lib/synapse" }
```
```bash
GEOIP_COUNTRY_URL=... GEOIP_COUNTRY_PATH=/var/lib/synapse GEOIP_REFRESH_SECS=28800
```
Threat Intelligence - Threat MMDB for real-time protection
```yaml
platform:
threat:
url: "https://download.gen0sec.com/v1"
path: "/var/lib/synapse"
refresh_secs: 300 # 5 minutes
```
```bash
THREAT_MMDB_URL=https://download.gen0sec.com/v1 THREAT_MMDB_PATH=/var/lib/synapse
```
Firewall & Network - Backend mode and interface configuration
```yaml
firewall:
mode: "auto" # auto, xdp, nftables, iptables, none
disable_xdp: false
network:
iface: "eth0"
ifaces: ["eth0", "eth1"] # overrides iface
ip_version: "both" # ipv4, ipv6, both
```
```bash
FIREWALL_MODE=auto NETWORK_IFACE=eth0 NETWORK_IP_VERSION=both
```
Logging - File and syslog configuration
```yaml
logging:
level: "info" # error, warn, info, debug, trace
file_logging_enabled: true
log_directory: "/var/log/synapse"
max_log_size: 104857600 # 100MB
log_file_count: 10
syslog:
enabled: false
facility: "daemon"
identifier: "synapse"
```
```bash
LOGGING_LEVEL=info LOGGING_FILE_ENABLED=true LOGGING_DIRECTORY=/var/log/synapse
```
Log files created: `error.log`, `app.log`, `access.log` (with automatic rotation and gzip compression).
Platform (Gen0Sec API) - API integration and log sending
```yaml
platform:
api_key: "your-api-key"
base_url: "https://api.gen0sec.com/v1"
log_sending_enabled: true
include_response_body: true
max_body_size: 1048576 # 1MB
```
```bash
API_KEY=your-api-key LOG_SENDING_ENABLED=true
```
Internal Services - CAPTCHA verification, ACME challenges server
```yaml
proxy:
internal_services:
enabled: true
port: 9180
bind_ip: "127.0.0.1"
```
```bash
INTERNAL_SERVICES_ENABLED=true INTERNAL_SERVICES_PORT=9180
```
Endpoints:
- `GET /health` - Health check
- `POST /cgi-bin/captcha/verify` - CAPTCHA verification
- `GET /.well-known/acme-challenge/*` - ACME HTTP-01 challenges
- `GET /cert/expiration` - Check all certificate expiration status
- `GET /cert/expiration/:domain` - Check specific certificate status
- `POST /cert/renew/:domain` - Manually trigger certificate renewal
Upstreams configuration
Synapse supports advanced upstream routing via a separate configuration file with hot-reloading. See [UPSTREAMS_CONFIG.md](./UPSTREAMS_CONFIG.md) for complete documentation.
Features: multiple service discovery providers (file, Consul, Kubernetes), global configuration, internal paths, per-path rate limits/headers/timeouts, weighted load balancing, and zero-downtime updates.
**Basic example (file provider):**
```yaml
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: "admin@example.com"
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 service discovery
```yaml
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 service discovery
```yaml
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
```
Example files: [file](./upstreams_example.yaml) | [kubernetes](./upstreams_example_kubernetes.yaml) | [consul](./upstreams_example_consul.yaml)
SIGHUP configuration reload
Synapse supports runtime configuration reload via `SIGHUP` signal:
```bash
kill -HUP $(cat /var/run/synapse.pid)
```
**Hot-reloadable settings:**
| Setting | Config Path | Notes |
|---------|-------------|-------|
| Log level | `logging.level` | Switches log verbosity instantly |
| Log sending | `platform.log_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 and WAF rules |
| GeoIP databases | `proxy.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`, `firewall.disable_xdp` | BPF programs 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 (write-once) |
| Content scanning | `proxy.content_scanning.*` | Scanner initialized once (write-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 |
| BPF stats intervals | `logging.bpf_stats.*` | Task timers set at spawn time |
| TCP fingerprint intervals | `logging.tcp_fingerprint.*` | Task timers set at spawn time |
| File logging config | `logging.file_logging_enabled`, `logging.log_directory` | Log appenders built at startup |
| Syslog config | `logging.syslog.*` | Syslog appender built at startup |
| IP version | `network.ip_version` | BPF filter compiled at startup |
| PROXY protocol | `proxy.protocol.*` | Listener configured at startup |
## Features
Multi-backend firewall
- **Automatic fallback** - XDP/BPF > nftables > iptables > userland
- **Dynamic access rules** - Allow/block lists auto-updated from Gen0Sec API
- **BPF map enforcement** - Rules enforced at kernel level via XDP
- **IPv4/IPv6 dual-stack** - Separate rule sets, zero-downtime updates
- **BPF statistics** - Packet counters, dropped IP tracking (XDP only)
Threat intelligence
- **IP reputation scoring** - Automatic scoring via Gen0Sec API
- **Threat MMDB** - Local MaxMind database for offline lookups (auto-updated)
- **GeoIP MMDB** - Country, ASN, and city-level geolocation (auto-updated)
- **Bot detection** - Advanced detection and mitigation
- **Redis caching** - Cached threat data for performance
JA4+ fingerprinting
- **JA4** - TLS client fingerprinting from ClientHello
- **JA4H** - HTTP header fingerprinting
- **JA4T** - TCP fingerprinting from SYN packet options
- **JA4L** - Latency fingerprinting from packet timing
- **JA4S** - TLS server fingerprinting from ServerHello
- **JA4X** - X.509 certificate fingerprinting
WAF (Wirefilter expressions)
- **Expression engine** - Filter by request method, path, headers, and more
- **Actions** - Allow, block, or challenge based on expression matches
- **Centralized management** - Expressions fetched from Gen0Sec API
- **Content scanning triggers** - Define when to scan based on request characteristics
TLS management
- **ACME/Let's Encrypt** - Automatic certificates with HTTP-01 and DNS-01 challenges
- **Wildcard detection** - Automatically uses DNS-01 for wildcard domains
- **Custom certificates** - Bring your own TLS certificates
- **HTTPS enforcement** - Force HTTPS with HTTP upgrade responses
- **Expiration monitoring** - Automatic renewal and manual trigger via API
Content scanning
- **ClamAV integration** - Real-time malware detection
- **Multipart/form scanning** - Scans uploads and form data
- **Wirefilter triggers** - Advanced rules for when to scan
- **Extension filtering** - Skip specific file extensions
## Requirements
| Requirement | Minimum | Recommended | Notes |
|-------------|---------|-------------|-------|
| **Kernel** | 4.18+ | 5.4+ | XDP support required |
| **glibc** | 2.31+ | 2.35+ | For binary releases |
| **Architecture** | x86_64 | x86_64, aarch64 | ARM64 supported |
| **Memory** | 128 MB | 512 MB+ | Depends on traffic |
| **Disk** | 100 MB | 500 MB+ | For logs and MMDB files |
| Dependency | Required | Purpose |
|------------|----------|---------|
| **libbpf** | Yes | eBPF program loading |
| **Redis** | Yes | Caching, certificate store |
| **ClamAV** | Optional | Content scanning |
Tested distributions
| Distribution | Version | Status | Notes |
|--------------|---------|--------|-------|
| **Ubuntu** | 24.04 LTS | ✅ Tested | Recommended |
| **Ubuntu** | 22.04 LTS | ✅ Tested | Fully supported |
| **Ubuntu** | 20.04 LTS | ✅ Tested | All features, glibc 2.31 |
| **Ubuntu** | 18.04 LTS | ✅ Tested | All features, kernel 4.15→5.4 HWE |
| **Ubuntu** | 16.04 LTS | ⚠️ Limited | iptables backend only (no XDP) |
| **Debian** | 12 (Bookworm) | ✅ Tested | Fully supported |
| **Debian** | 11 (Bullseye) | ✅ Compatible | glibc 2.31 |
| **RHEL/Rocky/Alma** | 9.x | ✅ Tested | Fully supported |
| **RHEL/CentOS** | 8.x | ⚠️ Compatible | Kernel 4.18 |
| **Fedora** | 39+ | ✅ Compatible | Latest kernel |
| **Amazon Linux** | 2023 | ✅ Compatible | AWS optimized |
Kernel feature requirements
| Feature | Required For | Check Command |
|---------|--------------|---------------|
| **XDP** | Packet filtering | `grep XDP /boot/config-$(uname -r)` |
| **BPF** | eBPF programs | `grep BPF /boot/config-$(uname -r)` |
| **BTF** | BPF Type Format | `ls /sys/kernel/btf/vmlinux` |
## Architecture
- **Multi-Backend Firewall** - XDP/nftables/iptables/userland packet filtering
- **HTTP/TLS Servers** - HTTP traffic handling and HTTPS connection management
- **Internal Services Server** - Unified server for CAPTCHA, ACME, and certificate management
- **Reverse Proxy** - Request forwarding to upstream services
- **Upstreams Manager** - Routing with service discovery, weighted load balancing, and hot-reloading
- **Threat Intelligence** - Gen0Sec API and Threat MMDB integration
- **GeoIP Manager** - Country, ASN, and city-level geolocation via MMDB
- **Access Rules Engine** - Dynamic IP allow/block lists with periodic API updates
- **BPF Statistics Collector** - Kernel-level packet processing tracking
- **TCP Fingerprint Collector** - SYN fingerprint extraction and analysis
- **Fingerprint Engine** - Complete JA4+ suite (JA4, JA4H, JA4T, JA4L, JA4S, JA4X)
- **CAPTCHA Engine** - Multi-provider CAPTCHA validation
- **Content Scanner** - ClamAV malware detection
- **ACME Manager** - HTTP-01 and DNS-01 certificate management
- **File/Syslog Loggers** - Rotating file-based and centralized syslog logging
- **Event Queue** - Unified batch processing for logs, statistics, and events
- **Redis Cache** - Certificates, threat intel, CAPTCHA, and content scan results
### Performance
- **Ultra-low latency** - XDP filtering operates in kernel space
- **High throughput** - Rust-based implementation with async I/O
- **Memory efficient** - Minimal footprint with efficient caching
- **Scalable** - Multiple network interfaces and concurrent connections
## Thank you!
[Cloudflare](https://github.com/cloudflare) for Pingora and Wirefilter
[Aralaz](https://github.com/sadoyan/aralez) for Aralez