5c654b3da8
- VitePress: custom theme (SF system fonts, glass nav, soft surfaces, pill buttons, light/dark code blocks, refined feature cards, platform showcase + stat strip). - Replace every emoji across docs and README with inline SVG icons. - Verify and fix doc accuracy against actual scripts: JSON schema (category+pattern only), env-var configuration for json2*/import_* scripts, owasp2json CLI surface. - Add public assets (logo.svg, favicon.svg, hero-shield.svg) and Shiki haproxy alias. - Workflows default to self-hosted runner-02 with a configurable fallback to GitHub runners via the RUNS_ON repo variable. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3.9 KiB
Getting Started
This guide walks you through installing Patterns and integrating the generated WAF rules into your web server.
Prerequisites
| Requirement | Notes |
|---|---|
| Python 3.11+ | Only required when building from source. The CI workflow targets 3.11. |
| pip | To install the packages listed in requirements.txt. |
| git | Optional — only needed if cloning the repository. |
Two installation paths
Option 1 — Download a pre-built release
The fastest path. A scheduled GitHub Actions workflow rebuilds every archive daily and publishes them on the Releases page.
| Archive | Contains | Target |
|---|---|---|
nginx_waf.zip |
waf_maps.conf, waf_rules.conf, bots.conf, category files |
Nginx |
apache_waf.zip |
Per-category ModSecurity .conf files, bots.conf |
Apache + mod_security2 |
traefik_waf.zip |
middleware.toml, bots.toml |
Traefik (file provider) |
haproxy_waf.zip |
waf.acl, bots.acl |
HAProxy |
Pick one, extract, then jump to the matching integration guide.
Option 2 — Build from source
Choose this path if you want to pin a specific OWASP CRS tag, customize the converter, or run the toolchain in your own CI:
git clone https://github.com/fabriziosalmi/patterns.git
cd patterns
pip install -r requirements.txt
# 1. Fetch the latest OWASP Core Rule Set into a JSON intermediate
python owasp2json.py
# 2. Convert the JSON into native rules for your platform
python json2nginx.py
python json2apache.py
python json2traefik.py
python json2haproxy.py
# 3. Generate bad-bot blocklists alongside
python badbots.py
::: tip GitHub API rate limits
owasp2json.py reads from the GitHub API. Set GITHUB_TOKEN in your environment to raise the rate limit when iterating locally.
:::
Output layout
After running the converters, generated files live under waf_patterns/:
waf_patterns/
├── nginx/ # waf_maps.conf, waf_rules.conf, bots.conf, per-category files
├── apache/ # sqli.conf, xss.conf, rce.conf, lfi.conf, … bots.conf
├── traefik/ # middleware.toml, bots.toml
└── haproxy/ # waf.acl, bots.acl
Next steps
Choose your platform to wire the rules into a running server:
For details on the bot blocklist itself, see Bad Bot Detection. For a reference of every script and the JSON schema that ties them together, see the API reference.
How updates flow
┌─────────────────────┐ daily cron ┌──────────────────────┐
│ coreruleset/ │ ───────────────▶ │ owasp2json.py │
│ coreruleset (GH) │ │ → owasp_rules.json │
└─────────────────────┘ └──────────┬───────────┘
│
┌─────────────────┬──────────────────┬──────┴──────────┐
▼ ▼ ▼ ▼
json2nginx.py json2apache.py json2traefik.py json2haproxy.py
│ │ │ │
▼ ▼ ▼ ▼
nginx_waf.zip apache_waf.zip traefik_waf.zip haproxy_waf.zip
(published as a GitHub Release)
To stay current, either download the latest archive or git pull and re-run the converters.