Files
headroom/deploy/beacon/query.sh
d603f038de harden: the deployment script interpolates the $bucket ... in query.sh (#2873)
## Description

Adds input validation for the \`R2_BUCKET\` environment variable in
\`deploy/beacon/query.sh\`, an operator-run local shell script (not a
web
service or request handler — it is never on a network path). The script
is
invoked manually or from a cron job by someone who already holds
Cloudflare R2
credentials on their workstation.

## Type of Change

- [x] Bug fix / security hardening
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Vulnerability

| Field | Value |
|-------|-------|
| ID | V-001 |
| Severity | HIGH |
| Scanner | multi_agent_ai |
| File | \`deploy/beacon/query.sh\` |

Description: Without this guard, a shell special character in
\`R2_BUCKET\`
(e.g. from a misconfigured env file or an untrusted CI/CD variable)
would
reach the DuckDB path string \`r2://\${BUCKET}/sessions//.json\`
unvalidated.

## Threat model

\`query.sh\` is an operator/admin script — it is not a CGI handler and
is not
reachable over a network. The threat scenario is: a workstation env file
that
has \`R2_BUCKET\` set to a value containing shell-special characters
(copied from
a non-R2 source), or a CI/CD pipeline that interpolates \`R2_BUCKET\`
from an
untrusted variable. The fix is defensive hardening appropriate to that
context.

## Changes Made

- Add an `R2_BUCKET` allowlist guard before environment loading,
credential checks, and DuckDB invocation.
- Add a dependency-free executable Bash regression covering invalid and
valid bucket names.

\`deploy/beacon/query.sh\` — one-line regex guard at line 23, running
before
env-file sourcing, credential checks, and DuckDB invocation:

\`\`\`bash
[[ "\$BUCKET" =~ ^[a-zA-Z0-9_-]+\$ ]] || {
echo "Invalid R2_BUCKET value — must contain only alphanumeric, hyphen,
or underscore characters" >&2
  exit 1
}
\`\`\`

## Testing

- [x] Regression tests pass
- [x] New executable test added

### Test Output

```text
PASS: 7 adversarial R2_BUCKET values rejected
PASS: 5 representative R2_BUCKET values accepted
All 12 tests passed.
```

\`deploy/beacon/test_query_bucket_validation.sh\` — pure bash, no
external
dependencies, no DuckDB or Cloudflare credentials needed. Run:

\`\`\`bash
bash deploy/beacon/test_query_bucket_validation.sh
\`\`\`

Rejected values (exit 1 + \`"Invalid R2_BUCKET"\` in stderr):

| Value | Threat |
|---|---|
| \`../etc/passwd\` | path traversal |
| \`bucket; rm -rf /\` | shell injection |
| \`bucket\$(whoami)\` | command substitution |
| \`bucket with spaces\` | word-splitting |
| \`bucket!@#\` | special characters |
| \`bucket.name\` | dot (outside grammar) |
| \`bucket/subpath\` | slash (outside grammar) |

Accepted values (pass validation, then fail at credential check —
proving
the guard was cleared without real credentials):

| Value | Notes |
|---|---|
| \`headroom-telemetry\` | production default |
| \`headroom_backup\` | underscore variant |
| \`my-bucket-123\` | alphanumeric + hyphens |
| \`MyBucket\` | mixed case |
| \`a\` | single character |

Accepted cases use a temporary empty file for \`HEADROOM_ENV_FILE\`. The
script
clears bucket validation and then fails with \`"R2_ACCOUNT_ID not set"\`
— a
distinct error that confirms validation was passed.

## Behavior preservation

Valid bucket names (alphanumeric, hyphens, underscores) are unaffected.
The
guard rejects only values that contain characters outside that grammar.

## Real Behavior Proof

- Environment: pure Bash test on the current PR head; no DuckDB or
Cloudflare credentials required.
- Exact command / steps: ran bash
deploy/beacon/test_query_bucket_validation.sh, which invokes query.sh
with seven adversarial and five representative valid R2_BUCKET values.
- Observed result: all 12 cases passed; invalid values were rejected
before credential setup and valid values reached the expected
missing-credential check.
- Not tested: live DuckDB/R2 access with production credentials.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

---------

Co-authored-by: OrbisAI Security <mediratta01.pally@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-09-09 22:31:57 -05:00

105 lines
4.5 KiB
Bash
Executable File

#!/usr/bin/env bash
# Query the telemetry corpus in R2 with DuckDB.
#
# ./query.sh # fleet summary
# ./query.sh sessions # one row per session (deduped)
# ./query.sh "SELECT ..." # your own SQL against the corpus
#
# Setup, once:
# brew install duckdb
# Cloudflare > R2 > API > Create Account API Token (Object Read only,
# scoped to headroom-telemetry), then put the values in ~/env.txt
# (or any file named by HEADROOM_ENV_FILE):
#
# R2_ACCOUNT_ID=...
# R2_ACCESS_KEY_ID=...
# R2_SECRET_ACCESS_KEY=...
#
# R2_ACCOUNT_TOKEN is Cloudflare's REST-API token and is NOT used here — the
# S3 protocol wants the access-key pair.
set -euo pipefail
BUCKET="${R2_BUCKET:-headroom-telemetry}"
[[ "$BUCKET" =~ ^[a-zA-Z0-9_-]+$ ]] || { echo "Invalid R2_BUCKET value — must contain only alphanumeric, hyphen, or underscore characters" >&2; exit 1; }
_repo_env="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/.env"
ENV_FILE="${HEADROOM_ENV_FILE:-$HOME/env.txt}"
[ -f "$ENV_FILE" ] || ENV_FILE="$_repo_env"
[ -f "$ENV_FILE" ] || { echo "no env file (~/env.txt or $_repo_env) — see this script's header" >&2; exit 1; }
# shellcheck disable=SC1090
set -a; source "$ENV_FILE"; set +a
for v in R2_ACCOUNT_ID R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY; do
[ -n "${!v:-}" ] || { echo "$v not set in $ENV_FILE" >&2; exit 1; }
done
command -v duckdb >/dev/null || { echo "duckdb not installed: brew install duckdb" >&2; exit 1; }
# Credentials go in via a heredoc on stdin, never on the command line, so they
# stay out of `ps` and shell history.
SECRET="
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET r2corpus (
TYPE r2,
KEY_ID '${R2_ACCESS_KEY_ID}',
SECRET '${R2_SECRET_ACCESS_KEY}',
ACCOUNT_ID '${R2_ACCOUNT_ID}'
);
"
# The corpus is heartbeats: a session reports every 5 minutes with CUMULATIVE
# totals under one id. So the row with the highest seq per (install, session) is
# the whole session — never SUM across heartbeats, you would count each session
# once per report.
DEDUPE="
CREATE OR REPLACE TEMP VIEW sessions AS
SELECT * FROM read_ndjson('r2://${BUCKET}/sessions/**/*.json', union_by_name = true)
QUALIFY row_number() OVER (
PARTITION BY resource['headroom.install_id'], session.id
ORDER BY session.seq DESC
) = 1;
"
case "${1:-summary}" in
summary)
# Fleet rates come from summing raw counts. Averaging the per-session
# rates.*_pct fields would weight a 10-token session equal to a 1M one.
QUERY="
SELECT count(*) AS sessions,
count(DISTINCT resource['headroom.install_id']) AS installs,
sum(session.turns) AS turns,
sum(tokens.saved) AS tokens_saved,
sum(tokens.tool_saved) AS tool_tokens_saved,
round(sum(tokens.attempted) * 100.0
/ nullif(sum(tokens.original), 0), 2) AS eligible_pct,
round(sum(tokens.saved) * 100.0
/ nullif(sum(tokens.attempted), 0), 2) AS yield_pct,
round(sum(tokens.saved) * 100.0
/ nullif(sum(tokens.original), 0), 2) AS saved_pct,
-- saved_pct/yield_pct above are context-compression only, because
-- tool_saved never lands in original/attempted. This is the
-- dashboard headline (server.py `savings_percent`): tool-schema
-- savings on BOTH sides, since deferred schemas were attempted work
-- that succeeded whole. On a tool-heavy fleet the two differ several-
-- fold, so say which one you are quoting.
round(sum(tokens.saved + tokens.tool_saved) * 100.0
/ nullif(sum(tokens.original + tokens.tool_saved), 0), 2)
AS all_layers_pct,
sum(failures) AS failures
FROM sessions;"
;;
sessions)
QUERY="
SELECT resource['headroom.install_id'][1:8] AS install,
session.id, session.seq, session.turns, session.duration_s,
tokens.original, tokens.attempted, tokens.saved,
rates.saved_pct, rates.eligible_pct, rates.yield_pct,
providers, models, skips
FROM sessions
ORDER BY session.duration_s DESC
LIMIT 50;"
;;
*) QUERY="$1" ;;
esac
printf '%s\n%s\n%s\n' "$SECRET" "$DEDUPE" "$QUERY" | duckdb -box