slowmist/MistEye-DepScan

# MistEye DepScan [中文版](README-CN.md) | [English](README.md) 一个极简依赖的 CLI 工具，通过调用 [MistEye](https://app.misteye.io/api-docs) 威胁情报 API 来扫描项目依赖和全局安装的包，以检测已知的恶意包和版本。 ## 隐私 ## 功能 - 极简的运行时依赖（Python 3.10+；在 3.10 中会自动安装 `tomli` 用于解析 `pyproject.toml`） - 简单的命令：`scan` / `global` / `check` - 多生态的 manifest 和 lock 文件解析：npm, PyPI, Rust, Go, RubyGems - 全局扫描支持系统 Python、Node 全局包 (npm/pnpm/yarn/nvm)、Rust `cargo install` 以及 Go `go install` 二进制文件 - 输出格式：终端表格 / JSON / SARIF - API 速率限制 (10 req/s) - 扫描时显示每个包的进度；使用 `-o` 保存完整报告 ## 安装 ``` git clone cd MisteyeDepscan python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . # 扫描当前项目 depscan scan . # 扫描全局安装的包（系统 Python、Node 全局包） depscan global ``` 在虚拟环境中安装后，只要激活了该 venv，就可以在该环境的 `bin` 目录（例如 `.venv/bin/depscan`）中使用 `depscan`。 ### 典型的 NVM 和 pnpm 路径 `depscan global` 会扫描 **npm -g**、**pnpm -g**、**yarn global** 以及位于 **nvm / fnm / volta** 版本目录下的包（不仅限于当前活动的 `npm root -g`）。 | 工具 | 典型根目录 | 已安装的 npm 包 | |------|--------------|------------------------| | **nvm** | `~/.nvm` (或 `$NVM_DIR`) | `~/.nvm/versions/node/v/lib/node_modules/` | | **pnpm global** | 因安装方式而异 | 运行 `pnpm root -g`；在 macOS 上通常是 `~/Library/pnpm`，在 Linux 上通常是 `~/.local/share/pnpm` | - 对于自定义的目录树，请使用 `depscan scan --depth 0`。 您也可以在不依赖 `PATH` 中的 `depscan` 的情况下运行： ``` python -m misteye_depscan scan . ``` ### 安装后找不到 `depscan`？ `pip install` 会创建 `depscan` 脚本，但其安装位置取决于您的 Python 和操作系统，并且可能不在 `PATH` 中。如果 pip 输出 `The script depscan is installed in '...' which is not on PATH`，请使用该路径，或者找到用户脚本目录： ``` python3 -m site --user-base # 脚本通常位于：

/bin ``` 要全局使用它，请将该 `bin` 目录添加到您的 shell 配置文件中（路径会因 Python 版本而异——请勿将 `3.10` 写死）： ``` export PATH="$(python3 -m site --user-base)/bin:$PATH" ``` 将其添加到 `~/.zshrc` 或 `~/.bashrc` 中，然后打开一个新的终端。对于开发环境而言，使用 venv（如上所述）仍然是最可靠的方法。 ### `depscan` 命令是在哪里定义的？ 注册于 [`pyproject.toml`](pyproject.toml)： ``` [project.scripts] depscan = "misteye_depscan.cli:main" ``` 安装时会生成一个 `depscan` 入口点，它会调用 [`src/misteye_depscan/cli.py`](src/misteye_depscan/cli.py) 中的 `main()`。模块入口为：[`src/misteye_depscan/__main__.py`](src/misteye_depscan/__main__.py)。 ## API Key 在 [app.misteye.io/api-keys](https://app.misteye.io/api-keys) 创建免费的 API key。 可以通过以下方式： ``` export MISTEYE_API_KEY="your-api-key" ``` 或者保存到配置文件中（必须是 `600` 权限模式）： ``` mkdir -p ~/.config/misteye printf '%s' "$MISTEYE_API_KEY" > ~/.config/misteye/api_key chmod 600 ~/.config/misteye/api_key ``` 首次在没有 key 的情况下进行交互式运行时，工具会提示您输入并保存一个。 ## 用法 ``` # 扫描当前项目 depscan scan . # 扫描特定项目 depscan scan /path/to/project # 扫描 Mac 系统级全局环境（默认） # - Python: Homebrew /usr/local / 系统 Framework 路径（不包括项目 .venv） # - Node: npm -g, pnpm -g, yarn global, nvm/fnm/volta 各版本全局包 depscan global # 仅限 Python 或 Node 全局包 depscan global --python-only depscan global --node-only # 检查单个包 depscan check requests==2.32.3 --pypi depscan check lodash@4.17.21 --npm # JSON / SARIF（适配 CI） depscan scan . --json depscan scan . --sarif depscan global --json # 将完整报告保存到文件 depscan scan . -o report.json depscan global -o global-report.json # 控制扫描深度（默认：10 层） depscan scan . --depth 20 # deeper depscan scan . --depth 1 # only root level depscan scan . --depth 0 # unlimited (full recursive) ``` ## 扫描结果与进度 每次扫描都会查询 MistEye API（无本地结果缓存）。这确保了绝不会漏掉新发现的威胁。 ### 进度输出 每个扫描完成的包都会打印一行（并发扫描；顺序可能与依赖列表不同）： ``` [1/120] requests==2.32.3 → No threat record [2/120] lodash@4.17.21 → No threat record [3/120] evil-pkg@1.0.0 → Threat detected · critical ``` API 的 `status: unknown` 会显示为 **No threat record**（绿色），而不是原始单词 `unknown`；但这**并不**意味着该包绝对安全。 保存完整报告：`depscan scan . -o report.json` 或 `depscan global -o global-report.json`。 静默模式：`--quiet`。禁用颜色：`depscan --no-color scan .` 或 `NO_COLOR=1`。 ## 生态系统（自动检测） 与 MistEye 保持一致：**npm**、**PyPI**、**Rust**、**Go** 和 **RubyGems** 会自动检测并扫描。 | 生态系统 | 标记文件 | 状态 | |-----------|--------------|--------| | **npm** | `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` | 支持 | | **PyPI** | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `Pipfile.lock`, `poetry.lock`, `uv.lock`, `setup.py`, `setup.cfg` | 支持 | | **Rust** | `Cargo.toml`, `Cargo.lock` (工作区优先使用根目录的 `Cargo.lock`) | 支持 | | **Go** | `go.mod`, `go.sum` (存在时优先使用 `go.sum`) | 支持 | | **RubyGems** | `Gemfile`, `Gemfile.lock` | 支持 | **自动检测规则** - 在项目树状结构下查找标记文件，跳过 `node_modules/`、`vendor/`、`.venv/`、`venv/`、`.tox/`、`site-packages/`、`dist/`、`build/` 等。 - 跳过这些目录仅影响**发现 manifest 的位置**；**`node_modules/` 下已安装的包仍会被扫描**（基于每个包的 `package.json`）。 **覆盖自动检测** ``` depscan scan . --ecosystem=npm depscan scan . --ecosystem=pypi depscan scan . --ecosystem=rust depscan scan . --ecosystem=go depscan scan . --ecosystem=rubygems depscan scan . --ecosystem=all depscan scan . --ecosystem=npm,pypi,rust,go,rubygems # default when omitted = auto-detect # 仅限 Manifest/lock（跳过 node_modules 已安装树） depscan scan . --no-node-modules ``` ## 支持的依赖文件 **默认（自动检测 npm / PyPI / Rust / Go / RubyGems）** - **PyPI**: `requirements*.txt`, `pyproject.toml` (PEP 621 + Poetry `[tool.poetry]` 包括 `group.*.dependencies`), `Pipfile`, `Pipfile.lock`, `poetry.lock`, `uv.lock`, `setup.py`, `setup.cfg` - **npm**: `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, 以及 `node_modules/**/package.json` - **Rust**: `Cargo.lock` (在工作区中首选；必要时回退到 `Cargo.toml`) - **Go**: `go.sum` (优先于同一模块的 `go.mod`) - **RubyGems**: `Gemfile` 和 `Gemfile.lock` ## API 响应 MistEye Detect API 使用 `status`： ``` { "status": "malicious", "matches": [...] } { "status": "unknown", "matches": [] } ``` | API `status` | 含义 | |---|---| | `malicious` | 匹配到已知的威胁情报 | | `unknown` | 数据库中无匹配项（显示为 **No threat record**；**并不**保证安全） | **退出码** | 代码 | 含义 | |------|---------| | 0 | 扫描完成；未发现恶意包（包含 `unknown` 项） | | 1 | 发现恶意包或版本 | | 2 | 扫描未完成 (API/网络/覆盖率问题) | | 3 | 配置错误（路径错误、缺少 API key） | PyPI 使用 `name==version`；npm 和其他生态系统在显示和 API 请求时均使用 `name@version`。跨生态系统的匹配（例如，针对 PyPI 扫描返回仅限 npm 的威胁指标）将被忽略，以避免因不同生态系统中存在同名包而导致的误报。 ## 参考 - MistEye API 文档：https://app.misteye.io/api-docs - MistEye API key：https://app.misteye.io/api-keys - MistEye Security Gate：https://github.com/slowmist/misteye-skills ## 许可证 MIT

标签：Python, 依赖扫描, 威胁情报, 开发者工具, 文档结构分析, 无后门, 模型提供商, 逆向工具