mstan/xboxlle-probe
GitHub: mstan/xboxlle-probe
一个用于在真实初代 Xbox 上执行低级硬件探测和数据采集的代理工具，供模拟器开发者将模拟行为与实际硬件测量结果进行对比验证。
Stars: 0 | Forks: 0
# xboxlle-probe
一个小型的 [nxdk](https://github.com/XboxDev/nxdk) 自制程序代理和主机端 Python 客户端，
用于观察真实的初代 Xbox。它最初是作为 `xboxlle` 的硬件预言机组件而诞生的：
模拟器的行为可以与实际硬件的测量结果进行比较，而不是
基于假设或另一个模拟器。
Xbox 运行 `xboxlle-probe.xbe`，它会监听 TCP 端口 4380。然后主机客户端可以：
- 识别正在运行的代理和 Xbox 内核；
- 运行带有 JSON 输出的、命名的只读 CPU 和 NV2A 探测；
- 读取受保护的 RAM、NV2A/MCPX MMIO 以及选定的 flash 范围；
- 将允许的范围批量读取到主机文件中；
- 在明确启用的不安全模式下，写入 RAM/MMIO 或执行上传的 x86 负载；
- 启动另一个 XBE 或返回到 dashboard。
命名的探测是面向人类和 AI 代理的预期接口。原始内存操作
是为硬件研究而存在的，但它们是高风险工具。
## 安全模型
该项目减少了意外误用；它并不能使底层硬件访问变得安全。
- Xbox 会显示警告，并在打开其监听器之前进行等待。
- 在该 TCP 会话发送确切的启用短语之前，每个原始读取、转储、写入、执行和标题控制请求都会被拒绝。
- 主机客户端在执行危险操作之前需要 `--i-accept-the-risk`。
- 直接读取和写入会进行范围检查。`WRITE` 绝不接受 flash 写入。
- 命名的探测使用一小部分固定的寄存器，这些寄存器已在一台 Xbox v1.1 上经过测试。
这些措施是护栏，而不是安全边界。`EXEC` 有意运行任意
x86 机器码，这可以绕过每个范围检查并访问存储或 flash。
只读 MMIO 并非普遍无害：某些硬件寄存器具有读取副作用，
错误的地址仍然可能导致机器死机。
在运行代理之前，请阅读 [SECURITY.md](SECURITY.md)。
## 要求
- 一台已经能够运行未签名自制程序的初代 Xbox。
- 一个由 Xbox 和主机计算机共享的私有、受信任的 LAN。
- [nxdk](https://github.com/XboxDev/nxdk) 及其前置条件以构建 XBE。
- 主机上安装了 Python 3.9 或更高版本。
- 一种 dashboard 或其他既定方法，用于传输和启动 XBE。
本项目不会绕过 Xbox 安全机制、安装软破解，或提供 Microsoft 固件、
密钥、EEPROM 内容、BIOS 镜像、dashboard 或其他受版权保护/主机专属的材料。
## 构建
递归克隆 nxdk，激活其环境，并将此 Makefile 指向它：
```
git clone --recursive https://github.com/XboxDev/nxdk.git
git clone https://github.com/mstan/xboxlle-probe.git
export NXDK_DIR="$PWD/nxdk"
eval "$("$NXDK_DIR/bin/activate" -s)"
make -C xboxlle-probe -j
```
XBE 生成为：
```
xboxlle-probe/bin/default.xbe
```
仓库 CI 固定了记录在 `.nxdk-version` 中的 nxdk 版本。当测量结果
必须可复现时，建议进行固定。
## 安装与启动
使用你现有的自制程序工作流将 `bin/default.xbe` 复制到你的 Xbox。例如，
将其放置在：
```
E:\Apps\xboxlle-probe\default.xbe
```
从你的 dashboard 启动它。屏幕将显示危险警告，等待 8 秒，
初始化网络，并显示其 IP 地址和监听端口。
提供了一个可选的 FTP 部署命令，但它会写入 Xbox 存储，因此
需要明确的风险接受确认：
```
python host/xbox_probe.py \
--host 192.168.1.50 \
--i-accept-the-risk \
deploy bin/default.xbe \
--ftp-user xbox
```
除非提供了 `--ftp-password` 或
`XBOX_PROBE_FTP_PASSWORD`，否则将通过交互方式请求密码。不要将密码放在脚本、shell 历史记录、Git、
issues 或探测结果中。
## 使用
显式设置地址。客户端故意没有内置 Xbox IP：
```
export XBOX_PROBE_HOST=192.168.1.50
```
检查连接性和元数据：
```
python host/xbox_probe.py ping
python host/xbox_probe.py info
```
运行固定的只读探测：
```
python host/xbox_probe.py probe cpu
python host/xbox_probe.py probe nv2a
```
CPU 结果示例：
```
{"probe":"cpu","agent":"xboxlle-probe v0.3.0","vendor":"GenuineIntel","max_leaf":2,"signature":"0x0000068a","features_edx":"0x0383f9ff","features_ecx":"0x00000000"}
```
受保护的原始读取（仍然危险——v0.1 曾因错误读取导致真实硬件死机）：
```
python host/xbox_probe.py --i-accept-the-risk read 0xfd000000 4
```
将允许的范围批量读取到本地文件：
```
python host/xbox_probe.py \
--i-accept-the-risk \
bulk-read 0xff000000 262144 \
--output flash.bin
```
所有原始或更改状态的命令都需要主机标志和会话启用：
```
python host/xbox_probe.py --i-accept-the-risk write 0x00011000 90909090
python host/xbox_probe.py --i-accept-the-risk exec payload.bin
```
对于原始读取、转储、写入、执行和标题控制，主机客户端会打开一个新的 TCP
会话，发送
`ARM I_ACCEPT_THE_RISK`，验证 `ARMED` 响应，然后才发送危险的
请求。该短语是一个防止意外的护栏，**而不是身份验证**。
## AI 辅助使用
AI 代理在与硬件交互之前应阅读 [AGENTS.md](AGENTS.md)。核心
规则是：
1. 绝不通过网络扫描来发现或猜测 Xbox IP。
2. 要求人类识别目标主机，并确认探测它是安全的。
3. 优先使用 `ping`、`info` 和固定的命名探测。
4. 未经人类对该确切操作的明确授权，
不得部署、写入、启动、转储或执行代码。
5. 在经过审查和清理之前，将所有硬件结果视为潜在的私密信息。
适合用于编写其他客户端的协议详细信息在 [docs/PROTOCOL.md](docs/PROTOCOL.md) 中。
关于原始硬件会话的清理报告位于
[docs/ORIGIN.md](docs/ORIGIN.md) 中。
## 开发
主机端测试不需要 Xbox：
```
python -m unittest discover -s tests -v
```
测试套件使用本地模拟 TCP 代理来验证组帧、批量传输和不安全
会话启用。
## 许可证
MIT。请参阅 [LICENSE](LICENSE)。
该软件以 **“原样”提供，不提供任何形式的保证**。使用风险由您自行承担。
标签：nxdk, Python, Xbox自制程序, 云资产清单, 并发处理, 无后门, 硬件探针, 硬件测试, 系统底层, 逆向工具, 逆向工程