openintelligence-labs/phantomdep

# PhantomDep [](LICENSE) [](https://www.rust-lang.org/) PhantomDep 是一个本地优先的依赖防火墙。它会在引入每个新依赖的确切时刻——AI 工具调用、IDE 编辑、shell 命令、manifest 更改、PR 或 CI——对其进行验证，并在包到达您的机器或仓库之前生成有证据支撑的判定。 2024 年 4 月，Lasso Security 在 PyPI 上注册了一个名为 `huggingface-cli` 的空 Python 包。三个月内有 30,000 名开发者安装了它。他们中的每一个人都是被 AI 助手告知去安装它的。构建 PhantomDep 就是为了让这种情况不再发生。  ## 工作原理 一个仅 5.5 MB 的 Rust 二进制文件，包装您的包管理器，挂钩您的 AI agent，在您的编辑器中作为 LSP 服务器运行，并拦截您的 CI。每次调用： 1. 从触发的边界（安装命令、钩子事件、源文件 diff、manifest 编辑）中提取包名。 2. 通过本地 SQLite 缓存（已找到包的 TTL 为 24 小时，404 的 TTL 为 5 分钟，以便快速捕获刚注册的抢注垃圾包）对照注册表（PyPI / npm / crates.io / Go modules）进行解析。 3. 与 [Phantom-DB](./phantom-db/) 交叉比对——这是一个公开的、基于 MIT 许可的已确认抢注垃圾包和已知恶意条目数据集。 4. 生成离散的 `Verdict`（`PHANTOM`、`SQUATTED`、`KNOWN_MALICIOUS`、`LOOKALIKE`、`REAL`、……）以及机器可读的证据包。没有黑盒评分。 5. 根据判定的默认操作进行拦截、警告或允许——可通过 `.phantomdep.toml` 按项目覆盖。 热判定在数十微秒内运行；冷判定每 24 小时每个包仅需一次 HTTPS 往返。 ## 安装 选择您已有的工具链——这四种方式都提供相同的静态二进制文件： ``` brew install openintelligence-labs/tap/phantomdep # Homebrew (macOS / Linux) npm install -g phantomdep # npm — downloads the binary for your platform pip install phantomdep # PyPI — binary ships inside the wheel cargo install --locked phantomdep # crates.io — builds from source ``` 或者直接从 [GitHub Releases](https://github.com/openintelligence-labs/phantomdep/releases) 下载静态二进制文件： ``` arch=$(uname -m | sed 's/^arm64$/aarch64/'); os=$([ "$(uname -s)" = Darwin ] && echo apple-darwin || echo unknown-linux-gnu) curl -sSfL "https://github.com/openintelligence-labs/phantomdep/releases/latest/download/phantomdep-${arch}-${os}.tar.gz" \ | tar -xz && sudo install phantomdep /usr/local/bin/ ``` 无需 Python 或 Node 运行时，无需注册，无遥测。该二进制文件可针对内置快照离线工作。 ## 包装包管理器 ``` phantomdep wrap pip install requests fastapi phantomdep wrap npm install react @anthropic-ai/sdk phantomdep wrap cargo add serde tokio phantomdep wrap go get github.com/spf13/cobra ``` 支持 `pip`、`uv`、`poetry`、`npm`、`pnpm`、`yarn`、`cargo` 和 `go`。如果每个包都是真实的，PhantomDep 会透明地 `exec` 底层命令。如果任何包是 `PHANTOM`、`SQUATTED`、`KNOWN_MALICIOUS` 或 `LOOKALIKE`，它将以退出代码 2 拦截——或者在交互式 shell 中提示。 ## 扫描仓库  ``` phantomdep scan . # walks .py / .js / .ts / .rs / .go + Cargo.toml + go.mod phantomdep scan . --format sarif # GitHub Code Scanning input phantomdep scan . --format markdown # PR-comment shaped output phantomdep scan . --format json ``` 一个 51 个文件的 Python 项目冷扫描约需 650 毫秒（每个唯一包一次 HTTPS RTT，并发为 16），热扫描约 13 毫秒。 ## 挂钩 Claude Code ``` phantomdep hook install ``` 将 `PreToolUse` 条目写入 `~/.claude/settings.json`，以便每个 `Bash` 安装命令和每个涉及依赖 manifest 的 `Write`/`Edit`/`MultiEdit` 都首先通过 PhantomDep。幂等且可逆（`phantomdep hook uninstall`）。 该钩子返回标准的 Claude Code 决策 JSON： ``` { "decision": "block", "reason": "PhantomDep blocked 1 package(s): huggingface-cli (Phantom) → did you mean: huggingface-hub" } ``` 根据 Claude Code 钩子规范，退出代码 2 + stderr 上的原因将作为拦截说明反馈给 Claude。 ## MCP 服务器 ``` phantomdep mcp ``` Stdio JSON-RPC，MCP 协议版本 `2025-06-18`。提供四个只读工具：`validate_package`、`validate_imports`、`suggest_real_alternative`、`phantom_db_status`。没有 shell 执行，没有文件系统更改，没有注册表更改，输出确定。将其接入 Cursor、Claude Desktop、Continue、Cline 或任何 MCP 客户端。 ## LSP 服务器 + IDE 扩展 ``` phantomdep lsp ``` 通过 stdio 的 LSP 3.17。针对幻觉/抢注/形似包的导入触发 `publishDiagnostics`，并提供可就地重写导入的 `textDocument/codeAction` 快速修复。 关于开箱即用的安装，请参阅 [VS Code 扩展](./extensions/vscode/)——在 VS Code、Cursor、Windsurf 以及任何其他 VS Code 分支中均可使用。 ## CI ``` # .github/workflows/phantomdep.yml name: PhantomDep on: [pull_request, push] jobs: scan: runs-on: ubuntu-latest permissions: contents: read security-events: write pull-requests: write steps: - uses: actions/checkout@v4 - uses: openintelligence-labs/phantomdep@v1 with: fail-on: block ``` 将 SARIF 上传到 GitHub Code Scanning，并在 PR 中发布置顶的 Markdown 评论。 ## 判定 | 判定 | 含义 | 默认操作 | |---|---|---| | `PHANTOM` | 在注册表中未找到包 | `BLOCK` | | `SQUATTED` | 为捕获安装而注册的幻觉名称 | `BLOCK` | | `KNOWN_MALICIOUS` | 列入 OpenSSF malicious-packages | `BLOCK` | | `INTERNAL_COLLISION` | 公开包与已知的内部名称冲突 | `BLOCK` | | `LOOKALIKE` | 与热门包的 Damerau-Levenshtein 距离 ≤1 | `WARN` | | `API_MISMATCH` | 包存在但未导出导入的符号 | `WARN` | | `REAL` | 包存在，无高置信度威胁信号 | `ALLOW`（带风险评分） | | `UNKNOWN` | 网络不可达，无快照，无 DB 条目 | `WARN` | 判定是确定且有顺序的：`PHANTOM > KNOWN_MALICIOUS > SQUATTED > INTERNAL_COLLISION > API_MISMATCH > LOOKALIKE > REAL > UNKNOWN`。第一个匹配的判定生效；后续信号将附加到证据包中。 每个发现都提供一个证据包： ``` { "name": "ccxt-mexc-futures", "ecosystem": "pypi", "verdict": "KNOWN_MALICIOUS", "action": "BLOCK", "confidence": 0.98, "evidence": [ { "signal": "phantom_db_hit", "status": "malicious", "intended_target": "ccxt", "first_observed": "2025-04-01" } ], "fixes": [{ "replacement": "ccxt", "confidence": 0.85 }] } ``` 可通过 `.phantomdep.toml` 按项目配置默认值： ``` [verdicts] phantom = "block" squatted = "block" lookalike = "warn" unknown = "warn" [ci] fail_on_verdict = ["phantom", "squatted", "known_malicious"] [allowlist] packages = ["my-internal-fresh-pkg@*"] ``` ## 性能 ``` $ phantomdep benchmark --iterations 100 PhantomDep benchmark (100 iterations, warm caches) scenario p50 (μs) p95 (μs) max (μs) ------------------------------------------------------------ real PyPI (cached) 21 24 53 real npm (cached) 11 14 24 phantom PyPI (cached) 38 44 58 offline resolve only 21 24 31 ```  可复现：`phantomdep benchmark --iterations 100 --json`。以上数据来自 Apple Silicon 上的 v1.0.1 发布版本，使用住宅宽带。冷网络判定主要受注册表 HTTPS 往返时间影响（对于热 TLS 通常为 10–30 毫秒，偶尔会出现高达约 350 毫秒的离群值）。完整的方法论、真实仓库扫描时间及复现命令：[docs/BENCHMARK.md](./docs/BENCHMARK.md)。 ## 支持的生态系统 | 生态系统 | 注册表 | Manifest | 源文件导入 | |---|---|---|---| | PyPI | `pypi.org/pypi/{name}/json` | `requirements.txt`, `pyproject.toml` | `.py`, `.pyi` | | npm | `registry.npmjs.org/{name}` | (计划中) | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | | crates.io | `crates.io/api/v1/crates/{name}` | `Cargo.toml` | (计划中) | | Go modules | `proxy.golang.org/{module}/@v/list` | `go.mod` | `.go` | | Maven | (计划中) | (计划中) | (计划中) | 通过 [deps.dev](https://docs.deps.dev/api/v3/) 进行跨生态系统回退，以获取统一的元数据。 ## 与现有工具的关系 | 工具 | 能否捕获 PhantomDep 所捕获的内容？ | |---|---| | Snyk, OSV-Scanner, Dependabot | 否——它们查找真实包中的 CVE。幻觉或抢注名称没有 CVE。 | | Socket | 部分能——行为风险在错误名称进入 `package.json` 后触发。PhantomDep 在其之前触发。 | | Phylum (Veracode) | 部分能——在已知恶意方面很强，但免费开发者层级在收购后未能保留。 | | Sonatype Guide | 针对 AI 助手拦截用例最接近的竞争对手。闭源，服务支持，无离线模式，无透明判定引擎。 | | Chainguard + Cursor | 仅限 Cursor 内部的精选注册表。替换注册表而不是对其进行验证。 | | Datadog `scfw` | 针对已知恶意 npm/PyPI 的安装时拦截。PhantomDep 添加了 agent 时、幻觉/抢注检测以及 Cargo + Go。 | PhantomDep **不**替代 CVE 扫描仪。将其与 [OSV-Scanner](https://github.com/google/osv-scanner) 或 Dependabot 搭配使用以应对已知漏洞；PhantomDep 负责处理它们都遗漏的引入时拦截。 ## Phantom-DB 已确认的抢注垃圾包和已知恶意条目以 JSON 文件形式存在于 [`phantom-db/`](./phantom-db/) 中，基于 MIT 许可。Schema 在 [`phantom-db/SCHEMA.md`](./phantom-db/SCHEMA.md) 中。该数据集是公开的，因此任何工具都可以从中同步。 一个具有代表性的条目： ``` { "name": "huggingface-cli", "ecosystem": "pypi", "status": "squatted", "first_observed": "2024-02-13", "intended_target": "huggingface-hub[cli]", "did_you_mean": ["huggingface-hub"], "evidence_url": "https://www.lasso.security/blog/ai-package-hallucinations" } ``` 未注册的高频幻觉被故意不提交到这里——这相当于发布了攻击者的购物清单。它们存在于受限的研究层级中，仅作为汇总统计或仅在攻击者实际注册了该名称后发布。 数据集自动增长：验证器工作流每小时运行一次，在攻击者注册幻觉名称时将 `phantom` 提升为 `squatted`；馈送工作流每晚运行，为人工审核呈现候选幽灵包。 ## 安全性 请参阅 [SECURITY.md](./SECURITY.md)。请勿针对安全漏洞发布公开的 issue。 ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。

标签：AI安全, Chat Copilot, Rust, 依赖管理, 可视化界面, 开发安全, 网络流量审计, 通知系统