WardenIPS

WardenIPS is a Linux-native intrusion prevention platform focused on one practical outcome: detect hostile behavior quickly and enforce blocks at the firewall layer with minimal operator friction.

It is designed for teams that want stronger protection than static log-based banning, without the operational weight of a full SIEM stack.

Maintainer: msncakma

Why Use WardenIPS

Most operators ask one simple question before adopting security tooling: Why should I run this instead of what I already have?

WardenIPS exists to answer that with clear, operational value:

• Real-time containment. It does not stop at alerting. It can apply firewall blocks when risk crosses your threshold.
• Behavioral scoring. It evaluates event patterns over time, not only single regex hits.
• Low-complexity operations. One service, one config, one dashboard, with systemd- and Docker-friendly workflows.
• Better context during incidents. You get recent events, active database bans, live firewall entries, ASN data, and operator-oriented hints in one place.
• Safe rollout model. Simulation mode lets you observe exactly what would be blocked before enforcement is enabled.

If you run internet-facing services and want practical prevention with transparent behavior, WardenIPS is the right fit.

Transparent Status

Current version: v1.0.0

This project is now in a stable major line, and that matters.

• Feature state: Core capabilities are in place and actively used.
• Stability state: Production-ready baseline with continued iterative improvements.
• Remaining risk: Threshold tuning, whitelist quality, and environment-specific traffic patterns still determine final safety.
• Honest recommendation: Deploy in simulation first, validate behavior, then enable enforcement.

WardenIPS remains intentionally transparent about maturity and operational risk. Stable does not mean zero false positives without environment tuning.

What It Does

WardenIPS continuously ingests service logs, converts them into structured security events, computes risk, and applies actions based on policy.

Detection and Scoring

• SSH brute-force and suspicious login behavior
• Nginx probing, traversal, and injection-like patterns
• Portscan telemetry and trap-port signals
• Minecraft bot-like connection bursts
• Multi-vector scoring across plugins and time windows

Enforcement

• Linux ipset plus iptables enforcement
• IPv4 and IPv6 support
• Permanent or timed bans
• One-way DB to firewall reconciliation from admin actions
• Simulation mode for no-risk policy validation

Intelligence and Enrichment

• AbuseIPDB-based blocklist ingestion (first-setup and daily refresh phases)
• ASN enrichment via local GeoLite2 database
• Optional suspicious ASN weighting in risk scoring

Visibility and Operations

• Public overview dashboard and authenticated admin console
• Live event stream, active DB bans, active firewall entries
• Query tools for IP, ASN, and username records
• Audit logging for sensitive admin actions

Minecraft Admin Intelligence

• Dedicated admin panel at /admin/minecraft for Minecraft and Velocity activity
• Entity investigation for username, IP, and ASN with timeline pivoting
• Duplicate email signal panel for player DB enrichment findings
• Watchlist workflow for suspicious player tracking
• Player-level operator actions: ban all known player IPs or whitelist them in one step
• Parser health view for Minecraft and Velocity log ingestion (enabled state, readability, recent event flow)
• Built-in analytics safeguards: API rate limiting, short TTL response cache, optional email masking

What It Does Not Do

WardenIPS is powerful, but it is not magic. It deliberately does not claim the following:

• It does not replace full EDR, SIEM, or forensic platforms.
• It does not guarantee zero false positives.
• It does not auto-know which IPs are business-critical for your environment.
• It does not make careless thresholding safe.

Security outcomes still depend on good policy, sane defaults, and staged rollout.

Architecture at a Glance

1. Tailers read service logs.
2. Plugins parse raw lines into normalized events.
3. Risk scoring evaluates severity with context.
4. Policy layer selects action (watch or ban).
5. Firewall manager applies enforcement.
6. Database stores event and ban history.
7. Dashboard and API expose current operational state.

For deeper technical detail, see WARDEN_ARCHITECTURE.md.

Installation

Fast Install (Debian/Ubuntu style)

sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/msncakma/WardenIPS/master/install.sh)"

Manual Install

sudo apt update
sudo apt install -y python3 python3-venv ipset iptables git
git clone https://github.com/msncakma/WardenIPS.git
cd WardenIPS
python3 -m venv venv
./venv/bin/python -m pip install -r requirements.txt
sudo nano config.yaml
sudo ./venv/bin/python main.py

Detailed instructions: INSTALL.md

First Deployment Checklist

Before enabling enforcement in production:

1. Add trusted management and admin source ranges to whitelist settings.
2. Confirm plugin log paths are correct for your distro and services.
3. Start in simulation mode and review generated actions.
4. Tune ban threshold and durations to your real traffic profile.
5. Keep out-of-band access available during first live rollout.

Dashboard and Authentication

• Public view: /dashboard
• Admin console: /admin
• First boot setup flow: /setup
• API bearer token support for automation clients
• Session timeout and login rate limiting
• Optional per-admin TOTP requirement

Important: The built-in dashboard is plain HTTP by default. Put it behind TLS if exposed externally.

Operational Commands

Service Control

sudo systemctl start wardenips
sudo systemctl stop wardenips
sudo systemctl restart wardenips
sudo systemctl status wardenips
sudo journalctl -u wardenips -f

Runtime Status

python3 main.py --status

Docker

docker compose up -d --build
docker compose logs -f wardenips

Uninstall

sudo sh uninstall.sh

Full cleanup:

sudo sh uninstall.sh --purge

Operational Control (v1.0.0+)

Release Notes

For full details of the major update, see RELEASE_NOTES.md.

WardenIPS provides two professional operational modes for managing your security posture:

Command-Line Interface (CLI)

The wardenips-cli tool allows operators to control WardenIPS from the command line:

# Ban an IP address (direct local access - requires root)
wardenips-cli ban add 192.168.1.100 --reason "SSH brute-force" --duration 3600

# List active bans
wardenips-cli ban list --output json

# Manage whitelist (add/remove trusted IPs)
wardenips-cli whitelist add 203.0.113.50 --tag "office"
wardenips-cli whitelist list

# Firewall operations
wardenips-cli firewall status
wardenips-cli firewall sync --dry-run  # Preview what would change

# Configuration management
wardenips-cli config reload --components whitelist,firewall  # Zero-downtime reload

# Check system status
wardenips-cli status  # Overall system health

# Plugin management
wardenips-cli plugins list
wardenips-cli plugins reload ssh

Features:

• Direct access mode (fast, local, root-required)
• Output formats: Text (default), JSON, CSV
• Dry-run mode for non-destructive testing

REST API

For multi-team or multi-machine setups, use the REST API with authentication:

# Authenticate and get session token
TOKEN=$(curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"xxx"}' | jq -r .session_token)

# Ban an IP (audited operation)
curl -X POST http://localhost:8080/api/admin/ban-ip \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"192.168.1.100","reason":"Brute-force","duration":3600}'

# Get dashboard overview (public endpoint, optional auth)
curl http://localhost:8080/api/stats

# Hot-reload configuration (API-based)
curl -X POST http://localhost:8080/api/admin/config/reload \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"components":["whitelist","firewall"]}'

API Features:

• Bearer token authentication with session management
• Role-based access control (Admin, Operator, Viewer, Analyst)
• Comprehensive audit logging of all operations
• 40+ endpoints covering all operational needs
• Structured JSON responses

Migration note:

• A modular migration namespace is available at /api/v2/*.
• Existing /api/* endpoints remain active for backward compatibility.
• New development and CLI/API parity checks should prefer /api/v2/* during Phase 3 refactoring.

Available Endpoints:

Category	Endpoints
Public	GET /api/health, /api/stats, /api/events, /api/bans, /api/firewall, etc.
Admin Users	GET/POST /api/admin/users, manage invites, assign roles
Whitelist	GET/POST/DELETE /api/admin/whitelist
Banning	POST /api/admin/ban-ip, DELETE /api/admin/ban/{ip}, bulk operations
Config	GET/PATCH /api/admin/config, hot-reload, validation
Operations	Firewall sync, plugin reload, database optimization

See DEVELOPER_GUIDE.md for complete API reference.

Release Model

WardenIPS follows a staged maturity policy:

• SNAPSHOT: active development, unstable by definition
• ALPHA: early feature validation
• BETA: feature complete with stabilization in progress
• RELEASE: production-oriented stable milestone

Current line is beta. Treat it as non-final until a RELEASE tag is published.

Security and Privacy Notes

• WardenIPS modifies host firewall state.
• Bad whitelisting or aggressive policy can block legitimate users.
• ASN enrichment is local database lookup, not per-event external API calls.
• Blocklist feeds are curated external intelligence and should be treated as one signal, not absolute truth.

Who This Is For

• VPS and bare-metal operators
• Game server administrators
• Small SaaS teams running Linux edge services
• Self-hosters who want practical prevention without heavy infrastructure

Contributing and Support

• File issues with logs, environment details, and reproduction steps.
• Pull requests are welcome for fixes, tests, and plugin improvements.
• Support the project: Ko-fi

License

MIT. See LICENSE.