Skip to content

INSTALLATION.md

Latest commit

 

History

History
213 lines (149 loc) · 4.86 KB

INSTALLATION.md

File metadata and controls

213 lines (149 loc) · 4.86 KB
Raw

Installation

Linux (quick install)

curl -fSL https://raw.githubusercontent.com/gen0sec/synapse/refs/heads/main/install.sh | sh

The installer sets up synapse-agent (agent mode) or synapse-proxy (proxy mode) as a systemd service.

# Start agent (default / firewall-only)
systemctl enable --now synapse-agent

# Or start proxy (full L7 inspection)
systemctl enable --now synapse-proxy

# Reload config at runtime
systemctl kill -s HUP synapse-agent

Configuration file: /etc/synapse/config.yaml

Windows

One-liner (PowerShell 5+, run as Administrator):

iwr -useb https://raw.githubusercontent.com/gen0sec/synapse/main/install.ps1 | iex

Or double-click install.bat (auto-elevates, no PowerShell setup required):

install.bat                     # interactive
install.bat YOUR-API-KEY        # with API key
install.bat /uninstall          # remove

Or run install.ps1 directly for full control:

# With API key
powershell -ExecutionPolicy Bypass -File install.ps1 -ApiKey "your-key"

# With eBPF for Windows (XDP/BPF packet filtering)
powershell -ExecutionPolicy Bypass -File install.ps1 -ApiKey "your-key" -WithEBPF

# Without registering as a service
powershell -ExecutionPolicy Bypass -File install.ps1 -NoService

# Uninstall (preserves config and logs)
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall

# Uninstall and purge all data
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall -PurgeConfig

After install, manage the service:

sc start Synapse
sc stop Synapse
sc control Synapse paramchange   # reload config without restart
synapse.exe --terminal           # open live TUI dashboard

Config: C:\ProgramData\Gen0Sec\Synapse\config.yaml Logs: C:\ProgramData\Gen0Sec\Synapse\logs\

On Windows, Synapse runs in agent mode. XDP/eBPF support requires eBPF for Windows v1.1.0+ with test signing enabled (bcdedit /set testsigning on). Pass -WithEBPF to the installer to download it automatically.

Ansible

git clone https://github.com/gen0sec/synapse.git
cd synapse/moat/ansible
cp hosts.example hosts
# Edit hosts with your server IPs
ansible-playbook playbook.yml -e gen0sec_api_token=your_key_here

The playbook supports Debian/Ubuntu and RedHat/CentOS/Fedora. Optional features: ClamAV, Redis, Fail2Ban.

Full details: ansible/README.md

Kubernetes / Helm

helm repo add gen0sec https://helm.gen0sec.com
helm repo update
helm search repo gen0sec   # gen0sec/synapse, gen0sec/synapse-stack

Minimal install:

export ARX_KEY="your-api-key"

helm upgrade --install synapse-stack gen0sec/synapse-stack \
  -n synapse --create-namespace \
  --set synapse.synapse.server.upstream="http://your-service:8080" \
  --set synapse.synapse.arxignis.apiKey="$ARX_KEY"

Wait for rollout:

kubectl -n synapse rollout status deploy/synapse-stack

Full Helm reference: docs/KUBERNETES.md

Docker

docker run \
  --cap-add=SYS_ADMIN \
  --cap-add=BPF \
  --cap-add=NET_ADMIN \
  -v /etc/synapse:/etc/synapse \
  ghcr.io/gen0sec/synapse:latest \
  -c /etc/synapse/config.yaml

Required capabilities:

  • SYS_ADMIN — eBPF program loading
  • BPF — BPF map access
  • NET_ADMIN — XDP attachment and nftables/iptables management

Killercoda playground

Try Synapse in the browser with no installation:

curl -sSL https://raw.githubusercontent.com/gen0sec/synapse/main/scenarios/synapse-operator/synapse.sh \
  | bash -s -- --api-key <YOUR_API_KEY>

Daemon mode (Linux background process)

Use daemon mode to run Synapse as a detached background process with privilege dropping:

daemon:
  enabled: true
  pid_file: "/var/run/synapse.pid"
  working_directory: "/"
  user: "nobody"
  group: "daemon"
  chown_pid_file: true

CLI flags:

synapse --daemon \
  --daemon-pid-file /var/run/synapse.pid \
  --daemon-user nobody \
  --daemon-group daemon \
  -c /etc/synapse/config.yaml

Signal handling:

# Reload config
kill -HUP $(cat /var/run/synapse.pid)

# Graceful shutdown
kill -TERM $(cat /var/run/synapse.pid)

Environment variables: DAEMON_ENABLED, DAEMON_PID_FILE, DAEMON_WORKING_DIRECTORY, DAEMON_USER, DAEMON_GROUP, DAEMON_CHOWN_PID_FILE.

Full daemon documentation: DAEMON_MODE.md

Building from source

# Clone
git clone https://github.com/gen0sec/synapse.git
cd synapse

# Default build (includes eBPF/XDP + IDS)
cargo build --release

# Run tests
cargo test

Build dependencies (Ubuntu/Debian):

apt-get install clang llvm libelf-dev libssl-dev zlib1g-dev \
  libzstd-dev pkg-config libcap-dev binutils-multiarch-dev cmake

See REQUIREMENTS.md for full dependency and platform information.