Initial commit

docs/research/local-vs-remote-agent-execution.md

@@ -0,0 +1,231 @@
+# Local vs. Remote Agent Execution: Security & Privacy Tradeoffs
+
+Research notes on when to run containerized Claude Code agents on a remote machine
+outside the local network versus inside it, focusing on security and privacy concerns.
+Relevant to a potential claude-bottle extension for remote agent execution.
+
+---
+
+## The core mental model
+
+The topology decision isn't "local = safe, remote = dangerous." The real variables are:
+**what can the agent reach if compromised**, **what's on the host if the container
+escapes**, and **whether credentials are short-lived and scoped**.
+
+---
+
+## Threat landscape by topology
+
+### Local (current claude-bottle model)
+
+- Container escape → developer laptop → `~/.ssh`, `~/.aws`, browser cookies, Keychain, everything
+- Outbound: Docker containers have full internet access by default; no egress monitoring on most home networks
+- Lateral movement: compromised container can reach the LAN — NAS, other machines, internal services
+- Notable: CVE-2025-59536 (CVSS 8.7, Feb 2026) — a poisoned `.claude/settings.json` in a repo gives RCE when Claude Code opens it. `--dangerously-skip-permissions` removes the last gate.
+- Supply chain: MCP servers, skills, and npm packages pulled during agent execution. ~20% of ClawHub skills were found malicious in early 2026.
+
+**What local topology protects:**
+- No inbound attack surface — nothing listening on a public port
+- Secrets stay physically on your hardware; no transit risk
+- Network egress bounded by the host router
+
+### Remote machine
+
+- New inbound attack surface (SSH/API port must be open; CISA notes exploitation of remote access vulns within 9–13 days of disclosure)
+- Secrets must travel from local to remote — each transit is a new exposure class
+- If the VM has a cloud IAM role attached → blast radius includes cloud APIs (S3, RDS, IAM, etc.)
+- Compromised remote host can read env vars injected into containers, intercept docker exec sessions, exfiltrate skills and prompts
+- **Worst case:** a remote VM connected back to the LAN via VPN is the worst of both worlds — internet-facing attack surface + full LAN access. This pattern should never be built.
+- Multiple agents sharing the same remote host creates cross-tenant bleed risk.
+
+**What remote topology can offer:**
+- Better isolation from the developer laptop — a compromised container doesn't reach `~/.ssh` or local credentials unless explicitly forwarded
+- Ephemeral compute — a cloud VM torn down after each session leaves no persistent attack surface
+- Cloud-native network controls (Security Groups, VPC firewall, PrivateLink) can be more granular than home router rules
+- VPC flow logs + CloudTrail give an audit trail that a home network doesn't
+
+---
+
+## Data sensitivity — when "on-prem" matters
+
+Data that should not leave the local network absent extraordinary controls:
+
+| Data type | Why |
+|---|---|
+| Private SSH keys | If copied to remote, stored outside your control; lateral movement via key reuse |
+| Secrets forwarded into containers (API tokens, OAuth tokens) | In-transit exposure; remote machine persistence risk |
+| Source code under NDA or with unreleased IP | Contractual and competitive risk |
+| PHI (HIPAA) | Requires BAA with every system that touches it; standard cloud VMs don't qualify |
+| PII of EU residents (GDPR) | Cannot legally transit US infrastructure without SCCs |
+| Internal API credentials for LAN systems | Sending to a remote agent that can reach back via VPN creates a remote-controlled pivot |
+
+Data that can go remote with proper controls:
+- Public open-source code
+- Non-sensitive project scaffolding
+- Prompts that don't contain embedded secrets
+- Derived outputs (build artifacts, test results) that don't contain source data
+
+---
+
+## Blast radius comparison
+
+### Worst case: local container compromise
+
+1. Container escape via kernel exploit → developer laptop
+2. From laptop: `~/.ssh/id_rsa`, `~/.aws/credentials`, browser session cookies, macOS Keychain, `~/.claude`
+3. Lateral movement to LAN — internal services, NAS, other dev machines
+4. Outbound: anything the home/office network allows
+
+### Worst case: remote container compromise
+
+1. Container escape → remote host
+2. From remote host: host environment credentials, any attached IAM role, secrets in the host filesystem
+3. If a VPN or SSH tunnel links remote machine to local network → full lateral movement back through that tunnel
+4. Cloud API access if the VM has IAM permissions → S3, RDS, EC2, Secrets Manager, etc.
+
+**Remote blast radius is potentially larger than local if:**
+- The remote VM has cloud IAM permissions broader than the local laptop environment
+- The remote machine is connected back to the local network via VPN (creating a pivot)
+- Multiple agents share the same remote host
+
+**Remote blast radius is smaller if:**
+- The remote VM is strictly isolated (no VPN back to LAN)
+- IAM role is locked to minimum necessary permissions
+- Remote host is ephemeral and torn down after each session
+
+Key insight: once a container is compromised via prompt injection, the blast radius is dominated by what the agent *can reach*, not by where it physically runs. Studies have measured an 82.4% inter-agent compromise rate in multi-agent systems.
+
+---
+
+## Credentials and secrets
+
+### Local topology (current claude-bottle)
+
+- Secrets live in the host environment or are prompted from `/dev/tty`
+- Forwarded to containers via `-e NAME` (not `=value`), never on argv, never in env-files for secrets
+- On container teardown, secrets are gone from that process space
+- Risk: container escape to host reaches the host env where the parent process ran
+
+### Remote topology
+
+Secrets must travel from their source to the remote machine. Mechanisms in increasing security order:
+
+1. **SSH env forwarding (`AcceptEnv`/`SendEnv`)** — secrets in plaintext in the SSH session; logged by some SSH daemon configurations
+2. **Encrypted orchestration channel** — secrets encrypted in transit, but remote machine must decrypt and expose them in memory
+3. **Vault/cloud secrets manager + dynamic credentials** — remote machine fetches its own short-lived secrets; local machine never sends secrets at all (best option)
+
+An 8,640x reduction in abuse window comes from switching from 90-day keys to 15-minute tokens. Static long-lived tokens (`CLAUDE_CODE_OAUTH_TOKEN`, `GITLAB_TOKEN`) are the biggest risk in a remote topology.
+
+**Proxy-inject pattern:** agent makes unauthenticated requests; a proxy outside the container injects credentials per-request. The container never sees the raw token. Anthropic's secure deployment docs recommend this pattern.
+
+---
+
+## Egress and exfiltration risk
+
+### Local topology
+
+- Monitoring: whatever the home/office router supports — usually minimal
+- Containment: `--network none` + a proxy socket provides the strongest containment; claude-bottle does not currently do this
+- DLP: essentially none unless specifically deployed on the LAN
+- Domain fronting risk: even allowlisted-domain proxies can be bypassed via domain fronting — an agent that can reach `api.anthropic.com` could relay data to an attacker-controlled backend through that domain
+- **claude-bottle today: containers have full outbound internet access. No egress restrictions.**
+
+### Remote topology (cloud VM)
+
+- VPC flow logs capture every connection attempt by IP/port — better than most home networks if configured
+- Security Groups can allowlist specific endpoints; a NAT gateway can be locked down
+- DLP tooling is more mature in cloud environments (AWS Macie, GCP DLP API, Cloudflare AI Gateway)
+- But only if configured. A raw cloud VM with default settings has worse egress monitoring than a corporate network.
+
+Strongest exfiltration controls for either topology:
+1. `--network none` in Docker + a unix socket proxy that enforces domain allowlists
+2. TLS inspection at the proxy to defeat domain fronting
+3. Audit log all outbound traffic at the proxy
+
+---
+
+## Compliance
+
+### HIPAA
+
+- PHI must stay within HIPAA-covered infrastructure. Standard commercial cloud VMs require a signed BAA with the provider. AWS Bedrock, Azure OpenAI, and Google Cloud can be configured with BAA coverage; a generic EC2 cannot.
+- If the agent processes any PHI, the remote machine must be in a HIPAA-qualified environment.
+- "Minimum necessary" rule: an agent with broad filesystem access to a repo containing PHI violates this unless carefully scoped.
+
+### GDPR
+
+- EU personal data cannot legally be sent to US infrastructure without Standard Contractual Clauses or adequacy decisions.
+- Local execution (if the developer is EU-based) sidesteps this. Remote execution on a US cloud VM requires SCCs.
+
+### SOC2
+
+- No specific data residency mandate, but all infrastructure that touches in-scope data must implement the trust criteria. A remote VM needs audit logs, access controls, and continuous monitoring — more operational overhead than local execution.
+
+---
+
+## Decision heuristics
+
+| Scenario | Recommendation |
+|---|---|
+| Solo developer, personal projects, no regulated data | Local is fine; add egress proxy for defense-in-depth |
+| Regulated data (HIPAA, GDPR, SOC2) | Local unless the remote environment is fully qualified |
+| Long-running automated tasks, no secrets in content | Remote VM acceptable with egress controls and ephemeral lifecycle |
+| Parallel agent fleet | Remote VM cluster with per-agent IAM roles, strict egress, centralized secret management |
+| Agent receives credentials that give network access to LAN | Keep local; never build a VPN-connected remote agent that can pivot back to the LAN |
+| Source code with embedded secrets (`.env`, API keys in config) | Local only, or sanitize before sending to remote |
+| Lack infrastructure maturity for proper remote config | Local — a poorly configured VM is strictly worse than a well-configured local container |
+
+---
+
+## Concrete recommendations if extending claude-bottle for remote
+
+1. **Never build the VPN-pivot pattern.** A remote agent connected back to the LAN via VPN is the worst of both worlds. If a remote agent needs LAN resources, expose those through a narrow API, not a VPN.
+
+2. **Add `--network none` + a proxy socket, even locally first.** The single highest-leverage change available right now. Bounds egress to allowlisted domains, prevents arbitrary exfiltration regardless of topology. Anthropic's secure deployment docs show exactly how to do this.
+
+3. **Use dynamic, short-lived credentials for the remote context.** Replace static tokens with per-task dynamically issued credentials (Vault with approle auth, or cloud workload identity federation). This eliminates the "credential concentration on remote host" problem.
+
+4. **Proxy-inject credentials; don't send them to the container.** The proxy runs on the remote host (not in the container); the credential lives only in the proxy process.
+
+5. **Scope IAM/cloud permissions to the minimum.** No `*:*` policies. No admin roles on the VM.
+
+6. **Make the remote VM ephemeral.** Spin it up for the session, tear it down when done. No persistent credentials or data between sessions.
+
+7. **Enable VPC flow logs and forward them somewhere.** Going remote buys you egress monitoring you don't have locally — but only if configured.
+
+8. **Validate hooks before execution.** `init-work` / `init-free-agent` copies a project into the container. That project may contain poisoned `.claude/settings.json` hooks (CVE-2025-59536 vector). `--dangerously-skip-permissions` removes the last gate; consider validating hooks before execution.
+
+---
+
+## Bottom line
+
+For the current claude-bottle use case (developer feature implementation, no regulated data,
+single developer), local execution is the right default. The biggest unaddressed risk
+right now isn't topology — it's that containers have unrestricted outbound internet access.
+Adding `--network none` + a proxy socket would be higher-leverage than any topology change.
+
+Remote execution becomes worth the complexity for parallelism at scale, long-running
+unattended tasks, or strict separation of agent compute from developer hardware — but
+only with egress controls, ephemeral lifecycle, and dynamic credential management in place.
+
+---
+
+## Sources
+
+- Penligent AI — AI Agents Hacking in 2026: Defending the New Execution Boundary
+- Repello AI — The Agentic AI security threat landscape in 2026
+- arxiv 2601.17548 — Prompt Injection Attacks on Agentic Coding Assistants
+- Unit42 (Palo Alto) — Navigating Security Tradeoffs of AI Agents
+- Trend Micro — Unveiling AI Agent Vulnerabilities Part III: Data Exfiltration
+- Help Net Security — 29 million leaked secrets in 2025: AI agents credentials are out of control
+- GitGuardian — Short-Lived Credentials in Agentic Systems: A Practical Trade-off Guide
+- Aembit — Securing AI Agents Without Static Credentials
+- Anthropic Docs — Securely Deploying AI Agents
+- Anthropic Engineering — Claude Code Sandboxing
+- TrueFoundry — Claude Code Sandboxing: Network Isolation, File System Controls
+- TrueFoundry — LLM Deployment in Regulated Industries: HIPAA, SOC2 & GDPR Playbook
+- MindStudio — AI Agent Compliance: GDPR SOC 2 and Beyond
+- OX Security — The Mother of All AI Supply Chains: Critical MCP Vulnerability
+- The Hacker News — Anthropic MCP Design Vulnerability Enables RCE
+- Straiker — Agent Hijacking: How Prompt Injection Leads to Full AI System Compromise
+- Seraphic Security — Secure Remote Access Best Practices 2025