Website   •   Issues Tracker   •   Linkedin   •   TryHackMe   •   Ko-Fi

SysWarden

SysWarden is an enterprise-grade, open-source firewall orchestrator designed to eliminate 99% of noisy, disruptive, and malicious internet traffic. Built around the Data-Shield IPv4 Blocklists community, it dynamically integrates GeoIP filtering, Spamhaus ASN blocking, and Fail2ban intrusion prevention. > Engineered for modern infrastructure, SysWarden provides hermetic Docker protection, automated AbuseIPDB reporting, and deploys a stealth WireGuard management VPN—all operating natively within the Linux kernel to guarantee maximum security with near-zero RAM consumption.

What Does SysWarden Protect?

SysWarden acts as an advanced, preemptive orchestration layer for your infrastructure. By leveraging community-driven threat intelligence and dropping malicious traffic natively at the firewall level (Kernel-Space) before it ever reaches your applications, it provides a highly optimized, impenetrable shield for your exposed assets.

It is highly recommended for securing:

• Public VPS & Bare Metal Servers: Defend your SSH ports, control panels, and core services against relentless brute-force campaigns and mass-scanning. SysWarden can even deploy a stealth WireGuard VPN to make your management interfaces completely invisible to the public internet.
• Websites & CMS (WordPress, Nginx, Apache): Instantly filter out bad bots, vulnerability scanners, and automated exploit attempts. By blocking threats at the network edge, your web servers preserve massive amounts of CPU and RAM for legitimate visitors.
• Public APIs & SaaS Platforms: Protect your endpoints from aggressive data scrapers, automated abuse, and Layer 7 DDoS probes, ensuring your resources remain dedicated to real users and your SLAs stay intact.
• Dockerized & Critical Infrastructure: Automatically injects hermetic firewall rules directly into the DOCKER-USER chain, guaranteeing that your exposed containers are shielded from global threats without breaking internal routing.
• Databases (MySQL, MongoDB, PostgreSQL): Shield your data stores from credential stuffing, unauthorized access, and ransomware gangs using a formidable combination of massive static IP sets and dynamic Fail2ban intrusion prevention.

By permanently silencing the internet's malicious "background noise", SysWarden ensures your infrastructure remains blazing fast, deeply secure, and focused entirely on serving real humans—while automatically reporting attackers back to the global community via AbuseIPDB.

Architecture

SysWarden (Technology Stack)
├── Core Orchestration
│   ├── Bash Scripting             # Automation, Logic & Hot-Reloading
│   └── Linux OS & Kernel          # Broad Support (Debian/Ubuntu, RHEL/Alma, Alpine)
│
├── Firewall & Networking Engine
│   ├── Nftables                   # Modern Packet Filtering (Flat Syntax & Chunking)
│   ├── IPSet + Iptables           # High-Performance Hashing (Legacy Fallback)
│   ├── Firewalld                  # Dynamic Zone Management (RHEL Ecosystem)
│   ├── Docker Integration         # Native DOCKER-USER Chain Isolation
│   └── WireGuard VPN              # Stealth Management Interface & Dynamic Clients
│
├── Active Defense & Daemons
│   ├── Python 3 (Daemon)          # Asynchronous AbuseIPDB API Reporting
│   ├── Python 3 (HTTP Server)     # Serverless Telemetry Dashboard UI
│   ├── Fail2ban                   # Dynamic Intrusion Prevention System (Custom Jails)
│   ├── Systemd / OpenRC           # OS-Specific Service & Persistence Management
│   └── Logrotate                  # Log Maintenance & Space Optimization
│
└── Threat Intelligence & Integrations
    ├── Data-Shield IPv4 Blocklist # Primary Threat Intelligence Source
    ├── Spamhaus / RADB            # Dynamic ASN Routing Data Validation
    ├── IPDeny                     # Country-Level Geo-Blocking Data Sets
    ├── AbuseIPDB API              # Community Attack Reporting (Outbound)
    └── Wazuh XDR Agent            # SIEM, File Integrity & Vulnerability Detection

Key Features

• Strict SSH Cloaking (Zero Trust): Enforces a mathematically absolute policy for SSH. Access is exclusively restricted to the WireGuard VPN (wg0) and Loopback (lo) interfaces. An immediate, top-priority kernel DROP rule explicitly prevents any public access, ensuring that even locally whitelisted IPs cannot bypass the VPN requirement for SSH.
• Serverless Telemetry Dashboard: A lightweight, real-time Web UI served via a native Python HTTP daemon. It provides live Layer 3 (Kernel) and Layer 7 (Fail2ban) blocking statistics, active jail triggers, and real-time IP registries without requiring heavy web servers like Nginx or Apache.
• Firewall State Machine: CLI commands (whitelist, blocklist) operate on a strict "Single Source of Truth" model. They securely write to local persistence files, universally purge memory conflicts, and trigger the orchestrator to completely rebuild the firewall safely, preserving the strict rule hierarchy across all OS backends.
• Universal OS Support: Auto-detects and seamlessly adapts to Debian, Ubuntu, CentOS Stream, Fedora, AlmaLinux, Rocky Linux, and Alpine Linux (OpenRC).
• Intelligent Backend Detection & Routing: Automatically selects and configures the optimal firewall technology present on your system (Nftables Flat Syntax, Firewalld Rich Rules, or IPSet/Iptables).
• Multi-Layer Threat Filtering: Instantly drops over 100,000+ known malicious IPs, restricts traffic from high-risk countries via GeoIP, and blocks rogue ASNs via Spamhaus/RADB.
• Hermetic Docker Isolation: Automatically secures exposed containers by injecting specialized rules into the DOCKER-USER chain without breaking internal bridge networking.
• Stealth Management VPN: Deploys a native WireGuard interface to hide your management ports from the public internet, including a built-in CLI orchestrator to instantly generate client profiles and QR codes.

Objectives

• Noise Reduction & Log Clarity: Drastically reduce log fatigue and SIEM ingestion costs (/var/log/auth.log, journalctl) by instantly dropping automated scanners, brute-forcers, and botnets at the network edge.
• Resource & Compute Optimization: Conserve critical CPU cycles, RAM, and bandwidth by dropping illegitimate packets natively in Kernel-Space rather than allowing user-space applications to process them.
• Proactive Community Security: Shift your infrastructure from a vulnerable "Reactive" stance to a fortified "Proactive" stance, preemptively blocking IPs that have attacked other community servers minutes ago.

Technical Deep Dive: Architectural Layering

A common concern among infrastructure engineers is that deploying massive static blocklists might conflict or create race conditions with dynamic Intrusion Prevention Systems (IPS) like Fail2ban. SysWarden elegantly resolves this through strict, sequential network layering.

Traffic Workflow

/ (Inbound Network Traffic Flow)
├── Layer 1: Kernel-Space Shield (Preemptive Static Defense)
│   ├── Orchestrator : Nftables (Flat Syntax) / Firewalld / IPSet (Auto-detected)
│   ├── Threat Intel : 100k+ Malicious IPs, Global GeoIP & ASN Routing Data
│   ├── Edge Routing : Handled natively, including DOCKER-USER chain isolation
│   └── Action       : DROP packets silently before they ever reach User-Space
│
└── Layer 2: User-Space Applications (Permitted Traffic)
    ├── Exposed Services & Proxies
    │   ├── Custom Ports (SSH, Web, Database, APIs)
    │   ├── WireGuard    (Stealth Management Interface & VPN)
    │   └── System Logs  (e.g., /var/log/syslog, journalctl, dmesg)
    │
    └── Layer 3: Active Response (Dynamic & Behavioral Defense)
        ├── Fail2ban Engine
        │   ├── Monitor : Behavioral anomalies & Brute-force patterns across services
        │   └── Action  : Inject dynamic, localized bans into the firewall backend
        │
        ├── SysWarden Python Daemon
        │   ├── Monitor : Real-time Firewall drops & Fail2ban verdicts via buffer
        │   └── Action  : Asynchronously report telemetry back to AbuseIPDB API
        │
        └── Wazuh XDR Agent (Optional)
            ├── Monitor : File Integrity Monitoring (FIM) & Critical System Events
            └── Action  : Stream encrypted security telemetry to Wazuh SIEM

1. The Nftables Engine & Fail2ban Synergy (Debian, Ubuntu, Alpine)

• Layer 1 (Preemptive Defense): SysWarden leverages a modern Nftables "Flat Syntax" architecture and intelligent chunking to inject massive, high-performance sets (100k+ IPs, GeoIP, ASN). This acts as an impenetrable static shield, dropping known threat actors at the Kernel level with a near-zero memory footprint.
• Layer 2 (Dynamic Analysis): Fail2ban serves as the secondary behavioral net, monitoring application logs for localized, zero-day brute-force attempts.
• The Result: Fail2ban's CPU and RAM consumption drops to virtually zero. By letting the Nftables engine filter out the internet's "background noise", Fail2ban only processes logs for traffic that has already passed the strict global blocklist.

2. The Firewalld Orchestration (RHEL, AlmaLinux, Rocky Linux)

On Enterprise Linux distributions, adhering to native firewalld architecture is critical for system stability and compliance.

• Native IPSet Integration: SysWarden programmatically defines massive, permanent ipset types deeply embedded within Firewalld's native XML configuration framework.
• Rich Rule Processing: It deploys high-priority "Rich Rules" that intercept and drop malicious traffic globally.
• Absolute Persistence: SysWarden strictly commits all configurations directly to /etc/firewalld/, ensuring absolute persistence across daemon reloads and hard reboots.

3. Community Threat Intelligence: AbuseIPDB Reporting

SysWarden operates on the philosophy of collective defense. It deploys an asynchronous Python daemon that actively parses firewall drops and Fail2ban jails, reporting confirmed attackers back to the AbuseIPDB platform to protect servers worldwide.

• Seamless Activation: Simply confirm the prompt with y during the interactive installation phase.
• API Authentication: Provide your standard AbuseIPDB API key. The daemon will securely store the credentials and autonomously push telemetry, helping keep the global registry of malicious IPv4 addresses highly accurate and up to date without impacting firewall performance.

4. Enterprise SIEM: Wazuh XDR Agent Integration

For organizations operating under strict compliance or utilizing centralized SIEM architectures, SysWarden includes a fully automated deployment pipeline for the Wazuh XDR Agent, flawlessly bridging edge firewall protection with centralized security telemetry.

• Zero-Touch Deployment: The orchestrator automatically identifies the host OS, securely fetches the official GPG keys and repositories, and installs the latest stable agent.
• Dynamic Provisioning: By supplying your Wazuh Manager IP, Agent Name, and Agent Group during the setup prompt, the script natively injects these exact parameters into the ossec.conf file—eliminating tedious manual post-install configuration.
• Auto-Whitelisting & Continuity: To guarantee uninterrupted log streaming, SysWarden automatically enforces high-priority bypass rules for your Wazuh Manager (ports 1514 and 1515), ensuring your SIEM traffic is never inadvertently disrupted by the overarching blocklists.

Installation & Usage (Root Privileges Required)

Zero-Touch Autodiscovery: SysWarden features an intelligent detection engine that automatically scans your environment for active services (Nginx, Apache, SSH, MongoDB) and configures the appropriate Fail2ban jails and firewall ports seamlessly.

1. System Preparation

Choose the command matching your operating system to ensure required dependencies are met.

# For Ubuntu / Debian
apt update && apt install wget -y

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

# For Alpine Linux
apk update && apk add wget bash

2. Download & Execution

Navigate to your local binaries directory and fetch the appropriate orchestrator for your architecture.

For Universal OS (Debian / Ubuntu / RHEL ecosystem):

cd /usr/local/bin/
wget https://github.com/duggytuxy/syswarden/releases/download/v9.53/install-syswarden.sh
chmod +x install-syswarden.sh
./install-syswarden.sh

For Alpine Linux (OpenRC):

cd /usr/local/bin/
wget https://github.com/duggytuxy/syswarden/releases/download/v9.53/install-syswarden-alpine.sh
chmod +x install-syswarden-alpine.sh
./install-syswarden-alpine.sh

3. Unattended Installation (CI/CD / Ansible)

You can bypass all interactive prompts by providing a configuration file.

Create and edit a file named syswarden-auto.conf using your preferred text editor (e.g., nano or vim):

nano /usr/local/bin/syswarden-auto.conf

Paste the following configuration into the file (exemple:)

# ==============================================================================
# Version=v9.53
# SYSWARDEN UNATTENDED INSTALLATION CONFIGURATION
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
#
# Usage: ./install-syswarden.sh syswarden-auto.conf
# ==============================================================================

# --- Enterprise Compliance Mode ---
# y = Strictly disables third-party telemetry/reporting (e.g., AbuseIPDB) to comply with corporate policies.
SYSWARDEN_ENTERPRISE_MODE="n"

# --- SSH Configuration ---
# Leave empty to auto-detect current active port
SYSWARDEN_SSH_PORT=""

# --- WireGuard Management VPN ---
# y = Enable, n = Disable
SYSWARDEN_ENABLE_WG="n"
SYSWARDEN_WG_PORT="51820"
SYSWARDEN_WG_SUBNET="10.66.66.0/24"

# --- Docker Integration ---
# y = Enable, n = Disable
SYSWARDEN_USE_DOCKER="n"

# --- Blocklist Selection ---
# 1 = Standard, 2 = Critical, 3 = Custom, 4 = None
SYSWARDEN_LIST_CHOICE="1"
# If choice is 3, provide the URL below
SYSWARDEN_CUSTOM_URL=""

# --- Geo-Blocking ---
# y = Enable, n = Disable
SYSWARDEN_ENABLE_GEO="n"
# Space-separated country codes (e.g., "ru cn kp ir")
SYSWARDEN_GEO_CODES="ru cn kp ir br vn in by ng bd pe mx ua my ph lt id af al bd by bo cl hr ec hk il kz lb my md pk ph qa sa sd tm uz zm zw ye"

# --- ASN Blocking ---
# Enable the ASN blocking module
SYSWARDEN_ENABLE_ASN="y"

# Master List (VPNs, Proxies, Linode, Tor Exit Nodes/Bulletproof Hosters)
SYSWARDEN_ASN_LIST="AS30823 AS210644 AS200593 AS202425 AS215540 AS9009 AS20473 AS60068 AS212238 AS16276 AS62282 AS14061 AS24940 AS398324 AS31173 AS11878 AS32097 AS43948 AS62240 AS16265 AS3223 AS53667 AS200651 AS58224 AS57821 AS199524 AS51852 AS197540"

# Include Spamhaus ASN-DROP list for known cybercriminal infrastructures
SYSWARDEN_USE_SPAMHAUS="y"

# --- AbuseIPDB Reporting ---
# y = Enable, n = Disable
SYSWARDEN_ENABLE_ABUSE="n"
SYSWARDEN_ABUSE_API_KEY=""
SYSWARDEN_REPORT_F2B="y"
SYSWARDEN_REPORT_FW="y"

# --- Wazuh Agent ---
# y = Enable, n = Disable
SYSWARDEN_ENABLE_WAZUH="n"
SYSWARDEN_WAZUH_IP=""
SYSWARDEN_WAZUH_NAME=""
SYSWARDEN_WAZUH_GROUP="default"
SYSWARDEN_WAZUH_COMM_PORT="1514"
SYSWARDEN_WAZUH_ENROLL_PORT="1515"

Pass the file as an argument (use the alpine script if applicable):

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

or

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

4. Serverless Telemetry Dashboard Access

SysWarden v9.30 includes a fully decoupled, real-time Telemetry Dashboard. For maximum security, the dashboard relies on a Python HTTP daemon that explicitly avoids listening on public network interfaces. Access depends on your WireGuard configuration:

Scenario A: WireGuard VPN Enabled (Recommended) If you chose to deploy the stealth management VPN during installation, the dashboard securely binds to the internal VPN subnet gateway.

1. Connect to the server using your generated WireGuard client profile.
2. Open your local browser and navigate to: http://10.66.66.1:9999 (Replace 10.66.66.1 with your defined WG_SUBNET gateway).

Scenario B: WireGuard VPN Disabled If you opted out of the VPN, the dashboard strictly binds to 127.0.0.1 (localhost) to prevent public exposure. You must use an SSH tunnel to access it.

ssh -L 9999:127.0.0.1:9999 your_user@your_server_ip -p YOUR_SSH_PORT

5. CLI Orchestration Commands

Once installed, SysWarden acts as a standalone CLI tool. You can manage your infrastructure security on the fly without ever editing configuration files manually.

Note: Replace install-syswarden.sh with install-syswarden-alpine.sh if you are on Alpine.

• Trigger Threat Intelligence Sync:

./install-syswarden.sh update

Forces an immediate refresh of the IPv4 blocklist, GeoIP datasets, and ASN routing tables, applying them natively to the kernel.

• Launch Live Attack Dashboard:

./install-syswarden.sh alerts

Opens the real-time terminal interface displaying active drops, blocked ASNs, and Fail2ban dynamic jails.

• Add Custom IP Exception:

./install-syswarden.sh whitelist

Interactively add a trusted IP address to bypass all overarching blocklists and Fail2ban monitoring.

• Add Custom IP Ban:

./install-syswarden.sh blocklist

Interactively permanently ban a specific malicious IP address across all ports.

• Generate WireGuard VPN Client:

./install-syswarden.sh wireguard-client

Instantly generates a new WireGuard client profile (with optimized MTU) and displays the configuration QR code in the terminal.

• Add Fail2ban jails after new services installed:

./install-syswarden.sh fail2ban-jails

Dynamically discover active services and reload Fail2ban jails without disruption.

• Inject Docker Shield:

./install-syswarden.sh protect-docker

Forces the injection of hermetic isolation rules into the DOCKER-USER iptables chain to protect exposed containers.

• Perform Core Engine Upgrade:

./install-syswarden.sh upgrade

Fetches the latest SysWarden architecture from the repository and performs a seamless hot-reload without dropping active connections.

System Architecture & File Structure

/ (Root File System)
├── etc/
│   ├── syswarden.conf                      # Centralized Configuration & Environment Variables
│   ├── syswarden/                          # Local Threat Intelligence Directory
│   │   ├── whitelist.txt                   # Custom IP/CIDR Routing Exceptions
│   │   ├── blocklist.txt                   # Custom Permanent IP Bans
│   │   ├── geoip.txt                       # Dynamic IPDeny Country-Level Blocklists
│   │   ├── asn.txt                         # Dynamic Spamhaus/RADB ASN Blocklists
│   │   └── ui/                             # Serverless Dashboard Web Root (HTML & JSON)
│   ├── wireguard/                          # Stealth Management VPN Configurations
│   │   ├── wg0.conf                        # Core Server Interface Configuration
│   │   └── clients/                        # Generated Client Profiles & MTU Settings
│   ├── fail2ban/
│   │   └── jail.local                      # Custom Jails (SSH, Web, DB) Injected by SysWarden
│   ├── logrotate.d/
│   │   └── syswarden                       # Log Rotation Policy
│   ├── cron.d/                             # (Mapped to /etc/crontabs/root on Alpine)
│   │   └── syswarden-update                # Hourly Threat Intelligence Sync Job
│   ├── systemd/system/                     # (For Debian/Ubuntu/RHEL Ecosystem)
│   │   ├── syswarden-reporter.service      # AbuseIPDB Asynchronous Daemon Service
│   │   └── syswarden-ui.service            # Serverless Telemetry Dashboard Service
│   └── init.d/                             # (For Alpine Linux / OpenRC Ecosystem)
│       ├── syswarden-reporter              # OpenRC AbuseIPDB Service
│       └── syswarden-ui                    # OpenRC Dashboard Service
│
├── usr/local/bin/
│   ├── install-syswarden.sh                # Main CLI Orchestrator (Universal OS)
│   ├── install-syswarden-alpine.sh         # Main CLI Orchestrator (Alpine Linux)
│   ├── syswarden-telemetry.sh              # Decoupled JSON Generator (Cron)
│   └── syswarden_reporter.py               # Python Log Analyzer & API Outbound Client
│
└── var/
    ├── log/
    │   ├── syswarden-install.log           # Verbose Installation & Debug Telemetry
    │   └── fail2ban.log                    # Dynamic Intrusion Prevention Logs
    └── ossec/etc/
        └── ossec.conf                      # Wazuh Agent Config

Uninstallation & System Teardown (Root Privileges Required)

SysWarden is designed to strictly respect your infrastructure. The uninstallation process performs a comprehensive and surgical teardown, ensuring no orphaned firewall rules, daemon remnants, or memory allocations are left behind.

Executing the uninstall orchestrator will autonomously:

• Flush Firewall States: Completely dismantle all injected Nftables, Firewalld, or IPSet blocklists, including Docker isolation rules, and restore standard traffic routing.
• Teardown VPN Interfaces: Safely disconnect the WireGuard wg0 interface and remove all generated client profiles.
• Halt Active Daemons: Stop, disable, and remove the AbuseIPDB Python reporter (via Systemd or OpenRC) and flush Fail2ban custom jails.
• Purge Scheduled Tasks: Remove all associated Cron jobs and Logrotate retention policies.
• Wipe Threat Intelligence Data: Delete the /etc/syswarden/ directory, configuration files, and all local IP datasets.

For Universal OS (Debian / Ubuntu / RHEL ecosystem):

./install-syswarden.sh uninstall

For Alpine Linux (OpenRC):

./install-syswarden-alpine.sh uninstall

The Wazuh XDR agent, if deployed during installation, will remain active and untouched, as SIEM agents are managed independently from the SysWarden core firewall engine.

Support & Sustainability

Help keep the tool alive Developing and maintaining a high-fidelity, real-time blocklist requires significant infrastructure resources and dedicated time. Your contributions are vital to ensure the project remains sustainable, up-to-date, and free for the community. If you find this project useful, consider supporting its ongoing development:

• ☕ Ko-Fi: https://ko-fi.com/laurentmduggytuxy

ABUSEIPDB Contributor

Duggy Tuxy
Verified Contributor

License & Copyright

• SysWarden © 2026
• Developed by Duggy Tuxy (Laurent Minne).

"This tool is open-source software licensed under the GNU GPLv3 License."