adbproxy 0.1.0__py3-none-any.whl

adbproxy-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: adbproxy
+Version: 0.1.0
+Summary: ADB smart-socket and device transport proxies
+Author: Forgo7ten
+License: MIT
+Project-URL: Homepage, https://github.com/Forgo7ten/adbproxy
+Project-URL: Repository, https://github.com/Forgo7ten/adbproxy
+Project-URL: Issues, https://github.com/Forgo7ten/adbproxy/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zstandard>=0.25.0
+Provides-Extra: lz4
+Requires-Dist: lz4>=4.3.0; extra == "lz4"
+Provides-Extra: brotli
+Requires-Dist: brotli>=1.1.0; extra == "brotli"
+Provides-Extra: decompress
+Requires-Dist: adbproxy[brotli,lz4]; extra == "decompress"
+Dynamic: license-file
+
+# adbproxy
+
+在 ADB client 与 server / 设备之间插入透明代理，解析并记录 ADB 协议流量，同时保持原始字节原样转发。
+
+适用于调试 adb 命令、观察 shell / sync / install 等协议交互、抓取 push/pull 文件内容。
+
+## 功能
+
+- **server-proxy**：MITM 本机 `adb client ↔ adb server` 的 smart-socket 链路（默认监听 `5037`，真实 server 挪到 `5038`）
+- **device-proxy**：模拟网络 adbd，接受 transport 协议连接，再经系统 adb server 转发到真实设备
+- 解析并记录 shell、sync、install、stream 等协议事件
+- 可选落盘 sync / install 文件内容，以及 `--debug` 原始 hex
+- 观察 / 解码 / 抓包失败时 fail-open，不中断透明转发
+
+## 架构
+
+```mermaid
+flowchart LR
+  Client[adb client]
+  SP[server-proxy :5037]
+  Server[adb server :5038]
+  Dev[真实设备]
+
+  Client -->|smart socket| SP
+  SP -->|smart socket| Server
+  Server --> Dev
+
+  Client2[adb client]
+  ServerFront[adb server :5037]
+  DP[device-proxy :5566]
+  ServerBack[adb server :5037]
+  Dev2[真实设备]
+
+  Client2 -->|smart socket| ServerFront
+  ServerFront -->|transport| DP
+  DP -->|smart socket| ServerBack
+  ServerBack --> Dev2
+```
+
+## 环境要求
+
+- Python ≥ 3.10
+- [uv](https://docs.astral.sh/uv/)
+- 系统 `adb`（Android platform-tools）
+
+## 安装
+
+```bash
+git clone <repo-url>
+cd adbproxy   # 或你的本地目录名
+uv sync
+```
+
+也可从 PyPI：
+
+```bash
+pip install adbproxy
+# 可选：sync 解压依赖
+pip install "adbproxy[decompress]"
+
+# 临时运行
+uvx adbproxy server --help
+uvx adbproxy device --help
+```
+
+`uv sync` 会安装依赖，并根据 `pyproject.toml` 的 `[project.scripts]` 注册命令行入口：
+
+| 命令 | 对应模块 | 作用 |
+|------|----------|------|
+| `adbproxy` | `adbproxy.cli.main:main` | **推荐**统一入口：`server` / `device` 子命令 |
+| `adb-server-proxy` | `adbproxy.cli.server:main` | 兼容旧入口（等同 `adbproxy server`） |
+| `adb-device-proxy` | `adbproxy.cli.device:main` | 兼容旧入口（等同 `adbproxy device`） |
+
+推荐启动方式：
+
+```bash
+# 统一入口（推荐）
+uv run adbproxy server --help
+uv run adbproxy device --help
+uv run python -m adbproxy server --help
+uv run python -m adbproxy device --help
+
+# 兼容旧 console script / 模块路径
+uv run adb-server-proxy --help
+uv run adb-device-proxy --help
+uv run python -m adbproxy.cli.server --help
+uv run python -m adbproxy.cli.device --help
+```
+
+下文示例统一使用 `adbproxy server` / `adbproxy device`。
+
+## 使用
+
+### 1. server-proxy（MITM 本机 5037）
+
+启动前确认本机 `5038` 未被占用。代理会接管默认 `5037`，把真实 adb server 挪到 `5038`；退出时按所有权恢复。
+
+```bash
+uv run adbproxy server
+# 等价：
+#   uv run python -m adbproxy server
+#   uv run adb-server-proxy
+
+# 可选参数：
+#   --debug        将每段 recv 的原始 hex 落盘
+#   --no-capture   不落盘 sync/install 文件，仅打印摘要
+```
+
+另开终端正常使用 adb（默认走 5037，即经过代理）：
+
+```bash
+adb devices -l
+adb shell echo hello
+adb push local.apk /data/local/tmp/
+adb install local.apk
+```
+
+### 2. device-proxy（模拟网络 adbd）
+
+默认监听 `5566`，后端复用系统 `5037` adb server，把请求转发到指定真实设备。
+
+```bash
+uv run adbproxy device \
+  --listen 5566 \
+  --target serial:<设备序列号>
+
+# 等价：
+# uv run python -m adbproxy device \
+#   --listen 5566 \
+#   --target serial:<设备序列号>
+# uv run adb-device-proxy \
+#   --listen 5566 \
+#   --target serial:<设备序列号>
+```
+
+`--target` 支持：
+
+| 值 | 含义 |
+|----|------|
+| `usb` | 自动选择首个 USB 且状态为 `device` 的设备（默认） |
+| `serial:<s>` | 指定序列号 |
+| `net:<ip>:<port>` | 先 `adb connect` 到该网络设备 |
+
+常用参数：
+
+```text
+--listen PORT           监听端口，默认 5566
+--adb-server-port PORT  后端 adb server 端口，默认 5037
+--debug                 原始 hex 落盘
+--no-capture            禁用 sync/install 文件落盘
+--banner-type TYPE      CNXN banner 前缀，默认 device
+```
+
+另开终端连接并操作：
+
+```bash
+adb connect 127.0.0.1:5566
+adb -s 127.0.0.1:5566 get-state
+adb -s 127.0.0.1:5566 shell echo hello
+adb -s 127.0.0.1:5566 push local.apk /data/local/tmp/
+adb disconnect 127.0.0.1:5566
+```
+
+## 输出目录
+
+运行时在项目根目录生成（可用 `ADB_PROXY_OUT_DIR` 覆盖）：
+
+| 路径 | 内容 |
+|------|------|
+| `out/logs/` | 事件日志；加 `--debug` 时另有 debug hex 日志 |
+| `out/files/` | sync push/pull、install 流捕获（未加 `--no-capture` 时） |
+
+```bash
+export ADB_PROXY_OUT_DIR=/tmp/adbproxy-out
+# 写入 /tmp/adbproxy-out/logs 与 /tmp/adbproxy-out/files
+```
+
+## 测试
+
+### 准备
+
+真机动态矩阵（push / pull / install）依赖测试 APK。仓库不附带该文件，运行前请自行放置：
+
+```bash
+# 任意可安装的 APK 即可
+cp /path/to/your.apk tests/app.apk
+```
+
+`tests/app.apk` 已在 `tests/.gitignore` 中忽略，不会被提交。
+
+无设备的单元 / 静态测试不需要该文件。
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `ADB_PROXY_REAL_DEVICE=1` | 启用真机动态用例；未设置时相关用例自动 skip |
+| `ADB_SERIAL` | 指定真机序列号；省略时取首个 USB 且状态为 `device` 的设备 |
+| `ADB_PROXY_OUT_DIR` | 覆盖运行产物根目录（日志 / 抓包），默认项目根 `out/` |
+
+### 全部测试
+
+```bash
+# 无设备：单元 + 静态；动态用例自动 skip
+uv run python -B -m unittest discover -s tests -v
+
+# 含真实设备动态矩阵（需先放置 tests/app.apk）
+export ADB_PROXY_REAL_DEVICE=1
+export ADB_SERIAL=<可选，默认取首个 USB device>
+uv run python -B -m unittest discover -s tests -v
+```
+
+### 按文件运行
+
+```bash
+# 包布局与导入
+uv run python -B -m unittest tests.test_imports -v
+
+# 统一 CLI 分发
+uv run python -B -m unittest tests.test_cli_main -v
+
+# 协议 / lease / 观察逻辑单元测试
+uv run python -B -m unittest tests.test_protocols -v
+
+# 真机动态矩阵（server-proxy + device-proxy；需 tests/app.apk）
+export ADB_PROXY_REAL_DEVICE=1
+export ADB_SERIAL=<可选>
+uv run python -B -m unittest tests.test_dynamic_commands -v
+```
+
+## 说明
+
+- 代理是透明的：解析失败不会改写或阻断转发字节

adbproxy-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+adbproxy/__init__.py,sha256=SyvqKj-mQPl-eKJ7YUkOXFCaFmDwqU99-dFdP-BhIGQ,57
+adbproxy/__main__.py,sha256=hWzaa5tcXvObGkgtL3sLK_8GTJ8QDV-MGIJUvlyYUfc,105
+adbproxy/config.py,sha256=yxjdP5X4T0q-ffMYxK1-EWT_TrHo0fdByEkUK3xGDYk,1718
+adbproxy/cli/__init__.py,sha256=ZXXukaAohUK_yPCxcYrsL0d-Dn_o82V2j_R5ZTKxOcw,77
+adbproxy/cli/device.py,sha256=1k1oMCH3dhc5mXB2EIfbdLEHzsCPMSTYVpU7O4FKcww,226
+adbproxy/cli/main.py,sha256=0YsGtrW1mx5euWfD8u5_R_h08VcDTScHC0-bhNPW33Y,1530
+adbproxy/cli/server.py,sha256=fRrv-zYis2tXvnzEuWPJ8CWFZGeO8CCccw9tkL_yMB4,187
+adbproxy/device/__init__.py,sha256=iZRxvRpb_gy7w5oLUoRdhJFYjwWodEb8Hf4Fg7nrLEE,47
+adbproxy/device/app.py,sha256=govCVOVwmYTJs_cvNf2n1xyEO-6HI2V3jBxxbRoTfyo,22027
+adbproxy/device/backend.py,sha256=8aWvRyFbCum4_jQ5idxxqxR78N9FBEWmtivfSdllH4M,9651
+adbproxy/device/banner.py,sha256=Ki6dLD_MDG_9DZgRHXLigUVtQX3Xs6XLfmVbJuPL_j4,955
+adbproxy/device/connection.py,sha256=LTOEVKKY2ZlAzk9Vc5UjUEl0YHBozs3hf3MBmN5rBng,18151
+adbproxy/device/session.py,sha256=_OF6q5Fg1YTs-r4bB9iRVy5BvaFrlwUWm1GQBRZpvOg,8800
+adbproxy/device/stream_table.py,sha256=PWgQAC8PZ23yP5CTGj16aYmSnGXu8-JRrUJxvsaCsM4,3709
+adbproxy/observers/__init__.py,sha256=Pf__wL0xXZkcaMhmIXb5KmqlbCukcvKRZOZUDB79qw4,57
+adbproxy/observers/events.py,sha256=6COj4bBWNMBMu6eW9q5i5O4LXwV9ZDWeofYBZ3GOhfE,384
+adbproxy/observers/install.py,sha256=wX_ZMEZuoGsAiXgvW8bAzAQ4G457XJQDb5swuXwwAGc,5076
+adbproxy/observers/shell.py,sha256=srI0r5TVeeEAu_FbkoeLZ_b4Bm-OuBPy6YWS-VYe7WA,16470
+adbproxy/observers/stream.py,sha256=S3_pRrFgbLNiZJb-zumzXpHyC1yssX52pVnZtb-mJR8,3335
+adbproxy/observers/sync.py,sha256=_1VSbBUDGnbFelCKKADHghV40VQ2f46UK3Stjs6jXmc,25531
+adbproxy/protocols/__init__.py,sha256=kklWY-mgLwigxI8sycNPXhECeaXFoOAYZh3KmZxZ-0E,60
+adbproxy/protocols/adb.py,sha256=w5FW6tbA545LF44kAMd0W-WKW7BP_BgGi3RUnAOrXUA,2254
+adbproxy/protocols/payload/__init__.py,sha256=GZYzSZOwziT0tJJb568DUx_WPKFRPhHegwrNhXRR8i4,485
+adbproxy/protocols/payload/install.py,sha256=yTT5-TOBDJF_DpDZA45RViLuj2S0n3jREyF8UHlCW7E,1919
+adbproxy/protocols/payload/shell_v2.py,sha256=ls9ENaYkTLA4uYvtmQ7k9jeladc5AEZkT1P-dVHaUf4,831
+adbproxy/protocols/payload/sync.py,sha256=zMxHsvloy77JCS3N2pSP0EZkOT3SqOTO49k-ofVm6xg,5929
+adbproxy/protocols/smart_socket/__init__.py,sha256=o592f7cFuRJgr7uMGl-F1SB6OSo5F-vxD6P_IBKAdEo,908
+adbproxy/protocols/smart_socket/classifier.py,sha256=KEarj6wcxAmcipoRRBedqVqWTxZHMToJmC9_3sc1YAo,2937
+adbproxy/protocols/smart_socket/conversation.py,sha256=JvT2ByQuEETXS7qQjLD2dvqhXUS4xU67t0ns1UTdIAM,14166
+adbproxy/protocols/smart_socket/handshake.py,sha256=LFAbNNekfsgQ0i3K4abLNPP_n8QN8EzkuZ1vVhSwT8o,2406
+adbproxy/protocols/smart_socket/wire.py,sha256=4o4sRh58QrTgq84oyXzPw8slKgCKBQ-Zi7IDNQ-5wKc,2946
+adbproxy/protocols/transport/__init__.py,sha256=dqVxU5ToPYDSBK2CE7dmEa9dqPRh3Wwoaj6HXPkDUwE,1110
+adbproxy/protocols/transport/codec.py,sha256=XP_ryUSIKhUUbO9lekB_ykQ3IrKkO8s1aiaR-5_DyFA,3569
+adbproxy/protocols/transport/constants.py,sha256=LP0MKpA8eASmhtOFV0NrD9P1mZlpmp3SAXcf5wXJnTk,813
+adbproxy/protocols/transport/errors.py,sha256=tTn31jy1D4MZpHKxkW4-e1cuDK9NbJP7BsrXf-RODCI,137
+adbproxy/runtime/__init__.py,sha256=00moyIMdBW1PXy7aKbiC_h8afxBGmjwsw3HOXm04Aw8,58
+adbproxy/runtime/adb_process.py,sha256=wlCdt9zOG6XL2P1BS0hLd4fZPbQkkzDhrisiHKSsLlo,7337
+adbproxy/runtime/capture.py,sha256=31NjX-2nL2pdBfWNE0KRKNa0z7ogP5YS6pItCgy4Y6E,1181
+adbproxy/runtime/logging.py,sha256=UrplyM3E6Q1VByaVS0X_6vKNUfCF4UW0LMPKbSq2HW8,3582
+adbproxy/runtime/sockets.py,sha256=eRhJpw1NDmKVyxiLT67r-yr4VxO543YE7sqw7p7C2MQ,288
+adbproxy/server/__init__.py,sha256=L1IHdCFZwkNaCnr2nbxNBIdOgemYqJZ5R6TWoxjEf4k,47
+adbproxy/server/app.py,sha256=YP2QGXop5hnvoBplhoe4rZJWnV39BxitUAjZcoNrvM4,8762
+adbproxy/server/connection.py,sha256=szc-H4Y8oXHG9x9zDMlXoTfJ-C9ZbG9Z36UKtoLTH1I,16742
+adbproxy-0.1.0.dist-info/licenses/LICENSE,sha256=hgdeQ4J8Xldhj6a2rhIFWEBRVx9AjI-CPKFlFSPdYOI,1066
+adbproxy-0.1.0.dist-info/METADATA,sha256=nEnxiHsEJbQv9WtOml6CPNu3_PcJEngZjK1UrDSAIfU,7040
+adbproxy-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+adbproxy-0.1.0.dist-info/entry_points.txt,sha256=ZknEQho_AXMf-yywpE0m2Ags-gsc1afYPt88F2taL6E,140
+adbproxy-0.1.0.dist-info/top_level.txt,sha256=pg358OC1LsblgQzVB3RlliEHDTPfVbfMOW9qC0Lr9Kc,9
+adbproxy-0.1.0.dist-info/RECORD,,

adbproxy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adbproxy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+adb-device-proxy = adbproxy.cli.device:main
+adb-server-proxy = adbproxy.cli.server:main
+adbproxy = adbproxy.cli.main:main

adbproxy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forgo7ten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adbproxy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+adbproxy