Getting Started

This Ansible playbook automates the installation and configuration of Synapse, providing a production-ready deployment with optional services like ClamAV, Redis, and Fail2Ban integration.

Overview

The Ansible playbook provides:

• Automated installation of Synapse and dependencies
• Support for Debian/Ubuntu and RedHat/CentOS/Fedora systems
• Automatic package detection (.deb/.rpm) with binary fallback
• Optional ClamAV and Redis installation
• Optional Fail2Ban integration with Gen0Sec API
• Modular role-based structure for flexibility
• Support for both Agent Mode and Proxy Mode

Operating Modes

Synapse supports two operating modes:

Agent Mode

• Purpose: Network-level firewall and access rules enforcement
• Features: XDP packet filtering, access rules, monitoring
• No Proxy: Does not handle HTTP/HTTPS traffic forwarding
• Use Cases: Edge firewall, network protection, access control without proxying
• Disabled Features: Threat Detection, Redis, GeoIP, Content Scanning, Pingora, ACME

Proxy Mode

• Purpose: Full reverse proxy with firewall capabilities
• Features: All agent mode features plus HTTP/HTTPS proxying, TLS termination, threat detection, ACME certificates
• Use Cases: Reverse proxy, load balancing, SSL termination, content scanning, threat detection
• All Features: Threat Detection, Redis, GeoIP, Content Scanning, Pingora, ACME enabled

Requirements

• Ansible 2.9 or later
• SSH access to target hosts with sudo privileges
• Linux kernel 4.18+ (for XDP support on target hosts)
• BPF support on target hosts

Quick Start

1. Clone the Repository

git clone https://github.com/gen0sec/synapse.git
cd synapse/ansible

2. Set Up Inventory File

Create your inventory file from the example:

cp hosts.example hosts

Edit hosts and add your server details:

# Single host
synapse-host ansible_host=192.168.1.100 ansible_user=root

# Or multiple hosts
[synapse-servers]
server1 ansible_host=192.168.1.100
server2 ansible_host=192.168.1.101

3. Configure Variables (Optional)

For better organization, you can use group variables:

mkdir -p group_vars
cp group_vars/all.example.yml group_vars/all.yml

Edit group_vars/all.yml and configure your settings:

synapse_version: "0.3.2"
synapse_branch: "main"
gen0sec_api_token: "your-api-key-here"
clamav_enabled: true
redis_enabled: true
fail2ban_enabled: true
# Operating mode: "agent" or "proxy" (default: "agent")
synapse_config_mode: "agent"

4. Run the Playbook

Run the playbook with the API token:

ansible-playbook playbook.yml -e gen0sec_api_token="your_api_key_here" --ask-become-pass

Or if you've configured group_vars/all.yml:

ansible-playbook playbook.yml

Configuration Variables

Synapse Variables

Variable	Default	Description
synapse_version	0.3.2	Version of Synapse to install
synapse_branch	main	GitHub branch for configuration files
gen0sec_api_token	""	Gen0Sec API token (can be set later)
clamav_enabled	true	Enable ClamAV installation and configuration
redis_enabled	true	Enable Redis installation
synapse_config_mode	"agent"	Operating mode: "agent" or "proxy"

Agent Mode Setup

Agent mode is the default and provides network-level firewall protection without HTTP proxying.

Quick Start - Agent Mode

1. Set up inventory and variables (as shown in Quick Start section above)

2. Configure for Agent Mode in group_vars/all.yml:

synapse_version: "0.3.2"
gen0sec_api_token: "your-api-key-here"
synapse_config_mode: "agent"  # Agent mode (default)
synapse_config_network_iface: "eth0"  # Auto-detected if not set
synapse_config_logging_level: "info"

3. Run the playbook:

ansible-playbook playbook.yml -e gen0sec_api_token="your_api_key_here" --ask-become-pass

Agent Mode Features

When running in agent mode, the following features are enabled:

• XDP-based packet filtering
• Access rules enforcement
• TCP fingerprinting (JA4+)
• BPF statistics
• Network monitoring

The following features are disabled in agent mode:

• Threat detection (requires proxy)
• Redis (not needed)
• GeoIP databases (not needed)
• Content scanning (requires proxy)
• Pingora proxy system (not used)
• ACME certificate management (not needed)

Agent Mode Configuration Example

# group_vars/all.yml
synapse_config_mode: "agent"
synapse_config_network_iface: "eth0"  # Primary interface (auto-detected)
synapse_config_arxignis_api_key: "your-api-key"
synapse_config_arxignis_log_sending_enabled: true
synapse_config_logging_level: "info"
synapse_config_bpf_stats_enabled: true
synapse_config_tcp_fingerprint_enabled: true

Proxy Mode Setup

Proxy mode provides full reverse proxy functionality with all features enabled.

Quick Start - Proxy Mode

1. Set up inventory and variables (as shown in Quick Start section above)

2. Configure for Proxy Mode in group_vars/all.yml:

synapse_version: "0.3.2"
gen0sec_api_token: "your-api-key-here"
clamav_enabled: true
redis_enabled: true
synapse_config_mode: "proxy"  # Enable proxy mode
synapse_config_network_iface: "eth0"  # Auto-detected if not set
synapse_config_logging_level: "info"
# Optional: Enable content scanning
synapse_config_content_scanning_enabled: true
# Optional: Configure ACME for TLS
synapse_config_acme_enabled: true
synapse_config_acme_email: "admin@example.com"

3. Run the playbook:

ansible-playbook playbook.yml -e gen0sec_api_token="your_api_key_here" --ask-become-pass

Proxy Mode Features

When running in proxy mode, all features are available:

• All agent mode features
• HTTP/HTTPS reverse proxy
• TLS termination (ACME or custom certificates)
• Content scanning with ClamAV
• GeoIP lookups
• Redis caching for certificates and threat intelligence
• Pingora proxy system
• ACME certificate management

Proxy Mode Configuration Example

# group_vars/all.yml
synapse_config_mode: "proxy"
synapse_config_network_iface: "eth0"  # Primary interface (auto-detected)
synapse_config_arxignis_api_key: "your-api-key"
synapse_config_redis_url: "redis://127.0.0.1/0"
synapse_config_redis_prefix: "g0s:synapse"
synapse_config_content_scanning_enabled: true
synapse_config_content_scanning_clamav_server: "localhost:3310"
synapse_config_acme_enabled: true
synapse_config_acme_email: "admin@example.com"
synapse_config_acme_storage_path: "/var/lib/synapse/acme"
synapse_config_logging_level: "info"

Proxy Mode with Upstream Configuration

For proxy mode, you'll also need to configure upstreams. The playbook downloads upstreams.yaml for binary installations. For package installations, create /etc/synapse/upstreams.yaml:

upstreams:
  - name: "backend"
    hosts:
      - address: "http://127.0.0.1:8081"
        weight: 100

Mode Comparison

Feature	Agent Mode	Proxy Mode
XDP Packet Filtering	✅	✅
Access Rules	✅	✅
Threat Detection	❌	✅
TCP Fingerprinting	✅	✅
HTTP/HTTPS Proxy	❌	✅
TLS Termination	❌	✅
Content Scanning	❌	✅
GeoIP Lookups	❌	✅
Redis Caching	❌	✅
ACME Certificates	❌	✅
Pingora Proxy	❌	✅

Fail2Ban Integration Variables

Variable	Default	Description
fail2ban_enabled	false	Enable Fail2Ban integration
gen0sec_expiration	600	Block expiration time in seconds (10 minutes)
fail2ban_jail_enabled	true	Enable fail2ban jails
fail2ban_backend	systemd	Fail2Ban backend (systemd or auto)

Installation Methods

The playbook automatically detects and uses the best installation method:

1. Package Installation (Preferred)

   • Detects package manager (apt, dnf, or yum)
   • Installs .deb package on Debian/Ubuntu
   • Installs .rpm package on RHEL/CentOS/Fedora

2. Binary Installation (Fallback)

   • Downloads binary if packages are unavailable
   • Downloads and configures config.yaml and upstreams.yaml

What Gets Installed

The playbook installs and configures:

• Dependencies: curl, sed, and other required packages
• Synapse: The reverse proxy and firewall application
• ClamAV (optional): Antivirus engine for content scanning
• Redis (optional): Caching backend for certificates and threat intelligence
• Fail2Ban (optional): Intrusion prevention with Gen0Sec API integration
• Systemd Service: Service configuration (enabled but not started)

Post-Installation

After the playbook completes:

1. Verify API Key

Check that your API key is set in the configuration:

grep api_key /etc/synapse/config.yaml

If not set, add it:

# Get your API key from https://dash.gen0sec.com/settings/api-keys
# Then edit /etc/synapse/config.yaml
sudo nano /etc/synapse/config.yaml

2. Start the Service

sudo systemctl start synapse

3. Check Service Status

sudo systemctl status synapse

4. Verify Installation

Test the health endpoint:

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "service": "synapse"
}

Fail2Ban Integration

To enable Fail2Ban integration with Gen0Sec API:

Enable via Command Line

ansible-playbook playbook.yml \
  -e gen0sec_api_token="your_api_key_here" \
  -e fail2ban_enabled=true
	--ask-become-pass

Enable via Group Variables

Add to group_vars/all.yml:

fail2ban_enabled: true
gen0sec_expiration: 600
fail2ban_jail_enabled: true
fail2ban_backend: systemd

The Fail2Ban integration will:

• Install fail2ban and jq
• Download and configure the Gen0Sec action file
• Configure jail.local with Gen0Sec integration
• Enable and start the fail2ban service

Advanced Usage

Customizing the Playbook

You can customize the playbook by:

1. Modifying roles: Edit role tasks in roles/synapse/tasks/main.yml
2. Adding custom tasks: Add tasks to playbook.yml
3. Using tags: Run specific parts with --tags:

# Only install Synapse, skip Fail2Ban
ansible-playbook playbook.yml --tags synapse

# Only configure Fail2Ban
ansible-playbook playbook.yml --tags fail2ban

Running on Specific Hosts

# Run on specific host group
ansible-playbook playbook.yml --limit synapse-servers

# Run on single host
ansible-playbook playbook.yml --limit server1

Dry Run

Test changes without applying them:

ansible-playbook playbook.yml --check --diff

Troubleshooting

Service Won't Start

1. Check logs:

   sudo journalctl -u synapse -n 50

2. Verify API key is set:

   sudo grep api_key /etc/synapse/config.yaml

3. Check configuration syntax:

   sudo synapse --config /etc/synapse/config.yaml --check

Package Installation Fails

The playbook automatically falls back to binary installation if packages are unavailable. Check the playbook output for the installation method used.

Network Interface Issues

Ensure the network interface specified in the configuration exists:

ip link show

Update /etc/synapse/config.yaml if needed:

network:
  iface: "eth0"  # Change to your interface

Switching Between Modes

To switch between agent and proxy modes after installation:

1. Edit the configuration:

sudo nano /etc/synapse/config.yaml

2. Change the mode:

# For agent mode
mode: "agent"

# For proxy mode
mode: "proxy"

3. Restart the service:

sudo systemctl restart synapse

Or update via Ansible:

ansible-playbook playbook.yml \
  -e gen0sec_api_token="your_api_key_here" \
  -e synapse_config_mode=proxy
	--ask-become-pass

Next Steps

• Configuration Guide - Detailed configuration options
• Daemon Mode - Running Synapse as a service
• Testing Guide - Validate your installation
• Access Rules - Configure network access rules
• Threat Detection - Threat detection features

Additional Resources

• Ansible Playbook Repository
• Get API Key
• Support