{"id":48431380,"url":"https://github.com/doctena-org/octorules-google","last_synced_at":"2026-04-06T11:01:01.668Z","repository":{"id":345711054,"uuid":"1185256753","full_name":"doctena-org/octorules-google","owner":"doctena-org","description":"Google Cloud Armor provider for octorules","archived":false,"fork":false,"pushed_at":"2026-03-31T13:29:15.000Z","size":260,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T15:27:35.681Z","etag":null,"topics":["cloud-armor","firewall","gcp","iac","octorules","security","yaml"],"latest_commit_sha":null,"homepage":"https://github.com/doctena-org/octorules","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doctena-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T11:54:13.000Z","updated_at":"2026-03-31T13:29:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/doctena-org/octorules-google","commit_stats":null,"previous_names":["doctena-org/octorules-google"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/doctena-org/octorules-google","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctena-org%2Foctorules-google","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctena-org%2Foctorules-google/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctena-org%2Foctorules-google/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctena-org%2Foctorules-google/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doctena-org","download_url":"https://codeload.github.com/doctena-org/octorules-google/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doctena-org%2Foctorules-google/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-armor","firewall","gcp","iac","octorules","security","yaml"],"created_at":"2026-04-06T11:01:00.738Z","updated_at":"2026-04-06T11:01:01.659Z","avatar_url":"https://github.com/doctena-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# octorules-google\n\nGoogle Cloud Armor provider for [octorules](https://github.com/doctena-org/octorules) — manages Cloud Armor security policy rules as YAML.\n\n## Installation\n\n```bash\npip install octorules-google\n```\n\nThis installs octorules (core), octorules-google, and\n[cel-python](https://pypi.org/project/cel-python/) for CEL expression\nvalidation in the linter. The provider is auto-discovered — no `class:` needed\nin config.\n\n## Configuration\n\n```yaml\nproviders:\n  google:\n    project: my-gcp-project\n  rules:\n    directory: ./rules\n\nzones:\n  my-security-policy:\n    sources:\n      - rules\n```\n\nEach zone name maps to a Cloud Armor security policy name. The provider\nresolves policy names at runtime.\n\n### Authentication\n\nAuthentication uses\n[Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)\n— no token is needed in the config file. Common options:\n\n- **`gcloud auth application-default login`** — for local development\n- **Service account key**: set `GOOGLE_APPLICATION_CREDENTIALS` to the JSON key path\n- **Workload Identity** (GKE, Cloud Run): automatic\n\nRequired IAM permissions:\n\n- `compute.securityPolicies.get`, `compute.securityPolicies.update` — for rule operations\n- `compute.securityPolicies.list` — for zone discovery\n- `compute.securityPolicies.addRule`, `compute.securityPolicies.removeRule` — for rule changes\n\n### Provider settings\n\nAll settings below go under the provider section (e.g. `providers.google`).\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `project` | `GCLOUD_PROJECT` env var | GCP project ID (required) |\n| `timeout` | `30` | API timeout in seconds |\n\nSafety thresholds are configured under `safety:` (framework-owned, not forwarded to the provider):\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `safety.delete_threshold` | `30.0` | Max % of rules that can be deleted |\n| `safety.update_threshold` | `30.0` | Max % of rules that can be updated |\n| `safety.min_existing` | `3` | Min rules before thresholds apply |\n\n## Supported features\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| Phase rules (4 phases) | Supported | Security policy rules |\n| Policy settings | Supported | Adaptive protection, DDoS config, default rule action |\n| Custom rulesets | Not supported | — |\n| Lists | Not supported | Use inline IP ranges in match config |\n| Page Shield | Not supported | — |\n| Zone discovery (`list_zones`) | Supported | Lists security policies |\n| Account-level scopes | Not supported | — |\n| Audit IP extraction (`octorules audit`) | Supported | `src_ip_ranges` + `inIpRange()` CEL |\n\n## Phase mapping\n\n| octorules phase | Cloud Armor concept |\n|---|---|\n| `gcloud_armor_custom_rules` | Custom rules (IP match, geo match, CEL expressions) |\n| `gcloud_armor_rate_rules` | Rate-limiting rules (throttle / rate_based_ban) |\n| `gcloud_armor_preconfigured_rules` | Preconfigured WAF rules (OWASP ModSecurity, etc.) |\n| `gcloud_armor_redirect_rules` | Redirect rules (302 response) |\n\nRules are identified by their integer **priority** (mapped to `ref` in octorules). All phases require `action` to be specified explicitly (no default action).\n\n## Rule format\n\nCloud Armor rules use a different structure from other providers. The `ref` field maps to the rule's integer priority:\n\n```yaml\n# rules/my-security-policy.yaml\ngcloud_armor_custom_rules:\n  - ref: \"1000\"\n    description: \"Block known bad IPs\"\n    action: deny(403)\n    match:\n      versioned_expr: SRC_IPS_V1\n      config:\n        src_ip_ranges:\n          - \"1.2.3.4/32\"\n          - \"5.6.7.0/24\"\n\n  - ref: \"2000\"\n    description: \"Rate limit API endpoints\"\n    action: throttle\n    match:\n      expr:\n        expression: \"request.path.startsWith('/api/')\"\n    rate_limit_options:\n      conform_action: allow\n      exceed_action: deny-429\n      rate_limit_threshold:\n        count: 100\n        interval_sec: 60\n\ngcloud_armor_preconfigured_rules:\n  - ref: \"3000\"\n    description: \"OWASP SQL injection protection\"\n    action: deny(403)\n    match:\n      expr:\n        expression: \"evaluatePreconfiguredWaf('sqli-v33-stable')\"\n```\n\n### CEL expressions\n\nCloud Armor uses [CEL (Common Expression Language)](https://cloud.google.com/armor/docs/rules-language-reference) for advanced match expressions. Examples:\n\n```yaml\n# IP-based matching\nmatch:\n  expr:\n    expression: \"inIpRange(origin.ip, '10.0.0.0/8')\"\n\n# Header matching\nmatch:\n  expr:\n    expression: \"request.headers['user-agent'].contains('BadBot')\"\n\n# Geo-based matching\nmatch:\n  expr:\n    expression: \"origin.region_code == 'US'\"\n```\n\n\u003e **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](https://github.com/doctena-org/octorules#rule-level-metadata) for syntax and examples.\n\n## Linting\n\n74 Cloud Armor-specific lint rules (GA prefix) covering structure, expressions, actions, rate limiting, redirects, sub-structure validation, and cross-rule analysis:\n\n| Prefix | Category | Rules |\n|--------|----------|-------|\n| GA001-GA003 | Structure | 3 |\n| GA100-GA108 | Priority / cross-rule | 7 |\n| GA200-GA201 | Action | 2 |\n| GA300-GA327 | Match / expression / CEL / sub-structure | 21 |\n| GA400-GA432 | Rate limit / redirect / action params | 31 |\n| GA500-GA503 | Best practice | 3 |\n| GA600-GA602 | Preview / catch-all | 3 |\n\n```bash\noctorules lint --config config.yaml\n```\n\nLint rules are registered automatically when octorules-google is installed. CEL expression validation uses [cel-python](https://pypi.org/project/cel-python/). See [docs/lint.md](docs/lint.md) for the full rule reference with examples.\n\n## Known limitations\n\n- **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.\n- **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.\n- **Policy settings require the extension.** Policy-level settings (`adaptive_protection_config`, `advanced_options_config`, `ddos_protection_config`, `default_rule_action`) are managed via the `gcloud_armor_policy_settings` extension. Without the extension enabled, these settings should be managed via `gcloud` or Terraform.\n\n\u003e **Note:** Per-rule rate limiting fields (`enforceOnKey`, `enforceOnKeyConfigs`, `banDurationSec`), header actions (`headerAction`), and CEL functions like `evaluateJsonPath()` are already supported — they pass through as-is in the rule dict.\n\n## Development\n\n```bash\ngit clone git@github.com:doctena-org/octorules-google.git\ncd octorules-google\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\nln -sf ../../scripts/hooks/pre-commit .git/hooks/pre-commit\n```\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoctena-org%2Foctorules-google","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoctena-org%2Foctorules-google","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoctena-org%2Foctorules-google/lists"}