pi-cloudflare 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cloudflare",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Cloudflare Agent Plugin and native Pi extension providing official skills and cf_-prefixed MCP tools.",
   "keywords": [
     "agent-plugin",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pi-cloudflare",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Cloudflare skills and cf_-prefixed MCP tools, with a native Pi adapter and an Agent Plugins 1.0 portable runtime.",
   "author": {
     "name": "0xPlayerOne",

package/skills/cloudflare-hardening/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: cloudflare-hardening
+description: Audits and hardens every Cloudflare account and zone in a user's estate by adopting free-tier security, performance, and reliability features. Use when a user asks to audit, harden, secure, optimize, or "get the most out of" Cloudflare, mentions Security Center insights, free-tier features, DNSSEC, WAF, security headers, cache or compression rules, TLS settings, bot protection, or Turnstile, or wants an estate-wide review rather than a single-zone change.
+---
+
+# Cloudflare hardening
+
+Takes a user's whole Cloudflare estate — every account, every zone — and moves it
+to a hardened, optimized baseline using features available on its plans.
+
+Two properties matter more than speed:
+
+- **Measure first.** The estate is the source of truth, not this document. Many
+  "gaps" are already handled by the origin, and several changes that look like
+  wins actively break things. Read the live state before writing anything.
+- **Prefer reversible, low-blast-radius changes.** Settings and rules are easy to
+  revert; DNS proxying and SSL mode are not. Where a change is an architecture
+  decision, surface it for the user instead of making it.
+
+## Before you start
+
+**Token scope.** The audit needs read access across accounts and zones, plus write
+access for whatever it changes. If calls fail with `403 Authentication error`,
+the token is missing a permission group — see the `cloudflare-api-token` and
+`cloudflare-token-scopes` skills for how to enumerate and extend groups. A JSON
+`403` is a scope gap; an HTML `403` from a dashboard session is a WAF challenge,
+not a permission problem.
+
+**Confirm the blast radius.** The user may want one zone, one account, or
+everything. Ask if it is not clear, and say what you are about to change before
+changing it. Reversible settings changes are usually fine to batch; anything in
+[Safety rules](#safety-rules-do-not-blanket-change) needs explicit sign-off.
+
+## Ground rules
+
+1. **Discover, never assume.** Enumerate accounts from `GET /accounts` and zones
+   from `GET /zones`. Never hard-code an account ID, zone ID, or domain — the
+   same skill has to run against estates the user has not described yet.
+
+2. **Read the live response, not just the config.** A setting being `on` does not
+   mean the header is present: an unproxied record never executes zone rules, and
+   an origin can override what you set. Probe the real URL before and after.
+
+3. **Never trust an HTTP 200.** Several Cloudflare endpoints return `200` and
+   change nothing. See [Silent no-ops](#silent-no-ops-http-200-with-no-effect).
+   After every write, re-read the resource and compare.
+
+4. **Distinguish entitlement from permission.** When a call fails, replay it with
+   the user's dashboard session (or check the dashboard UI). If that also fails,
+   it is a plan gate, not a token-scope problem — do not add permission groups
+   chasing it.
+
+5. **Allow time to propagate.** Rule and setting changes can read back stale for
+   a couple of minutes. Re-probe with a cache-busting query before concluding a
+   write failed.
+
+## Workflow
+
+### 1. Inventory (read-only)
+
+Run the bundled audit script. It walks every account and zone and prints a gap
+report without changing anything:
+
+```bash
+CLOUDFLARE_API_TOKEN=... node scripts/audit.mjs          # human summary
+CLOUDFLARE_API_TOKEN=... node scripts/audit.mjs --json   # machine-readable
+```
+
+The script reports gaps; it deliberately does not fix them, because several
+fixes need judgement from the live probe. Work from its output, and see
+`references/api-reference.md` for the underlying calls if you need to go beyond
+it.
+
+### 2. Per zone: settings and rules
+
+For each zone, read `GET /zones/:id/settings` and reconcile against this
+baseline. Only change what differs, and note that the estate's current values may
+be deliberate.
+
+| Setting | Baseline | Notes |
+| --- | --- | --- |
+| `min_tls_version` | `1.2` | `1.3` only if no legacy clients. `1.0`/`1.1` are deprecated and dropped by browsers |
+| `always_use_https` | `on` | Redirects http to https |
+| `automatic_https_rewrites` | `on` | |
+| `tls_1_3` | `zrt` | `zrt` adds zero-round-trip resumption |
+| `0rtt` | `on` | Skips a round trip on repeat visits. 0-RTT is replayable, so avoid it if the zone fronts non-idempotent writes on the same connection |
+| `early_hints` | `on` | HTTP 103 preloads critical assets |
+| `http2`, `http3`, `brotli`, `websockets`, `ipv6`, `opportunistic_encryption` | `on` | Usually already on |
+| `security_level` | `medium` | Raise only during an active attack |
+| `development_mode` | `off` | Never leave on; it disables caching and most optimizations |
+
+Then check the ruleset phases and add what is missing:
+
+- **`http_request_firewall_managed`** — deploy the **free managed ruleset**. This
+  is usually the single highest-value change, because the ruleset object already
+  exists on every zone but ships *unapplied*: there is no entrypoint until an
+  `execute` rule references it. A zone with no entrypoint has zero managed WAF
+  coverage. Payload in `references/api-reference.md`.
+- **`http_response_headers_transform`** — add the baseline security headers the
+  live response is actually missing.
+- **`http_response_compression`** — extend compression to binary model and font
+  types the built-in set omits.
+- **`http_request_cache_settings`** — only with a measured reason; see
+  [Safety rules](#safety-rules-do-not-blanket-change).
+
+### 3. Per zone: DNSSEC
+
+Read `GET /zones/:id/dnssec`. If `disabled`, it is safe to stage: enabling is
+**inert** until the registrar publishes the matching DS record, and an absent DS
+cannot break validation. Confirm the parent has no DS first (`dig +short DS
+<zone>`), then enable and hand the user the DS record.
+
+Publishing the DS **cannot be automated**. Verify this rather than promising it:
+Cloudflare's OpenAPI spec contains no registrar-side DS write, and
+`PUT /accounts/:id/registrar/domains/:domain` accepts only `auto_renew`,
+`locked`, and `privacy` — it returns `200` and ignores `ds_records`. Report which
+domains are at which registrar, with the DS record for each, and let the user
+finish it in the dashboard or at the registrar.
+
+### 4. Per account
+
+- **Security Center** (`GET /accounts/:id/security-center/insights`) — the
+  starting point for what the platform itself flags. Insights re-evaluate on
+  Cloudflare's schedule (roughly daily), so they will not clear immediately after
+  a fix. Some are non-actionable; see `references/paid-features.md`.
+- **Zero Trust** — check existing Access apps have a policy, and that session
+  duration is sensible. Do not create apps unprompted; report.
+- **Turnstile** — creating a widget is free. The **secret is returned only in the
+  create response** and never again, so capture it immediately and persist it
+  somewhere durable (see the Secrets Store notes in `references/api-reference.md`).
+- **Secrets Store / Registrar / storage inventory** — useful context; report
+  rather than change.
+
+### 5. Verify and report
+
+Re-probe everything you changed, from the public internet:
+
+```bash
+curl -sI https://<zone>/ | grep -iE "^(strict-transport-security|x-content-type-options|referrer-policy)"
+```
+
+Then confirm the zone still resolves and serves (`dig +short A`, HTTP status), and
+close with the report format below.
+
+## Silent no-ops: HTTP 200 with no effect
+
+The most dangerous failure mode here, because the write looks successful. Every
+item below was confirmed against the live API. Always re-read the resource after
+writing and compare values.
+
+| Operation | Behaviour |
+| --- | --- |
+| DNSSEC enable | `PATCH` with an empty body and `PUT` with an empty body both return `200` and leave the zone `disabled`. Use `PATCH {status:"active"}` (documented) or `PUT {status:"active"}`, then re-read to confirm it reached `pending` |
+| Registrar domain update | `PUT` returns `200` for any body but applies only `auto_renew`, `locked`, `privacy`. Unknown fields, including `ds_records`, are silently dropped |
+| `PATCH /zones/:id/settings/:setting` | Unknown or removed settings are ignored, and the response echoes the *unchanged* value. Compare the returned value to what you sent |
+| Bot management | `PATCH` returns `405 10405 Method not allowed for this authentication scheme`; use `PUT`. The AI-bot fields live here, not under `/settings` |
+
+Related method quirks worth knowing: some bulk endpoints take an **array** as the
+request body and reject a single object with `1001 invalid_json_body`.
+
+## Free vs paid
+
+Most Cloudflare features have a generous free tier; a handful are paid and a few
+carry a fixed monthly cost even at zero usage. Read
+`references/paid-features.md` before promising anything, and apply this rule:
+
+- **Free, or metered with no fixed cost** — adopt it.
+- **Fixed monthly cost** — do not enable it unasked. Report it as available and
+  let the user decide.
+
+Where a Security Center insight recommends something paid, say so plainly rather
+than leaving the user to chase it. Those insights cannot be "fixed" on a free
+plan.
+
+## Safety rules (do not blanket-change)
+
+These are the changes that look like hardening and are actually outages. Measure,
+then decide — and get explicit sign-off where the change is not trivially
+reversible.
+
+- **HSTS.** `includeSubDomains` breaks every subdomain that is not HTTPS-capable,
+  and browsers cache it for `max_age`. A too-long `max_age`, or `preload`, is
+  effectively irreversible. Only enable `includeSubDomains` after confirming all
+  subdomains serve HTTPS, and never set `preload` casually.
+- **`browser_cache_ttl` and cache rules.** Origins frequently send correct
+  `Cache-Control` already. Overriding it can serve stale HTML or one user's data
+  to another. Never blanket-cache HTML or API responses; scope rules to
+  content-hashed, immutable assets, and verify the origin's current header first.
+- **SSL mode.** `full` → `full (strict)` requires a valid origin certificate.
+  Changing it without checking breaks the site.
+- **Orange-cloud proxying.** Do not proxy records to clear a
+  `cname_record_not_proxied` insight. Third-party hosts frequently do not support
+  it (Shopify storefronts, some SaaS TLS flows), and proxying interacts with the
+  host's own certificate provisioning and HTTP-01 validation. Treat these as
+  intentional until the user decides.
+- **Rocket Loader, Auto Minify, and other JS-rewriting features.** They can break
+  SPAs and modern bundlers. Enable only with a tested rollback path.
+- **`security_level` → `under_attack`** is an emergency setting. Never leave it on.
+
+Also worth checking before you trust a zone-level change: **is the hostname
+actually proxied?** If the response has no `cf-ray` header, traffic reaches the
+origin directly and no zone setting, rule, or transform applies — including
+everything you just configured. Report this; it is often the reason "nothing
+changed".
+
+## Report format
+
+Close with what changed, what was already fine, what is gated, and what needs the
+user. Be concrete about evidence — a claim about a header or certificate should
+come from a probe, not from the setting you just wrote.
+
+```text
+Summary: <what was audited, what was changed>
+Changed: <per zone/account: setting or rule, old value -> new value>
+Already optimal: <checked and left alone, with the measurement that justified it>
+Gated by plan: <feature, tier required - not enabled>
+Needs you: <DNS registrar steps, secrets to store, architecture decisions>
+Verified: <probes run and their results>
+```
+
+## References
+
+- `references/api-reference.md` — verified endpoint calls and payload shapes for
+  every change above.
+- `references/paid-features.md` — free-tier limits, plan gates, and which
+  Security Center insights cannot be resolved for free.
+- `scripts/audit.mjs` — read-only estate audit; run this first.

package/skills/cloudflare-hardening/references/api-reference.md

@@ -0,0 +1,270 @@
+# API reference
+
+Verified calls for each change the hardening skill makes. All paths are relative
+to `https://api.cloudflare.com/client/v4`. Send
+`Authorization: Bearer $CLOUDFLARE_API_TOKEN` and
+`Content-Type: application/json`.
+
+Read the current value before writing, and re-read after — see the silent-no-op
+table in `SKILL.md`.
+
+## Discovery
+
+```bash
+GET /accounts?per_page=50
+GET /zones?per_page=50
+GET /zones/:zone_id/settings
+GET /zones/:zone_id/dns_records?per_page=100
+```
+
+`GET /zones` returns each zone's `account`, `plan`, and `status`, so the whole
+estate can be walked from these four calls.
+
+To learn whether a hostname is proxied, look for the `cf-ray` response header on
+a live request rather than trusting the DNS record alone.
+
+## Zone settings
+
+```bash
+PATCH /zones/:zone_id/settings/:setting_id
+{ "value": <value> }
+```
+
+| Setting | Value | Notes |
+| --- | --- | --- |
+| `min_tls_version` | `"1.2"` | |
+| `always_use_https` | `"on"` | |
+| `automatic_https_rewrites` | `"on"` | |
+| `tls_1_3` | `"zrt"` | |
+| `0rtt` | `"on"` | |
+| `early_hints` | `"on"` | |
+| `brotli` | `"on"` | |
+| `security_level` | `"medium"` | Raise only during an attack |
+
+HSTS is a nested object:
+
+```jsonc
+PATCH /zones/:zone_id/settings/security_header
+{
+  "value": {
+    "strict_transport_security": {
+      "enabled": true,
+      "max_age": 15552000,          // 180 days
+      "include_subdomains": true,   // only if every subdomain is HTTPS-capable
+      "preload": false,             // effectively irreversible; leave false
+      "nosniff": true
+    }
+  }
+}
+```
+
+Some settings are read-only on a given plan and arrive with `"editable": false`.
+Check that field before attempting a write; the PATCH will not tell you.
+
+## Bot management
+
+The AI-bot and fight-mode fields live here, not under `/settings`. Use `PUT` —
+`PATCH` answers `405 10405`.
+
+```jsonc
+// read first, then write back the merged object
+GET /zones/:zone_id/bot_management
+
+PUT /zones/:zone_id/bot_management
+{ "ai_bots_protection": "block" }   // disabled | only_on_ad_pages | block
+```
+
+## Free managed WAF ruleset
+
+The managed ruleset object **already exists** on every zone but is not applied —
+there is no entrypoint until a rule executes it. A zone with no entrypoint has no
+managed WAF coverage at all.
+
+```bash
+# 1. find the managed ruleset id for this zone
+GET /zones/:zone_id/rulesets
+# → look for phase "http_request_firewall_managed"
+
+# 2. apply it
+PUT /zones/:zone_id/rulesets/phases/http_request_firewall_managed/entrypoint
+{
+  "rules": [
+    {
+      "action": "execute",
+      "description": "Deploy Cloudflare Free Managed Ruleset",
+      "enabled": true,
+      "expression": "true",
+      "action_parameters": { "id": "<managed ruleset id>" }
+    }
+  ]
+}
+```
+
+Coverage is a fixed set of CVE signatures (Log4j, Shellshock, common WordPress
+plugin and injection families) — not a general-purpose WAF. Verified behaviour:
+
+| Probe | Result |
+| --- | --- |
+| `${jndi:…}` in a request **header** | `403` — blocked |
+| Shellshock payload in `User-Agent` | `403` — blocked |
+| `${jndi:…}` in the **URI path** | `307`/`308` — NOT blocked (those are path-normalization redirects) |
+| SQLi / XSS payloads | Not covered |
+
+Do not read a non-`403` on a URI payload as a broken deployment.
+
+Read the ruleset with `GET /zones/:zone_id/rulesets/:ruleset_id` to inspect the
+signature list on the user's plan.
+
+## Response header transform rules
+
+Preserve any rules already in the phase — read the entrypoint first, then PUT the
+merged list. Strip server-assigned fields (`id`, `version`, `last_updated`,
+`ref`) from rules you read back.
+
+```jsonc
+PUT /zones/:zone_id/rulesets/phases/http_response_headers_transform/entrypoint
+{
+  "rules": [
+    {
+      "action": "rewrite",
+      "description": "Baseline security headers",
+      "enabled": true,
+      "expression": "true",
+      "action_parameters": {
+        "headers": {
+          "x-content-type-options": { "operation": "set", "value": "nosniff" },
+          "referrer-policy": { "operation": "set", "value": "strict-origin-when-cross-origin" },
+          "x-frame-options": { "operation": "set", "value": "SAMEORIGIN" },
+          "permissions-policy": { "operation": "set", "value": "camera=(), microphone=(), geolocation=()" }
+        }
+      }
+    }
+  ]
+}
+```
+
+Only add headers the live response is missing — an origin that already sets one
+should keep its own value. Use `operation: "add"` for genuinely multi-value
+headers so origin values are preserved.
+
+Expression operators are plan-gated: `matches` (regex) needs Business or WAF
+Advanced, while `in`, `eq`, `starts_with`, `extension`, `len`, and `substring`
+work on Free. Match on file extension rather than hash-shaped paths.
+
+A missing entrypoint answers `404` with error code `10003
+could not find entrypoint ruleset in the <phase> phase` — which confirms the
+permission is present, so treat it as "nothing configured yet", not a failure.
+
+## Compression rules
+
+Cloudflare's built-in compression covers js/css/json/svg/wasm but omits several
+binary types that compress well:
+
+```jsonc
+PUT /zones/:zone_id/rulesets/phases/http_response_compression/entrypoint
+{
+  "rules": [
+    {
+      "action": "compress_response",
+      "description": "Compress model and font assets",
+      "enabled": true,
+      "expression": "(http.request.uri.path.extension in {\"glb\" \"gltf\" \"bin\" \"woff\" \"woff2\" \"ttf\"})",
+      "action_parameters": {
+        "algorithms": [{ "name": "brotli" }, { "name": "gzip" }]
+      }
+    }
+  ]
+}
+```
+
+Confirm the payload actually shrinks by requesting the asset with and without
+`Accept-Encoding: br` and comparing `content-encoding` / `content-length`.
+
+## DNSSEC
+
+```bash
+GET /zones/:zone_id/dnssec     # status: disabled | pending | active
+PATCH /zones/:zone_id/dnssec   # documented path
+{ "status": "active" }
+```
+
+`PUT` with an explicit `{"status":"active"}` body also works. Empty-body `PATCH`
+and empty-body `PUT` both return `200` without enabling anything — re-read to
+confirm the zone reached `pending`.
+
+Enabling is safe and inert: resolution is unaffected until the registrar
+publishes the DS. Check the parent first:
+
+```bash
+dig +short DS <zone>      # empty means no DS is published
+```
+
+The response carries the record to hand the user:
+
+```
+<zone>. 3600 IN DS <key_tag> <algorithm> <digest_type> <digest>
+```
+
+**There is no API to publish the DS.** Confirmed by searching Cloudflare's
+published OpenAPI spec for `dnssec`/`ds_record` in every registrar section (no
+matches) and by writing to the registrar endpoint, which returns `200` and
+ignores the field. The user finishes this in the dashboard or at their registrar.
+
+## Turnstile
+
+```bash
+GET  /accounts/:account_id/challenges/widgets
+POST /accounts/:account_id/challenges/widgets
+{ "name": "<name>", "domains": ["<zone>"], "mode": "managed" }
+# → result.sitekey and result.secret — the secret is shown ONCE
+```
+
+The secret is never returned again. Store it immediately, ideally in the
+account's Secrets Store:
+
+```bash
+GET /accounts/:account_id/secrets_store/stores
+# reuse an existing store if one exists — the Free plan allows only one
+
+POST /accounts/:account_id/secrets_store/stores/:store_id/secrets
+# body is an ARRAY; a bare object fails with 1001 invalid_json_body
+[
+  { "name": "TURNSTILE_SITEKEY", "value": "<sitekey>", "scopes": ["workers"] },
+  { "name": "TURNSTILE_SECRET",  "value": "<secret>",  "scopes": ["workers"] }
+]
+```
+
+Stored values are write-only on read-back, so capture them from the create
+response. `GET /accounts/:account_id/secrets_store/quota` shows usage.
+
+## Registrar
+
+Read-only in practice:
+
+```bash
+GET /accounts/:account_id/registrar/domains?per_page=100
+GET /accounts/:account_id/registrar/domains/:domain
+```
+
+The `ds_records` array shows what is published at the registry (`[]` when
+nothing is). `PUT` accepts only `auto_renew`, `locked`, and `privacy`.
+
+## Verification probes
+
+```bash
+# security headers, cache directives, proxy status
+curl -sI https://<zone>/ | grep -iE "^(strict-transport-security|referrer-policy|x-content-type-options|cf-ray|cache-control)"
+
+# compression
+curl -sI -H "Accept-Encoding: br" https://<zone>/<asset> | grep -iE "^(content-encoding|content-length)"
+
+# WAF (expect 403 once the managed ruleset is applied)
+curl -s -o /dev/null -w '%{http_code}\n' -H 'User-Agent: () { :;}; /bin/bash -c "echo pwned"' https://<zone>/
+
+# resolution and DNSSEC health
+dig +short A <zone> @1.1.1.1
+dig <zone> @8.8.8.8 | grep -oE "status: [A-Z]+"   # NOERROR = healthy; SERVFAIL = broken
+```
+
+Responses can be cached briefly after a change — re-probe with a cache-busting
+query string before concluding a write failed.

package/skills/cloudflare-hardening/references/paid-features.md

@@ -0,0 +1,91 @@
+# Plan gates and paid features
+
+Cloudflare's free tiers are generous and most hardening items cost nothing. This
+file records which features are gated, so the audit does not chase a plan limit
+with permission changes.
+
+**Numbers change.** Fetch current limits from
+`https://developers.cloudflare.com/` before quoting a quota or a price. The
+plan *gates* below are the durable part; the figures are not.
+
+## Gated on the Free plan
+
+Confirmed by replaying each call with a full dashboard session — if the session
+also fails, it is entitlement rather than token scope. These return an
+entitlement or quota message, so **adding permission groups will not help**.
+
+| Feature | Signal | Notes |
+| --- | --- | --- |
+| Argo Smart Routing | `401 1015` | Paid zone setting, fixed monthly cost |
+| Polish / Mirage / WebP | `editable: false` on the setting | Paid image optimizations |
+| Image Transformations / Images | `allowed: 0` on `/accounts/:id/images/v1/stats` | Needs a paid Images plan |
+| Snippets | `403 snippets are not allowed` | Free-plan-disabled; rules out serving small responses like `security.txt` |
+| Containers | `401` | Requires the Workers Paid plan |
+| Workers for Platforms (dispatch) | `403 10121` | Paid/Enterprise |
+| Spectrum | `403 10007` | Paid |
+| Stream | `403` | Paid |
+| Load Balancing, Health Checks, Waiting Rooms | Paid | Read access still works for inventory |
+| Custom hostnames (SSL for SaaS) | `403 1404` | No quota allocated; Enterprise |
+| Logpush jobs (account) | `401` without `Logs Write` | This one is a **scope** gap, not a plan gate — grant `Logs Write` and it works |
+
+Two zone settings are not merely gated but **deprecated**:
+
+- `waf` → `400 WAF is deprecated for this zone, Managed Rulesets should be used
+  instead.` Use the managed ruleset entrypoint instead.
+- `minify` → accepts the PATCH and returns `200` with the value unchanged. Treat
+  auto-minify as unavailable and minify at build time.
+
+## Free-tier features worth adopting
+
+Everything here is free or metered with no fixed monthly cost, which makes it
+safe to enable without a spending decision:
+
+- TLS 1.2+ minimum, Always Use HTTPS, automatic HTTPS rewrites, TLS 1.3 with 0-RTT
+- HTTP/2, HTTP/3, Brotli, Early Hints, WebSockets
+- The **managed WAF ruleset** (a fixed CVE signature set)
+- Custom WAF rules and rate limiting (metered)
+- DNSSEC, HSTS, `security.txt` via a zone rule or the app
+- Page Shield reporting, API discovery, bot fight mode, AI-bot blocking
+- Cache rules, compression rules, response-header transform rules, origin rules,
+  config rules, single redirects, page rules
+- Workers, KV, D1, R2 (with egress-free reads), Hyperdrive, Queues
+- Zero Trust Access (free up to a seat cap), Cloudflare Tunnel
+- Turnstile, Web Analytics, Workers AI, Vectorize, AI Gateway, Secrets Store
+
+## Security Center insights that cannot be resolved for free
+
+Security Center recommends things the current plan may not include. Report these
+as gated rather than leaving the user to chase them, and note that dismissing an
+insight is a legitimate way to clear it when the recommendation does not apply:
+
+| Insight | Why it cannot be actioned |
+| --- | --- |
+| `argo_smart_routing_not_enabled` | Paid feature with a fixed monthly cost |
+| `polish_not_enabled` | Paid zone setting |
+| `cname_record_not_proxied` | Usually intentional — see the proxying note below |
+| `security_txt_not_enabled` | No public API, and Snippets are Free-plan-disabled. Needs a Workers route, a zone rule, or the app itself to serve the file |
+
+Insights also re-evaluate on Cloudflare's schedule (roughly daily), so a correct
+fix will not clear the insight immediately. Do not re-apply a change because the
+insight is still listed.
+
+## Two cost shapes
+
+When judging whether to enable something, distinguish:
+
+- **Metered, no fixed cost** — free until a usage threshold, then billed per unit.
+  Safe to enable; the failure mode is a surprise bill only at high volume.
+- **Fixed monthly cost** — billed whether or not it is used (Argo, Polish,
+  Load Balancing, and similar). Do not enable these during an audit. Report them
+  as available and let the user make the call.
+
+## Not a Cloudflare setting
+
+Two common hardening items have no API and belong to the application or the
+registrar:
+
+- **`security.txt`** — serve it from the app's static assets or a Workers route.
+  There is no API for it (Security Center exposes only insights, classification,
+  severity, type, audit-log, and context endpoints).
+- **DNSSEC DS records** — published at the registrar, not by API. See
+  `api-reference.md`.

package/skills/cloudflare-hardening/scripts/audit.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+/**
+ * Read-only Cloudflare estate audit.
+ *
+ * Walks every account and zone the token can see and reports hardening gaps.
+ * Makes GET requests only — it never changes anything. Fixes need judgement
+ * from the live probe, so they stay with the agent (see ../SKILL.md).
+ *
+ * Usage:
+ *   CLOUDFLARE_API_TOKEN=... node audit.mjs [options]
+ *
+ * Options:
+ *   --json            machine-readable output
+ *   --no-probe        skip live HTTP probes (faster, config-only)
+ *   --account <id>    limit to one account
+ *   --zone <name>     limit to one zone
+ *   --help
+ *
+ * Exit codes: 0 = audit completed, 1 = no usable credential, 2 = fatal error.
+ * A finding does not fail the run — this is a report, not a gate.
+ */
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const BASE = 'https://api.cloudflare.com/client/v4'
+const args = process.argv.slice(2)
+const flag = (name) => args.includes(name)
+const option = (name) => {
+  const i = args.indexOf(name)
+  return i >= 0 ? args[i + 1] : undefined
+}
+
+if (flag('--help')) {
+  const source = readFileSync(new URL(import.meta.url), 'utf8')
+  const block = source.slice(source.indexOf('/**') + 3, source.indexOf('*/'))
+  console.log(
+    block
+      .split('\n')
+      .map((line) => line.replace(/^\s*\* ?/, ''))
+      .join('\n')
+      .trim()
+  )
+  process.exit(0)
+}
+
+const AS_JSON = flag('--json')
+const PROBE = !flag('--no-probe')
+const ONLY_ACCOUNT = option('--account')
+const ONLY_ZONE = option('--zone')
+
+/** Resolve the token the same way the extension does: env, then the native Pi file. */
+function resolveToken() {
+  if (process.env.CLOUDFLARE_API_TOKEN?.trim()) return process.env.CLOUDFLARE_API_TOKEN.trim()
+  try {
+    const contents = readFileSync(join(homedir(), '.pi', 'cloudflare-api-token'), 'utf8')
+    const match =
+      /^\s*export\s+CLOUDFLARE_API_TOKEN=(?:"([^"\r\n]*)"|'([^'\r\n]*)'|([^\s#\r\n]+))\s*$/m.exec(contents)
+    return match?.[1] || match?.[2] || match?.[3] || undefined
+  } catch {
+    return undefined
+  }
+}
+
+const token = resolveToken()
+if (!token) {
+  console.error('No credential found. Set CLOUDFLARE_API_TOKEN or create ~/.pi/cloudflare-api-token.')
+  console.error('See the cloudflare-api-token skill for how to mint one.')
+  process.exit(1)
+}
+
+const HEADERS = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
+
+/** GET a path, returning { status, result, error }. Never throws on HTTP errors. */
+async function get(path) {
+  try {
+    const response = await fetch(`${BASE}${path}`, { headers: HEADERS })
+    const contentType = response.headers.get('content-type') ?? ''
+    if (!contentType.includes('json')) return { status: response.status, error: `non-JSON response (likely a WAF challenge)` }
+    const body = await response.json().catch(() => null)
+    if (!response.ok) {
+      const err = body?.errors?.[0]
+      return { status: response.status, error: `${err?.code ?? ''} ${err?.message ?? ''}`.trim() }
+    }
+    return { status: response.status, result: body?.result }
+  } catch (error) {
+    return { status: 0, error: error.message }
+  }
+}
+
+// Settings that harden a zone, with the target value and why.
+const SETTING_BASELINE = {
+  min_tls_version: { target: '1.2', why: 'TLS 1.0/1.1 are deprecated and dropped by browsers' },
+  always_use_https: { target: 'on', why: 'redirect http to https' },
+  automatic_https_rewrites: { target: 'on', why: 'rewrite mixed-content links' },
+  tls_1_3: { target: 'zrt', why: 'TLS 1.3 with zero-round-trip resumption' },
+  '0rtt': { target: 'on', why: 'skip a round trip on repeat visits' },
+  early_hints: { target: 'on', why: 'HTTP 103 preloads critical assets' },
+  brotli: { target: 'on', why: 'compression' },
+  http2: { target: 'on', why: 'protocol' },
+  http3: { target: 'on', why: 'protocol' },
+  websockets: { target: 'on', why: 'protocol' },
+  ipv6: { target: 'on', why: 'protocol' },
+  development_mode: { target: 'off', why: 'disables caching and optimization; must never be left on' },
+}
+
+// Settings whose current value is the user's call, reported but not flagged.
+const SETTING_BASELINE_INFO = {
+  security_level: { target: 'medium', why: 'raise only during an attack' },
+  rocket_loader: { target: 'off', why: 'rewrites JS; can break SPAs' },
+}
+
+const RULESET_PHASES = [
+  'http_request_firewall_managed',
+  'http_response_headers_transform',
+  'http_response_compression',
+  'http_request_cache_settings',
+  'http_request_dynamic_redirect',
+  'http_request_origin',
+  'http_config_settings',
+  'http_request_firewall_custom',
+]
+
+// Headers we expect on a hardened content response. HSTS is handled separately
+// because enabling includeSubDomains needs care and sign-off.
+const EXPECTED_HEADERS = ['x-content-type-options', 'referrer-policy']
+
+const findings = []
+const add = (scope, severity, subject, message, action) =>
+  findings.push({ scope, severity, subject, message, action })
+
+async function probeHost(hostname) {
+  try {
+    const response = await fetch(`https://${hostname}/`, {
+      redirect: 'manual',
+      signal: AbortSignal.timeout(15000),
+    })
+    const headers = {}
+    for (const name of [...EXPECTED_HEADERS, 'strict-transport-security', 'cf-ray']) {
+      headers[name] = response.headers.get(name)
+    }
+    return { status: response.status, headers }
+  } catch (error) {
+    return { status: 0, error: error.message }
+  }
+}
+
+async function auditZone(zone) {
+  const zoneFindingsStart = findings.length
+  const settingsRes = await get(`/zones/${zone.id}/settings`)
+  const settings = {}
+  for (const item of settingsRes.result ?? []) {
+    settings[item.id] = { value: item.value, editable: item.editable }
+  }
+
+  if (settingsRes.error) {
+    add(zone.name, 'blocked', 'settings', `could not read zone settings: ${settingsRes.error}`, 'check token scope')
+  } else {
+    for (const [id, { target, why }] of Object.entries(SETTING_BASELINE)) {
+      const current = settings[id]
+      if (!current) continue
+      const normalised = typeof target === 'string' ? String(current.value) : current.value
+      if (normalised === target) continue
+      if (current.editable === false) {
+        add(zone.name, 'gated', id, `${current.value} (target ${target}) — read-only on this plan`, why)
+      } else {
+        add(zone.name, 'high', id, `${current.value} → ${target}`, why)
+      }
+    }
+    for (const [id, { target, why }] of Object.entries(SETTING_BASELINE_INFO)) {
+      const current = settings[id]
+      if (!current || String(current.value) === target) continue
+      add(zone.name, 'info', id, `currently ${current.value}`, why)
+    }
+  }
+
+  // Ruleset phases: distinguish "nothing configured" from "cannot read".
+  const phases = {}
+  for (const phase of RULESET_PHASES) {
+    const res = await get(`/zones/${zone.id}/rulesets/phases/${phase}/entrypoint`)
+    const code = res.error?.split(' ')[0]
+    phases[phase] = res.status === 200 ? ((res.result?.rules?.length ?? 0) > 0 ? 'configured' : 'empty') : code === '10003' ? 'none' : `err:${res.error}`
+  }
+
+  if (phases.http_request_firewall_managed === 'none' || phases.http_request_firewall_managed === 'empty') {
+    add(
+      zone.name,
+      'high',
+      'managed WAF ruleset',
+      'free managed ruleset not applied — zone has no managed WAF coverage',
+      'PUT the http_request_firewall_managed entrypoint with an execute rule'
+    )
+  }
+  for (const phase of ['http_response_headers_transform', 'http_response_compression']) {
+    if (phases[phase] === 'none') {
+      add(zone.name, 'info', phase, 'not configured', 'add rules if the live probe shows a gap')
+    }
+  }
+
+  // DNSSEC.
+  const dnssec = await get(`/zones/${zone.id}/dnssec`)
+  const dnssecStatus = dnssec.result?.status
+  if (dnssecStatus === 'disabled') {
+    add(zone.name, 'high', 'dnssec', 'disabled', 'enable (inert until the registrar publishes the DS), then hand over the DS record')
+  } else if (dnssecStatus === 'pending') {
+    add(zone.name, 'medium', 'dnssec', 'pending — registrar DS not published', `publish: ${dnssec.result?.ds ?? 'read DS from the API'}`)
+  }
+
+  // Bot management (AI bots / fight mode live here, not under /settings).
+  const bot = await get(`/zones/${zone.id}/bot_management`)
+  if (bot.result) {
+    if (bot.result.ai_bots_protection && bot.result.ai_bots_protection !== 'block') {
+      add(zone.name, 'info', 'ai_bots_protection', `currently ${bot.result.ai_bots_protection}`, 'consider "block" (PUT, not PATCH)')
+    }
+    if (bot.result.fight_mode === false) {
+      add(zone.name, 'info', 'bot fight mode', 'disabled', 'consider enabling')
+    }
+  }
+
+  // DNS insight into proxying — the usual reason zone rules appear to do nothing.
+  const records = await get(`/zones/${zone.id}/dns_records?per_page=100`)
+  let proxied = 0
+  let unproxied = 0
+  if (Array.isArray(records.result)) {
+    for (const record of records.result) {
+      if (['TXT', 'MX', 'NS', 'SRV', 'CAA'].includes(record.type)) continue
+      if (record.proxied) proxied += 1
+      else unproxied += 1
+    }
+  }
+
+  const zoneResult = { zone: zone.name, account: zone.account?.name, plan: zone.plan?.name, settings, phases, dnssec: dnssecStatus, proxied, unproxied }
+
+  if (PROBE) {
+    const live = await probeHost(zone.name)
+    zoneResult.live = live
+    if (live.status === 0) {
+      add(zone.name, 'info', 'live probe', `could not reach the zone: ${live.error}`, 'verify the hostname serves traffic')
+    } else if (!live.headers['cf-ray']) {
+      add(
+        zone.name,
+        'high',
+        'not proxied',
+        'apex response has no cf-ray — traffic bypasses Cloudflare, so NO zone setting, rule, or transform applies',
+        'report to the user as an architecture decision; do not proxy third-party hosts to clear it'
+      )
+    } else if (live.status !== 200) {
+      // A redirect or error page has no content body to protect, so missing
+      // response headers here are not a real gap. Only note it.
+      add(zone.name, 'info', 'no content served', `HTTP ${live.status} at the apex — header checks skipped`, 'check a content hostname')
+    } else {
+      for (const header of EXPECTED_HEADERS) {
+        if (!live.headers[header]) {
+          add(zone.name, 'medium', header, 'absent on the live response', 'add via a response-header transform rule if the origin does not set it')
+        }
+      }
+      if (!live.headers['strict-transport-security']) {
+        add(zone.name, 'info', 'hsts', 'not served', 'enabling includeSubDomains requires every subdomain to be HTTPS-capable; get sign-off')
+      }
+    }
+  }
+
+  zoneResult.findings = findings.slice(zoneFindingsStart)
+  return zoneResult
+}
+
+async function auditAccount(account) {
+  const accountStart = findings.length
+  const summary = { account: account.name, id: account.id, plan: account.plan?.name }
+
+  const quotas = await get(`/accounts/${account.id}/secrets_store/quota`)
+  if (quotas.error) {
+    add(account.name, 'blocked', 'secrets store', quotas.error, 'grant Secrets Store read to inventory')
+  } else {
+    summary.secretsStore = quotas.result
+  }
+
+  const widgets = await get(`/accounts/${account.id}/challenges/widgets`)
+  if (widgets.error) {
+    add(account.name, 'blocked', 'turnstile', widgets.error, 'grant Turnstile read to inventory')
+  } else {
+    summary.turnstileWidgets = (widgets.result ?? []).map((w) => w.name)
+    if ((widgets.result ?? []).length === 0) {
+      add(account.name, 'info', 'turnstile', 'no widgets', 'free to create; the secret is returned once')
+    }
+  }
+
+  const apps = await get(`/accounts/${account.id}/access/apps`)
+  if (apps.error) {
+    add(account.name, 'blocked', 'zero trust', apps.error, 'grant Access read to inventory')
+  } else {
+    summary.accessApps = (apps.result ?? []).length
+  }
+
+  const insights = await get(`/accounts/${account.id}/security-center/insights?per_page=100`)
+  if (insights.error) {
+    add(account.name, 'blocked', 'security center', insights.error, 'grant Security Center Insights read')
+  } else {
+    const issues = insights.result?.issues ?? []
+    summary.insights = issues.map((i) => ({ class: i.issue_class, severity: i.severity, subject: i.subject }))
+    for (const issue of issues) {
+      add(account.name, 'info', issue.issue_class, `${issue.severity} — ${issue.subject}`, 'see references/paid-features.md for gated items')
+    }
+  }
+
+  const domains = await get(`/accounts/${account.id}/registrar/domains?per_page=100`)
+  summary.registrarDomains = domains.error
+    ? { error: domains.error }
+    : (domains.result ?? []).map((d) => ({ name: d.name, dsPublished: (d.ds_records ?? []).length > 0 }))
+
+  summary.findings = findings.slice(accountStart)
+  return summary
+}
+
+// --- main ---
+
+const accountsRes = await get('/accounts?per_page=50')
+if (accountsRes.error) {
+  console.error(`Could not list accounts: ${accountsRes.error}`)
+  console.error('The token needs account read access. See the cloudflare-api-token skill.')
+  process.exit(2)
+}
+let accounts = accountsRes.result ?? []
+if (ONLY_ACCOUNT) accounts = accounts.filter((a) => a.id === ONLY_ACCOUNT || a.name === ONLY_ACCOUNT)
+
+const zonesRes = await get('/zones?per_page=50')
+if (zonesRes.error) {
+  console.error(`Could not list zones: ${zonesRes.error}`)
+  process.exit(2)
+}
+let zones = zonesRes.result ?? []
+if (ONLY_ZONE) zones = zones.filter((z) => z.name === ONLY_ZONE)
+if (ONLY_ACCOUNT) {
+  const ids = new Set(accounts.map((a) => a.id))
+  zones = zones.filter((z) => ids.has(z.account?.id))
+}
+
+const auditedZones = []
+for (const zone of zones) auditedZones.push(await auditZone(zone))
+
+const auditedAccounts = []
+for (const account of accounts) auditedAccounts.push(await auditAccount(account))
+
+const report = {
+  generatedAt: new Date().toISOString(),
+  accounts: auditedAccounts,
+  zones: auditedZones,
+  findings,
+}
+
+if (AS_JSON) {
+  console.log(JSON.stringify(report, null, 2))
+} else {
+  const order = { high: 0, medium: 1, gated: 2, blocked: 3, info: 4 }
+  const sorted = [...findings].sort((a, b) => (order[a.severity] ?? 9) - (order[b.severity] ?? 9))
+
+  console.log(`Cloudflare estate audit — ${accounts.length} account(s), ${zones.length} zone(s)`)
+  console.log(`Plans: ${[...new Set(zones.map((z) => z.plan?.name))].join(', ') || 'unknown'}\n`)
+
+  const groups = { high: [], medium: [], gated: [], blocked: [], info: [] }
+  for (const finding of sorted) (groups[finding.severity] ?? groups.info).push(finding)
+
+  /**
+   * Collapse findings that repeat across many zones into one line, so a report
+   * about a large estate stays readable. A distinct message still gets its own
+   * line — only exact (subject, message) repeats are aggregated.
+   */
+  const emit = (label, list) => {
+    if (list.length === 0) return
+    const collapsed = new Map()
+    for (const finding of list) {
+      const key = `${finding.subject}\u0000${finding.message}\u0000${finding.action ?? ''}`
+      const entry = collapsed.get(key)
+      if (entry) {
+        entry.scopes.push(finding.scope)
+      } else {
+        collapsed.set(key, { ...finding, scopes: [finding.scope] })
+      }
+    }
+
+    console.log(`${label} (${list.length} across ${new Set(list.map((f) => f.scope)).size} subject(s))`)
+    for (const entry of collapsed.values()) {
+      if (entry.scopes.length === 1) {
+        console.log(`  ${entry.scopes[0].padEnd(24)} ${entry.subject.padEnd(32)} ${entry.message}`)
+      } else {
+        const names = entry.scopes.join(', ')
+        const shown = names.length > 90 ? `${names.slice(0, 87)}...` : names
+        console.log(`  ${`${entry.scopes.length} zones`.padEnd(24)} ${entry.subject.padEnd(32)} ${entry.message}`)
+        console.log(`  ${''.padEnd(24)} ${shown}`)
+      }
+      if (entry.action && entry.severity !== 'info') console.log(`  ${''.padEnd(24)} → ${entry.action}`)
+    }
+    console.log('')
+  }
+
+  emit('ACTION NEEDED', groups.high)
+  emit('WORTH REVIEWING', groups.medium)
+  emit('GATED BY PLAN', groups.gated)
+  emit('COULD NOT READ (token scope?)', groups.blocked)
+  emit('CONTEXT', groups.info)
+
+  const high = groups.high.length
+  console.log(high === 0 ? 'No high-severity gaps found.' : `${high} high-severity gap(s) to address.`)
+  console.log('\nThis audit changed nothing. Read ../SKILL.md before applying fixes —')
+  console.log('several endpoints return HTTP 200 without applying the change.')
+}