PR #74468: fix(exec): reject invalid host targets

• Repository: openclaw/openclaw
• Author: vyctorbrzezowski
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/74468

Description (problem / solution / changelog)

Summary

• Problem: per-call exec host values outside auto, sandbox, gateway, and node were normalized away, so hostname-like input could silently fall back to the default target.
• Why it matters: a malformed direct exec request should fail closed before any command launches instead of relying on fallback routing.
• What changed: validate per-call exec host values before target resolution, tighten the exec tool schema enum, add regression coverage for invalid string and non-string host values, and document the allowed host set.
• What did NOT change (scope boundary): no new config keys, no approval/elevated routing changes, and no change to default host=auto behavior.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes #74426
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: direct exec calls used the permissive target normalizer, which returned null for unknown host values and allowed target resolution to fall back to the configured/default target.
• Missing detection / guardrail: regression coverage did not assert that malformed per-call host input fails before command launch.
• Contributing context (if known): N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/exec-approvals-policy.test.ts, src/agents/bash-tools.exec-foreground-failures.test.ts
• Scenario the test should lock in: invalid string and non-string per-call host values throw before the exec command can launch.
• Why this is the smallest reliable guardrail: one policy helper test locks the closed host set, and one exec tool test verifies runtime behavior at the command boundary.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Direct exec calls with malformed host values now fail with an explicit validation error instead of falling back to the configured/default exec target. Valid auto, sandbox, gateway, and node behavior is unchanged.

Diagram (if applicable)

Before:
exec({ command, host: "spark-ff13" }) -> invalid host normalizes to null -> default target runs command

After:
exec({ command, host: "spark-ff13" }) -> validation error -> command is not launched

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes
• Data access scope changed? No
• If any Yes, explain risk + mitigation: command execution input validation is stricter; malformed per-call host values now fail closed before launch.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node.js v24.14.0, pnpm
• Model/provider: N/A
• Integration/channel (if any): exec tool
• Relevant config (redacted): N/A

Steps

1. Call the exec tool with host: "spark-ff13" and a command.
2. Call the exec tool with a non-string host value.

Expected

• The exec tool rejects the malformed host before launching the command.

Actual

• Before this change, invalid host-like values could be treated like no per-call host override and fall back to the default target.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

New regression tests cover invalid string and non-string host values, and the focused test lane passes.

Human Verification (required)

What I personally verified (not just CI), and how:

• Verified scenarios: invalid string host, non-string host, blank/undefined host, valid trimmed host, existing exec target runtime tests.
• Edge cases checked: blank host remains equivalent to no override; gateway with whitespace still normalizes correctly; non-string input fails explicitly.
• What I did not verify: full pnpm build && pnpm check && pnpm test; this PR was validated with focused tests plus check:changed for the touched surface.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: callers relying on malformed host values silently falling back will now get an error.
  • Mitigation: documented the allowed host set and preserved fallback behavior for missing/blank host values.

AI-assisted disclosure

This PR was AI-assisted. I reviewed the diff, understand the changed exec validation path, and ran the validation listed above, including local codex review --base origin/main.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/tools/exec.md (modified, +1/-0)
• src/agents/bash-tools.exec-foreground-failures.test.ts (modified, +28/-0)
• src/agents/bash-tools.exec.ts (modified, +3/-2)
• src/agents/bash-tools.schemas.ts (modified, +6/-5)
• src/infra/exec-approvals-policy.test.ts (modified, +13/-0)
• src/infra/exec-approvals.ts (modified, +26/-0)