GuardianTUI is an advanced L7 Reverse Proxy & Intrusion Prevention System (IPS) written in Go. It provides real-time threat detection, automated blocking, and a high-performance Terminal User Interface (TUI) for monitoring.
- Core Architecture
- Installation & Building
- Quick Start
- Configuration Guide
- Network Defense
- Operational Modes
- TUI Dashboard Guide
- Forensics & Logs
GuardianTUI operates as a transparent layer between the internet and your application.
- Recursive Normalization: Decodes up to 3 layers of obfuscation (Base64, Hex, Double URL Encoding, HTML Entities) before analysis.
- Heuristic Scoring Engine: Calculates a "Threat Score" for incoming requests, specifically optimized for LLM/AI prompts.
- Sharded Probing Detection: Uses high-performance memory sharding to track "Probing Bots" that test multiple vulnerabilities over time.
- Active Mitigation: Automatically serves a 403 Forbidden page with a unique Incident ID to blocked attackers.
GuardianTUI incorporates a specialized Illicit Content Shield designed to identify and block requests related to child sexual abuse material (CSAM).
- 🧠 Heuristic Scoring Engine: Beyond simple keywords, it uses a multi-layered scoring system that analyzes combinations of terms and context.
- 🔄 Advanced Normalization: Bypasses attempts to hide illicit terms using leetspeak (e.g.,
@fora,4fora), Base64, or Hex encoding. - 🚨 Priority Scanning: This check runs with absolute priority before any other security analysis, ensuring zero tolerance for illicit content.
- 🤖 Integrated AI Safety: Deep integration with the AI Shield to detect and block attempts to generate, describe, or roleplay illicit content via LLMs.
- 📊 Detailed Alerts: Incidents are flagged specifically as
ZERO TOLERANCE: CSAM Shieldin the TUI and logs for immediate forensic awareness.
- Go 1.21 or higher.
- Linux/macOS/Windows (TUI optimized for Unix-like terminals).
git clone https://github.com/lilsheepyy/GuardianTUI.git
cd GuardianTUI
go build -o guardiantui main.goProtect a local application running on port 3000:
./guardiantui -target http://localhost:3000Access your app through http://localhost:8080 (default proxy port).
The main configuration file controls the intensity of the security engine.
engine:
max_scan_size_bytes: 1048576 # Scan up to 1MB of payload
probing_window_seconds: 60 # Time window to track suspicious IPs
probing_threshold_unique: 3 # Block if 3+ unique attack types detected
spam_threshold_total: 5 # Block if 5+ attacks of any type detected
ai_protection:
endpoints: ["/v1/chat", "/api"] # Endpoints requiring AI heuristics
score_threshold: 5 # Stricter if lower (default 5)
protect_pii: true # Block Credit Cards/SSNs in prompts
blocked_keywords: # Instant block for these words
- "internal_key"
- "admin_password"
whitelist:
- "127.0.0.1" # Your own IP to avoid self-blockingDefine your own weights for specific prompt patterns.
[
{
"pattern": "(?i)reveal your secret key",
"weight": 5,
"description": "Custom Secret Key Leakage"
},
{
"pattern": "(?i)ignore instructions",
"weight": 3,
"description": "Override Attempt"
}
]If the cumulative weight of matched patterns reaches the score_threshold, the request is blocked.
Block automated scanners by their signature in config.yaml:
blocked_user_agents:
- "CensysInspect"
- "Go-http-client"
- "zgrab"
- "sqlmap"Manage high-threat actors through local files or remote URLs. GuardianTUI automatically refreshes these lists every 1 minute and performs an immediate update upon startup.
- 🔥 FireHOL Proxies: Comprehensive aggregate of open proxies detected in the last 30 days.
- 🛡️ Spamhaus DROP: "Do Not Route Or Peer" list containing hijacked or malicious network blocks.
- 🛑 AbuseIPDB: Highly reported IPs with 100% confidence level for recent malicious activity.
- 🔐 SSL Proxies: A frequently updated feed of active open SSL proxies used for anonymization.
# Path to an external file with IPs/CIDRs to block (one per line)
blocklist_path: "blocklist.txt"
# Remote blocklist URLs (Refreshed every 60 seconds)
remote_blocklists:
- "https://raw.githubusercontent.com/firehol/blocklist-ipsets/refs/heads/master/sslproxies_7d.ipset"
- "https://raw.githubusercontent.com/firehol/blocklist-ipsets/refs/heads/master/firehol_proxies.netset"
- "https://www.spamhaus.org/drop/drop.txt"
- "https://raw.githubusercontent.com/borestad/blocklist-abuseipdb/main/abuseipdb-s100-1d.ipv4"GuardianTUI maintains a Local Persistent Cache in the proxylistblock/ folder:
- Automatic Sanitization: All lists are stripped of headers, comments (
;or#), and metadata descriptions. - Clean Storage: Files like
spamhaus_drop.txtandabuseipdb.txtare stored as pure IP/CIDR lists for easy audit. - No Latency: The engine performs a full update in the background every minute without interrupting active traffic filtering.
GuardianTUI can automatically manage SSL certificates.
sudo ./guardiantui -target http://localhost:3000 -domain example.comUseful for testing HTTPS features locally.
./guardiantui -target http://localhost:3000 -https -listen :443./guardiantui -target http://localhost:3000 -listen :9000 -log security.logThe Terminal interface is your live mission control:
- Live Log Feed: Shows real-time requests. Red entries indicate blocked threats.
- Traffic Stats: Breakdown of allowed vs. blocked traffic.
- Threat Chart: Visualizes attack frequency over time.
- Search Mode (
/): Type any string (IP, ID, or Type) to filter logs instantly. - Navigation: Use arrow keys to scroll through the history of captured attacks.
Every block event is recorded in guardian.log with a structured format:
[2026-03-31 14:20:05] ID:e6b8a1 ID IP:1.2.3.4 POST /v1/chat | Status:BLOCKED:AI Abuse | Agent:Mozilla/5.0...
The Incident ID shown in the log matches the ID displayed to the user on the block page, allowing you to quickly find the exact request that triggered a block when a user reports a false positive.
Distributed under the MIT License. Created by sheep.