claude-ops: fleet-state.sh's FLEET_STATE_HOOK_UTILS test override is not gated to test contexts

[kyle-sexton]

Problem

plugins/claude-ops/skills/plugins/scripts/fleet-state.sh lines ~62-69:

HOOK_UTILS="${FLEET_STATE_HOOK_UTILS:-${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT_DEFAULT}/hooks/hook-utils.sh}"
if [[ -f "$HOOK_UTILS" ]]; then
  source "$HOOK_UTILS"

FLEET_STATE_HOOK_UTILS is documented as "testing only" but is not restricted to test contexts at runtime — any process able to set this env var (a malicious project .claude/settings.json env block, a hook that exports it, an inherited shell environment) can point it at an arbitrary file and have it sourced with the script's ambient permissions. The [[ -f "$HOOK_UTILS" ]] guard only checks the path exists, not that it's the trusted default.

Observed vs expected

Observed: the override is unconditional — any caller-set env var wins over the trusted CLAUDE_PLUGIN_ROOT-derived default, in production as well as tests.
Expected: the override should only be honored in a recognized test context (e.g. gated behind an existing test-mode flag this script or its harness already uses), or the sourced path should be validated against an allowlist/expected location before sourcing.

Category

security (hardening — low severity, requires the attacker to already have process-level env-var control, at which point broader compromise paths likely already exist)

Confidence

PLAUSIBLE, per the reviewing pass — not confirmed exploitable in the current harness, flagged for awareness/hardening.

Lane / source

work lane, 2026-07-21. Surfaced by a security-review pass on PR #795 (fix/254-fleet-state-review-gaps) — explicitly called out as pre-existing (unchanged by that PR) and out of that PR's scope to fix. Filed standalone per the review-deferral exemption to the intake throttle (a citable issue number is needed for the deferral).

[kyle-sexton]

This was generated by AI during triage.

Triage: VERIFIED against main — routed status: ready (decision-defaulted). Security hardening.

Category: security (hardening). Reporter severity: low; confidence PLAUSIBLE (not confirmed exploitable — requires the attacker to already hold process-level env-var control). Priority medium (rule 5 default — not blocking, not scaling-chain; area: security noted; claude-ops sits outside the week's priority-plugin set → low within-tier ordering). Filed standalone correctly (review-deferral exemption to the intake throttle).

Verification

Confirmed on main by reading the script: the HOOK_UTILS assignment honors FLEET_STATE_HOOK_UTILS unconditionally, then sources it after only an existence check — no test-context gating, no path validation. The "testing only" documentation comment carries no runtime enforcement. This one is the code-execution vector: the resolved path is sourced, so a caller-controlled env var yields arbitrary code run with the script's ambient permissions.

Additional finding surfaced during verification (same file): the sibling test overrides — FLEET_STATE_INSTALLED_JSON, FLEET_STATE_MARKETPLACES_JSON, FLEET_STATE_USER_SETTINGS, FLEET_STATE_CATALOG_DIR — share the same ungated pattern, but are read as data (JSON paths), not sourced. Lower risk (they can redirect what data is read → wrong output, not code execution). A thorough fix should treat the whole FLEET_STATE_* test-override family consistently, with HOOK_UTILS as the priority because it executes.

Problem (behavioral)

In production, any process able to set FLEET_STATE_HOOK_UTILS (a project .claude/settings.json env block, a hook that exports it, an inherited shell env) overrides the trusted CLAUDE_PLUGIN_ROOT-derived default and gets its file sourced. The existence guard checks only that the path exists, not that it is the trusted location.

Acceptance (behavioral contract)

• In a normal (non-test) run, the fleet-state script sources hook-utils only from its trusted, plugin-root-derived location — a caller-set FLEET_STATE_HOOK_UTILS must NOT be able to redirect what gets sourced in production (fail-closed: ignore the override outside recognized test context).
• The same gating covers the sibling FLEET_STATE_* data-path overrides so the test-override family is consistent, not a per-var patchwork.
• The existing test harness that relies on these overrides continues to work under whatever recognized test-context signal the fix adopts.
• No behavior change to the legitimate Claude-Code-set env vars the script documents as non-test (those stay honored).

Decision defaulted: gate the whole FLEET_STATE_* test-override family behind an explicit recognized test-context opt-in; production ignores them — veto before merge

Two fail-closed forks: (recommended) honor the FLEET_STATE_* test overrides only when a recognized test-context signal is set (an explicit test-mode opt-in the harness sets), so production always uses the trusted defaults — simplest, treats the family uniformly, matches the reporter's primary "expected"; (alternative, maintainer-vetoable) keep the overrides honorable anywhere but validate the resolved HOOK_UTILS path against the expected trusted location (allowlist) before sourcing. The worker should adopt whichever test-context signal the harness already uses; if none exists, introducing a minimal explicit opt-in is in-scope. Security review at PR time is expected — veto/redirect the approach before merge if the chosen gating is wrong.

Source: security-review pass on PR #795 (fix/254-fleet-state-review-gaps), flagged pre-existing and out of that PR's scope.

[kyle-sexton]