Skip to content

Deployment Tutorial

Jump to bottom
🔐Laurent M🔐 edited this page Jul 3, 2026 · 31 revisions

Deployment Tutorial

System Pre-requisites

Warning

Deprecation Notice: Legacy Bash Scripts
The legacy Bash orchestrator scripts (install-syswarden.sh, syswarden-manager.sh) are officially deprecated. SysWarden is now a fully compiled Go ecosystem.

Important

Supported OS: Debian 12+, Ubuntu 24.04+, RHEL 9+, Oracle Linux 10+, Fedora 43+, CentOS Stream, AlmaLinux 10+, Rocky Linux 9+, Alpine Linux 3.21+ & FreeBSD 14+.

Ensure your system is fully up-to-date before deploying SysWarden:

# FreeBSD 14+
pkg update && pkg install -y wget curl git

# Debian / Ubuntu
apt update && apt upgrade -y && apt install wget curl git -y

# RHEL / AlmaLinux / Rocky Linux / Fedora
dnf update -y && dnf install wget curl git -y

Package Installation (.deb & .rpm) (Recommended)

Install SysWarden using native packages for your distribution. This method places the syswarden Go binary natively in your PATH and sets up all required directories.

# 1. Fetch the latest release version automatically
VERSION=$(curl -s https://api.github.com/repos/duggytuxy/syswarden/releases/latest | grep '"tag_name":' | cut -d '"' -f 4)
V_NUM=${VERSION#v}

# 2. Download the appropriate package for your distribution and its associated checksum file from the GitHub assets
# For Debian/Ubuntu (amd64 & arm64)
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden_${V_NUM}_amd64.deb
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden_${V_NUM}_arm64.deb
# For RHEL/AlmaLinux/Rocky (x86_64 & aarch64)
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden-${V_NUM}-1.x86_64.rpm
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden-${V_NUM}-1.aarch64.rpm
# For Alpine Linux (x86_64 & aarch64)
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden_${V_NUM}_x86_64.apk
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden_${V_NUM}_aarch64.apk
# For FreeBSD 14+ (amd64)
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden-${V_NUM}.txz

# Also download the checksum file
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/SHA256SUMS.txt

# 3. Verify package integrity
sha256sum -c SHA256SUMS.txt --ignore-missing

# 4. Install the package
# For Debian/Ubuntu systems
apt-get install -y ./syswarden_${V_NUM}_*.deb

# For RHEL/AlmaLinux/Rocky systems
dnf install -y ./syswarden-${V_NUM}-1.*.rpm

# For Alpine Linux
apk add --allow-untrusted ./syswarden_${V_NUM}_*.apk

# For FreeBSD 14+ systems
pkg add ./syswarden-${V_NUM}.txz

Source Installation (Go 1.26+ Required)

If you wish to compile SysWarden natively from source, ensure you have Go 1.26+ installed.

# Clone the repository
git clone https://github.com/duggytuxy/syswarden.git
cd syswarden || exit

# Compile all modules (Core, CLI, TUI) via the PowerShell script
./build.ps1

# OR compile manually via the Go workspace
cd src/core/syswarden-cli && go build -o syswarden main.go
mv syswarden /usr/local/bin/

Enterprise Installation (Default-Deny / SLSA Level 3)

SysWarden releases are cryptographically signed using GitHub Artifact Attestations to guarantee supply chain integrity. For environments compliant with ISO 27001 or NIS2, it is imperative to verify the binary's provenance before execution.

# 1. Fetch the latest release version automatically
VERSION=$(curl -s https://api.github.com/repos/duggytuxy/syswarden/releases/latest | grep -oP '"tag_name": "\K(.*)(?=")')

# 2. Download the release bundle
wget https://github.com/duggytuxy/syswarden/releases/download/${VERSION}/syswarden-release.tar.gz

# 3. Verify the cryptographic attestation using the official GitHub CLI
gh attestation verify syswarden-release.tar.gz --owner duggytuxy

# 4. If the verification is successful (exit code 0), extract the bundle and deploy
tar -xzf syswarden-release.tar.gz

Unattended Installation & Configuration (CI/CD / Ansible)

You can bypass interactive installation prompts by providing a configuration file (syswarden-auto.conf). This is perfect for fleet management or Terraform cloud-init deployments.

# Complete configuration example for syswarden-auto.conf
SYSWARDEN_ENTERPRISE_MODE="n"
SYSWARDEN_SSH_PORT="22"
SYSWARDEN_FIREWALL_BACKEND="nftables"
SYSWARDEN_WHITELIST_INFRA="y"
SYSWARDEN_WHITELIST_IPS="192.168.1.50 203.0.113.10"
SYSWARDEN_ENABLE_WG="y"
SYSWARDEN_WG_PORT="51820"
SYSWARDEN_WG_SUBNET="10.66.66.0/24"
SYSWARDEN_USE_DOCKER="y"
SYSWARDEN_HARDENING="n"
APPLY_CIS_L2_HARDENING="y"

# Layer 2 / Network Interface Filtering
SYSWARDEN_ENABLE_L2="y"
SYSWARDEN_ARP_PROTECT="y"

# Local LAN Mode (Air-Gapped)
SYSWARDEN_LAN_MODE="n"
# Honeyports (Insider Threat L3 Lures)
SYSWARDEN_HONEYPORTS="6379, 3306"

SYSWARDEN_LIST_CHOICE="1"
SYSWARDEN_CUSTOM_URL=""
SYSWARDEN_ENABLE_GEO="n"
# Classic mode: block these countries
SYSWARDEN_GEO_CODES="ru cn kp ir"
# Zero-Trust Strict ALLOW: if populated (e.g. "FR DE"), all other countries are blocked
SYSWARDEN_GEO_ALLOWED=""

SYSWARDEN_ENABLE_ASN="y"
# Classic mode: block these ASNs
SYSWARDEN_ASN_LIST="AS30823 AS210644"
# Zero-Trust Strict ALLOW: if populated (e.g. "AS1234"), all other ASNs are blocked
SYSWARDEN_ASN_ALLOWED=""
SYSWARDEN_USE_SPAMHAUS="y"
SYSWARDEN_ENABLE_ABUSE="y"
SYSWARDEN_ABUSE_API_KEY="your_80_char_api_key_here"
SYSWARDEN_REPORT_F2B="y"
SYSWARDEN_REPORT_FW="y"

# High-Availability Cluster Configuration
SYSWARDEN_HA_ENABLED="y"
SYSWARDEN_HA_PEER_IP="10.0.0.2"
SYSWARDEN_HA_PEER_PORT="22"
SYSWARDEN_HA_STRICT_HOST_KEY="n"

# SIEM Forwarding Configuration
SYSWARDEN_SIEM_ENABLED="y"
SYSWARDEN_SIEM_IP="192.168.1.100"
SYSWARDEN_SIEM_PORT="514"
SYSWARDEN_SIEM_PROTO="udp"
SYSWARDEN_SIEM_TLS_CA="/etc/ssl/certs/siem.pem"

# Wazuh HIDS Integration
SYSWARDEN_ENABLE_WAZUH="y"
SYSWARDEN_WAZUH_IP="10.0.0.5"
SYSWARDEN_WAZUH_NAME="web-prod-01"
SYSWARDEN_WAZUH_GROUP="default"
SYSWARDEN_WAZUH_COMM_PORT="1514"
SYSWARDEN_WAZUH_ENROLL_PORT="1515"
SYSWARDEN_SECURE_WIPE_CONF="y"

Pass the file as an argument to the CLI:

syswarden install --config /path/to/syswarden-auto.conf

Enterprise Telemetry Dashboard Access

SysWarden v2.00.0 introduces two distinct Terminal User Interfaces (TUI) for real-time observability of the system daemon (syswarden-core) and WAF.

# Launch the main interactive terminal dashboard
syswarden tui

# Display real-time security alerts and blocked attacks
syswarden alerts

CLI Orchestration Commands

Note

All actions are now centralized in the single syswarden Go binary.

# Refresh Threat Intelligence feeds (IPv4/IPv6 blocklists, GeoIP, ASN tables)
syswarden update-feeds

# Hot-reload the firewall backend and rules without dropping active connections
syswarden reload

# Add a trusted IP address or Subnet (CIDR) to bypass all overarching blocklists
syswarden whitelist <IP/CIDR>

# Permanently ban a specific malicious IP or Subnet across all ports
syswarden block <IP/CIDR>

# Remove an IP or Subnet from the blocklist
syswarden unblock <IP/CIDR>

# Remove an IP or Subnet from the whitelist
syswarden unwhitelist <IP/CIDR>

# Display current high-availability synchronization status
syswarden ha-sync

Day 2 Operations: Real-time Rules & Exceptions

The syswarden binary provides state-aware control over your firewall rules. It strictly synchronizes the local configuration files, the Netfilter/nftables memory, and the Fail2ban jails simultaneously.

# 1. Global Diagnostic (Checks Kernel rules, states, and configurations)
syswarden check <IP>

# 2. Absolute VIP Whitelist (Bypasses all drops at hardware/L3 level)
syswarden whitelist <IP/CIDR>

# 3. Add Infrastructure IP addresses to selectively bypass blocklists
syswarden infra <IP>

# 4. Cloaked SSH Bypass (Allows a specific IP to dynamically bypass the VPN Guillotine/SSH drop)
syswarden allow-ssh <IP> <PORT>
syswarden revoke-ssh <IP>

# 5. List all manual overrides and persistent memory rules
syswarden list

Compliance & Security Audit (syswarden audit)

A standalone Purple Team compliance subcommand to verify DevSecOps locks post-installation. It automatically runs phases corresponding to OS Hardening, Log Routing, Threat Intelligence, Telemetry, and Default-Deny remote access checks.

syswarden audit

Note

The audit tool interacts directly with the syswarden-core daemon via Unix Domain Sockets to validate idempotency and system integrity without shell-outs.

Native Autocompletion (TAB)

SysWarden CLI is built with cobra and natively supports shell auto-completion for bash, zsh, fish, and powershell. When installing SysWarden via .deb or .rpm packages, the completion script is automatically generated and placed into /etc/bash_completion.d/syswarden.

You can simply type sudo syswarden and press <TAB> to see all available commands and flags.

Replacing Fail2ban (Native WAAP L7 Engine)

Starting with v2.01.0, SysWarden completely replaces Fail2ban. It autonomously tails your application logs (Traefik, Nginx, Apache) in a lightweight asynchronous Goroutine, parsing for HTTP 401/403/404 errors.

To enable it, we strongly recommend reading the syswarden manual to master the architecture, then simply edit your configuration using syswarden config and fill in the following variables:

# Space-separated list of application access logs to tail
SYSWARDEN_BRUTEFORCE_LOGS="/var/log/traefik/access.log /var/log/nginx/*.log"
# Number of authentication failures allowed before ban
SYSWARDEN_BRUTEFORCE_THRESHOLD="5"
# Sliding window in seconds for the threshold
SYSWARDEN_BRUTEFORCE_WINDOW="60"

Once configured, run syswarden reload or syswarden install. You can safely uninstall Fail2ban (apt-get purge fail2ban) as SysWarden natively tracks these attacks in-memory without any OS resource bloat.

Tip

Pro Tip (Zero-Config WAAP Auto-Discovery): By default, SYSWARDEN_BRUTEFORCE_LOGS is set to "auto". SysWarden will intelligently scan your server and automatically monitor Nginx, Apache, Caddy, Traefik, or Lighttpd logs if they exist. If you prefer manual configuration, you can specify exact paths separated by a space (e.g. /path/to/nginx.log /path/to/apache.log), or use the wildcard * (e.g. /var/log/nginx/*.log). If left empty (""), the WAAP (L7) engine sleeps completely (0% CPU usage).

Layer 2 Protection (Anti-ARP Flooding)

Starting with v2.01.11, SysWarden offers robust OSI Layer 2 protection to secure virtual instances (Docker, Proxmox) and physical LAN environments. This natively operates via nftables using the netdev and arp families.

# Enable OSI Layer 2 ARP Spoofing Prevention
SYSWARDEN_ENABLE_L2="y"

# Activate strict ARP Flooding protection (Limits ARP requests to 10/second to prevent network poisoning without breaking HA/VRRP)
SYSWARDEN_ARP_PROTECT="y"

Local LAN Mode (Air-Gapped / Zero-Trust)

If SysWarden is installed on a strictly internal, non-exposed server (e.g., inside a private VLAN without NAT Port-Forwarding), you can explicitly enable LAN Mode.

SYSWARDEN_LAN_MODE="y"

# If you have a custom blocklist hosted internally:
SYSWARDEN_LIST_CHOICE="3"
SYSWARDEN_CUSTOM_URL="https://your-internal-server.local/custom_blocklist.txt"

When enabled, SysWarden intelligently skips the massive downloads of public OSINT blocklists (Data-Shield, GeoIP, ASN) to heavily conserve RAM and Bandwidth. It will strictly focus on internal Zero-Trust defenses: Advanced WAAP (L7) monitoring (SQLi, XSS, Brute-force), ARP protections (L2), and processing your Custom IP Lists (defined via the SYSWARDEN_CUSTOM_URL above).

Insider Threat Detection (Shadow Mode & Honeyports)

Starting with v3.20.0, SysWarden introduces Shadow Mode and Honeyports for zero-trust internal network defense.

1. Shadow Mode When a whitelisted infrastructure IP or an administrator triggers a WAAP (L7) rule or hits a Honeyport (e.g., trying an RCE or brute-force), SysWarden intelligently prevents locking them out. Instead of an L3 DROP, it triggers a SHADOW-ALERT.

  • Effect: Service continues without interruption.
  • Observability: SOC immediately receives a highly visible notification (Slack, Discord, Teams) and the alert flashes ORANGE in syswarden tui.

2. Honeyports (L3 Lures) Deploy fake, non-existent ports directly in the kernel firewall to trap internal scanners.

# Comma-separated list of decoy ports to trap attackers
SYSWARDEN_HONEYPORTS="6379, 27017, 3306"

Any external connection to these ports instantly results in an IP ban. Internal whitelisted IPs trigger a Shadow Alert.

Uninstallation (Scorched Earth)

Securely teardown all iptables/nftables drops, Fail2ban jails, UI Dashboards, SQLite databases, Cron jobs, and IP datasets.

Caution

This is a true Scorched Earth uninstallation. It actively flushes systemd journals and log files to prevent Ghost IPs from resurrecting during future installations, while explicitly protecting your Wazuh Agents and custom WireGuard configurations.

syswarden uninstall

Clone this wiki locally