Getting Started
Synapse is a high-performance Active NDR agent built in Rust. On Linux it filters and fingerprints in the kernel via eBPF/XDP. A Windows agent ships too, capturing at L4 through an NDIS filter and able to use eBPF for Windows for XDP filtering. The unified firewall rule backend is still in development there, so pages below describe Linux unless they say otherwise.
Quick Start
1. Get your credentials
Two different secrets, from two places in the dashboard:
| Where | For | |
|---|---|---|
| Repository credential | Clients → Repository Access | Downloading the packages |
| API key | API keys | The running agent, as platform.api_key |
The repository credential is scoped per host — tick APT, RPM, Docker or Releases for the channels you install from. A key without the right scope fails as an authentication error.
2. Pick your build
Two choices — a role, and whether the ML models come with it:
| Package | Role | ML |
|---|---|---|
synapse-agent | Telemetry, firewall enforcement and IDS on the host. Most machines want this. | — |
synapse-proxy | Terminates traffic you route through it, inspects it at L7. | — |
synapse-agent-ml / synapse-proxy-ml | The same, plus bundled models for on-host inference. | Yes |
The four conflict, so one at a time — and the systemd unit is named after the package you chose.
3. Add the repository
Debian and Ubuntu below; RHEL, binary, Docker, Kubernetes and Windows are on the Installation Guide.
export GEN0SEC_KEY='<your repository credential>'
# The credential apt authenticates with
sudo install -d -m 0755 /etc/apt/auth.conf.d
printf 'machine apt.gen0sec.com login x password %s\n' "$GEN0SEC_KEY" \
| sudo tee /etc/apt/auth.conf.d/gen0sec.conf > /dev/null
sudo chmod 600 /etc/apt/auth.conf.d/gen0sec.conf
# The key it verifies the repository against, from a keyserver rather than
# from a Gen0Sec host — so trust needs no credential of its own.
sudo install -d -m 0700 /root/.gnupg
sudo gpg --keyserver hkp://keyserver.ubuntu.com:80 --no-default-keyring \
--keyring /usr/share/keyrings/gen0sec.gpg \
--recv-keys C1631499081A7146332D2038798FF49A6E9DA146
# The source itself
echo "deb [signed-by=/usr/share/keyrings/gen0sec.gpg] https://apt.gen0sec.com stable main" \
| sudo tee /etc/apt/sources.list.d/gen0sec.list > /dev/null
4. Install
sudo apt-get update
sudo apt-get install -y synapse-agent
sudo systemctl enable --now synapse-agent
5. Connect it to the platform
# /etc/synapse/config.yaml
platform:
api_key: "<your API key>"
sudo systemctl restart synapse-agent
Then check it came up:
systemctl status synapse-agent
journalctl -u synapse-agent -f
A healthy start logs the interfaces it attached to.
Modes
Agent and Proxy differ in what they can enforce. You select between them by installing the matching package, above.
| Feature | Proxy | Agent |
|---|---|---|
| HTTP/HTTPS Reverse Proxy | Yes | No |
| TLS Termination | 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 | Full on Linux, L4-only on Windows |
| 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 | Optional | Shared certificate store across proxy instances; storage defaults to file |
| 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 |
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