Skip to content

docs(runner): send Origin and browser User-Agent in the /telemetry WAF verify curl - #380

Merged
demtario merged 1 commit into
masterfrom
docs/o11y-waf-verify-curl-headers
Sep 29, 2026
Merged

demtario merged 1 commit into
masterfrom
docs/o11y-waf-verify-curl-headers

Conversation

@demtario

@demtario demtario commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Context

The WAF-exception verification in runner/docs/run-and-deploy.md (section 10, /telemetry/*) posts a <script> payload to /telemetry/collect with a bare curl. That route runs the browser gates in workers/o11y/src/gates/browser.ts first: the request host is read from Origin (falling back to Referer) and must be demos.handsontable.com (or localhost only when O11Y_ENV=local), otherwise the Worker answers 403 {"error":"host"}; a User-Agent matching BOT_RE (packages/runtime/src/telemetry/classify.ts, includes curl/) answers 403 {"error":"bot"}. So the documented probe could never pass: it returned a Worker 403 that reads exactly like the WAF still blocking. The curl now sends an Origin and a browser User-Agent, and one sentence explains why. Note: /telemetry/v1/logs is gated only by x-o11y-secret (no host or bot gate), and no other curl in runner/docs posts to a browser-gated route, so this is the only example changed.

Types of changes

  • New example
  • Update to an existing example
  • README / documentation change
  • Demo runner (runner/) change
  • CI / tooling change

How was this verified?

Docs-only change. Read the gate code (gates/browser.ts, gates/util.ts#requestHost/isAllowedHost, BOT_RE) and handleOtlpLogs/checkExportSecret to confirm which routes apply which gate; grepped runner/docs (run-and-deploy, observability-contract, ADRs) for other /telemetry/* curls. A teammate reported the same payload returning 204 in production with these two headers. No production calls were made from this branch.

Checklist

  • New/renamed example: added to runner/config/frameworks.json (see CONTRIBUTING.md); otherwise it won't appear on demos.handsontable.com (n/a, no example changed)
  • New example: added a row to the tables in README.md (n/a)
  • Ran pnpm build (and pnpm dev) in the affected example/server-example locally (n/a, docs only)

Related issue(s):

  1. None

Note

Low Risk
Documentation-only change to a deploy runbook curl example; no runtime or security logic is modified.

Overview
Updates the WAF exception verification for /telemetry/* in run-and-deploy.md so the example curl matches what /telemetry/collect actually enforces before the Worker parses the body.

The doc now notes that browser gates (workers/o11y/src/gates/browser.ts) return Worker 403 with {"error":"host"} or {"error":"bot"} when Origin/Referer or User-Agent fail—so a bare curl could look like the WAF still blocking. The probe adds Origin: https://demos.handsontable.com and a browser User-Agent, keeping the intended signal: 400/401 means the request reached the Worker, 403 at the edge means the WAF.

Reviewed by Cursor Bugbot for commit 0a1164b. Bugbot is set up for automated code reviews on this repo. Configure here.

…WAF verify curl

The probe posts to /telemetry/collect, whose browser gates 403 a request with no allowed Origin/Referer (host) or a bot User-Agent (bot). A bare curl therefore gets a Worker 403 that reads like the WAF still blocking.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@demtario
demtario merged commit 2122f26 into master Sep 29, 2026
8 checks passed
@demtario
demtario deleted the docs/o11y-waf-verify-curl-headers branch September 29, 2026 11:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant