octorules-azure

Azure WAF provider for octorules — manages Azure Web Application Firewall custom rules as YAML.

Supports both Azure Front Door WAF (Premium/Standard) and Application Gateway WAF (WAF_v2) through a unified interface. Users write the same YAML regardless of which WAF type is deployed.

Alpha — this provider has comprehensive offline test coverage (698 tests) but has not yet been tested against live Azure WAF APIs. Use with caution and report any issues.

Installation

pip install octorules-azure

This installs octorules (core) and octorules-azure. The provider is auto-discovered — no class: needed in config.

Configuration

# config.yaml
providers:
  azure:
    subscription_id: env/AZURE_SUBSCRIPTION_ID
    resource_group: rg-waf-production
    waf_type: front_door       # or "app_gateway"
    timeout: 30                # API timeout in seconds
    max_workers: 1             # parallel workers for multi-zone ops
  rules:
    directory: ./rules

zones:
  apiwafpolicy:
    sources:
      - rules
  websitewafpolicy:
    sources:
      - rules

Each zone name maps to an Azure WAF policy name. The provider resolves policy names at runtime. Front Door WAF policy names allow only alphanumerics and must start with a letter; Application Gateway policy names also allow hyphens, periods, and underscores. The env/ prefix resolves values from environment variables at runtime. All keys under the provider section are forwarded to the provider constructor as keyword arguments (octodns-style passthrough).

Provider settings

All settings below go under the provider section (e.g. providers.azure).

Authentication

Uses DefaultAzureCredential — no token is needed in the config file. Common options:

• Service principal (CI/CD): AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET env vars
• Managed identity (Azure VMs, ACI, App Service): assign identity to the resource, grant WAF Contributor role
• Azure CLI (local development): run az login before octorules commands
• Certificate (automated systems): AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_CERTIFICATE_PATH env vars

The service principal or managed identity needs the Contributor or Network Contributor role on the resource group containing WAF policies.

Safety thresholds are configured under safety: (framework-owned, not forwarded to the provider):

Examples

The examples/ directory contains a working single-provider config.yaml plus rules/examplewafpolicy.yaml demonstrating every supported phase and key. Copy it as a starting point.

Nested format (recommended)

All Azure WAF sections nest under a single azure: block:

# rules/examplewafpolicy.yaml
azure:
  waf_custom_rules:
    - ref: BlockBadIPs
      priority: 1
      action: Block
      matchConditions:
        - matchVariable: RemoteAddr
          operator: IPMatch
          matchValue:
            - 192.168.1.0/24

  waf_rate_rules:
    - ref: RateLimitAPI
      priority: 100
      action: Block
      ruleType: RateLimitRule
      rateLimitDurationInMinutes: 1
      rateLimitThreshold: 100
      groupBy:
        - variableName: SocketAddr
      matchConditions:
        - matchVariable: RequestUri
          operator: BeginsWith
          matchValue:
            - /api/

  waf_managed_rules:
    - ref: Microsoft_DefaultRuleSet
      ruleSetType: Microsoft_DefaultRuleSet
      ruleSetVersion: "2.1"
      ruleSetAction: Block

  waf_policy_settings:
    mode: Prevention
    requestBodyCheck: Enabled

  waf_managed_exclusions:
    - matchVariable: RequestArgNames
      selectorMatchOperator: Equals
      selector: q

Supported features

Phases

Rule format

The same YAML format works for both Front Door and Application Gateway. The adapter translates API-level differences (field naming, SDK models) transparently.

Custom rules

# rules/examplewafpolicy.yaml
azure:
  waf_custom_rules:
    # Block specific IP ranges
    - ref: BlockBadIPs
      priority: 1
      action: Block
      matchConditions:
        - matchVariable: RemoteAddr
          operator: IPMatch
          matchValue:
            - 192.168.1.0/24
            - 10.0.0.0/8

    # Block requests with suspicious user-agent
    - ref: BlockBadUserAgents
      priority: 2
      action: Block
      matchConditions:
        - matchVariable: RequestHeader
          selector: User-Agent
          operator: Contains
          matchValue:
            - evilbot
            - scanner
          transforms:
            - Lowercase

    # Geo-block: allow only US and CA
    - ref: GeoBlock
      priority: 3
      action: Block
      matchConditions:
        - matchVariable: RemoteAddr
          operator: GeoMatch
          negateCondition: true
          matchValue:
            - US
            - CA

    # Block requests matching a regex pattern
    - ref: BlockAdminPaths
      priority: 4
      action: Block
      matchConditions:
        - matchVariable: RequestUri
          operator: RegEx
          matchValue:
            - "^/admin/.*\\.php$"
          transforms:
            - Lowercase

Rate-limit rules

azure:
  waf_rate_rules:
    # Rate limit API endpoints to 100 requests per minute per client IP
    - ref: RateLimitAPI
      priority: 100
      action: Block
      ruleType: RateLimitRule
      rateLimitDurationInMinutes: 1
      rateLimitThreshold: 100
      groupBy:
        - variableName: SocketAddr
      matchConditions:
        - matchVariable: RequestUri
          operator: BeginsWith
          matchValue:
            - /api/

Rule fields reference

Match condition fields

WAF Type Differences

The adapter pattern handles all API differences transparently. Users write identical YAML regardless of waf_type:

Linting

79 lint rules with AZ prefix covering structure, priority, action, match conditions, rate limits, cross-rule analysis, best practices, and managed rule sets. See docs/lint.md for the full reference with examples.

octorules lint --config config.yaml

Known limitations

• Front Door propagation delay: Configuration changes can take up to 45 minutes to propagate to all edge nodes globally. Plan accordingly for production deployments.
• No PATCH API: Azure WAF uses full-policy PUT. octorules always fetches the current policy first and merges changes, but concurrent external modifications during sync could conflict (mitigated by ETag retry).
• No custom rulesets or lists: Azure WAF has no equivalent of AWS Rule Groups or IP Sets. IP addresses are inline in matchConditions (max 600 per condition, 60,000 across all rules).
• Regex limit: Maximum 5 custom rules using the RegEx operator per policy.
• Priority must be globally unique: Rule priorities must be unique across ALL custom rules in a policy (both MatchRule and RateLimitRule combined), not just within a phase.

Development

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -v
.venv/bin/ruff check octorules_azure/ tests/
.venv/bin/ruff format --check octorules_azure/ tests/

Pre-commit hook:

pre-commit install

License

octorules-azure is licensed under the Apache License 2.0.