octorules-google

Google Cloud Armor provider for octorules — manages Cloud Armor security policy rules as YAML.

Installation

pip install octorules-google

This installs octorules (core), octorules-google, and cel-python for CEL expression validation in the linter. The provider is auto-discovered — no class: needed in config.

Configuration

providers:
  google:
    project: my-gcp-project
  rules:
    directory: ./rules

zones:
  my-security-policy:
    sources:
      - rules

Each zone name maps to a Cloud Armor security policy name. The provider resolves policy names at runtime.

Authentication

Authentication uses Application Default Credentials — no token is needed in the config file. Common options:

• gcloud auth application-default login — for local development
• Service account key: set GOOGLE_APPLICATION_CREDENTIALS to the JSON key path
• Workload Identity (GKE, Cloud Run): automatic

Required IAM permissions:

• compute.securityPolicies.get, compute.securityPolicies.update — for rule operations
• compute.securityPolicies.list — for zone discovery
• compute.securityPolicies.addRule, compute.securityPolicies.removeRule — for rule changes

Provider settings

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

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-security-policy.yaml demonstrating every supported phase and key. Copy it as a starting point.

Supported features

Phase mapping

Rules are identified by their integer priority (mapped to ref in octorules). All phases require action to be specified explicitly (no default action).

Rule format

Cloud Armor rules nest under a single google: block. The ref field maps to the rule's integer priority:

# rules/my-security-policy.yaml
google:
  custom_rules:
    - ref: "1000"
      description: "Block known bad IPs"
      action: deny(403)
      match:
        versioned_expr: SRC_IPS_V1
        config:
          src_ip_ranges:
            - "1.2.3.4/32"
            - "5.6.7.0/24"

    - ref: "2000"
      description: "Rate limit API endpoints"
      action: throttle
      match:
        expr:
          expression: "request.path.startsWith('/api/')"
      rate_limit_options:
        conform_action: allow
        exceed_action: deny-429
        rate_limit_threshold:
          count: 100
          interval_sec: 60

  preconfigured_rules:
    - ref: "3000"
      description: "OWASP SQL injection protection"
      action: deny(403)
      match:
        expr:
          expression: "evaluatePreconfiguredWaf('sqli-v33-stable')"

  policy_settings:
    ddosProtectionConfig:
      ddosProtection: ADVANCED

CEL expressions

Cloud Armor uses CEL (Common Expression Language) for advanced match expressions. Examples:

# IP-based matching
match:
  expr:
    expression: "inIpRange(origin.ip, '10.0.0.0/8')"

# Header matching
match:
  expr:
    expression: "request.headers['user-agent'].contains('BadBot')"

# Geo-based matching
match:
  expr:
    expression: "origin.region_code == 'US'"

Rule-level metadata: All Cloud Armor 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.

Linting

88 Cloud Armor-specific lint rules (GA prefix) covering structure, expressions, actions, rate limiting, redirects, sub-structure validation, and cross-rule analysis:

octorules lint --config config.yaml

Lint rules are registered automatically when octorules-google is installed. CEL expression validation uses cel-python. See docs/lint.md for the full rule reference with examples.

Known limitations

• Non-atomic updates: Cloud Armor does not support atomic bulk rule replacement. put_phase_rules patches existing rules in place, adds new rules, then removes stale rules — so the policy never has fewer rules than intended. Each API call is retried for transient errors with exponential backoff. If an operation fails after retries, partial progress is logged and the next sync will reconcile.
• Policy creation/deletion: octorules-google manages rules within existing security policies. Creating or deleting policies (and attaching them to backend services) should be done via gcloud or Terraform.
• Policy creation is out of scope, policy settings are not. Policy-level settings (adaptive_protection_config, advanced_options_config, ddos_protection_config, default_rule_action, recaptcha_options_config) are managed under google: policy_settings: in the zone file. Anything above that level — creating or deleting the policy itself — belongs to gcloud or Terraform.

Note: Per-rule rate limiting fields (enforceOnKey, enforceOnKeyConfigs, banDurationSec), header actions (headerAction), and CEL functions like evaluateThreatIntelligence() are already supported — they pass through as-is in the rule dict.

Development

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

License

octorules-google is licensed under the Apache License 2.0.