mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 18:41:07 +08:00
## 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>
105 lines
4.5 KiB
Bash
Executable File
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
|