Custom Regex Rules

The Custom Rule Engine operates as a Phase 1 Pre-Filter in the request pipeline (engine priority 250). It executes prior to the AST Semantic Analysis Engine (priority 290+). Custom rules are designed to intercept high-frequency reconnaissance, scanner headers, and custom application path blocks. When a rule triggers with a block action, execution short-circuits immediately, eliminating unnecessary AST parsing overhead.

You can manage custom rules visually in the Rules section of the Web Console (sites[].waf.custom_rules), via the cheesewaf rules CLI utility, or using REST APIs.

Configuration Example

custom_rules:
  - id: "block-admin-probe"
    name: "Admin path probe"
    pattern: "(?i)/(wp-admin|phpmyadmin|\\.git)"
    location: "uri"
    action: "block"
    severity: "medium"
    enabled: true
    priority: 180
  - id: "challenge-bot-header"
    name: "Challenge suspicious scraper header"
    pattern: "(?i)(headlesschrome|phantomjs)"
    location: "header"
    action: "challenge"
    severity: "high"
    enabled: true
    priority: 200

Field Reference & Valid Enumerations

Deterministic Enforcement & Policy Bypass

Custom rules represent explicit administrative intent rather than probabilistic detector signals. Within the data plane pipeline:

• Direct Execution: When a request matches a custom rule, the engine unconditionally and immediately executes the designated action (block, challenge, or log).
• Exempt from Policy Thresholds: Unlike semantic detections, custom rule actions bypass protection_policy.web_attack gates (such as minimum severity thresholds, model confidence filters, or aggregate risk score ceilings), guaranteeing deterministic enforcement as configured.

Security Constraints & Quota Limits

To prevent malformed or unbounded rules from causing performance degradation, the configuration validator enforces strict boundaries:

• Resource Limits: A single site supports up to 256 custom rules (maxCustomRulesCount = 256). Import document size must not exceed 1MB, and total pattern length across all rules cannot exceed 256KB. The imported document must explicitly define the custom_rules root key.
• ReDoS Immunity: Backed by Go’s regexp (RE2 guarantees linear-time execution, eliminating catastrophic backtracking ReDoS). Expressions exceeding 4096 compiled program instructions are rejected.
• Deduplication Check: Rule IDs must be unique within each site. Duplicate location + pattern combinations are strictly rejected.
• Content-Disposition Sanitization: When exporting rule archives (GET /api/rules/export), output filenames are strictly sanitized against an [A-Za-z0-9._-] whitelist, preventing HTTP response header injection and directory traversal attacks.

Batch Import, Export & Template Generation

CheeseWAF provides seamless CLI and Web UI workflows for importing and exporting rules in YAML and JSON:

1. CLI Management

# Generate official custom rule YAML template
cheesewaf rules example --format yaml --file template.yaml

# Validate and replace custom rules for a target site (triggers smooth daemon hot-reload)
cheesewaf rules import --site site-prod-01 --file new-rules.yaml

# Export custom rules of a site to JSON
cheesewaf rules export --site site-prod-01 --format json --file rules-backup.json

2. Web Management Console

In the Rules page of the Web Console, click the Import / Export button in the header:

• Drag and drop or upload local .yaml or .json rule definition files.
• Inspect syntax validation and preview differences prior to committing.
• Download a full JSON or YAML rule backup with a single click.

Operational Best Practices

• Focus on Definitive Signatures: Use custom rules for known static probes (admin interfaces, sensitive files, scanner fingerprints). Defer complex application injection patterns (SQL injection, XSS) to the AST semantic engine.
• Leverage Short-Circuiting: Order high-confidence malicious signatures with lower priority numbers to drop bad traffic early, minimizing server CPU load.