anapeksha/pico-bit-py

# Pico Bit [](https://github.com/anapeksha/pico-bit/actions/workflows/ci.yml) [](https://github.com/anapeksha/pico-bit/actions/workflows/release.yml) `pico-bit` 是一个针对 Raspberry Pi Pico 2 W 的开源 MicroPython 项目。它结合了 USB HID DuckyScript runtime、由 Wi-Fi 承载的操作员 portal，以及用于授权安全研究、实验室自动化和防御性验证的可选 Rust agent 投递流程。 Pico 通过 USB 输入 payload，在 `http://192.168.4.1` 提供 browser UI，并可以在 Pico 文件系统上暂存一个上传的可执行文件，以便通过 USB 进行投递。 ## 亮点 - 启动时和按需执行 `payload.dd` - 带有保存、验证和运行操作的 browser 编辑器 - portal 中的行级别 dry-run 诊断 - 根据 OS 和键盘布局选择主机输入目标 - 为 runtime MSC/HID 设备共享的 Host USB 状态 - 将单二进制文件作为 `payload.exe` 或 `payload.bin` 进行 USB 暂存 - 实时执行时间轴，以及 loot 导入和 `loot.json` 下载 - 固化在固件 flash 中的预编译 Svelte 5 + Tailwind v4 前端 - 冻结的 UF2 构建版本，以及带有 SHA-256 校验和的发布元数据 ## 硬件支持 - 支持的开发板：仅限 Raspberry Pi Pico 2 W (`RPI_PICO2_W`) - 使用 Pico 自身的 USB 数据端口进行 HID 和 MSC 投递 ## 默认访问 | 项目 | 值 | |------|-------| | Wi-Fi SSID | `PicoBit` | | Wi-Fi 密码 | `PicoBit24Net` | | Portal URL | `http://192.168.4.1` | | Portal 用户名 | `admin` | | Portal 密码 | `PicoBit24Admin` | ## 刷入发布版 UF2 1. 连接 Pico 的同时按住 `BOOTSEL` 键。 2. 从[发布页面](https://github.com/anapeksha/pico-bit/releases/latest)下载最新的 `pico-bit-RPI_PICO2_W-.uf2`。 3. 将其复制到 `RPI-RP2` 驱动器。 4. 等待开发板重启。 5. 加入 `PicoBit` Wi-Fi 网络并打开 `http://192.168.4.1`。 首次启动时，如果 `payload.dd` 不存在，Pico Bit 会创建它。 ## 从源码构建 ### 前置条件 - Python `3.11` 到 `3.14` - [`uv`](https://docs.astral.sh/uv/) - 用于前端构建的 Node.js `24` - 如果要将本地构建直接复制到 Pico，则需要 `mpremote` - 如果要在本地构建 agent 二进制文件，则需要 Rust 安装依赖： ``` uv sync npm ci --prefix web ``` ### 构建本地 Runtime 制品 这会创建： - `dist/boot.py` - `dist/boot.mpy` - `dist/mpy/**/*.mpy` ``` uv run python scripts/build.py ``` 如果前端资产已经是最新的，你可以跳过 Vite 步骤： ``` uv run python scripts/build.py --skip-frontend ``` ### 使用 `mpremote` 将本地构建复制到 Pico 一次性安装 `mpremote`： ``` python3 -m pip install mpremote ``` 复制捆绑的 boot 文件： ``` mpremote connect auto fs cp dist/boot.py :boot.py mpremote connect auto reset ``` 如果你想手动播种一个本地 payload 文件： ``` mpremote connect auto fs cp payload.dd :payload.dd ``` ### 在 Linux 上构建冻结的 UF2 安装固件构建前置条件： ``` sudo apt-get update sudo apt-get install -y build-essential cmake gcc-arm-none-eabi libnewlib-arm-none-eabi ninja-build ``` 然后构建发布版 UF2： ``` uv run python scripts/release.py build-uf2 \ --micropython-ref v1.28.0 \ --board RPI_PICO2_W \ --release-version v0.0.2 ``` 有用的发布选项： - `--usb-profile default|generic-composite|generic-keyboard|hobbyist` - `--ap-ssid ...` - `--ap-password ...` - `--portal-username ...` - `--portal-password ...` 制品会存放在 `dist/` 中，包括 `.uf2` 文件和 `release.json`。 ## 构建 Rust Agent 二进制文件 Rust agent 位于 [`agent/`](agent/) 目录下。可用的二进制文件有： - `recon` - `exfil` - `persist` - `wipe` ### 本地开发检查 ``` cargo check --manifest-path agent/Cargo.toml --bins ``` ### 本地原生构建 ``` cargo build --manifest-path agent/Cargo.toml --release --bin exfil cargo build --manifest-path agent/Cargo.toml --release --bin persist cargo build --manifest-path agent/Cargo.toml --release --bin wipe cargo build --manifest-path agent/Cargo.toml --release --bin recon --features with-sysinfo ``` ### Linux 发布风格构建 ``` rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl python3 -m pip install ziglang cargo install cargo-zigbuild ``` ``` cargo zigbuild --manifest-path agent/Cargo.toml --release --target x86_64-unknown-linux-musl --bin exfil cargo zigbuild --manifest-path agent/Cargo.toml --release --target x86_64-unknown-linux-musl --bin persist cargo zigbuild --manifest-path agent/Cargo.toml --release --target x86_64-unknown-linux-musl --bin wipe cargo zigbuild --manifest-path agent/Cargo.toml --release --target x86_64-unknown-linux-musl --bin recon --features with-sysinfo ``` 将 target 替换为 `aarch64-unknown-linux-musl` 即可适用于 `arm64`。 ## 前端开发 使用模拟的 Pico API 在本地运行 portal： ``` npm --prefix web run dev ``` 要针对真实硬件测试 Vite 前端： ``` PICOBIT_PROXY=http://192.168.4.1 npm --prefix web run dev ``` ## 本地验证 ``` npm --prefix web run build npm --prefix web run check npm --prefix web run lint npm --prefix web run test uv run python -c "from scripts.helpers.assets import sync_web_assets; sync_web_assets(check=True, skip_build=True)" uv run ruff format --check . uv run ruff check scripts src tests uv run pyright uv run pytest uv run python scripts/build.py --skip-frontend ``` ## 仓库说明 - `src/web_assets.py` 是从 `dist/web/` 生成的，不应手动编辑 - 固件从驻留在 flash 中的字节提供生成的静态路由表，包括 `/`、`/assets/index.css` 和 `/assets/index.js` - `payload.dd` 在 Pico 文件系统上是可写的，并没有被冻结到固件中 - portal 一次暂存一个可执行文件，Windows agent 对应 `payload.exe`，Linux/macOS agent 对应 `payload.bin` - armory 上传仅限可执行文件，最大容量为 `1 MB` - `src/usb.py` 是共享 `machine.USBDevice` 单例、MSC 能力检测、runtime `active()` 状态以及暂存二进制文件名的唯一事实来源 - `src/keyboard.py` 拥有 HID 键盘 runtime 和键盘布局元数据；`src/boot.py` 先初始化 USB，然后初始化键盘 - 发布版 UF2 构建通过内置 USB MSC 暴露 Pico 文件系统，并附加 HID 键盘接口以进行离线投递 - 主机卷名可能有所不同，并且可能显示为 `No Name`，因此 USB stager 会根据文件名搜索 `payload.exe` 或 `payload.bin` - 成功的上传会刷新共享 USB runtime，以便暂存的文件在挂载的 Pico 驱动器上变得可见 - 通过 USB 投递的 agent 可以将 `loot-usb.json` 写入 Pico 驱动器；portal 会将其导入到规范的 `loot.json` 中 ## 发布 GitHub releases 会发布： - 针对 `RPI_PICO2_W` 的 UF2 固件 - 预构建的 Windows、Linux 和 macOS agent 包 - 包含发布元数据、文件大小和 SHA-256 校验和的 `release.json` 手动运行发布可以独立构建固件和 agent 包，部分重新运行会为未更改的资产保留校验和元数据。 ## 负责任的使用 仅在你拥有或被明确授权测试的系统上使用 Pico Bit。未经授权访问计算机系统是非法的，不在本项目的范围内。 ## 许可证 GPL-3.0-only。请参阅 [LICENSE](LICENSE)。

标签：DuckyScript, MicroPython, MITM代理, Raspberry Pi Pico, SBOM分析, Svelte, USB HID注入, 可视化界面, 硬件安全工具, 红队自动化, 网络信息收集, 逆向工具