susatest-agent 0.3.0

Local agent for SUSATest — connects your Android or Windows device to the cloud testing platform

susatest-agent

Local agent for SUSATest — connects your Android device to the cloud testing platform.

Install

pip install susatest-agent

Usage

1. Get your API key at: https://susatest.com/app/settings
2. Connect your Android device via USB (USB debugging enabled)
3. Run:

susatest-agent connect --api-key susa_YOUR_API_KEY

Your device will appear in the SUSATest dashboard. Upload an APK and tests run directly on your phone.

Requirements

• Python 3.9+
• ADB installed (adb in PATH) — comes with Android Studio
• Android device connected via USB with USB debugging enabled

Commands

# Connect to SUSATest (default server)
susatest-agent connect --api-key susa_xxxx

# Connect specific device (if multiple)
susatest-agent connect --api-key susa_xxxx --device R5CR1234567

# Custom server URL
susatest-agent connect --api-key susa_xxxx --server https://your-server.com

# Custom ADB path
susatest-agent connect --api-key susa_xxxx --adb-path /path/to/adb

# Agent-side network capture (SPEC-114, see below)
susatest-agent prepare-device --device <serial>
susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy

How It Works

The agent runs an HTTP long-poll loop against susatest.com (no WebSocket; App Runner doesn't support WS). When you start a test on the website:

1. Server queues commands (tap, screenshot, swipe, etc.) for your agent
2. Agent polls /api/agent/poll (blocks up to 30s)
3. Agent executes commands via ADB on your local device
4. Agent POSTs results back to the server

No inbound ports needed — the connection is outbound only.

Agent-side network capture (SPEC-114)

For HTTPS traffic capture during mobile sessions (feeds the pentest layer), the agent can run a local mitmproxy that the test device is configured to proxy through. This needs one-time prep per device.

One-time prep

pip install -U mitmproxy frida-tools requests
susatest-agent prepare-device --device <serial>

prepare-device walks you through:

1. Generating the mitmproxy CA cert (auto-runs mitmdump --version).
2. Pushing the CA to /sdcard/mitmproxy-ca-cert.cer.
3. Opening the device's certificate-install screen (you tap through: name the cert → OK).
4. Detecting the device CPU arch + pushing the matching frida-server binary to /data/local/tmp/frida-server.
5. Creating /sdcard/.susatest-test-rig marker so subsequent runs know this is a prepared rig.

Per session

susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy

The --with-proxy flag runs preflight on startup; if any check fails (mitmdump missing, CA cert missing, marker file absent), the agent prints actionable fix steps and exits non-zero rather than starting in a broken state.

When a session starts on the server, the agent receives start_proxy, spawns mitmdump on a free local port (9100+), configures the device's HTTP proxy via adb reverse, optionally injects a Frida SSL pinning bypass on app spawn, and the mitmproxy addon POSTs each captured flow to the SUSA backend's ingest endpoint. Flows include the full request

• response (headers, bodies up to 10KB, status, response time).

For the operator validation runbook see docs/SPEC-114-PHASE-4-RUNBOOK.md in the SUSA repo.

Force flag (NOT recommended for daily-driver phones)

susatest-agent connect --api-key susa_xxxx --device <serial> --with-proxy --force

--force skips the test-rig marker check. Use only on devices you've manually prepared. Do not use on a phone you use for normal browsing — the proxy setting would route all your HTTP traffic through a defunct proxy after the agent stops.

License

MIT