Back to Docs Hub

Deployment Tutorial

System Pre-requisites

Deprecation Notice: Alpine Linux

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

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

1. Standard Installation (Root Required)

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

git clone 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

2. 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/<version>/syswarden_<version>_all.deb
# OR for RHEL/Rocky/AlmaLinux
wget https://github.com/duggytuxy/syswarden/releases/download/<version>/syswarden-<version>-1.noarch.rpm

wget 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

3. 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

4. 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

5. Enterprise Telemetry Dashboard Access

SysWarden serves a real-time Telemetry Dashboard via a hardened Nginx reverse proxy. Setting SYSWARDEN_ENTERPRISE_MODE="y" disables outbound API reporting but keeps this local dashboard fully functional.

✓ URL: https://<YOUR_SERVER_IP>:9999 (Accept the self-signed certificate warning).
✓ Default-Deny Access: The dashboard enforces strict IP whitelisting. If WireGuard is enabled, your wg0 subnet is natively authorized. Otherwise, your current Admin SSH IP is whitelisted automatically.

6. CLI Orchestration Commands

# 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

7. 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

8. 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

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

9. Uninstallation (Scorched Earth)

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

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