# AIWAF Flask
AIWAF (AI Web Application Firewall) for Flask provides advanced, self-learning protection for your Flask web applications. It supports IP/keyword blocking, rate limiting, honeypot timing, header validation, anomaly detection, and UUID tampering, with flexible storage options: **database**, **CSV files**, or **in-memory**.
## Features
- IP and keyword blocking
- Rate limiting with burst detection
- Honeypot timing protection
- Header validation
- Anomaly detection (extensible)
- UUID tampering detection
- **Path exemptions** - Prevent false positives for legitimate resources
- **Flexible storage**: Database, CSV files, or in-memory
- Zero-dependency protection (works without database)
## Function Names
AIWAF Flask provides two function names for registering middleware:
- **`register_aiwaf_middlewares(app)`** - Current recommended name
- **`register_aiwaf_protection(app)`** - Backward compatibility alias
Both functions work identically and provide the same protection features.
```python
from flask import Flask
from aiwaf_flask import register_aiwaf_middlewares
# OR: from aiwaf_flask import register_aiwaf_protection
app = Flask(__name__)
app.config['AIWAF_USE_CSV'] = True
# Both of these work the same way:
register_aiwaf_middlewares(app)
# register_aiwaf_protection(app) # Alternative
```
## Installation
```bash
pip install flask flask-sqlalchemy # For database storage
# OR
pip install flask # For CSV/in-memory storage only
```
## Storage Options
### 1. **CSV Storage (Recommended for small apps)**
```python
from flask import Flask
from aiwaf_flask import register_aiwaf_middlewares
app = Flask(__name__)
# CSV Configuration (no database needed!)
app.config['AIWAF_USE_CSV'] = True
app.config['AIWAF_DATA_DIR'] = 'aiwaf_data' # Optional: custom directory
# AIWAF Settings
app.config['AIWAF_RATE_WINDOW'] = 60
app.config['AIWAF_RATE_MAX'] = 100
register_aiwaf_middlewares(app)
```
### 2. **Database Storage (Recommended for production)**
```python
from flask import Flask
from aiwaf_flask.db_models import db
from aiwaf_flask import register_aiwaf_middlewares
app = Flask(__name__)
# Database Configuration
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///aiwaf.db'
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
# AIWAF Settings
app.config['AIWAF_RATE_WINDOW'] = 60
app.config['AIWAF_RATE_MAX'] = 100
db.init_app(app)
with app.app_context():
db.create_all()
register_aiwaf_middlewares(app)
```
### 3. **In-Memory Storage (For testing)**
```python
from flask import Flask
from aiwaf_flask import register_aiwaf_middlewares
app = Flask(__name__)
# Force in-memory storage
app.config['AIWAF_USE_CSV'] = False
register_aiwaf_middlewares(app, use_database=False)
```
## Configuration Options
```python
# Rate Limiting
app.config['AIWAF_RATE_WINDOW'] = 60 # Time window in seconds
app.config['AIWAF_RATE_MAX'] = 100 # Max requests per window
app.config['AIWAF_RATE_FLOOD'] = 200 # Auto-block threshold
# Honeypot Protection
app.config['AIWAF_MIN_FORM_TIME'] = 2.0 # Minimum form submission time
# CSV Storage (if enabled)
app.config['AIWAF_USE_CSV'] = True # Enable CSV storage
app.config['AIWAF_DATA_DIR'] = 'aiwaf_data' # CSV files directory
# Logging Configuration
app.config['AIWAF_ENABLE_LOGGING'] = True # Enable request logging
app.config['AIWAF_LOG_DIR'] = 'aiwaf_logs' # Log files directory
app.config['AIWAF_LOG_FORMAT'] = 'combined' # Log format: combined, common, csv, json
# Path Exemptions
app.config['AIWAF_EXEMPT_PATHS'] = { # Paths exempt from AIWAF protection
'/favicon.ico',
'/robots.txt',
'*.css', # Wildcard patterns
'/static/', # Directory patterns
}
```
## Path Exemptions (Prevent False Positives)
AIWAF supports **path-based exemptions** to prevent false positives for legitimate resources that might return 404s or should not be subject to security filtering.
### Default Exempt Paths
AIWAF includes sensible defaults for common legitimate resources:
```python
# SEO and crawlers
'/favicon.ico', '/robots.txt', '/sitemap.xml', '/ads.txt'
# Apple and mobile devices
'/apple-touch-icon.png', '/manifest.json', '/browserconfig.xml'
# Health checks and monitoring
'/health', '/healthcheck', '/ping', '/status'
# Well-known URIs (SSL certificates, security policies)
'/.well-known/'
# Static file extensions (wildcards)
'*.css', '*.js', '*.png', '*.jpg', '*.ico', '*.woff2'
# Static directories
'/static/', '/assets/', '/css/', '/js/', '/images/', '/fonts/'
```
### Custom Path Exemptions
Configure custom exempt paths for your application:
```python
# Override defaults with custom paths
app.config['AIWAF_EXEMPT_PATHS'] = {
# Essential SEO files
'/favicon.ico',
'/robots.txt',
'/sitemap.xml',
# Health monitoring
'/health',
'/api/health',
# Public APIs
'/api/public/',
'/webhook/github',
# Static assets
'*.css', '*.js', '*.png', '*.pdf',
'/static/', '/assets/',
# Custom application paths
'/special-public-endpoint',
'/custom-health-check',
}
```
### Pattern Types
- **Exact paths**: `/favicon.ico` (matches exactly)
- **Wildcard patterns**: `*.css` (matches any .css file)
- **Directory patterns**: `/static/` (matches anything under /static/)
- **Case insensitive**: `/FAVICON.ICO` also matches
### Why Use Path Exemptions?
- **Prevent SEO issues**: Search engines can safely crawl `/robots.txt`, `/sitemap.xml`
- **Avoid blocking legitimate 404s**: `favicon.ico` requests won't trigger blocking
- **Load balancer compatibility**: Health checks always work (`/health`, `/ping`)
- **Static asset safety**: CSS/JS/images load without interference
- **SSL certificate support**: `/.well-known/` URIs for ACME challenges
## Web Server Logging
AIWAF Flask includes comprehensive logging that generates **standard web server logs** compatible with tools like Gunicorn, Nginx, and Apache log analyzers.
### Log Formats
#### **Combined Log Format (Default)**
```
127.0.0.1 - - [14/Sep/2025:15:02:41 +0000] "GET /api/data HTTP/1.1" 200 1234 "http://example.com" "Mozilla/5.0" 50ms - "-"
203.0.113.10 - - [14/Sep/2025:15:02:42 +0000] "GET /admin.php HTTP/1.1" 403 0 "-" "BadBot/1.0" 10ms BLOCKED "Malicious keyword: .php"
```
#### **CSV Format (Easy Analysis)**
```csv
timestamp,ip,method,path,status_code,response_time_ms,blocked,block_reason
2025-09-14T15:02:41,127.0.0.1,GET,/api/data,200,50,False,
2025-09-14T15:02:42,203.0.113.10,GET,/admin.php,403,10,True,Malicious keyword: .php
```
#### **JSON Format (Structured)**
```json
{"timestamp": "2025-09-14T15:02:41", "ip": "127.0.0.1", "method": "GET", "path": "/api/data", "status_code": 200, "blocked": false}
{"timestamp": "2025-09-14T15:02:42", "ip": "203.0.113.10", "method": "GET", "path": "/admin.php", "status_code": 403, "blocked": true, "block_reason": "Malicious keyword: .php"}
```
### Log Configuration
```python
app.config['AIWAF_ENABLE_LOGGING'] = True # Enable logging
app.config['AIWAF_LOG_DIR'] = 'logs' # Log directory
app.config['AIWAF_LOG_FORMAT'] = 'combined' # Format: combined, common, csv, json
```
### Generated Log Files
- **`access.log`** - All HTTP requests (main access log)
- **`error.log`** - HTTP errors (4xx, 5xx status codes)
- **`aiwaf.log`** - AIWAF security events and blocks
### Log Analysis
```bash
# Analyze logs with detailed statistics
python aiwaf_console.py logs --log-dir logs --format combined
# Sample output:
# 📊 AIWAF Access Log Analysis
# Total Requests: 1,250
# Blocked Requests: 45 (3.6%)
# Average Response Time: 85ms
# Top IPs, paths, block reasons, hourly patterns, etc.
```
## Usage Examples
Your routes are automatically protected:
```python
@app.route('/')
def home():
return render_template('home.html') # Protected by AIWAF
@app.route('/api/data')
def api_data():
return jsonify({'data': 'protected'}) # Rate limited & validated
```
## Managing Protection Lists
```python
from aiwaf_flask.storage import add_ip_whitelist, add_ip_blacklist, add_keyword
# Add IPs to whitelist (bypass all protection)
add_ip_whitelist('192.168.1.100')
# Add IPs to blacklist (block completely)
add_ip_blacklist('10.0.0.1', reason='Suspicious activity')
# Add malicious keywords to block
add_keyword('wp-admin')
add_keyword('.env')
```
## CSV Files Structure
When using CSV storage, AIWAF creates these files in your data directory:
- `whitelist.csv` - Whitelisted IP addresses
- `blacklist.csv` - Blacklisted IP addresses with reasons
- `keywords.csv` - Blocked keywords
Example `blacklist.csv`:
```csv
ip,reason,added_date
10.0.0.1,Suspicious activity,2025-09-14T10:30:00
192.168.1.50,Rate limit exceeded,2025-09-14T11:15:00
```
## Command Line Management
AIWAF Flask includes a powerful CLI tool for managing IP exemptions, blacklists, and blocked keywords from the command line.
### Basic Usage
```bash
# Show help
python aiwaf_console.py --help
# Show current statistics
python aiwaf_console.py stats
# List all data
python aiwaf_console.py list all
```
### IP Management
```bash
# Add IP to whitelist
python aiwaf_console.py add whitelist 192.168.1.100
# Add IP to blacklist with reason
python aiwaf_console.py add blacklist 10.0.0.5 --reason "Brute force attack"
# Remove IP from whitelist
python aiwaf_console.py remove whitelist 192.168.1.100
# Remove IP from blacklist
python aiwaf_console.py remove blacklist 10.0.0.5
# List specific data types
python aiwaf_console.py list whitelist
python aiwaf_console.py list blacklist
```
### Keyword Management
```bash
# Add blocked keyword
python aiwaf_console.py add keyword "sql injection"
python aiwaf_console.py add keyword "script"
# List blocked keywords
python aiwaf_console.py list keywords
```
### Configuration Backup/Restore
```bash
# Export current configuration
python aiwaf_console.py export backup.json
# Import configuration from backup
python aiwaf_console.py import backup.json
```
### Custom Data Directory
```bash
# Use custom data directory
python aiwaf_console.py --data-dir /path/to/custom/aiwaf_data stats
```
### Example CLI Session
```bash
# Check current status
python aiwaf_console.py stats
# Add some IPs to whitelist
python aiwaf_console.py add whitelist 192.168.1.100
python aiwaf_console.py add whitelist 10.0.0.50
# Block a malicious IP
python aiwaf_console.py add blacklist 203.0.113.10 --reason "SQL injection attempts"
# Add dangerous keywords
python aiwaf_console.py add keyword "union select"
python aiwaf_console.py add keyword "drop table"
# Review all settings
python aiwaf_console.py list all
# Create backup
python aiwaf_console.py export production_backup.json
```
### Programmatic Management
You can also use the CLI functionality in your Python code:
```python
from aiwaf_flask.cli import AIWAFManager
# Initialize manager
manager = AIWAFManager()
# Add IPs programmatically
manager.add_to_whitelist("192.168.1.100")
manager.add_to_blacklist("10.0.0.5", "Suspicious activity")
# Get current lists
whitelist = manager.list_whitelist()
blacklist = manager.list_blacklist()
keywords = manager.list_keywords()
# Export configuration
manager.export_config("backup.json")
```
## CLI Features & Real-World Examples
AIWAF Flask includes powerful command-line tools for production management. The CLI works independently without requiring Flask to be installed, making it perfect for system administration and automation.
### Quick Setup
```bash
# Show CLI status and help
python aiwaf_setup.py
# Install Flask if needed (optional for CLI-only usage)
python aiwaf_setup.py install-flask
# Run interactive demo
python aiwaf_setup.py demo
```
### Production Management Examples
#### **Emergency IP Blocking**
```bash
# Block attacking IPs immediately
python aiwaf_console.py add blacklist 203.0.113.10 --reason "SQL injection attack detected"
python aiwaf_console.py add blacklist 198.51.100.5 --reason "Brute force login attempts"
python aiwaf_console.py add blacklist 10.0.0.1 --reason "Suspicious port scanning"
# Verify blocks are active
python aiwaf_console.py list blacklist
```
#### **Whitelist Management**
```bash
# Add trusted networks
python aiwaf_console.py add whitelist 192.168.1.0/24
python aiwaf_console.py add whitelist 10.0.0.0/8
python aiwaf_console.py add whitelist 172.16.0.0/12
# Add specific trusted IPs
python aiwaf_console.py add whitelist 203.0.113.100 # Office IP
python aiwaf_console.py add whitelist 198.51.100.200 # API partner
```
#### **Security Keywords**
```bash
# Block common attack patterns
python aiwaf_console.py add keyword "union select"
python aiwaf_console.py add keyword "drop table"
python aiwaf_console.py add keyword "<script>"
python aiwaf_console.py add keyword "javascript:"
python aiwaf_console.py add keyword "eval("
python aiwaf_console.py add keyword "base64_decode"
# Review blocked keywords
python aiwaf_console.py list keywords
```
#### **Daily Operations**
```bash
# Morning security check
python aiwaf_console.py stats
# Review recent blocks
python aiwaf_console.py list blacklist
# Create daily backup
python aiwaf_console.py export "backup-$(date +%Y%m%d).json"
# Clean up test entries
python aiwaf_console.py remove whitelist 192.168.1.99
python aiwaf_console.py remove blacklist 10.0.0.99
```
### Automation Scripts
#### **Security Incident Response**
```bash
#!/bin/bash
# incident_response.sh - Block multiple IPs from security incident
MALICIOUS_IPS=(
"203.0.113.10"
"198.51.100.5"
"192.0.2.15"
"198.51.100.25"
)
for ip in "${MALICIOUS_IPS[@]}"; do
python aiwaf_console.py add blacklist "$ip" --reason "Security incident #2025-001"
done
# Create incident backup
python aiwaf_console.py export "incident-2025-001-backup.json"
echo "Blocked ${#MALICIOUS_IPS[@]} IPs from security incident"
```
#### **Configuration Deployment**
```bash
#!/bin/bash
# deploy_config.sh - Deploy AIWAF configuration to production
# Backup current config
python aiwaf_console.py export "backup-before-deploy-$(date +%Y%m%d-%H%M).json"
# Deploy new configuration
python aiwaf_console.py import "production-config.json"
# Verify deployment
python aiwaf_console.py stats
python aiwaf_console.py list all
```
### Real CLI Session Output
```bash
$ python aiwaf_console.py stats
📁 Using CSV storage: aiwaf_data
📊 AIWAF Statistics
==================================================
Whitelisted IPs: 5
Blacklisted IPs: 3
Blocked Keywords: 8
Storage Mode: CSV
Data Directory: aiwaf_data
$ python aiwaf_console.py list all
📁 Using CSV storage: aiwaf_data
🟢 Whitelisted IPs (5):
• 192.168.1.100
• 192.168.1.200
• 10.0.0.50
• 203.0.113.100
• 198.51.100.200
🔴 Blacklisted IPs (3):
• 203.0.113.10 - SQL injection attack detected (2025-09-14T09:15:30)
• 198.51.100.5 - Brute force login attempts (2025-09-14T10:22:15)
• 10.0.0.1 - Suspicious port scanning (2025-09-14T11:45:22)
🚫 Blocked Keywords (8):
• union select
• drop table
• <script>
• javascript:
• eval(
• base64_decode
• onload=
• document.cookie
$ python aiwaf_console.py export production-backup.json
📁 Using CSV storage: aiwaf_data
✅ Configuration exported to production-backup.json
```
### Configuration Format
The exported JSON configuration contains all security settings:
```json
{
"whitelist": [
"192.168.1.100",
"192.168.1.200",
"10.0.0.50"
],
"blacklist": {
"203.0.113.10": {
"timestamp": "2025-09-14T09:15:30.123456",
"reason": "SQL injection attack detected"
},
"198.51.100.5": {
"timestamp": "2025-09-14T10:22:15.789012",
"reason": "Brute force login attempts"
}
},
"keywords": [
"union select",
"drop table",
"<script>",
"eval("
],
"exported_at": "2025-09-14T14:30:00.000000",
"storage_mode": "CSV"
}
```
### Integration with Monitoring
```bash
# Add to crontab for daily reports
0 9 * * * /path/to/python /path/to/aiwaf_console.py stats >> /var/log/aiwaf-daily.log
# Add to monitoring script
python aiwaf_console.py stats | grep -E "(Blacklisted|Keywords)" | \
awk '{if($3 > 100) print "ALERT: High security blocks detected"}'
```
## Production Deployment
```python
# config.py
import os
class ProductionConfig:
# Use PostgreSQL in production
SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')
# Stricter limits for production
AIWAF_RATE_MAX = 50
AIWAF_RATE_FLOOD = 100
AIWAF_MIN_FORM_TIME = 3.0
# app.py
app.config.from_object(ProductionConfig)
```
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/aayushgauba/aiwaf_flask",
"name": "aiwaf-flask",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Aayush Gauba <gauba.aayush@gmail.com>",
"keywords": "flask, security, firewall, web, protection, middleware, rate-limiting, ip-blocking, ddos, waf",
"author": "Aayush Gauba",
"author_email": "Aayush Gauba <gauba.aayush@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/75/03/5211ca6716cb662201a63676c04eb20d393243ae2919dfc074ed3b59781c/aiwaf_flask-0.1.4b0.tar.gz",
"platform": null,
"description": "# AIWAF Flask\n\nAIWAF (AI Web Application Firewall) for Flask provides advanced, self-learning protection for your Flask web applications. It supports IP/keyword blocking, rate limiting, honeypot timing, header validation, anomaly detection, and UUID tampering, with flexible storage options: **database**, **CSV files**, or **in-memory**.\n\n## Features\n- IP and keyword blocking\n- Rate limiting with burst detection\n- Honeypot timing protection\n- Header validation\n- Anomaly detection (extensible)\n- UUID tampering detection\n- **Path exemptions** - Prevent false positives for legitimate resources\n- **Flexible storage**: Database, CSV files, or in-memory\n- Zero-dependency protection (works without database)\n\n## Function Names\n\nAIWAF Flask provides two function names for registering middleware:\n\n- **`register_aiwaf_middlewares(app)`** - Current recommended name\n- **`register_aiwaf_protection(app)`** - Backward compatibility alias\n\nBoth functions work identically and provide the same protection features.\n\n```python\nfrom flask import Flask\nfrom aiwaf_flask import register_aiwaf_middlewares\n# OR: from aiwaf_flask import register_aiwaf_protection\n\napp = Flask(__name__)\napp.config['AIWAF_USE_CSV'] = True\n\n# Both of these work the same way:\nregister_aiwaf_middlewares(app)\n# register_aiwaf_protection(app) # Alternative\n```\n\n## Installation\n\n```bash\npip install flask flask-sqlalchemy # For database storage\n# OR\npip install flask # For CSV/in-memory storage only\n```\n\n## Storage Options\n\n### 1. **CSV Storage (Recommended for small apps)**\n```python\nfrom flask import Flask\nfrom aiwaf_flask import register_aiwaf_middlewares\n\napp = Flask(__name__)\n\n# CSV Configuration (no database needed!)\napp.config['AIWAF_USE_CSV'] = True\napp.config['AIWAF_DATA_DIR'] = 'aiwaf_data' # Optional: custom directory\n\n# AIWAF Settings\napp.config['AIWAF_RATE_WINDOW'] = 60\napp.config['AIWAF_RATE_MAX'] = 100\n\nregister_aiwaf_middlewares(app)\n```\n\n### 2. **Database Storage (Recommended for production)**\n```python\nfrom flask import Flask\nfrom aiwaf_flask.db_models import db\nfrom aiwaf_flask import register_aiwaf_middlewares\n\napp = Flask(__name__)\n\n# Database Configuration\napp.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///aiwaf.db'\napp.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False\n\n# AIWAF Settings\napp.config['AIWAF_RATE_WINDOW'] = 60\napp.config['AIWAF_RATE_MAX'] = 100\n\ndb.init_app(app)\nwith app.app_context():\n db.create_all()\n\nregister_aiwaf_middlewares(app)\n```\n\n### 3. **In-Memory Storage (For testing)**\n```python\nfrom flask import Flask\nfrom aiwaf_flask import register_aiwaf_middlewares\n\napp = Flask(__name__)\n\n# Force in-memory storage\napp.config['AIWAF_USE_CSV'] = False\n\nregister_aiwaf_middlewares(app, use_database=False)\n```\n\n## Configuration Options\n\n```python\n# Rate Limiting\napp.config['AIWAF_RATE_WINDOW'] = 60 # Time window in seconds\napp.config['AIWAF_RATE_MAX'] = 100 # Max requests per window\napp.config['AIWAF_RATE_FLOOD'] = 200 # Auto-block threshold\n\n# Honeypot Protection\napp.config['AIWAF_MIN_FORM_TIME'] = 2.0 # Minimum form submission time\n\n# CSV Storage (if enabled)\napp.config['AIWAF_USE_CSV'] = True # Enable CSV storage\napp.config['AIWAF_DATA_DIR'] = 'aiwaf_data' # CSV files directory\n\n# Logging Configuration\napp.config['AIWAF_ENABLE_LOGGING'] = True # Enable request logging\napp.config['AIWAF_LOG_DIR'] = 'aiwaf_logs' # Log files directory\napp.config['AIWAF_LOG_FORMAT'] = 'combined' # Log format: combined, common, csv, json\n\n# Path Exemptions\napp.config['AIWAF_EXEMPT_PATHS'] = { # Paths exempt from AIWAF protection\n '/favicon.ico',\n '/robots.txt', \n '*.css', # Wildcard patterns\n '/static/', # Directory patterns\n}\n```\n\n## Path Exemptions (Prevent False Positives)\n\nAIWAF supports **path-based exemptions** to prevent false positives for legitimate resources that might return 404s or should not be subject to security filtering.\n\n### Default Exempt Paths\n\nAIWAF includes sensible defaults for common legitimate resources:\n\n```python\n# SEO and crawlers\n'/favicon.ico', '/robots.txt', '/sitemap.xml', '/ads.txt'\n\n# Apple and mobile devices \n'/apple-touch-icon.png', '/manifest.json', '/browserconfig.xml'\n\n# Health checks and monitoring\n'/health', '/healthcheck', '/ping', '/status'\n\n# Well-known URIs (SSL certificates, security policies)\n'/.well-known/'\n\n# Static file extensions (wildcards)\n'*.css', '*.js', '*.png', '*.jpg', '*.ico', '*.woff2'\n\n# Static directories\n'/static/', '/assets/', '/css/', '/js/', '/images/', '/fonts/'\n```\n\n### Custom Path Exemptions\n\nConfigure custom exempt paths for your application:\n\n```python\n# Override defaults with custom paths\napp.config['AIWAF_EXEMPT_PATHS'] = {\n # Essential SEO files\n '/favicon.ico',\n '/robots.txt',\n '/sitemap.xml',\n \n # Health monitoring \n '/health',\n '/api/health',\n \n # Public APIs\n '/api/public/',\n '/webhook/github',\n \n # Static assets\n '*.css', '*.js', '*.png', '*.pdf',\n '/static/', '/assets/',\n \n # Custom application paths\n '/special-public-endpoint',\n '/custom-health-check',\n}\n```\n\n### Pattern Types\n\n- **Exact paths**: `/favicon.ico` (matches exactly)\n- **Wildcard patterns**: `*.css` (matches any .css file) \n- **Directory patterns**: `/static/` (matches anything under /static/)\n- **Case insensitive**: `/FAVICON.ICO` also matches\n\n### Why Use Path Exemptions?\n\n- **Prevent SEO issues**: Search engines can safely crawl `/robots.txt`, `/sitemap.xml`\n- **Avoid blocking legitimate 404s**: `favicon.ico` requests won't trigger blocking\n- **Load balancer compatibility**: Health checks always work (`/health`, `/ping`)\n- **Static asset safety**: CSS/JS/images load without interference\n- **SSL certificate support**: `/.well-known/` URIs for ACME challenges\n\n## Web Server Logging\n\nAIWAF Flask includes comprehensive logging that generates **standard web server logs** compatible with tools like Gunicorn, Nginx, and Apache log analyzers.\n\n### Log Formats\n\n#### **Combined Log Format (Default)**\n```\n127.0.0.1 - - [14/Sep/2025:15:02:41 +0000] \"GET /api/data HTTP/1.1\" 200 1234 \"http://example.com\" \"Mozilla/5.0\" 50ms - \"-\"\n203.0.113.10 - - [14/Sep/2025:15:02:42 +0000] \"GET /admin.php HTTP/1.1\" 403 0 \"-\" \"BadBot/1.0\" 10ms BLOCKED \"Malicious keyword: .php\"\n```\n\n#### **CSV Format (Easy Analysis)**\n```csv\ntimestamp,ip,method,path,status_code,response_time_ms,blocked,block_reason\n2025-09-14T15:02:41,127.0.0.1,GET,/api/data,200,50,False,\n2025-09-14T15:02:42,203.0.113.10,GET,/admin.php,403,10,True,Malicious keyword: .php\n```\n\n#### **JSON Format (Structured)**\n```json\n{\"timestamp\": \"2025-09-14T15:02:41\", \"ip\": \"127.0.0.1\", \"method\": \"GET\", \"path\": \"/api/data\", \"status_code\": 200, \"blocked\": false}\n{\"timestamp\": \"2025-09-14T15:02:42\", \"ip\": \"203.0.113.10\", \"method\": \"GET\", \"path\": \"/admin.php\", \"status_code\": 403, \"blocked\": true, \"block_reason\": \"Malicious keyword: .php\"}\n```\n\n### Log Configuration\n\n```python\napp.config['AIWAF_ENABLE_LOGGING'] = True # Enable logging\napp.config['AIWAF_LOG_DIR'] = 'logs' # Log directory\napp.config['AIWAF_LOG_FORMAT'] = 'combined' # Format: combined, common, csv, json\n```\n\n### Generated Log Files\n\n- **`access.log`** - All HTTP requests (main access log)\n- **`error.log`** - HTTP errors (4xx, 5xx status codes)\n- **`aiwaf.log`** - AIWAF security events and blocks\n\n### Log Analysis\n\n```bash\n# Analyze logs with detailed statistics\npython aiwaf_console.py logs --log-dir logs --format combined\n\n# Sample output:\n# \ud83d\udcca AIWAF Access Log Analysis\n# Total Requests: 1,250\n# Blocked Requests: 45 (3.6%)\n# Average Response Time: 85ms\n# Top IPs, paths, block reasons, hourly patterns, etc.\n```\n\n## Usage Examples\n\nYour routes are automatically protected:\n\n```python\n@app.route('/')\ndef home():\n return render_template('home.html') # Protected by AIWAF\n\n@app.route('/api/data')\ndef api_data():\n return jsonify({'data': 'protected'}) # Rate limited & validated\n```\n\n## Managing Protection Lists\n\n```python\nfrom aiwaf_flask.storage import add_ip_whitelist, add_ip_blacklist, add_keyword\n\n# Add IPs to whitelist (bypass all protection)\nadd_ip_whitelist('192.168.1.100')\n\n# Add IPs to blacklist (block completely)\nadd_ip_blacklist('10.0.0.1', reason='Suspicious activity')\n\n# Add malicious keywords to block\nadd_keyword('wp-admin')\nadd_keyword('.env')\n```\n\n## CSV Files Structure\n\nWhen using CSV storage, AIWAF creates these files in your data directory:\n\n- `whitelist.csv` - Whitelisted IP addresses\n- `blacklist.csv` - Blacklisted IP addresses with reasons\n- `keywords.csv` - Blocked keywords\n\nExample `blacklist.csv`:\n```csv\nip,reason,added_date\n10.0.0.1,Suspicious activity,2025-09-14T10:30:00\n192.168.1.50,Rate limit exceeded,2025-09-14T11:15:00\n```\n\n## Command Line Management\n\nAIWAF Flask includes a powerful CLI tool for managing IP exemptions, blacklists, and blocked keywords from the command line.\n\n### Basic Usage\n\n```bash\n# Show help\npython aiwaf_console.py --help\n\n# Show current statistics\npython aiwaf_console.py stats\n\n# List all data\npython aiwaf_console.py list all\n```\n\n### IP Management\n\n```bash\n# Add IP to whitelist\npython aiwaf_console.py add whitelist 192.168.1.100\n\n# Add IP to blacklist with reason\npython aiwaf_console.py add blacklist 10.0.0.5 --reason \"Brute force attack\"\n\n# Remove IP from whitelist\npython aiwaf_console.py remove whitelist 192.168.1.100\n\n# Remove IP from blacklist\npython aiwaf_console.py remove blacklist 10.0.0.5\n\n# List specific data types\npython aiwaf_console.py list whitelist\npython aiwaf_console.py list blacklist\n```\n\n### Keyword Management\n\n```bash\n# Add blocked keyword\npython aiwaf_console.py add keyword \"sql injection\"\npython aiwaf_console.py add keyword \"script\"\n\n# List blocked keywords\npython aiwaf_console.py list keywords\n```\n\n### Configuration Backup/Restore\n\n```bash\n# Export current configuration\npython aiwaf_console.py export backup.json\n\n# Import configuration from backup\npython aiwaf_console.py import backup.json\n```\n\n### Custom Data Directory\n\n```bash\n# Use custom data directory\npython aiwaf_console.py --data-dir /path/to/custom/aiwaf_data stats\n```\n\n### Example CLI Session\n\n```bash\n# Check current status\npython aiwaf_console.py stats\n\n# Add some IPs to whitelist\npython aiwaf_console.py add whitelist 192.168.1.100\npython aiwaf_console.py add whitelist 10.0.0.50\n\n# Block a malicious IP\npython aiwaf_console.py add blacklist 203.0.113.10 --reason \"SQL injection attempts\"\n\n# Add dangerous keywords\npython aiwaf_console.py add keyword \"union select\"\npython aiwaf_console.py add keyword \"drop table\"\n\n# Review all settings\npython aiwaf_console.py list all\n\n# Create backup\npython aiwaf_console.py export production_backup.json\n```\n\n### Programmatic Management\n\nYou can also use the CLI functionality in your Python code:\n\n```python\nfrom aiwaf_flask.cli import AIWAFManager\n\n# Initialize manager\nmanager = AIWAFManager()\n\n# Add IPs programmatically\nmanager.add_to_whitelist(\"192.168.1.100\")\nmanager.add_to_blacklist(\"10.0.0.5\", \"Suspicious activity\")\n\n# Get current lists\nwhitelist = manager.list_whitelist()\nblacklist = manager.list_blacklist()\nkeywords = manager.list_keywords()\n\n# Export configuration\nmanager.export_config(\"backup.json\")\n```\n\n## CLI Features & Real-World Examples\n\nAIWAF Flask includes powerful command-line tools for production management. The CLI works independently without requiring Flask to be installed, making it perfect for system administration and automation.\n\n### Quick Setup\n\n```bash\n# Show CLI status and help\npython aiwaf_setup.py\n\n# Install Flask if needed (optional for CLI-only usage)\npython aiwaf_setup.py install-flask\n\n# Run interactive demo\npython aiwaf_setup.py demo\n```\n\n### Production Management Examples\n\n#### **Emergency IP Blocking**\n```bash\n# Block attacking IPs immediately\npython aiwaf_console.py add blacklist 203.0.113.10 --reason \"SQL injection attack detected\"\npython aiwaf_console.py add blacklist 198.51.100.5 --reason \"Brute force login attempts\"\npython aiwaf_console.py add blacklist 10.0.0.1 --reason \"Suspicious port scanning\"\n\n# Verify blocks are active\npython aiwaf_console.py list blacklist\n```\n\n#### **Whitelist Management**\n```bash\n# Add trusted networks\npython aiwaf_console.py add whitelist 192.168.1.0/24\npython aiwaf_console.py add whitelist 10.0.0.0/8\npython aiwaf_console.py add whitelist 172.16.0.0/12\n\n# Add specific trusted IPs\npython aiwaf_console.py add whitelist 203.0.113.100 # Office IP\npython aiwaf_console.py add whitelist 198.51.100.200 # API partner\n```\n\n#### **Security Keywords**\n```bash\n# Block common attack patterns\npython aiwaf_console.py add keyword \"union select\"\npython aiwaf_console.py add keyword \"drop table\"\npython aiwaf_console.py add keyword \"<script>\"\npython aiwaf_console.py add keyword \"javascript:\"\npython aiwaf_console.py add keyword \"eval(\"\npython aiwaf_console.py add keyword \"base64_decode\"\n\n# Review blocked keywords\npython aiwaf_console.py list keywords\n```\n\n#### **Daily Operations**\n```bash\n# Morning security check\npython aiwaf_console.py stats\n\n# Review recent blocks\npython aiwaf_console.py list blacklist\n\n# Create daily backup\npython aiwaf_console.py export \"backup-$(date +%Y%m%d).json\"\n\n# Clean up test entries\npython aiwaf_console.py remove whitelist 192.168.1.99\npython aiwaf_console.py remove blacklist 10.0.0.99\n```\n\n### Automation Scripts\n\n#### **Security Incident Response**\n```bash\n#!/bin/bash\n# incident_response.sh - Block multiple IPs from security incident\n\nMALICIOUS_IPS=(\n \"203.0.113.10\"\n \"198.51.100.5\" \n \"192.0.2.15\"\n \"198.51.100.25\"\n)\n\nfor ip in \"${MALICIOUS_IPS[@]}\"; do\n python aiwaf_console.py add blacklist \"$ip\" --reason \"Security incident #2025-001\"\ndone\n\n# Create incident backup\npython aiwaf_console.py export \"incident-2025-001-backup.json\"\necho \"Blocked ${#MALICIOUS_IPS[@]} IPs from security incident\"\n```\n\n#### **Configuration Deployment**\n```bash\n#!/bin/bash\n# deploy_config.sh - Deploy AIWAF configuration to production\n\n# Backup current config\npython aiwaf_console.py export \"backup-before-deploy-$(date +%Y%m%d-%H%M).json\"\n\n# Deploy new configuration\npython aiwaf_console.py import \"production-config.json\"\n\n# Verify deployment\npython aiwaf_console.py stats\npython aiwaf_console.py list all\n```\n\n### Real CLI Session Output\n\n```bash\n$ python aiwaf_console.py stats\n\ud83d\udcc1 Using CSV storage: aiwaf_data\n\n\ud83d\udcca AIWAF Statistics\n==================================================\nWhitelisted IPs: 5\nBlacklisted IPs: 3\nBlocked Keywords: 8\nStorage Mode: CSV\nData Directory: aiwaf_data\n\n$ python aiwaf_console.py list all\n\ud83d\udcc1 Using CSV storage: aiwaf_data\n\n\ud83d\udfe2 Whitelisted IPs (5):\n \u2022 192.168.1.100\n \u2022 192.168.1.200\n \u2022 10.0.0.50\n \u2022 203.0.113.100\n \u2022 198.51.100.200\n\n\ud83d\udd34 Blacklisted IPs (3):\n \u2022 203.0.113.10 - SQL injection attack detected (2025-09-14T09:15:30)\n \u2022 198.51.100.5 - Brute force login attempts (2025-09-14T10:22:15)\n \u2022 10.0.0.1 - Suspicious port scanning (2025-09-14T11:45:22)\n\n\ud83d\udeab Blocked Keywords (8):\n \u2022 union select\n \u2022 drop table\n \u2022 <script>\n \u2022 javascript:\n \u2022 eval(\n \u2022 base64_decode\n \u2022 onload=\n \u2022 document.cookie\n\n$ python aiwaf_console.py export production-backup.json\n\ud83d\udcc1 Using CSV storage: aiwaf_data\n\u2705 Configuration exported to production-backup.json\n```\n\n### Configuration Format\n\nThe exported JSON configuration contains all security settings:\n\n```json\n{\n \"whitelist\": [\n \"192.168.1.100\",\n \"192.168.1.200\",\n \"10.0.0.50\"\n ],\n \"blacklist\": {\n \"203.0.113.10\": {\n \"timestamp\": \"2025-09-14T09:15:30.123456\",\n \"reason\": \"SQL injection attack detected\"\n },\n \"198.51.100.5\": {\n \"timestamp\": \"2025-09-14T10:22:15.789012\", \n \"reason\": \"Brute force login attempts\"\n }\n },\n \"keywords\": [\n \"union select\",\n \"drop table\",\n \"<script>\",\n \"eval(\"\n ],\n \"exported_at\": \"2025-09-14T14:30:00.000000\",\n \"storage_mode\": \"CSV\"\n}\n```\n\n### Integration with Monitoring\n\n```bash\n# Add to crontab for daily reports\n0 9 * * * /path/to/python /path/to/aiwaf_console.py stats >> /var/log/aiwaf-daily.log\n\n# Add to monitoring script\npython aiwaf_console.py stats | grep -E \"(Blacklisted|Keywords)\" | \\\n awk '{if($3 > 100) print \"ALERT: High security blocks detected\"}'\n```\n\n## Production Deployment\n\n```python\n# config.py\nimport os\n\nclass ProductionConfig:\n # Use PostgreSQL in production\n SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')\n \n # Stricter limits for production\n AIWAF_RATE_MAX = 50\n AIWAF_RATE_FLOOD = 100\n AIWAF_MIN_FORM_TIME = 3.0\n\n# app.py\napp.config.from_object(ProductionConfig)\n```\n\n## License\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Advanced AI-powered Web Application Firewall for Flask with intelligent threat detection, rate limiting, IP blocking, and real-time protection against web attacks",
"version": "0.1.4b0",
"project_urls": {
"Bug Tracker": "https://github.com/aayushgauba/aiwaf-flask/issues",
"Documentation": "https://github.com/aayushgauba/aiwaf-flask#readme",
"Homepage": "https://github.com/aayushgauba/aiwaf-flask",
"Repository": "https://github.com/aayushgauba/aiwaf-flask.git"
},
"split_keywords": [
"flask",
" security",
" firewall",
" web",
" protection",
" middleware",
" rate-limiting",
" ip-blocking",
" ddos",
" waf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d2d5c3151bb54bf061af0d1c9c6185f72d082832320d4166b3476f26117af3fa",
"md5": "3137c326f2df305056165f2af2da411b",
"sha256": "60ad5b8e907f06844052bf4f9b94b112a660a61093d40d75c44c76b505cad5dd"
},
"downloads": -1,
"filename": "aiwaf_flask-0.1.4b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3137c326f2df305056165f2af2da411b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38442,
"upload_time": "2025-09-14T20:11:24",
"upload_time_iso_8601": "2025-09-14T20:11:24.055136Z",
"url": "https://files.pythonhosted.org/packages/d2/d5/c3151bb54bf061af0d1c9c6185f72d082832320d4166b3476f26117af3fa/aiwaf_flask-0.1.4b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "75035211ca6716cb662201a63676c04eb20d393243ae2919dfc074ed3b59781c",
"md5": "879635334e14e120059d6929f6ac7589",
"sha256": "45c37bc421b230d348fae4c461fdbe28a31b05ddc4c14c6ecd1837a92dc5a3b5"
},
"downloads": -1,
"filename": "aiwaf_flask-0.1.4b0.tar.gz",
"has_sig": false,
"md5_digest": "879635334e14e120059d6929f6ac7589",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42392,
"upload_time": "2025-09-14T20:11:25",
"upload_time_iso_8601": "2025-09-14T20:11:25.563399Z",
"url": "https://files.pythonhosted.org/packages/75/03/5211ca6716cb662201a63676c04eb20d393243ae2919dfc074ed3b59781c/aiwaf_flask-0.1.4b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 20:11:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aayushgauba",
"github_project": "aiwaf_flask",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiwaf-flask"
}
JSON
