How h1v9/balooproxyx works
Project Type and Purpose
• balooProxyX is an open-source, production-ready reverse proxy written in Go that provides staged DDoS mitigation (cookie challenge, PoW JS, captcha), TLS fingerprinting, custom firewall rules, and alerting via Discord.
File Structure
• Top-level:
– main.go, Dockerfile, systemd example files, config examples
– assets/html (challenge/error page templates)
– assets/server (default cert/key)
– global/fingerprints (local TLS fingerprint JSON stores)
• core/ directory:
– core/config (config generation & init)
– core/firewall (fingerprint loading, rule evaluation with go-filter)
– core/proxy (proxy logic, X-Forwarded-For handling)
– core/server (HTTP listener, middleware, template rendering, monitor)
– core/utils (helpers: encryption, discord alerts, debugging)
– core/api, core/db, core/domains (supporting modules)
README for Insights
• Customizable firewall via wireguard-style expressions
• Three challenge stages, Discord alert integration, Cloudflare mode
• Docker and systemd deployment options
Main Components
a. External Clients (“Users/Bots”)
b. (Optional) Cloudflare Edge (TLS passthrough or proxy)
c. balooProxyX Node
• TLS Termination & Fingerprint Loader (core/firewall → global/fingerprints)
• Config Loader (core/config → config.json)
• Rule Engine (core/firewall using go-filter)
• Challenge Pipeline (cookie → JS PoW → captcha; assets/html via core/server/template.go)
• Proxy Forwarder (core/proxy → backend domain over HTTP/HTTPS)
• Monitor & Metrics (core/server/monitor, core/utils/debug)
• Alerting (core/utils/discord hooking into attack start/end)
• API Endpoints (core/api for potential external control)
d. Backend Services (your origin web servers)
e. Data Stores
• Configuration JSON (disk)
• TLS fingerprint JSON files (global/fingerprints)
f. External Integrations
• Discord Webhooks (alert channel)
• Optional GitHub version-check API
• Deployment orchestrators (Docker container, systemd unit)
Relationships and Interactions
1. Client → (Cloudflare) → balooProxyX TLS Listener
2. TLS handshake triggers fingerprint lookup
3. Request flows into Rule Engine → adjusts suspicion level
4. Based on susLv, one or more challenges served via HTML templates
5. Successful requests forwarded to backend (with X-Forwarded-For)
6. Backend response returned to client
7. Monitoring collects CPU/RPS/bypass data → logs to console or daemon mode
8. On attack events, send Discord alerts
Architectural Patterns and Technologies
• Layered pipeline: TLS → Fingerprint → Firewall Rules → Challenge → Forward
• Modular Go packages for separation of concerns
• go-filter rule engine for extensible firewall expressions
• HTML template subsystem for challenge pages
• JSON-based config and data storage
• Docker + systemd for deployment
Essential Elements Checklist
• Clear labels for every component and sub-component
• Notation of Daemon (-d) and Stealth modes for console output and branding