Getting Started
Synapse is a high-performance XDR with eBPF-powered firewall and reverse proxy built with Rust. Protect your Linux servers with kernel-level packet filtering and threat intelligence.
Quick Start
Ubuntu / Debian Install
curl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh
Run Synapse
# Run with config file
synapse -c /etc/synapse/config.yaml
# Set mode via environment variable (default: agent)
export MODE="proxy" # or "agent"
Installation Methods
Ansible
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
Supports Debian/Ubuntu and RedHat/CentOS/Fedora with optional ClamAV, Redis, and Fail2Ban.
Kubernetes (Helm)
helm repo add gen0sec https://helm.gen0sec.com
helm install synapse-stack
Killercoda Playground
curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh | bash -s -- --api-key <YOUR_API_KEY>
Docker
docker run \
--cap-add=SYS_ADMIN --cap-add=BPF --cap-add=NET_ADMIN \
-e API_KEY="your-api-key" \
-e MODE="proxy" \
synapse -c /etc/synapse/config.yaml
Required Capabilities
Docker containers need SYS_ADMIN, BPF, and NET_ADMIN capabilities for XDP/eBPF support.
Modes
Synapse runs in two modes: Agent (default) and Proxy.
| Feature | Proxy | Agent |
|---|---|---|
| HTTP/HTTPS Reverse Proxy | Yes | No |
| TLS & ACME Certificates | Yes | No |
| Upstreams & Load Balancing | Yes | No |
| WAF, Rate Limiting, CAPTCHA | Yes | No |
| Content Scanning (ClamAV) | Yes | No |
| XDP Firewall & Access Rules | Yes | Yes |
| Threat Intelligence & GeoIP | Yes | Yes |
| JA4+ Fingerprinting | Full | Network-level |
| BPF Stats & TCP Fingerprinting | Yes | Yes |
| File/Syslog Logging | Yes | Yes |
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.
mode: "agent" # default, can be omitted
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.
mode: "proxy"
proxy:
address_http: "0.0.0.0:80"
address_tls: "0.0.0.0:443"
upstream:
conf: "/etc/synapse/upstreams.yaml"
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 (Proxy) | Caching, certificate store |
| ClamAV | Optional | Content scanning |
Tested Distributions
| Distribution | Version | Status |
|---|---|---|
| Ubuntu | 24.04 LTS | Tested, Recommended |
| Ubuntu | 22.04 LTS | Tested |
| Ubuntu | 20.04 LTS | Tested |
| Debian | 12 (Bookworm) | Tested |
| RHEL/Rocky/Alma | 9.x | Tested |
| Fedora | 39+ | Compatible |
| Amazon Linux | 2023 | Compatible |
Post-Installation
1. Configure API Key
# Get your API key from https://dash.gen0sec.com/settings/api-keys
sudo nano /etc/synapse/config.yaml
platform:
api_key: "your-api-key"
2. Start the Service
sudo systemctl start synapse
sudo systemctl enable synapse
sudo systemctl status synapse
3. Verify
# Check logs
sudo journalctl -u synapse -f
Next Steps
- Synapse Overview - Full feature overview
- Installation Guide - Detailed installation options
- Configuration - Complete configuration reference
- Access Rules - Configure network access rules
- Threat Detection - Threat intelligence features