Summary

This PR hardens the API-started agent boundary so shell-capable tools are not enabled solely because a request appears to come from loopback.

• Requires explicit operator opt-in via VIBE_TRADING_ENABLE_SHELL_TOOLS before API-created SWARM workers or session AgentLoop attempts can receive bash / background shell tools.
• Adds regression coverage for DNS-rebinding-shaped requests to both /swarm/runs and /sessions/{session_id}/messages, proving shell tools are not enabled by default.
• Preserves remote/LAN API-key behavior and the existing explicit shell-tool opt-in for trusted deployments.

Security issues covered

Before this PR

• _shell_tools_enabled_for_request() returned true for any loopback client.
• /swarm/runs passed that value into runtime.start_run(..., include_shell_tools=...).
• /sessions/{session_id}/messages passed that value into svc.send_message(..., include_shell_tools=...).
• Built-in SWARM presets and the normal AgentLoop registry can expose shell-capable tools such as bash when shell tools are enabled.
• If a request reached the local API as a loopback peer, shell tools could be exposed without an explicit operator opt-in.

After this PR

• API-started agents only receive shell tools when VIBE_TRADING_ENABLE_SHELL_TOOLS is explicitly enabled.
• Loopback peer IP remains insufficient to grant host shell capability.
• Regression tests cover loopback requests with attacker-controlled Host / Origin and verify include_shell_tools=False for both SWARM and session message flows.

Explicit operator choice

Secure default:

VIBE_TRADING_ENABLE_SHELL_TOOLS unset or false

Behavior:

• API-created SWARM workers do not receive shell-capable tools, even for loopback clients.
• Session AgentLoop attempts started through the API do not receive shell-capable tools, even for loopback clients.
• Research workflows can still start; shell-capable tools are filtered out.

Explicit trusted opt-in:

VIBE_TRADING_ENABLE_SHELL_TOOLS=1

Behavior:

• Operators who intentionally trust their deployment can still expose shell tools to API-started agents.

Why this matters

Shell-capable agent tools execute commands on the host as the API process user. Browser-origin requests can reach local services through localhost and DNS-rebinding patterns, so peer IP alone is not a reliable expression of operator intent.

A safer boundary is an explicit server-side operator opt-in for shell-capable tools.

How this differs from related PRs

• [security] fix(api): reject rebound loopback hosts #242 hardens Host-header validation for the live-runner DNS-rebinding path.
• This PR hardens shell-tool exposure itself. It prevents loopback status from granting bash / background shell capability to API-started SWARM workers or session AgentLoop attempts.
• The fixes are complementary: Host validation blocks rebound admission paths, while this PR makes the dangerous shell-tool capability require explicit operator opt-in even when a request is local.

Attack flow

1. API_AUTH_KEY is configured.
2. Attacker hosts a web page at attacker.example:8899.
3. Browser resolves attacker.example to the attacker first, then rebinding points it at 127.0.0.1.
4. Browser sends same-origin JSON requests with Host/Origin attacker.example:8899 but loopback peer IP.
5. The local API treats the request as loopback.
6. The request reaches `/swarm/runs` or `/sessions/{session_id}/messages` without an Authorization header.
7. The route starts an agent workflow with `include_shell_tools=True` because the peer is loopback.
8. The agent runtime can receive shell-capable tools such as `bash`.

Affected code

Root cause

• Loopback peer IP was treated as sufficient intent to expose host shell tools.
• Browser-to-localhost and DNS-rebinding threat models can make attacker-triggered requests appear as loopback.
• Shell/process tools are a host capability and should require explicit server-side operator configuration, not request-locality inference.

CVSS assessment

• Issue: DNS-rebinding-triggered API agent shell-tool exposure
• Suggested severity: Critical
• Suggested CVSS v3.1: 9.6
• Suggested vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:H/I:H/A:H

Rationale: a remote attacker needs a victim to visit an attacker-controlled page, but no API key or Vibe-Trading credentials are required. The resulting workflow can expose host command-execution-capable tools in the local API process context.

Safe reproduction steps

Before the fix, a Docker proof using the real FastAPI app, real routes, real session/SWARM services, and a deterministic fake LLM showed:

[docker-proof:remote-control] create_status= 401
[docker-proof:remote-control] marker_exists= False
[docker-proof:dns-rebound-loopback] message_status= 200
[docker-proof:dns-rebound-loopback] marker_exists= True
[docker-proof:dns-rebound-loopback] marker_content= proof
[docker-proof] remote_blocked_but_rebound_session_rce_allowed= True

After this PR, the same session proof no longer exposes bash, so the marker is not created:

[docker-proof:remote-control] create_status= 401
[docker-proof:remote-control] marker_exists= False
[docker-proof:dns-rebound-loopback] create_status= 201
[docker-proof:dns-rebound-loopback] message_status= 200
[docker-proof:dns-rebound-loopback] fake_llm_calls= 1
[docker-proof:dns-rebound-loopback] marker_exists= False
[docker-proof] remote_blocked_but_rebound_session_rce_allowed= False

Expected vulnerable behavior

On vulnerable code, a rebound loopback request can cause an API-started agent workflow to receive shell tools without VIBE_TRADING_ENABLE_SHELL_TOOLS being set.

Changes in this PR

• Changes _shell_tools_enabled_for_request() to rely only on VIBE_TRADING_ENABLE_SHELL_TOOLS.
• Keeps explicit operator opt-in behavior intact.
• Adds/updates tests proving:
  • loopback requests do not enable shell tools by default
  • remote requests do not enable shell tools by default
  • explicit opt-in enables shell tools
  • DNS-rebinding-shaped /swarm/runs requests get include_shell_tools=False
  • DNS-rebinding-shaped /sessions/{session_id}/messages requests get include_shell_tools=False

Files changed

Maintainer impact

• Secure-by-default deployments no longer expose host shell tools through API-started agents based only on loopback locality.
• Operators who intentionally need shell tools can enable VIBE_TRADING_ENABLE_SHELL_TOOLS=1.
• Existing API auth behavior is otherwise unchanged.

Fix rationale

Host shell tools are a high-impact local capability. They should be gated by explicit server-side configuration so that browser-origin request tricks cannot turn request locality into host command execution capability.

Type of change

• Security fix
• Tests
• Documentation
• Refactor

Test plan

Local validation:

PYTHONPATH=agent python -m pytest agent/tests/test_security_auth_api.py -q
python -m py_compile agent/api_server.py agent/tests/test_security_auth_api.py
git diff --check

Result:

42 passed, 2 warnings in 0.25s

Docker validation:

docker run --rm -v "$PWD:/repo" -w /repo python:3.11-slim bash -lc '
apt-get update -qq && apt-get install -y -qq git >/dev/null &&
python -m pip install -q pytest fastapi httpx rich pydantic python-multipart sse-starlette pyyaml python-dotenv fastmcp &&
PYTHONPATH=agent python -m pytest agent/tests/test_security_auth_api.py -q &&
python -m py_compile agent/api_server.py agent/tests/test_security_auth_api.py
'

Result:

42 passed, 3 warnings in 0.22s

After-fix Docker proof for the session route:

[docker-proof:dns-rebound-loopback] marker_exists= False
[docker-proof] remote_blocked_but_rebound_session_rce_allowed= False

Disclosure notes

This PR is intentionally bounded to shell-tool exposure for API-started agent workflows. It does not claim to replace Host-header/DNS-rebinding admission hardening; it complements that boundary by requiring explicit operator opt-in before shell-capable tools are exposed to agents started through the API.