Skip to content

fix(computer-server): close Android VM escape vectors in command routing - #1193

Closed
ddupont808 wants to merge 11 commits into
mainfrom
ddupont/android-adb-shell-routing
Closed

fix(computer-server): close Android VM escape vectors in command routing#1193
ddupont808 wants to merge 11 commits into
mainfrom
ddupont/android-adb-shell-routing

Conversation

@ddupont808

@ddupont808 ddupont808 commented Mar 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Critical: android.py run_command had a host-bypass via substring matching on "uv", "python", "/home/androidusr" — trivially bypassable by any authenticated caller. Removed; all commands now route through adb shell unconditionally.
  • PTY: /pty endpoint enforced adb shell only when no command param was supplied. Explicit command param bypassed this and gave a host PTY. Now adb shell is enforced unconditionally on Android.
  • Platform handlers: linux/macos/windows run_command now route through adb shell when IS_CUA_ANDROID is set as defense-in-depth.

Test plan

  • run_command on Android routes all commands through adb shell with no host execution path
  • PTY sessions on Android always launch adb shell, even when a command body param is passed

Summary by CodeRabbit

  • New Features

    • Added cua-sandbox Python SDK for controlling sandboxed VMs and containers across multiple platforms (Docker, QEMU, Hyper-V, Lume, Android emulator, Tart) with a unified async API.
    • Added support for multiple sandbox transport protocols: HTTP, WebSocket, Cloud, SSH, VNC, ADB, and QMP.
    • Added chainable image builder with OS-specific package managers and layer composition.
    • Added new sandbox examples for Android, cloud deployments, and custom images.
  • Documentation

    • Updated custom agent examples and guides with simplified registration patterns.
  • Tests

    • Added cold-start benchmarking and comprehensive integration tests.

ddupont808 and others added 11 commits March 11, 2026 15:15
Rewrote both custom agent doc pages to accurately reflect the codebase:
- Correct perform_task signature (includes tracer param)
- Show @register_agent decorator pattern
- Add --with flag for dev without rebuilding Docker image
- Complete action types and AgentResult reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ocker runtimes

- New cua-sandbox package: declarative Image API, layered disk caching, multi-runtime support
- QEMU WSL2 runtime: runs QEMU inside WSL2 with KVM hardware acceleration on Windows
- Hyper-V runtime: builds Windows images from ISO with native Hyper-V Gen2 VMs
- Shared Windows unattended install (builder/windows_unattend.py): Autounattend.xml, ISO creation
- OCI registry push/pull for QEMU disk images
- Computer-server setup script installs cua-computer-server only (no PyTorch/agent)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Cloud sandboxes are now the default path — sandbox() connects to the
CUA platform API, provisions VMs, and delegates control via HTTPTransport.
Ephemeral inference: image= creates+destroys, name= connects only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ple sandboxes

Adds AndroidEmulatorRuntime with headless toggle, ADB/VNC/SSH/QMP transports,
cloud transport timeout increase (10min), and example sandbox scripts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… VM creation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…and hardware keys

Adds sb.mobile.* methods (tap, swipe, scroll, pinch, home, back, etc.)
backed by ADB shell commands, and an ephemeral Android example.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…se VM escape vectors

- android.py: remove host-bypass heuristic in run_command that allowed
  any command containing "uv", "python", or "/home/androidusr" to execute
  on the container host instead of inside the emulator; all commands now
  route through adb shell unconditionally
- main.py: PTY endpoint now enforces adb shell on Android regardless of
  any caller-supplied command parameter, closing the bypass where an
  explicit command could get a host PTY
- linux/macos/windows run_command: route through adb shell when
  IS_CUA_ANDROID is set

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@vercel

vercel Bot commented Mar 19, 2026

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview, Comment Mar 19, 2026 5:41am

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

📦 Publishable packages changed

  • pypi/computer-server

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

@coderabbitai

coderabbitai Bot commented Mar 19, 2026

Copy link
Copy Markdown
Contributor

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b1a48051-8f97-4770-a2da-6d566c3e67a1

📥 Commits

Reviewing files that changed from the base of the PR and between d8d4a41 and 74db37b.

⛔ Files ignored due to path filters (2)
  • libs/python/cua-sandbox/uv.lock is excluded by !**/*.lock
  • libs/python/cua-sandbox/vnc_screen.png is excluded by !**/*.png
📒 Files selected for processing (79)
  • .github/workflows/ci-cold-start-benchmark.yml
  • docs/content/docs/cuabench/examples/custom-agent.mdx
  • docs/content/docs/cuabench/guide/advanced/custom-agents.mdx
  • examples/sandboxes/android_baremetal.py
  • examples/sandboxes/android_vnc_docker.py
  • examples/sandboxes/custom_qcow2_osworld.py
  • examples/sandboxes/ephemeral_android.py
  • examples/sandboxes/ephemeral_cloud.py
  • libs/python/computer-server/computer_server/handlers/android.py
  • libs/python/computer-server/computer_server/handlers/linux.py
  • libs/python/computer-server/computer_server/handlers/macos.py
  • libs/python/computer-server/computer_server/handlers/windows.py
  • libs/python/computer-server/computer_server/main.py
  • libs/python/cua-sandbox/README.md
  • libs/python/cua-sandbox/cua_sandbox/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/_auth.py
  • libs/python/cua-sandbox/cua_sandbox/_config.py
  • libs/python/cua-sandbox/cua_sandbox/agent.py
  • libs/python/cua-sandbox/cua_sandbox/builder/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/builder/__main__.py
  • libs/python/cua-sandbox/cua_sandbox/builder/build.py
  • libs/python/cua-sandbox/cua_sandbox/builder/executor.py
  • libs/python/cua-sandbox/cua_sandbox/builder/overlay.py
  • libs/python/cua-sandbox/cua_sandbox/builder/windows_unattend.py
  • libs/python/cua-sandbox/cua_sandbox/image.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/clipboard.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/keyboard.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/mobile.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/mouse.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/screen.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/shell.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/terminal.py
  • libs/python/cua-sandbox/cua_sandbox/interfaces/window.py
  • libs/python/cua-sandbox/cua_sandbox/localhost.py
  • libs/python/cua-sandbox/cua_sandbox/registry/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/registry/cache.py
  • libs/python/cua-sandbox/cua_sandbox/registry/manifest.py
  • libs/python/cua-sandbox/cua_sandbox/registry/media_types.py
  • libs/python/cua-sandbox/cua_sandbox/registry/qemu_builder.py
  • libs/python/cua-sandbox/cua_sandbox/registry/ref.py
  • libs/python/cua-sandbox/cua_sandbox/registry/resolve.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/android_emulator.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/base.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/docker.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/hyperv.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/images.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/lume.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/qemu.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/qemu_installer.py
  • libs/python/cua-sandbox/cua_sandbox/runtime/tart.py
  • libs/python/cua-sandbox/cua_sandbox/sandbox.py
  • libs/python/cua-sandbox/cua_sandbox/sync/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/transport/__init__.py
  • libs/python/cua-sandbox/cua_sandbox/transport/adb.py
  • libs/python/cua-sandbox/cua_sandbox/transport/base.py
  • libs/python/cua-sandbox/cua_sandbox/transport/cloud.py
  • libs/python/cua-sandbox/cua_sandbox/transport/http.py
  • libs/python/cua-sandbox/cua_sandbox/transport/local.py
  • libs/python/cua-sandbox/cua_sandbox/transport/osworld.py
  • libs/python/cua-sandbox/cua_sandbox/transport/qmp.py
  • libs/python/cua-sandbox/cua_sandbox/transport/ssh.py
  • libs/python/cua-sandbox/cua_sandbox/transport/vnc.py
  • libs/python/cua-sandbox/cua_sandbox/transport/vncssh.py
  • libs/python/cua-sandbox/cua_sandbox/transport/websocket.py
  • libs/python/cua-sandbox/pyproject.toml
  • libs/python/cua-sandbox/tests/__init__.py
  • libs/python/cua-sandbox/tests/conftest.py
  • libs/python/cua-sandbox/tests/test_cloud.py
  • libs/python/cua-sandbox/tests/test_config.py
  • libs/python/cua-sandbox/tests/test_image.py
  • libs/python/cua-sandbox/tests/test_integration_agent.py
  • libs/python/cua-sandbox/tests/test_integration_interfaces.py
  • libs/python/cua-sandbox/tests/test_integration_sync.py
  • libs/python/cua-sandbox/tests/test_oci.py
  • libs/python/cua-sandbox/tests/test_runtime.py
  • libs/python/cua-sandbox/tests/test_transport_http.py
  • tests/cold_start_benchmark.py

📝 Walkthrough

Walkthrough

This pull request introduces a new cua-sandbox Python library for managing ephemeral and persistent sandboxed VM/container environments with a unified async API, alongside updates to Android handling in computer-server handlers, documentation refactors for custom agents, example sandbox scripts, and a cold-start benchmark workflow and test suite.

Changes

Cohort / File(s) Summary
CI & Testing
.github/workflows/ci-cold-start-benchmark.yml, tests/cold_start_benchmark.py
New GitHub Actions workflow and benchmark script for measuring OS image provisioning cold-start times with Slack notifications.
Android Handler Updates
libs/python/computer-server/computer_server/handlers/android.py, linux.py, macos.py, windows.py, main.py
Refactored command execution to conditionally route through ADB when IS_CUA_ANDROID environment variable is set, unifying Android emulator shell command handling across platforms; updated /pty endpoint to force "adb shell" for Android contexts.
Documentation & Guides
docs/content/docs/cuabench/examples/custom-agent.mdx, docs/content/docs/cuabench/guide/advanced/custom-agents.mdx
Simplified custom agent documentation to focus on @register_agent decorator pattern, BaseAgent subclassing, and new --agent / --agent-kwarg CLI interface; removed legacy .cua/agents.yaml and Docker configuration details.
Example Sandbox Scripts
examples/sandboxes/ephemeral_cloud.py, ephemeral_android.py, android_baremetal.py, android_vnc_docker.py, custom_qcow2_osworld.py
New example scripts demonstrating sandbox provisioning workflows: cloud Linux, ephemeral Android, bare-metal Android emulator, Docker-based VNC Android, and custom OSWorld qcow2 images.
cua-sandbox Core Library — Configuration & Auth
libs/python/cua-sandbox/cua_sandbox/__init__.py, _config.py, _auth.py
Package initializer with public API exports; configuration module for API key/base URL resolution with multi-source fallback (environment, credentials file, global config); authentication module with browser-based login and whoami verification.
cua-sandbox Core Library — Image Builder
libs/python/cua-sandbox/cua_sandbox/image.py, builder/__init__.py, builder/build.py, builder/executor.py, builder/overlay.py, builder/windows_unattend.py
Immutable Image builder with OS-specific constructors and chainable layer methods (apt/brew/choco/winget/apk/uv/pip/run/env/copy/expose); orchestration to build base Windows/Linux images and user overlays via LayerExecutor; qcow2 backing-file/overlay management; Windows unattended installation ISO generation.
cua-sandbox Core Library — Registry & OCI
libs/python/cua-sandbox/cua_sandbox/registry/ref.py, media_types.py, manifest.py, cache.py, qemu_builder.py, resolve.py
OCI reference parsing, media-type constants for VM/container detection, multi-arch manifest fetching with platform selection, image format/kind/OS detection, filesystem caching, QEMU image building/pushing/pulling with chunked distribution, and manifest-driven image resolution and pulling.
cua-sandbox Core Library — Runtime Implementations
libs/python/cua-sandbox/cua_sandbox/runtime/base.py, docker.py, qemu.py, qemu_installer.py, hyperv.py, lume.py, android_emulator.py, tart.py, images.py
Abstract Runtime interface and implementations for Docker containers, bare-metal/Docker/WSL2 QEMU VMs, Hyper-V Windows VMs, Lume macOS VMs, Android Emulator, and Tart macOS; portable QEMU/wimlib installers; image tag resolution and port mapping.
cua-sandbox Core Library — Transport Layer
libs/python/cua-sandbox/cua_sandbox/transport/base.py, http.py, websocket.py, local.py, cloud.py, vnc.py, ssh.py, vncssh.py, qmp.py, adb.py, osworld.py, __init__.py
Abstract Transport base class and implementations for HTTP/SSE, WebSocket, local (via cua_auto), cloud VM API, VNC, SSH, VNC+SSH hybrid, QMP (QEMU), ADB (Android), and OSWorld Flask server communication.
cua-sandbox Core Library — Interfaces & Sandbox
libs/python/cua-sandbox/cua_sandbox/interfaces/*.py, agent.py, localhost.py, sandbox.py, sync/__init__.py
Interface classes (Screen, Mouse, Keyboard, Clipboard, Shell, Terminal, Window, Mobile) providing high-level operations on top of Transport; Sandbox orchestration selecting runtime and transport, managing lifecycle; Localhost for direct host control; SandboxHandler/LocalhostHandler adapters for agent integration; synchronous blocking wrappers via _SyncProxy.
cua-sandbox Tests & Utilities
libs/python/cua-sandbox/README.md, pyproject.toml, tests/conftest.py, test_*.py
Package documentation, build configuration, and comprehensive asyncio-based integration/unit test suite covering transports, runtimes, image building, OCI manifest detection, cloud sandbox lifecycle, config/auth flows, and interface operations.

Sequence Diagram

sequenceDiagram
    participant User
    participant Sandbox
    participant Runtime
    participant Transport
    participant Image as Image/Registry
    participant Guest as Guest (VM/Container)

    User->>Sandbox: sandbox(image=..., local=True)
    Sandbox->>Image: resolve image kind (if needed)
    Sandbox->>Sandbox: auto-select runtime<br/>(Docker/QEMU/etc.)
    
    Sandbox->>Runtime: Runtime.start(image, name)
    Runtime->>Guest: Launch VM/container<br/>(via Docker/QEMU/etc.)
    Guest-->>Runtime: RuntimeInfo<br/>(host, api_port, vnc_port)
    
    Sandbox->>Transport: Select transport type<br/>(HTTP/VNC/SSH/etc.)
    Transport->>Transport: connect()
    Transport-->>Sandbox: Connected
    
    Sandbox-->>User: Sandbox instance<br/>(with interfaces)
    
    User->>Sandbox: screenshot()/click()/type()
    Sandbox->>Transport: send(action, params)
    Transport->>Guest: HTTP POST /cmd<br/>or VNC/SSH/ADB command
    Guest-->>Transport: Response (image/result/status)
    Transport-->>Sandbox: Parsed result
    Sandbox-->>User: Return value

    User->>Sandbox: close()
    Sandbox->>Transport: disconnect()
    Sandbox->>Runtime: stop()
    Runtime->>Guest: Terminate VM/container
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

Poem

🐰 Behold, a sandbox spreads its wings,
Where VMs dance and containers sing,
From Android emulators to clouds on high,
A transport layer beneath the sky!
With transports many and runtimes grand,
The sandbox kingdom now takes its stand. 🎪

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ddupont/android-adb-shell-routing

@sentry

sentry Bot commented Mar 19, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
.../computer-server/computer_server/handlers/linux.py 0.00% 3 Missing ⚠️
...ibs/python/computer-server/computer_server/main.py 0.00% 3 Missing ⚠️

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant