krishnamallam/upbox

# upbox **主页：** · **仓库：** [](LICENSE) [](#roadmap) [](#) [](#) **upbox** 是一个纯本地的代理和仪表盘，它可以按工具、按请求向你准确展示你的 AI 助手将哪些代码、文件和 prompt 发送到了云端。 它不会将数据发送到任何地方。也不会回传数据。它只包含一个二进制文件、一个 SQLite 数据库和一个运行在你机器上的小型 Web UI。 ## 存在的问题 当你在 Cursor 中按下 Tab，在 Copilot 中按下 ⌘K，或者向 Claude 粘贴内容时，你的设想是“只有我的 prompt 被发送出去了”。但实际情况要复杂得多：当前文件、邻近文件、项目树、环境元数据，有时甚至包括最近的 shell 历史记录都会被发送出去。 供应商并不一定是在暗箱操作。只是他们的文档与人们认为正在发生的事情并不一致，而且目前没有内置的方法可以从外部进行验证。 在 2026 年，这种差距比六个月前更为关键： - **EU AI Act 执法。** 高风险 AI 系统的全部义务将于 **2026 年 8 月 2 日** 生效。合规性要求回答“从终端发出了什么？”——大多数组织都无法回答。 - **真实的安全事件。** 通过 AI 助手泄露源代码已不再只是假设。 - **工具泛滥。** 一个典型的开发者会同时运行 4-8 个 AI 工具。没有人能追踪所有的数据。 - **信任崩塌。** 一个监控你 AI 流量的闭源工具本身就是一个隐私问题。审计工具必须是开源的。 ## 它的功能 安装本地 CA，将你的 AI 工具指向 upbox 代理，然后就可以进行监控了。 - **实时推送。** 实时查看每个请求，并按工具（Cursor、Claude desktop、Copilot、ChatGPT、Codeium 等）进行分组。 - **检查请求体。** 查看实际的 prompt、文件内容和请求头。 - **转发前脱敏。** 正则表达式规则会在请求到达云端*之前*剥离 `.env` 块、API 密钥和 PII 模式。 - **域名强制执行。** 按工具设置目标允许名单。阻止或警告未知主机。查看收据记录。 - **审计日志。** JSON Lines + CSV 导出。防篡改哈希链。符合 Article-26 要求的字段。 - **纯本地运行。** 数据保存在磁盘上的 SQLite 中。仪表盘仅绑定到 `127.0.0.1`。upbox 本身不会进行任何外部调用。 ## 安装 选择适合你配置的方法。所有方法都会将相同的 `upbox` 命令安装到 `PATH` 中。需要 Python 3.12+。 ### 方法 1 — pipx *（推荐大多数用户使用）* `pipx` 会将 CLI 工具安装到一个隔离的 venv 中，同时保持它们在 `PATH` 上。不会与你的系统 Python 或其他项目发生冲突。 ``` # 如果尚未安装，请安装 pipx python3 -m pip install --user pipx python3 -m pipx ensurepath # 安装 upbox pipx install upbox # 验证 upbox --help ``` ### 方法 2 — uv tool 如果你使用 [uv](https://docs.astral.sh/uv/)（Astral 的 Python 工具链），它内置了一个比 pipx 更快的工具安装器。 ``` uv tool install upbox upbox --help ``` ### 方法 3 — uvx *（无需安装，运行一次即可）* 无需全局安装即可运行 upbox。uv 会在第一次运行时解析并缓存依赖，之后就会瞬间启动。 ``` uvx upbox --help uvx upbox init uvx upbox start ``` 适合用于一次性冒烟测试；但不太适合作为日常驱动，因为每次命令都会重新解析。 ### 方法 4 — pip + venv *（无需额外工具）* ``` python3 -m venv ~/.venvs/upbox ~/.venvs/upbox/bin/pip install upbox ~/.venvs/upbox/bin/upbox --help # 可选： symlink 到 PATH ln -s ~/.venvs/upbox/bin/upbox ~/.local/bin/upbox ``` 在 Ubuntu 24+、Debian 12+ 以及最新的 Fedora 上，系统级的 `pip install` 被 [PEP 668](https://peps.python.org/pep-0668/) 阻止。请使用 venv（如上所示）或方法 1-3。 ### 方法 5 — 从源码安装 *（最新的 `main` 分支）* 适合需要最新前沿特性或进行开发的用户： ``` git clone https://github.com/krishnamallam/upbox.git cd upbox uv sync # installs runtime + dev deps from uv.lock uv run upbox --help ``` ### 方法 6 — 直接从标签或分支安装 ``` # 最新 tagged release pipx install git+https://github.com/krishnamallam/upbox.git@v0.1.0 # 最新 main pipx install git+https://github.com/krishnamallam/upbox.git@main # 或通过 pip/venv pip install git+https://github.com/krishnamallam/upbox.git@v0.1.0 ``` ### 方法 7 — 可编辑安装 *（二次开发 upbox）* ``` git clone https://github.com/krishnamallam/upbox.git cd upbox uv sync --dev # adds pytest, ruff, mypy, httpx uv run upbox --help # runs your local checkout ``` 对代码的修改会立即生效。有关测试和 lint 命令，请参见 [开发](#development) 部分。 ## 快速开始 安装完成后，三条命令即可让你运行起来： ``` upbox init # one-time: generates + installs the local CA upbox start # boots proxy on :8888 and dashboard on :8800 # Ctrl+C 停止两者。 ``` 然后： 1. 将 AI 工具指向 `http://127.0.0.1:8888`（或设置 `HTTPS_PROXY=http://127.0.0.1:8888`）。 2. 打开位于 `http://127.0.0.1:8800` 的仪表盘。 各工具的配置方法（Cursor、Claude desktop / Code、GitHub Copilot、ChatGPT、curl、SDK 客户端）：[docs/configuring-tools.md](docs/configuring-tools.md)。 ## 验证安装 以下命令都应该成功执行： ``` upbox --help # CLI lists: init, start, proxy, dashboard, stop, status, export upbox status # reports CA trust per layer for your platform ``` 端到端冒烟测试（在运行 `upbox init` 之后）： ``` # 终端 1 upbox proxy # 终端 2 curl --proxy http://127.0.0.1:8888 \ --cacert ~/.upbox/ca/upbox-ca.pem \ https://httpbin.org/anything # 终端 3 upbox dashboard # 打开 http://127.0.0.1:8800 — curl 请求应在约 2 秒内出现 ``` 如果 curl 命令行因 TLS 警告而报错，说明你的 CA 安装不彻底——请运行 `upbox status` 查看缺失了哪个层级并修复它（参见 [docs/installing-ca.md](docs/installing-ca.md))。 ## 平台注意事项 - **macOS** — `upbox init` 会提示使用 sudo 安装到系统钥匙串。Cursor、Claude Desktop、VSCode 和浏览器都会从中读取证书。 - **Linux** — 在运行 `upbox init` 之前，请安装 `libnss3-tools`（Debian / Ubuntu）或 `nss-tools`（Fedora），以便 Firefox / Chrome / 基于 NSS 的 Electron 应用也能信任该 CA。对于基于 Node 的 Electron 应用（Cursor、Claude Desktop、VSCode），请使用 `NODE_EXTRA_CA_CERTS=$HOME/.upbox/ca/upbox-ca.pem` 启动它们。 - **Windows** — `upbox init` 会写入到按用户划分的受信任根存储区，无需管理员权限提升。Firefox 使用自己的 NSS 数据库；请通过 Settings → Privacy → Certificates → View Certificates → Authorities → Import 手动导入证书。 完整的各平台安装 + 卸载操作指南：[docs/installing-ca.md](docs/installing-ca.md)。 ## 卸载 ``` upbox init --uninstall # remove CA from every trust store it was installed into rm -rf ~/.upbox/ # remove cert, audit db, rules (optional) # 然后使用你当初使用的安装工具卸载软件包本身： pipx uninstall upbox # if you used pipx uv tool uninstall upbox # if you used uv tool ~/.venvs/upbox/bin/pip uninstall upbox # if you used a venv ``` ## 开发 克隆并安装开发依赖： ``` git clone https://github.com/krishnamallam/upbox.git cd upbox uv sync --dev ``` 然后： ``` # 运行完整 test suite（约 2 秒，85 个测试） uv run pytest -v # 运行单个 test 文件 uv run pytest tests/test_capture.py -v # Lint + format uv run ruff check . uv run ruff format . # Type check uv run mypy upbox # 从你的 checkout 运行 upbox（无需安装） uv run upbox --help uv run upbox status uv run upbox proxy ``` CI 会在 `ubuntu-latest`、`macos-latest` 和 `windows-latest` 上运行相同的流程。完整的 14 天构建计划及其背后的架构决策记录在 [PLAN.md](PLAN.md) 中。 ## 架构 ``` ┌──────────────────┐ AI tool ───▶ │ mitmproxy core │ ───▶ cloud LLM │ + upbox addons │ └────────┬─────────┘ ▼ ┌───────────────┐ ┌──────────────────┐ │ SQLite │ ◀──── │ Dashboard │ │ audit log │ │ (FastAPI + HTMX)│ └───────────────┘ └──────────────────┘ ``` 单个 Python 进程。mitmproxy 作为代理核心（MIT 许可，久经考验）。SQLite 作为审计存储。FastAPI + HTMX 用于仪表盘——快速、无需构建步骤、无需 JS 框架。 ## 威胁模型 **upbox 能够防御的威胁** - 你已经信任的 AI 工具中出现的意外数据泄密。 - 意外将 `.env` 内容或 API 密钥粘贴到云端 LLM 中。 - 在需要回答“上个月我们的笔记本电脑向 AI 供应商发送了什么？”时出现的合规漏洞。 **upbox 无法防御的威胁** - 固定证书并拒绝本地 CA 的工具（除非绕过，否则某些工具将无法工作）。 - 不通过你的工具而直接读取文件的恶意本地进程。 - 在安装之前已经泄露的数据。 **upbox 自身的所作所为** - 通过你安装（并可以卸载）的本地 CA 读取你的 AI 流量。 - 将审计数据存储在 `~/.upbox/upbox.db` 中（SQLite；计划在 v0.2 中支持静态数据加密）。 - 仅在 `127.0.0.1` 上提供仪表盘服务。 - 绝不主动发起任何外部网络调用。 ## EU AI Act 和 GDPR 映射 upbox 是一款面向部署者的工具。它本身不能证明你符合合规要求——但它能生成合规所需的*证据和控制措施*： | 义务 | upbox 提供的内容 | |---|---| | **AI Act Article 4** — AI 素养（自 2025 年 2 月起生效） | 一份可见、可查的记录，展示了 AI 工具在你的终端上正在做什么。真实的记录胜过 PPT 上的政策。 | | **AI Act Article 26** — 部署者义务（日志记录、监控、人工监督） | 按请求的审计日志：时间戳、工具、目标地址、大小、状态、应用的脱敏规则。JSON Lines + CSV 导出。 | | **AI Act Article 50** — 透明度（2026 年 8 月 2 日适用） | 足以支持对受影响人群履行透明度义务的 AI 系统交互记录。 | | **AI Act Article 99** — 处罚 | 帮助证明善意的努力和具体的技术措施。 | | **GDPR Article 5** — 数据最小化 | 脱敏引擎会在转发前剥离 PII。 | | **GDPR Article 32** — 处理安全 | 提供可见性 + 控制离开终端的数据的技术措施。 | | **GDPR Article 35** — DPIA | 提供具体的数据流以填补影响评估。 | **主要来源**（官方 ELI URL —— 稳定链接）： - AI Act 全文： - AI Act 实施时间表： - GDPR 全文： **逐条参考：** - AI Act Art. 4 — - AI Act Art. 26 — - AI Act Art. 50 — - AI Act Art. 99 — - GDPR Art. 5 — - GDPR Art. 32 — - GDPR Art. 35 — upbox 不是法律建议。请咨询法律顾问以获取合规认证。 ## 路线图 **v0.1 — "第一张疯传的截图"**（目标：2026 年 7 月 15 日） - 本地 CA 设置，mitmproxy 引导 - 工具指纹识别（Cursor、Claude desktop、Copilot、ChatGPT、Codeium） - 实时仪表盘 - 正则表达式脱敏引擎 - SQLite 审计日志 - JSONL + CSV 导出 **v0.1.1 — 发行版优化**（目标：v0.1 发布后 1-2 周） - **原生二进制文件** — Windows 的单文件 `.exe`，macOS 的 `.dmg`（或 Homebrew formula），Linux 的 AppImage。让非 Python 用户可以一键安装。可能会通过 PyInstaller 实现；如果杀毒软件误报成为一个真正的问题，将在发布前获取代码签名证书。 - Windows 上的 Firefox NSS 自动安装。 - YAML 规则文件的热重载（目前需要重启 `upbox start`）。 **v0.2 — "为合规而生"**（目标：2026 年 8 月 1 日 — AI Act 执法前夕） - Article 26 审计日志导出格式 - 防篡改哈希链 - SQLite 静态数据加密 - 团队模式（中央仪表盘，多个终端，局域网内可用） **v0.3 及以后** - 用于自定义工具指纹的 Plugin SDK - 配套的浏览器扩展（适用于 Web LLM 应用） - macOS 菜单栏应用，Windows 托盘应用 - 可配置的保留策略和告警 ## 致谢 upbox 依赖于： - **[mitmproxy](https://mitmproxy.org)** (MIT) — 代理核心。如果没有它，这个项目需要一年而不是两周的时间来完成。 - **[FastAPI](https://fastapi.tiangolo.com)** (MIT) — 仪表盘后端。 - **[HTMX](https://htmx.org)** (BSD-2-Clause) — 无需构建步骤的仪表盘前端。 - **[SQLite](https://sqlite.org)** (公共领域) — 审计日志存储。 - **[Pico](https://picocss.com)** (MIT) — 仪表盘的最简 CSS。 - **[Typer](https://typer.tiangolo.com)** (MIT) — CLI。 完整的第三方许可证文本保留在 [`LICENSES/`](LICENSES/) 中。 ## 许可证 upbox 基于 **[MIT License](LICENSE)** 授权。 该项目的早期草案曾考虑使用 AGPL-3.0（“监控者必须可被监控”）。之所以选择 MIT，是因为最有可能大规模部署 upbox 的受众——那些有严格开源政策公司的安全团队——无法轻易采用 AGPL。这种摩擦的成本超过了理念上的胜利。 审计工具保持开放和可检查的特性，是通过开源承诺本身来保证的，而不是通过某个许可证条款。任何人都可以将 upbox 分叉成闭源产品。但不应该信任它们的分叉版本来审计你的流量。请信任这个仓库，否则就谁都别信。 ## 贡献 upbox 目前处于 1.0 版本之前的阶段，正在快速迭代中。欢迎提交 Issues、想法和 PR。 目前最快的帮助方式是：在 v0.1 发布时安装它，用你日常使用的 AI 工具运行它，并报告让你感到意外的地方。首发截图就是最好的营销活动——而你提供的可能就是下一个震撼亮相的截图。

标签：AI助手监控, AI安全, Chat Copilot, Claude监控, Copilot监控, Cursor监控, EU AI Act, HTTPS解密, JSONLines, MIT开源, Python, SQLite, TCP SYN 扫描, Web UI, 人工智能安全, 代码防泄漏, 企业合规, 合规性, 大模型工具监控, 威胁情报, 开发者工具, 提示词审计, 数据防泄漏(DLP), 数据隐私, 无后门, 本地CA, 本地代理, 本地部署, 流量抓包, 源代码保护, 网络安全, 网络审计, 逆向工具, 透明网关, 隐私保护, 零信任