gen0sec/synapse
GitHub: gen0sec/synapse
基于 eBPF/XDP 的 Rust 高性能 Linux 服务器防护方案，集成反向代理、防火墙和威胁检测能力。
Stars: 101 | Forks: 8
```
### Docker
```
# 所需 capabilities
--cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN
```
## 模式
Synapse 以两种模式运行：**Agent**（默认）和 **Proxy**。
| 特性 | Proxy | Agent |
|---------|:-----:|:-----:|
| **HTTP/HTTPS 反向代理** | ✅ | ❌ |
| **TLS 与 ACME 证书** | ✅ | ❌ |
| **上游与负载均衡** | ✅ | ❌ |
| **WAF, 速率限制, CAPTCHA** | ✅ | ❌ |
| **内容扫描 (ClamAV)** | ✅ | ❌ |
| **XDP 防火墙与访问规则** | ✅ | ✅ |
| **威胁情报与 GeoIP** | ✅ | ✅ |
| **JA4+ 指纹识别** | ✅ 完整 | ✅ 网络级别 |
| **BPF 统计与 TCP 指纹识别** | ✅ | ✅ |
| **文件/Syslog 日志** | ✅ | ✅ |
## 配置
Synapse 支持三种配置方式（优先级从高到低）：
1. **YAML 配置文件** - 通过 `config.yaml` ([示例](./config_example.yaml))
2. **命令行参数** - 通过 CLI 标志覆盖特定设置
3. **环境变量** - `export API_KEY="your-key"`
### CLI 选项
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `-c`, `--config ` | 配置文件路径 (YAML) | - |
| `--security-rules-config ` | 安全规则文件 (无 API key 时的回退) | `security_rules.yaml` |
| `-i`, `--iface ` | XDP 网络接口 | `eth0` |
| `--ifaces
更多安装方式
### Ansible ``` git clone https://github.com/gen0sec/synapse.git cd synapse/moat/ansible cp hosts.example hosts # 编辑 hosts 并添加您的服务器详情 ansible-playbook playbook.yml -e gen0sec_api_token=your_key_here ``` 特性：支持 Debian/Ubuntu + RedHat/CentOS/Fedora，可选 ClamAV/Redis/Fail2Ban。[更多详情。](./ansible/README.md) ### Kubernetes ``` helm repo add gen0sec https://helm.gen0sec.com helm install synapse-stack ``` [更多详情。](./docs/OPERATOR_README.md) ### Killercoda Playground ``` curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key详细功能对比
| 特性 | Proxy 模式 | Agent 模式 | |---------|-------------------|------------| | **HTTP/HTTPS 反向代理** | ✅ 完全支持 | ❌ 不可用 | | **TLS 证书管理** | ✅ ACME 和自定义证书 | ❌ 不可用 | | **上游与负载均衡** | ✅ 文件, Consul, Kubernetes | ❌ 不可用 | | **热重载上游** | ✅ 零停机更新 | ❌ 不可用 | | **XDP 数据包过滤** | ✅ 内核级过滤 | ✅ 内核级过滤 | | **多后端防火墙** | ✅ XDP/nftables/iptables/用户态 | ✅ XDP/nftables/iptables/用户态 | | **访问规则执行** | ✅ IP 允许/阻止列表 | ✅ IP 允许/阻止列表 | | **动态访问规则** | ✅ 从 Gen0Sec API 自动更新 | ✅ 从 Gen0Sec API 自动更新 | | **BPF 统计收集** | ✅ 数据包处理指标 (仅 XDP) | ✅ 数据包处理指标 (仅 XDP) | | **TCP 指纹识别** | ✅ SYN 数据包分析 | ✅ SYN 数据包分析 | | **JA4+ 指纹识别** | ✅ JA4, JA4H, JA4T, JA4L, JA4S, JA4X | ✅ JA4T, JA4L (网络级别) | | **Wirefilter 表达式 (WAF)** | ✅ 高级请求过滤 | ❌ 不可用 | | **速率限制** | ✅ 每规则速率限制 | ❌ 不可用 | | **内容扫描 (ClamAV)** | ✅ 恶意软件检测 | ❌ 不可用 | | **CAPTCHA 防护** | ✅ hCaptcha, reCAPTCHA, Turnstile | ❌ 不可用 | | **威胁情报** | ✅ 实时 MMDB + HTTP 级别 | ✅ 智能列表 (网络级别) | | **GeoIP 数据库** | ✅ 国家, ASN, 城市查询 | ⚠️ 仅通过智能列表 | | **内部服务服务器** | ✅ ACME, CAPTCHA 端点 | ❌ 不可用 | | **Redis 缓存** | ✅ 证书, 威胁情报, 验证 | ❌ 不可用 | | **访问日志发送** | ✅ 发送到 Gen0Sec API | ❌ 不可用 | | **文件/Syslog 日志** | ✅ 轮转日志 | ✅ 轮转日志 | | **多网络接口** | ✅ 高可用性设置 | ✅ 高可用性设置 | | **多线程运行时** | ✅ 默认 | ⚠️ 默认单线程 |Agent 模式 (默认)
独立 Agent 专注于执行访问规则，不包含 HTTP/HTTPS 代理。适用于不需要请求代理的网络级防护。 ``` mode: "agent" # default, can be omitted ``` ``` # 通过 environment variable 设置 export MODE="agent" ``` 用例： - 无需代理的网络级防火墙防护 - 边缘访问规则执行 - 无 HTTP 开销的内核级 IP 阻断 - 与现有反向代理或负载均衡器集成Proxy 模式
功能齐全的反向代理，支持 HTTP/HTTPS，将请求转发到上游服务器，同时在内核级别应用访问规则和威胁情报。 ``` mode: "proxy" proxy: address_http: "0.0.0.0:80" address_tls: "0.0.0.0:443" upstream: conf: "/etc/synapse/upstreams.yaml" ``` ``` # 通过 environment variable 设置 export MODE="proxy" ```- ` | 附加接口 (逗号分隔，覆盖 `--iface`) | - |
| `--log-level
环境变量参考
``` # Application mode export MODE="proxy" # or "agent" # Redis 配置 export REDIS_URL="redis://127.0.0.1/0" export REDIS_PREFIX="ax:synapse" # Network 配置 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 配置 export API_KEY="your-api-key" export BASE_URL="https://api.gen0sec.com/v1" export LOG_SENDING_ENABLED="true" # 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="turnstile" export CAPTCHA_TOKEN_TTL="7200" export CAPTCHA_CACHE_TTL="300" # 内容扫描 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 配置 export INTERNAL_SERVICES_ENABLED="true" export INTERNAL_SERVICES_PORT="9180" export INTERNAL_SERVICES_BIND_IP="127.0.0.1" # PROXY protocol 配置 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" # 日志 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" ``` 完整列表请参见 [ENVIRONMNET_VARS.md](./docs/ENVIRONMNET_VARS.md)。功能配置示例
BPF 统计 - 内核级数据包处理统计 (需要 XDP)
``` logging: bpf_stats: enabled: true log_interval_secs: 60 enable_dropped_ip_events: true dropped_ip_events_interval_secs: 30 ``` ``` BPF_STATS_ENABLED=true BPF_STATS_LOG_INTERVAL=60 ```TCP 指纹识别 - 用于行为分析的 TCP SYN 数据包指纹
``` 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 ``` ``` TCP_FINGERPRINT_ENABLED=true TCP_FINGERPRINT_LOG_INTERVAL=60 ```内容扫描 - 基于 ClamAV 的恶意软件检测
``` proxy: content_scanning: enabled: true clamav_server: "localhost:3310" max_file_size: 10485760 # 10MB ``` ``` CONTENT_SCANNING_ENABLED=true CLAMAV_SERVER=localhost:3310 ```CAPTCHA 防护 - hCaptcha, reCAPTCHA, 或 Turnstile
``` 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 ``` ``` CAPTCHA_SITE_KEY=... CAPTCHA_SECRET_KEY=... CAPTCHA_PROVIDER=turnstile ```ACME (自动 TLS) - 自动 Let's Encrypt 证书
``` proxy: acme: enabled: true port: 9180 email: "admin@example.com" storage_path: "/var/lib/synapse/acme" storage_type: "redis" # or "file" development: false ``` ``` ACME_ENABLED=true ACME_EMAIL=admin@example.com ACME_STORAGE_TYPE=redis ```GeoIP 数据库 - 国家、ASN 和城市级地理定位
``` 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" } ``` ``` GEOIP_COUNTRY_URL=... GEOIP_COUNTRY_PATH=/var/lib/synapse GEOIP_REFRESH_SECS=28800 ```威胁情报 - 用于实时防护的 Threat MMDB
``` platform: threat: url: "https://download.gen0sec.com/v1" path: "/var/lib/synapse" refresh_secs: 300 # 5 minutes ``` ``` THREAT_MMDB_URL=https://download.gen0sec.com/v1 THREAT_MMDB_PATH=/var/lib/synapse ```防火墙与网络 - 后端模式和接口配置
``` 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 ``` ``` FIREWALL_MODE=auto NETWORK_IFACE=eth0 NETWORK_IP_VERSION=both ```日志 - 文件和 Syslog 配置
``` 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" ``` ``` LOGGING_LEVEL=info LOGGING_FILE_ENABLED=true LOGGING_DIRECTORY=/var/log/synapse ``` 生成的日志文件：`error.log`, `app.log`, `access.log` (自动轮转和 gzip 压缩)。Platform (Gen0Sec API) - API 集成和日志发送
``` 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 ``` ``` API_KEY=your-api-key LOG_SENDING_ENABLED=true ```内部服务 - CAPTCHA 验证，ACME 挑战服务器
``` proxy: internal_services: enabled: true port: 9180 bind_ip: "127.0.0.1" ``` ``` INTERNAL_SERVICES_ENABLED=true INTERNAL_SERVICES_PORT=9180 ``` 端点： - `GET /health` - 健康检查 - `POST /cgi-bin/captcha/verify` - CAPTCHA 验证 - `GET /.well-known/acme-challenge/*` - ACME HTTP-01 挑战 - `GET /cert/expiration` - 检查所有证书过期状态 - `GET /cert/expiration/:domain` - 检查特定证书状态 - `POST /cert/renew/:domain` - 手动触发证书续订上游配置
Synapse 支持通过单独的配置文件进行高级上游路由，并支持热重载。完整文档请参见 [UPSTREAM_CONFIG.md](./UPSTREAMS_CONFIG.md)。 特性：多种服务发现提供商 (file, Consul, Kubernetes)，全局配置，内部路径，每路径速率限制/headers/超时，加权负载均衡，以及零停机更新。 **基础示例 (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: "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 服务发现
``` 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: "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 配置重载
Synapse 支持通过 `SIGHUP` 信号进行运行时配置重载： ``` kill -HUP $(cat /var/run/synapse.pid) ``` **支持热重载的设置：** | 设置 | 配置路径 | 备注 | |---------|-------------|-------| | 日志级别 | `logging.level` | 立即切换日志详细程度 | | 日志发送 | `platform.log_sending_enabled` | 启用/禁用 API 日志发送 | | API key | `platform.api_key` | 更新 platform 凭证 | | Base URL | `platform.base_url` | 更改 API endpoint | | 包含响应体 | `platform.include_response_body` | 切换访问日志中的 body 捕获 | | 最大 body 大小 | `platform.max_body_size` | 调整日志的 body 大小限制 | | 上游 | `proxy.upstream.conf` | 重新读取 upstreams YAML 文件 | | 安全规则 | 本地文件或 API | 重新获取访问规则和 WAF 规则 | | GeoIP 数据库 | `proxy.geoip.*` | 重新下载 MMDB 文件 | **需要重启的设置：** | 设置 | 配置路径 | 原因 | |---------|-------------|--------| | 监听地址 | `proxy.address_http`, `proxy.address_tls` | 端口绑定在启动时设置 | | 网络接口 | `network.iface`, `network.ifaces` | XDP 在启动时附加 | | 防火墙模式 | `firewall.mode`, `firewall.disable_xdp` | BPF 程序在启动时加载 | | 运行时线程 | `multi_thread`, `worker_threads` | Tokio 运行时创建于启动时 | | 守护进程设置 | `daemon.*` | 进程守护化是一次性的 | | Redis 连接 | `proxy.redis.*` | 连接池创建于启动时 | | CAPTCHA 配置 | `proxy.captcha.*` | 提供商初始化一次 (只写) | | 内容扫描 | `proxy.content_scanning.*` | 扫描器初始化一次 (只写) | | 证书路径 | `proxy.certificates` | 在启动时加载 | | ACME 设置 | `proxy.acme.*` | ACME 管理器创建于启动时 | | 内部服务 | `proxy.internal_services.*` | 服务器在启动时绑定 | | BPF 统计间隔 | `logging.bpf_stats.*` | 任务计时器设置于生成时 | | TCP 指纹间隔 | `logging.tcp_fingerprint.*` | 任务计时器设置于生成时 | | 文件日志配置 | `logging.file_logging_enabled`, `logging.log_directory` | 日志 appender 构建于启动时 | | Syslog 配置 | `logging.syslog.*` | Syslog appender 构建于启动时 | | IP 版本 | `network.ip_version` | BPF 过滤器编译于启动时 | | PROXY protocol | `proxy.protocol.*` | 监听器配置于启动时 |多后端防火墙
- **自动回退** - XDP/BPF > nftables > iptables > 用户态 - **动态访问规则** - 通过 Gen0Sec API 自动更新的允许/阻止列表 - **BPF map 执行** - 通过 XDP 在内核级别执行规则 - **IPv4/IPv6 双栈** - 独立的规则集，零停机更新 - **BPF 统计** - 数据包计数器，被阻断 IP 跟踪 (仅 XDP)威胁情报
- **IP 信誉评分** - 通过 Gen0Sec API 自动评分 - **Threat MMDB** - 用于离线查询的本地 MaxMind 数据库 (自动更新) - **GeoIP MMDB** - 国家、ASN 和城市级地理定位 (自动更新) - **Bot 检测** - 高级检测和缓解 - **Redis 缓存** - 缓存威胁数据以提高性能JA4+ 指纹识别
- **JA4** - 从 ClientHello 进行 TLS 客户端指纹识别 - **JA4H** - HTTP header 指纹识别 - **JA4T** - 从 SYN 数据包选项进行 TCP 指纹识别 - **JA4L** - 从数据包时序进行延迟指纹识别 - **JA4S** - 从 ServerHello 进行 TLS 服务器指纹识别 - **JA4X** - X.509 证书指纹识别WAF (Wirefilter 表达式)
- **表达式引擎** - 根据请求方法、路径、headers 等进行过滤 - **动作** - 根据表达式匹配进行允许、阻止或挑战 - **集中管理** - 从 Gen0Sec API 获取表达式 - **内容扫描触发器** - 根据请求特征定义何时扫描TLS 管理
- **ACME/Let's Encrypt** - 支持 HTTP-01 和 DNS-01 挑战的自动证书 - **通配符检测** - 对通配符域自动使用 DNS-01 - **自定义证书** - 自带 TLS 证书 - **HTTPS 强制** - 通过 HTTP 升级响应强制 HTTPS - **过期监控** - 自动续订和通过 API 手动触发内容扫描
- **ClamAV 集成** - 实时恶意软件检测 - **Multipart/form 扫描** - 扫描上传和表单数据 - **Wirefilter 触发器** - 用于决定何时扫描的高级规则 - **扩展名过滤** - 跳过特定文件扩展名已测试的发行版
| 发行版 | 版本 | 状态 | 备注 | |--------------|---------|--------|-------| | **Ubuntu** | 24.04 LTS | ✅ 已测试 | 推荐 | | **Ubuntu** | 22.04 LTS | ✅ 已测试 | 完全支持 | | **Ubuntu** | 20.04 LTS | ✅ 已测试 | 所有功能, glibc 2.31 | | **Ubuntu** | 18.04 LTS | ✅ 已测试 | 所有功能, 内核 4.15→5.4 HWE | | **Ubuntu** | 16.04 LTS | ⚠️ 有限 | 仅 iptables 后端 (无 XDP) | | **Debian** | 12 (Bookworm) | ✅ 已测试 | 完全支持 | | **Debian** | 11 (Bullseye) | ✅ 兼容 | glibc 2.31 | | **RHEL/Rocky/Alma** | 9.x | ✅ 已测试 | 完全支持 | | **RHEL/CentOS** | 8.x | ⚠️ 兼容 | 内核 4.18 | | **Fedora** | 39+ | ✅ 兼容 | 最新内核 | | **Amazon Linux** | 2023 | ✅ 兼容 | AWS 优化 |内核功能要求
| 功能 | 用于 | 检查命令 | |---------|--------------|---------------| | **XDP** | 数据包过滤 | `grep XDP /boot/config-$(uname -r)` | | **BPF** | eBPF 程序 | `grep BPF /boot/config-$(uname -r)` | | **BTF** | BPF 类型格式 | `ls /sys/kernel/btf/vmlinux` |标签：CISA项目, Docker镜像, IP 地址批量处理, JA4指纹, JSONLines, Linux服务器安全, Rust, TLS证书管理, XDP, 入侵防御, 内核级安全, 包过滤, 反向代理, 可视化界面, 威胁情报, 子域名突变, 开发者工具, 开源安全工具, 搜索引擎查询, 服务器防护, 系统提示词, 网络安全, 网络流量审计, 请求拦截, 逆向工程平台, 通知系统, 防火墙, 隐私保护, 零信任