Back to Docs Hub

Deployment Tutorial

System Pre-requisites

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

# Alpine Linux
apk update && apk upgrade && apk add curl wget git bash

# Slackware (via slackpkg)
slackpkg update && slackpkg upgrade-all
slackpkg install wget curl git

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
chmod +x *.sh

Execute the installer matching your OS:

# Debian / Ubuntu / RHEL / AlmaLinux
./install-syswarden.sh

# Alpine Linux (OpenRC)
./install-syswarden-alpine.sh

# Slackware (BSD-init)
./install-syswarden-slackware.sh

2. 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_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"
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"

Pass the file as an argument during installation:

./install-syswarden.sh syswarden-auto.conf

3. 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).
✓ Zero Trust 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.

4. CLI Orchestration Commands

Note: Replace install-syswarden.sh with the Alpine/Slackware equivalent if applicable.

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

# 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

6. 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 Zero Trust 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.

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