Skip to content

Deployment Tutorial

Jump to bottom
🔐Laurent M🔐 edited this page May 20, 2026 · 31 revisions

Deployment Tutorial

System Pre-requisites

Warning

Deprecation Notice: Alpine Linux > Alpine Linux support is officially deprecated. Please deploy SysWarden on systems utilizing the systemd ecosystem (RHEL, Debian, Ubuntu, etc).

Important

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

Ensure your system is fully up-to-date and has the essential core utilities installed before deploying SysWarden:

# 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

Standard Installation (Root Required)

First, clone the repository and assign execution privileges to the scripts:

git clone [https://github.com/duggytuxy/syswarden.git](https://github.com/duggytuxy/syswarden.git)
cd syswarden || exit
chmod +x build.sh
./build.sh

Execute the installer matching your OS:

# Debian / Ubuntu / RHEL / AlmaLinux
cd dist/ || exit
./install-syswarden.sh

Package Installation (.deb & .rpm)

Install SysWarden using native packages for your distribution.

# 1. Download the package and its associated checksum file
wget [https://github.com/duggytuxy/syswarden/releases/download/](https://github.com/duggytuxy/syswarden/releases/download/)<version>/syswarden_<version>_all.deb
# OR for RHEL/Rocky/AlmaLinux
wget [https://github.com/duggytuxy/syswarden/releases/download/](https://github.com/duggytuxy/syswarden/releases/download/)<version>/syswarden-<version>-1.noarch.rpm

wget [https://github.com/duggytuxy/syswarden/releases/download/](https://github.com/duggytuxy/syswarden/releases/download/)<version>/SHA256SUMS.txt

# 2. Verify Integrity
sha256sum -c SHA256SUMS.txt --ignore-missing

# 3. For Debian/Ubuntu systems
apt-get install -y ./syswarden_<version>_all.deb
syswarden /opt/syswarden/syswarden-auto.conf

# 4. For RHEL/AlmaLinux/Rocky systems
dnf install -y ./syswarden-<version>-1.noarch.rpm
syswarden /opt/syswarden/syswarden-auto.conf

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 script's provenance before execution.

# 1. Download the release bundle
wget https://github.com/duggytuxy/syswarden/releases/latest/download/syswarden-release.tar.gz

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

# 3. If the verification is successful (exit code 0), extract and run
tar -xzf syswarden-release.tar.gz
chmod +x install-syswarden.sh
./install-syswarden.sh

Unattended Installation (CI/CD / Ansible)

You can bypass all interactive 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"
SYSWARDEN_LIST_CHOICE="1"
SYSWARDEN_CUSTOM_URL=""
SYSWARDEN_ENABLE_GEO="n"
SYSWARDEN_GEO_CODES="ru cn kp ir"
SYSWARDEN_ENABLE_ASN="y"
SYSWARDEN_ASN_LIST="AS30823 AS210644"
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"
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 during installation:

cp syswarden-auto.conf dist/
cd dist/ || exit
./install-syswarden.sh syswarden-auto.conf

Enterprise Telemetry Dashboard Access

./install-syswarden.sh tui

or

syswarden tui (via package .deb or .rpm)

CLI Orchestration Commands

Note

./install-syswarden.sh or syswarden (via package .deb or .rpm)

# Forces an immediate refresh of the IPv4 blocklist, GeoIP datasets, and ASN tables.
./install-syswarden.sh update

# Opens the real-time terminal interface displaying active drops and Fail2ban dynamic jails.
./install-syswarden.sh alerts

# Interactively add a trusted IP address to bypass all overarching blocklists.
./install-syswarden.sh whitelist

# Interactively permanently ban a specific malicious IP address across all ports.
./install-syswarden.sh blocklist

# Instantly generates a new WireGuard client profile and displays the QR code.
./install-syswarden.sh wireguard-client

# Dynamically discover active services and reload Fail2ban jails without disruption.
./install-syswarden.sh fail2ban-jails

# Forces the injection of hermetic isolation rules into the DOCKER-USER chain.
./install-syswarden.sh protect-docker

# Fetches the latest SysWarden architecture from GitHub and performs a hot-reload.
./install-syswarden.sh upgrade

Day 2 Operations: The Manager CLI

The syswarden-manager.sh script provides strict, state-aware control over your firewall rules without requiring full orchestrator re-runs for simple tasks. It ensures that local files, Netfilter memory, and Fail2ban jails remain perfectly synchronized.

# 1. Global XDR Diagnostic (Checks Kernel, Fail2ban, and local files)
syswarden-manager.sh check <IP>

# 2. Immediate Kernel Drop (Hot-adds IP to hardware/L3 drop sets)
syswarden-manager.sh block <IP>

# 3. Surgical Unban (Clears from IPSet, Nftables, and Fail2ban memory)
syswarden-manager.sh unblock <IP>

# Interactively add Infrastructure IP addresses to bypass all overarching blocklists.
syswarden-manager.sh whitelist-infra

# 4. Absolute VIP Whitelist (Bypasses all drops at Priority -32000 / NIC level)
syswarden-manager.sh whitelist <IP>

# 5. Cloaked SSH Bypass (Allows a specific IP to bypass the VPN Guillotine)
syswarden-manager.sh allow-ssh <IP> [PORT]
syswarden-manager.sh revoke-ssh <IP>

# 6. Review all manual overrides and persistences
syswarden-manager.sh list

Compliance & Security Audit (syswarden-audit.sh)

A standalone Purple Team compliance script to verify DevSecOps locks post-installation. The tool features an interactive menu allowing you to run a full scan or selectively audit specific architectural phases:

  • Phase 1 & 2: Verifies OS Hardening, Privilege Separation, and Log Routing (Anti-Injection).
  • Phase 3 & 4: Audits the Kernel Shield, Threat Intelligence sets, and Layer 7 Fail2ban Engine.
  • Phase 5 & 6: Checks Telemetry Pipeline stability and validates Default-Deny Remote Access (VPN/SSH).
  • Phase 7 & 8: Exposed Services Mapping (CSPM) and Firewall Idempotency (Anti-Duplication rules).
./syswarden-audit.sh

Note

Results are simultaneously written to /var/log/syswarden-audit.log for SIEM ingestion.

Uninstallation (Scorched Earth)

Securely teardown all iptables 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.

./install-syswarden.sh uninstall

Clone this wiki locally