Web Application Firewall (WAF) 🛡️

Modular and configurable Web Application Firewall (WAF) server written in TypeScript using Express.js. Protect your web applications from attacks with flexible filtering, IP banning, geolocation-based rules, and bot detection.

✨ Key Features

• ⚖️ Flexible Blocking Rules - Static IP lists, behavioral filters, and request rate limiting
• ⛔ Jail System - Temporary IP banning with progressive escalation for repeat offenders
• ✉️ Whitelist/Blacklist - Allow or block by IP, subnet, country, or city
• 🌍 GeoIP Detection - Country and city-based filtering using MaxMind databases
• 🤖 Bot Detection - Advanced bot detection and browser fingerprinting (Under Attack mode)
• 🛡️ REST API - Manage bans and monitor status via HTTP API
• 📊 Prometheus Metrics - Export metrics for monitoring and alerting
• 💾 Flexible Storage - In-memory or file-based ban storage
• 🔎 Audit Mode - Test rules safely without blocking traffic
• ⚙️ Reverse Proxy - Proxy validated requests to your backend

🚀 Quick Start

Using Docker (Recommended)

# Download GeoIP databases
mkdir -p geoip_data && cd geoip_data
wget https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-Country.mmdb
wget https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-City.mmdb
cd ..

# Create minimal config.yaml (see docs for full examples)
cat > config.yaml <<'EOF'
proxy:
  host: "http://host.docker.internal:8080"  # Your backend URL

api:
  auth:
    enabled: false
    username: 'admin'
    password: 'admin'

metrics:
  enabled: true
  auth:
    enabled: false
    username: 'admin'
    password: 'admin'

wafMiddleware:
  mode: audit  # Use 'normal' for production

  detectClientIp:
    headers: ["x-forwarded-for"]

  detectClientCountry:
    method: geoip

  detectClientCity:
    method: geoip

jailManager:
  enabled: true
  storage:
    driver: memory
  filterRules:
    - name: "rate-limit"
      type: "composite"
      uniqueClientKey: ["ip"]
      conditions: []
      period: 60
      limit: 1000
      duration: 300
      escalationRate: 1.5

sentry:
  enabled: false
  dsn: ''
  debug: false
EOF

# Run WAF
docker run -d \
  --name waf \
  -p 3000:3000 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v $(pwd)/geoip_data:/app/geoip_data:ro \
  ghcr.io/someblackmagic/web-application-firewall:latest

# Check logs
docker logs -f waf

Access at: http://localhost:3000

Alternative: Binary from Releases

# Download latest binary
wget https://github.com/SomeBlackMagic/WebApplicationFirewall/releases/latest/download/waf-linux-x64
chmod +x waf-linux-x64

# Run
./waf-linux-x64

See Quick Start Guide for detailed instructions.

📚 Documentation

Complete documentation is available in the docs/ directory.

Getting Started

• Installation Guide
• Quick Start
• Running with Docker
• First Configuration

Configuration

• Configuration Overview
• Filter Rules - Define blocking rules
• Jail System - IP banning configuration
• Static Lists - Whitelist/Blacklist
• Geolocation - Country/city detection
• Configuration Examples - Ready-to-use configs

Architecture & Concepts

• Architecture Overview
• Request Flow
• Rule Types
• Ban Escalation

API & Monitoring

• API Reference
• Prometheus Metrics
• Grafana Dashboard

Guides

• Troubleshooting
• Use Cases & Examples
• Performance Tuning
• Security Best Practices

Deployment

• Docker Deployment
• Docker Compose
• High Availability

Development

• Development Setup
• Testing
• Contributing

🐳 Docker

# Pull latest image
docker pull ghcr.io/someblackmagic/web-application-firewall:latest

# Run
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/geoip_data:/app/geoip_data \
  ghcr.io/someblackmagic/web-application-firewall:latest

See Docker Guide for details.

🤝 Contributing

We welcome contributions! Please see:

• Contributing Guide
• Code of Conduct (if available)
• Development Setup

📄 License

This project is licensed under the GNU License.

🔗 Links

• GitHub Repository
• Issue Tracker
• Releases
• Documentation

💡 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by the WAF community