octorules-aws

AWS WAF v2 provider for octorules — manages AWS WAF Web ACL rules, Rule Groups, and IP Sets as YAML.

Installation

pip install octorules-aws

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

Configuration

providers:
  aws:
    region: us-east-1
    waf_scope: REGIONAL
  rules:
    directory: ./rules

zones:
  my-web-acl:
    sources:
      - rules

Each zone name maps to an AWS WAF Web ACL name. The provider resolves Web ACL names to IDs at runtime.

Authentication

AWS credentials are resolved via the standard boto3 credential chain — no token is needed in the config file. Common options:

• Environment variables: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
• Shared credentials file: ~/.aws/credentials
• IAM role (EC2, ECS, Lambda): automatic

Required IAM permissions:

• wafv2:GetWebACL, wafv2:UpdateWebACL — for phase rule operations
• wafv2:ListWebACLs — for zone ID resolution and zone discovery
• wafv2:GetRuleGroup, wafv2:UpdateRuleGroup, wafv2:ListRuleGroups — for custom rulesets (Rule Groups)
• wafv2:GetIPSet, wafv2:UpdateIPSet, wafv2:CreateIPSet, wafv2:DeleteIPSet, wafv2:ListIPSets — for lists (IP Sets)

Provider settings

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

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/my-web-acl.yaml demonstrating every supported phase and key using the nested aws: format. Copy it as a starting point.

Zone files nest all AWS WAF sections under a single aws: block.

Supported features

Phase mapping

All phases require action to be specified explicitly (no default action).

Rule-level metadata: All AWS WAF rules support the octorules: key for per-rule metadata — ignored: true to skip a rule during plan/sync, and included/excluded to restrict rules to specific providers. See octorules core docs for syntax and examples.

Custom rulesets (Rule Groups)

AWS WAF Rule Groups map to octorules custom rulesets. octorules manages the full lifecycle: create, update rules, and delete.

Managing an existing Rule Group

# rules/my-web-acl.yaml
aws:
  custom_rulesets:
    - id: abcd1234-5678-9012-3456-789012345678
      name: My Rule Group
      phase: aws_waf_custom
      rules:
        - ref: block-bad-ips
          Action:
            Block: {}
          Statement:
            IPSetReferenceStatement:
              ARN: arn:aws:wafv2:us-east-1:123456789012:regional/ipset/blocked/efgh5678
          VisibilityConfig:
            SampledRequestsEnabled: true
            CloudWatchMetricsEnabled: true
            MetricName: BlockBadIPs

Creating a new Rule Group

Omit the id field and add capacity to create a new Rule Group:

aws:
  custom_rulesets:
    - name: Block Bad Actors
      capacity: 100
      phase: aws_waf_custom
      rules:
        - ref: block-scanner
          Action:
            Block: {}
          Statement:
            ByteMatchStatement:
              SearchString: "BadBot"
              FieldToMatch:
                SingleHeader:
                  Name: user-agent
              PositionalConstraint: CONTAINS
              TextTransformations:
                - Priority: 0
                  Type: LOWERCASE
          VisibilityConfig:
            SampledRequestsEnabled: true
            CloudWatchMetricsEnabled: true
            MetricName: BlockScanner

capacity is an AWS WAF concept — an immutable budget (1-5000) that limits rule complexity within the Rule Group. It cannot be changed after creation. If you need more capacity, delete and recreate the Rule Group with a higher value.

How it works:

• The name field is the identity key. Rule Groups are matched between YAML and AWS by name.
• The presence of a custom_rulesets: key means ALL Rule Groups are managed — Rule Groups in AWS not in YAML are planned for deletion.
• If the custom_rulesets: key is absent, Rule Groups are ignored entirely.
• id is optional: present for existing Rule Groups, absent for new ones.
• After creation, use octorules dump to export the assigned id back to YAML.

Lists (IP Sets & Regex Pattern Sets)

AWS WAF IP Sets and Regex Pattern Sets map to octorules lists. Add a lists section under aws::

# rules/my-web-acl.yaml
aws:
  lists:
    - name: blocked-ips
      kind: ip
      description: "Known bad IPs"
      items:
        - ip: "1.2.3.4/32"
        - ip: "10.0.0.0/8"

    - name: bad-ua-patterns
      kind: regex
      description: "Bad user-agent patterns"
      items:
        - pattern: "BadBot.*"
        - pattern: "EvilCrawler/\\d+"

IP lists (kind: ip) map to AWS WAF IP Sets. Regex lists (kind: regex) map to AWS WAF Regex Pattern Sets and are referenced via RegexPatternSetReferenceStatement.

Note: ASN, hostname, and redirect list kinds are not available for AWS WAF.

Linting

96 AWS-specific lint rules (WA prefix) covering structure, actions, statements, and cross-rule analysis:

octorules lint --config config.yaml

Lint rules are registered automatically when octorules-aws is installed. See docs/lint.md for the full rule reference with examples.

Note: WA500 checks for duplicate MetricName within a single phase. WA501 checks across phases — AWS WAF requires MetricName to be unique across all rules in a Web ACL.

Known limitations

• Web ACL creation/deletion: octorules-aws manages rules and Rule Groups within existing Web ACLs. Creating or deleting Web ACLs must be done via the AWS console, CLI, or Terraform.
• Concurrent updates: Rule updates use AWS WAF optimistic locking (LockToken). Stale lock errors are retried automatically (up to 3 attempts with linear backoff). If the same Web ACL is updated by multiple writers targeting the same phase simultaneously, the last writer wins.
• Rule Group capacity is immutable: AWS WAF sets Rule Group capacity at creation time. To change capacity, delete and recreate the Rule Group with the new value.

Development

git clone git@github.com:doctena-org/octorules-aws.git
cd octorules-aws
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

License

octorules-aws is licensed under the Apache License 2.0.