A Web Application Firewall for Python that stops attacks before they reach your application code, with comprehensive audit logging and compliance support.
Most web applications handle sensitive data and are exposed to automated attacks. LeWAF blocks SQL injection, XSS, and command injection attempts at the middleware layer, before they reach your business logic. Instead of implementing security checks in every endpoint, deploy LeWAF once and protect your entire application.
Organizations subject to PCI-DSS, GDPR, or SOC 2 need audit logs showing what security controls are in place and which attacks were blocked. LeWAF provides structured logging with automatic data masking (credit cards, passwords, tokens) and detailed attack records that satisfy auditor requirements.
Security vulnerabilities evolve constantly. LeWAF uses the OWASP Core Rule Set (CRS), maintained by security experts and updated regularly. Deploy rule updates without changing your application code. When new attack patterns emerge, update your WAF rules instead of patching multiple endpoints.
Security teams can write and test WAF rules independently of application deployments. Development teams continue shipping features while security teams tune protection rules. LeWAF's rule language (SecLang) is standard across ModSecurity-compatible systems, enabling knowledge transfer and shared rule sets.
Block malicious requests to REST or GraphQL APIs before they consume database resources or trigger expensive operations. Rate limit requests per client, validate JWT tokens at the edge, and log all blocked attempts for security analysis.
Add security controls to applications that can't be easily modified. Deploy LeWAF as a reverse proxy or middleware to protect applications written years ago, without source code changes or redeployment.
Different tenants may require different security policies. Load tenant-specific rule sets dynamically, enforce rate limits per organization, and maintain separate audit logs for each customer.
Deploy once at the API gateway to protect all downstream microservices. Centralized security policy enforcement reduces duplicated security code across services and provides unified logging.
Test security rules in staging before production deployment. Catch configuration errors early and validate that legitimate traffic passes through while attacks are blocked.
- Python web applications using FastAPI, Flask, Django, or Starlette
- Organizations requiring audit logs for compliance (PCI-DSS, GDPR, SOC 2)
- API providers needing rate limiting and attack protection
- Security teams wanting centralized rule management
- DevOps teams deploying containerized applications with security requirements
LeWAF is a Python implementation of the ModSecurity/Coraza Web Application Firewall specification. It runs as middleware in your web application, inspecting HTTP requests and responses against security rules before they reach your application code.
The system uses the OWASP Core Rule Set (CRS) - 594 security rules maintained by security researchers and updated as new threats emerge. LeWAF is compatible with ASGI (async) and WSGI (sync) frameworks: FastAPI, Flask, Django, and Starlette.
Key capabilities:
- Blocks SQL injection, XSS, command injection, path traversal attacks
- PCI-DSS and GDPR compliant audit logging with automatic data masking
- Drop-in middleware with minimal performance impact
- Configurable through code or YAML files
- Scales horizontally, no shared state between instances
- 1258 automated tests, load tested at 1000+ requests/second
# Clone repository
git clone https://github.com/abilian/lewaf.git
cd lewaf
# Install with uv
uv sync
# Run tests
uv run pytest -q
# Output: 1183 passed, 75 skipped in ~38sfrom lewaf.integration import WAF
# Create WAF with CRS rules
waf = WAF({
"rules": [
'SecRule ARGS "@rx <script" "id:1001,phase:2,deny,msg:\'XSS Attack\'"',
'SecRule ARGS "@rx (union.*select)" "id:1002,phase:2,deny,msg:\'SQL Injection\'"',
]
})
# Process request
tx = waf.new_transaction()
tx.process_uri("/api/users?id=123", "GET")
# Check for attacks
result = tx.process_request_headers()
if result:
print(f"Attack detected: {result['rule_id']}")from starlette.applications import Starlette
from lewaf.integrations.starlette import create_waf_app
app = Starlette(routes=[...])
# Add WAF protection
waf_app = create_waf_app(app, rules=[
'SecRule ARGS "@rx <script" "id:1001,phase:2,deny,msg:\'XSS\'"'
])See docs/guides/quickstart.md for detailed setup instructions.
Version: 0.7.0 Status: Beta Test Coverage: 1258 automated tests Code Quality: Zero linting/type errors Documentation: 15000+ lines of documentation
1258 automated tests covering:
- Core WAF engine and rule processing
- Framework integrations (FastAPI, Flask, Django, Starlette)
- Attack detection and blocking
- Compliance logging and data masking
- Performance under load
- Error handling and edge cases
See CHANGELOG.md for release history and feature details.
- Quickstart Guide - Get LeWAF running in 5 minutes with examples
- API Reference - Complete API documentation (1,538 lines)
- Django Integration - Integrate with Django applications
- FastAPI Integration - Integrate with FastAPI applications
- Flask Integration - Integrate with Flask applications
- Starlette Integration - Integrate with Starlette applications
- Docker Deployment - Deploy LeWAF in Docker containers
- Kubernetes Deployment - Deploy LeWAF in Kubernetes clusters
- Performance Tuning - Optimize LeWAF for high-traffic applications
- Troubleshooting - Diagnose and resolve common issues
- Custom Rules Guide - Write application-specific WAF rules
- Audit Logging - Configure compliance logging
- Developer Guide - Setup, coding guidelines, testing requirements
- Changelog - Release history and feature details
The examples/ directory contains ready-to-run code:
- Framework integrations: FastAPI, Flask, Django, Starlette implementations
- Audit logging: PCI-DSS and GDPR compliant logging setup
- Production deployment: Docker and Kubernetes configurations
- Custom rules: Application-specific security rules
LeWAF operates as middleware in your web application stack. When an HTTP request arrives:
- Request inspection: Headers, URI, query parameters, and body are extracted
- Rule evaluation: Security rules run in phases (headers → body → response)
- Pattern matching: Requests are checked against threat patterns (SQL injection, XSS, etc.)
- Action execution: Malicious requests are blocked; legitimate requests pass through
- Audit logging: All security events are logged with masked sensitive data
The rule engine uses the ModSecurity SecLang specification, the same rule language used by enterprise WAF systems. This means security professionals can apply existing knowledge and rule sets directly to LeWAF.
LeWAF implements the ModSecurity/Coraza WAF specification and is compatible with:
- OWASP Core Rule Set: 594 of ~650 rules (92% compatibility)
- ModSecurity rules: Standard SecLang syntax
- Python frameworks: FastAPI, Flask, Django, Starlette
- Deployment platforms: Docker, Kubernetes, traditional servers
This compatibility means you can use community-maintained rule sets, share security policies across different WAF implementations, and leverage existing security team expertise.
The drop action in ModSecurity forcefully terminates TCP connections. This requires low-level socket access that is not available in Python WSGI/ASGI middleware. In LeWAF, drop behaves identically to deny - it returns an error response but the TCP connection may remain open.
Workaround: Use deny instead. For true connection dropping, deploy a native WAF (nginx ModSecurity module, Apache mod_security) in front of your Python application.
The exec action is intentionally disabled for security reasons. Executing arbitrary shell commands from WAF rules creates significant security risks including remote code execution and privilege escalation.
Workaround: If you need external command execution, implement it through a secure hook mechanism outside the WAF rule engine with proper auditing and access controls.
We welcome contributions! See CONTRIBUTING.md for:
- Development setup
- Coding guidelines
- Testing requirements
- Git workflow
# Run tests
uv run pytest
# Run linting
uv run ruff check .
# Auto-fix issues
uv run ruff check . --fix && uv run ruff format .
# Build package
uv buildApache Software License 2.0 (matching OWASP CRS and Coraza)
- Architecture: Based on Go Coraza project
- Rules: OWASP Core Rule Set
- Standards: ModSecurity/Coraza SecLang specification
- Issues: GitHub Issues
- Documentation: See docs above
- CRS Documentation: https://coreruleset.org/
- Coraza Documentation: https://coraza.io/
LeWAF: Lightweight Web Application Firewall for Python 🛡️