mirror of
https://github.com/fabriziosalmi/patterns.git
synced 2025-12-17 17:55:48 +00:00
ea474cbcf2
- Create docs/ directory with VitePress configuration - Add documentation for all web servers (Nginx, Apache, Traefik, HAProxy) - Add bad bot detection and API reference documentation - Add GitHub Actions workflow for automatic deployment to GitHub Pages - Configure VitePress with sidebar, navigation, and search
224 lines
4.1 KiB
Markdown
224 lines
4.1 KiB
Markdown
# API Reference
|
|
|
|
This page documents the Python scripts that power the Patterns project.
|
|
|
|
## Core Scripts
|
|
|
|
### owasp2json.py
|
|
|
|
Fetches and parses OWASP Core Rule Set patterns from GitHub.
|
|
|
|
```bash
|
|
python owasp2json.py
|
|
```
|
|
|
|
**Output**: `owasp_rules.json`
|
|
|
|
**Configuration**:
|
|
- Uses environment variable `OWASP_REPO` to specify source repository
|
|
- Default: `coreruleset/coreruleset`
|
|
|
|
**Features**:
|
|
- Fetches latest CRS rules from GitHub
|
|
- Parses `.conf` files for regex patterns
|
|
- Extracts rule metadata (ID, severity, category)
|
|
- Outputs structured JSON for conversion scripts
|
|
|
|
---
|
|
|
|
### json2nginx.py
|
|
|
|
Converts OWASP JSON rules to Nginx WAF configuration.
|
|
|
|
```bash
|
|
python json2nginx.py
|
|
```
|
|
|
|
**Input**: `owasp_rules.json`
|
|
**Output**: `waf_patterns/nginx/`
|
|
|
|
**Generated Files**:
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `waf_maps.conf` | Map directives (http block) |
|
|
| `waf_rules.conf` | If statements (server block) |
|
|
| `README.md` | Integration instructions |
|
|
|
|
**Environment Variables**:
|
|
- `INPUT_FILE` - Path to OWASP JSON (default: `owasp_rules.json`)
|
|
- `OUTPUT_DIR` - Output directory (default: `waf_patterns/nginx`)
|
|
|
|
---
|
|
|
|
### json2apache.py
|
|
|
|
Converts OWASP JSON rules to Apache ModSecurity format.
|
|
|
|
```bash
|
|
python json2apache.py
|
|
```
|
|
|
|
**Input**: `owasp_rules.json`
|
|
**Output**: `waf_patterns/apache/`
|
|
|
|
**Generated Files**:
|
|
- Category-specific `.conf` files (sqli.conf, xss.conf, etc.)
|
|
- Each file contains ModSecurity `SecRule` directives
|
|
|
|
---
|
|
|
|
### json2traefik.py
|
|
|
|
Converts OWASP JSON rules to Traefik middleware configuration.
|
|
|
|
```bash
|
|
python json2traefik.py
|
|
```
|
|
|
|
**Input**: `owasp_rules.json`
|
|
**Output**: `waf_patterns/traefik/`
|
|
|
|
**Generated Files**:
|
|
- `middleware.toml` - Traefik middleware configuration
|
|
- `README.md` - Integration instructions
|
|
|
|
---
|
|
|
|
### json2haproxy.py
|
|
|
|
Converts OWASP JSON rules to HAProxy ACL format.
|
|
|
|
```bash
|
|
python json2haproxy.py
|
|
```
|
|
|
|
**Input**: `owasp_rules.json`
|
|
**Output**: `waf_patterns/haproxy/`
|
|
|
|
**Generated Files**:
|
|
- `waf.acl` - Main WAF ACL rules
|
|
- `README.md` - Integration instructions
|
|
|
|
---
|
|
|
|
### badbots.py
|
|
|
|
Generates bad bot blocking configurations from public bot lists.
|
|
|
|
```bash
|
|
python badbots.py
|
|
```
|
|
|
|
**Output**: Bot configurations in each `waf_patterns/*/` directory
|
|
|
|
**Features**:
|
|
- Fetches from multiple public bot lists
|
|
- Includes fallback sources for reliability
|
|
- Generates platform-specific configs
|
|
|
|
---
|
|
|
|
## Import Scripts
|
|
|
|
These scripts help import existing WAF configurations.
|
|
|
|
### import_nginx_waf.py
|
|
|
|
Import Nginx WAF patterns from external sources.
|
|
|
|
```bash
|
|
python import_nginx_waf.py --source /path/to/external/rules
|
|
```
|
|
|
|
### import_apache_waf.py
|
|
|
|
Import Apache ModSecurity rules.
|
|
|
|
```bash
|
|
python import_apache_waf.py --source /path/to/modsec/rules
|
|
```
|
|
|
|
### import_traefik_waf.py
|
|
|
|
Import Traefik middleware configurations.
|
|
|
|
```bash
|
|
python import_traefik_waf.py --source /path/to/traefik/config
|
|
```
|
|
|
|
### import_haproxy_waf.py
|
|
|
|
Import HAProxy ACL rules.
|
|
|
|
```bash
|
|
python import_haproxy_waf.py --source /path/to/haproxy/acl
|
|
```
|
|
|
|
---
|
|
|
|
## Data Structures
|
|
|
|
### owasp_rules.json Format
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "942100",
|
|
"pattern": "(?i:union.*select)",
|
|
"category": "sqli",
|
|
"severity": "critical",
|
|
"location": "request-uri",
|
|
"description": "SQL Injection Attack Detected"
|
|
}
|
|
]
|
|
```
|
|
|
|
**Fields**:
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `id` | string | OWASP CRS rule ID |
|
|
| `pattern` | string | Regex pattern |
|
|
| `category` | string | Attack category (sqli, xss, rce, etc.) |
|
|
| `severity` | string | critical, high, medium, low |
|
|
| `location` | string | Where to match (request-uri, headers, etc.) |
|
|
| `description` | string | Human-readable description |
|
|
|
|
---
|
|
|
|
## Extending the Project
|
|
|
|
### Adding a New Platform
|
|
|
|
1. Create `json2<platform>.py` based on existing converters
|
|
2. Add output directory in `waf_patterns/<platform>/`
|
|
3. Update GitHub Actions workflow
|
|
4. Add documentation in `docs/`
|
|
|
|
### Custom Pattern Sources
|
|
|
|
Modify `owasp2json.py` to add new pattern sources:
|
|
|
|
```python
|
|
SOURCES = [
|
|
"coreruleset/coreruleset",
|
|
"your-org/your-rules",
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
Listed in `requirements.txt`:
|
|
|
|
```
|
|
requests>=2.28.0
|
|
beautifulsoup4>=4.11.0
|
|
```
|
|
|
|
Install with:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|