RuiQi WAF

A modern web application firewall (WAF) management system built on top of HAProxy and OWASP Coraza WAF with the Coraza SPOA integration. This system provides a comprehensive backend API for managing HAProxy configurations, Coraza WAF rules, and traffic inspection.

🌐 Click To Run

run the application in less than 30 seconds,default username: admin,default password: admin123

📺 Demo Video

output.mp4

📸 RuiQi WAF Interface Showcase

Core Architecture

Simple WAF implements a modular architecture with HAProxy at the front handling traffic and multiple security engines providing protection:

1. Coraza WAF Engine: OWASP ModSecurity-compatible filtering
2. MicroEngine: Rule-based matching engine for IP filtering, URL checking, and complex conditional logic
3. Geographic Analysis: Location-based traffic filtering
4. Rate Limiting: Traffic control and request throttling

The system uses a plugin architecture that allows for continuous enhancement with new security modules.

graph TD
    Client[Client] -->|HTTP Request| HAProxy
    HAProxy -->|TCP Connection| SPOE[Coraza SPOE Agent]
    SPOE -->|Message Type Recognition| TypeCheck
    TypeCheck -->|coraza-req| ReqHandler[Request Handler]
    TypeCheck -->|coraza-res| ResHandler[Response Handler]
    ReqHandler -->|Get App Name| ReqApp[Find Application]
    ResHandler -->|Get App Name| ResApp[Find Application]
    ReqApp -->|Process Request| ReqProcess[Request Processor]
    ResApp -->|Process Response| ResProcess[Response Processor]
    ReqProcess --> Return[Return Results to HAProxy]
    ResProcess --> Return
    HAProxy -->|Apply Action| Action[Allow/Deny/Log]
    Action -->|Response| Client

Loading

SPOE Communication Workflow

[HAProxy Request] → [internal.Agent.Serve(Listener)]
                          ↓
                   Create spop.Agent
                   agent := spop.Agent{
                       Handler: a,
                       BaseContext: a.Context,
                   }
                          ↓
                [spop.Agent.Serve(Listener)]
                          ↓
                   Accept new connections
                   nc, err := l.Accept()
                          ↓
                   Create protocol handler
                   p := newProtocolClient(ctx, nc, as, handler)
                          ↓
                   Start goroutine for connection
                   go func() {
                       p.Serve()
                   }()
                          ↓
                [protocolClient.Serve]
                   Process frames in connection
                          ↓
                [frameHandler processes Frame]
                   Dispatch based on frame type
                          ↓
                [onNotify handles messages]
                   Create message scanner and objects
                   Call Handler.HandleSPOE
                          ↓
                [internal.Agent.HandleSPOE processing]
                          ↓
                   Parse message type (coraza-req/coraza-res)
                          ↓
                   Get application name
                          ↓
                   Find Application
                          ↓
                   Execute message handler
                          ↓
                   Process return results
                          ↓
                [Return to HAProxy]

Features

• Multi-Engine Protection

  • Coraza WAF Engine:

    • OWASP Core Rule Set (CRS) support
    • ModSecurity SecLang rule compatibility
    • Custom rule management

  • MicroEngine:

    • Rule-based matching for IP, URL, and request path
    • Complex condition combinations (AND/OR logic)
    • IP blacklist/whitelist with CIDR support
    • Efficient regex matching with caching

  • Geographic Analysis:

    • Country and region-based filtering
    • Geographic attack visualization

  • Traffic Control:

    • Rate limiting and request throttling
    • Connection control mechanisms

• HAProxy Integration

  • Full HAProxy lifecycle management (start, stop, restart)
  • Dynamic configuration generation
  • Real-time status monitoring

• Advanced Security

  • HTTP request inspection
  • HTTP response inspection
  • Real-time attack detection and prevention
  • RBAC user permission system

• Monitoring and Logging

  • WAF attack logs and analytics
  • Traffic statistics
  • Performance metrics

• API-Driven Workflow

  • RESTful API with Gin framework
  • Swagger/ReDoc API documentation
  • JWT authentication

Prerequisites

• Go 1.24.1 or higher
• Node.js 23.10.0 and pnpm 10.11.0 (for frontend development)
• HAProxy 3.0 (for local development)
• MongoDB 6.0
• Docker and Docker Compose (for containerized deployment)

Local Development

1. Clone the repository:

git clone https://github.com/HUAHUAI23/RuiQi.git
cd RuiQi

2. Setup the frontend development environment:

cd server/web
pnpm install
pnpm dev # For development mode with hot reload
# or
pnpm build # For production build
cd ../..

3. Configure backend environment:

cp server/.env.template server/.env
# Edit .env with your configurations

4. Run the Go backend service:

go work use ./coraza-spoa ./pkg ./server
cd server
go run main.go

The development server will start with:

• API server: http://localhost:2333/api/v1
• Swagger UI: http://localhost:2333/swagger/index.html
• ReDoc UI: http://localhost:2333/redoc
• Frontend: http://localhost:2333/

Docker Deployment

1. Clone the repository:

git clone https://github.com/HUAHUAI23/RuiQi.git
cd RuiQi

2. Build the Docker image:

docker build -t ruiqi-waf:latest .

3. Run as a standalone container:

docker run -p 2333:2333 -p 8080:8080 -p 443:443 -p 80:80 -p 9443:9443 -p 8404:8404 ruiqi-waf:latest

4. Alternatively, use Docker Compose for a complete deployment with MongoDB:

# Edit docker-compose.yaml to configure environment variables if needed
docker-compose up -d

This will start both MongoDB and Simple WAF services with all required configurations.

Roadmap

Our project features and development progress:

1. Monitoring Dashboard

   • Real-time attack visualization map
   • Geographic attack origin analytics
   • Comprehensive security metrics dashboard

2. Advanced Traffic Control

   • Fine-grained rate limiting
   • Request frequency analysis
   • Adaptive throttling based on traffic patterns

3. Alert Integration

   • Webhook alert system
   • Integration with popular messaging platforms
   • Customizable alert templates

4. AI Security Analysis

   • ML-based attack pattern detection
   • AI-assisted rule generation
   • Automated ModSecurity directive creation
   • MCP (Model Control Plane) integration

5. Enhanced Rule Management

   • OWASP Top 10 specific rule templates
   • Rule effectiveness scoring
   • One-click protection profiles

For detailed technical documentation on engine architecture and implementation, see the proposals in the /doc/proposal directory.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• OWASP Coraza WAF
• Coraza SPOA
• HAProxy
• Go Gin Framework