OreWatch

多生态恶意包检测与供应链安全扫描器

一款生产级安全工具，用于检测 npm、PyPI、Maven、RubyGems、Go 和 Cargo 生态系统中的恶意包与供应链威胁。利用从可信安全来源自动收集的威胁情报，识别项目中受感染的依赖项。

OreWatch 是产品及 PyPI 包名。当前源代码仓库路径仍使用 ore-mal-pkg-inspector。

视频

安装

https://github.com/rapticore/ore-mal-pkg-inspector/issues/2#issue-4215016110

OreWatch 与 Cursor

https://github.com/rapticore/ore-mal-pkg-inspector/issues/3#issue-4215017945

OreWatch 与 CodeX

https://github.com/rapticore/ore-mal-pkg-inspector/issues/4#issue-4215019385

OreWatch 与 Claude-Code

https://github.com/rapticore/ore-mal-pkg-inspector/issues/5#issue-4215021599

---

目录

• 问题
• 解决方案
• 主要特性
• 为什么选择 OreWatch？
• 从这里开始
• 快速入门
  • 前提条件
  • 安装
  • 首次扫描
• 用法
  • 基本命令
  • 高级用法
  • 命令行参考
  • 后台监控
• 采用指南
• 分发
  • macOS 受管部署
• 日志与调试
• 输出与报告
• CI/CD 集成
• 故障排除
• 常见问题
• 贡献
• 安全策略
• 路线图
• 许可证
• 支持
• 致谢

---

问题

供应链攻击已成为软件入侵的首要威胁向量。 仅 2024 年，就有数千个恶意包被发布到 npm、PyPI 及其他包注册表，通过拼写域名欺骗、依赖混淆以及 Shai-Hulud 等复杂恶意软件活动针对开发者。

挑战： 组织与开发者需要：

• 扫描跨多个编程生态系统的依赖项
• 持续跟进来自多个来源的快速演变的威胁情报
• 不仅检测已知恶意包，还要检测入侵指标（IoC）
• 将安全扫描集成到现有开发工作流中
• 快速响应新发现的威胁

缺口： 现有方案通常：

• 局限于单一生态系统（仅 npm、仅 PyPI 等）
• 依赖人工维护的威胁列表
• 缺乏 IoC 检测能力
• 难以集成到自动化管道
• 属于不透明的专有黑盒工具

---

解决方案

OreWatch 通过以下方式解决这些挑战：

全面的多生态系统覆盖： 单一工具支持 npm、PyPI、Maven、RubyGems、Go 和 Cargo 包

自动化威胁情报： 动态收集并合并来自可信安全研究来源的数据

主动 IoC 检测： 识别 Shai-Hulud 攻击模式及其他恶意代码指标，超越简单的包名匹配

CI/CD 就绪： 设计用于无缝集成到 GitHub Actions、GitLab CI、Jenkins 及其他自动化平台

开源透明： 检测逻辑、数据源和扫描方法完全可见

---

主要特性

多生态系统支持 扫描 npm、PyPI、Maven、RubyGems、Go 和 Cargo 包，并根据项目结构自动检测生态系统。

统一威胁情报数据库 根据动态收集的可信安全研究来源的恶意包数据库进行检查。

自动生态系统检测 根据目录结构、文件名智能识别生态系统，并可在单次运行中扫描多个生态系统。

入侵指标（IoC）检测 扫描 Shai-Hulud 攻击模式（原始及 2.0 变种）、恶意钩子、可疑工作流及已知载荷文件。

Shai-Hulud 集成 针对 OreNPMGuard 提供的全面 Shai-Hulud 受影响包列表交叉引用 npm 包。

结构化 JSON 报告 生成机器可读的 JSON 报告，包含显式的威胁数据元数据及 SARIF 风格的文件位置信息。

灵活输入格式 支持标准依赖文件（package.json、requirements.txt 等）及通用包列表（文本、JSON、YAML）。

生产级日志 通过 --verbose 和 --debug 标志可配置详细级别，用于故障排除和审计追踪。

安全且快速 只读操作，不修改代码，针对大型代码库高效扫描进行优化。

---

为什么选择 OreWatch？

对比单一生态系统工具 大多数安全扫描器专注于一个包管理器。OreWatch 为六个主要生态系统提供统一保护，对于现代多语言开发环境至关重要。

对比人工威胁列表 静态恶意包列表会迅速过时。我们的自动收集器每天从多个权威来源获取最新威胁情报。

对比仅包名检测 仅检查包名会遗漏复杂攻击。IoC 检测能够识别尚未列入黑名单的包中的恶意代码模式。

对比人工安全审计 人工依赖项审查耗时且易出错。自动化扫描可在每次构建中实现持续安全验证。

对比商业黑盒工具 专有工具缺乏检测逻辑的透明度。作为开源项目，每条检测规则和数据源均可审计。

诞生故事 OreWatch 源自 OreNPMGuard 的开发，后者是一款专门针对 Shai-Hulud npm 攻击的扫描器。在该项目期间，我们认识到需要更广泛的多生态系统覆盖能力。2025 年 12 月，我们将多生态系统检测能力提取并增强为独立的工具，保留了 OreNPMGuard 对 npm 的关注，同时使 OreWatch 能够服务于所有主要包生态系统的更广泛的开发者社区。

---

从这里开始

如果你是首次采用 OreWatch，请选择与你的工作流最匹配的最简路径：

我想...	使用此路径	从这开始
立即扫描一个仓库	CLI 扫描	orewatch /path/to/project
在后台保护本地开发	单例监控	orewatch monitor quickstart /path/to/project --client claude_code
从 Cursor、Claude Code 或 Codex 使用 OreWatch	MCP 桥接	`orewatch monitor quickstart /path/to/project --client <cursor
集成到 VS Code、PyCharm 或 Xcode	本地主机 API	orewatch monitor quickstart /path/to/project --client vscode
获取可见的 macOS 提醒和原生审查界面	菜单栏应用	orewatch monitor menubar
在 CI 中验证构建	一次性 CLI 扫描	orewatch . --strict-data

大多数开发者推荐的首运行序列：

1. 使用 pip install . 或已发布的包安装 OreWatch。
2. 运行 orewatch monitor quickstart /path/to/project --client <你的客户端>。
3. 使用 orewatch monitor status 验证守护进程。
4. 如果你在 macOS 上，启动 orewatch monitor menubar 以获取通知和本地界面。

如果你想要更短的设置指南及可复制粘贴的命令，请使用 docs/adoption-guide.md。

---

快速入门

前提条件

• Python 3.14 或更高版本
• pip 用于安装依赖项
• Git 用于克隆仓库
• 互联网连接 用于初始威胁情报设置
• OpenSSL 用于监控快照工作流中的签名快照密钥生成、发布和验证

安装

OreWatch 可通过 pipx（推荐）、Homebrew（macOS）、pip 或 源码 安装。所有方法均生成 orewatch CLI 命令。

选项 1 — pipx（推荐）

pipx 将 OreWatch 安装到其隔离环境中，同时使 orewatch 命令全局可用。这是大多数开发者的最佳选择。```bash

Install pipx if you don't have it

python3.14 -m pip install --user pipx python3.14 -m pipx ensurepath

Install OreWatch

pipx install --python python3.14 orewatch

If you want the macOS menu bar app on a fresh install, use this instead:

pipx install --python python3.14 'orewatch[mac-menubar]'

Verify

orewatch --help

Optional macOS menu bar app

orewatch monitor menubar

如果你已经通过 pipx 安装了 `orewatch`，并且之后想添加 macOS 菜单栏应用，请将 Cocoa 绑定注入到同一个 pipx 环境中：```bash
pipx inject orewatch pyobjc-framework-Cocoa

升级:```bash pipx upgrade orewatch

**卸载：**```bash
pipx uninstall orewatch

选项 2 — Homebrew (macOS)

对于偏好 Homebrew 管理的安装的 macOS 用户：```bash

Add the OreWatch tap

brew tap rapticore/tap

Install

brew install rapticore/tap/orewatch

Verify

orewatch --help

Optional macOS menu bar app

orewatch monitor menubar

**升级:**```bash
brew update && brew upgrade orewatch

卸载：```bash brew uninstall orewatch brew untap rapticore/tap # optional — removes the tap

> **注意：** Homebrew 配方包含了 `orewatch monitor menubar` 所需的 Cocoa 绑定。如果较旧的 Homebrew 安装报告 `ModuleNotFoundError: No module named 'AppKit'`，请运行 `brew update && brew reinstall rapticore/tap/orewatch`，以便配方重建其隔离的 Python 环境并支持菜单栏。

#### 选项 3 — pip

对于 CI 管道、Docker 镜像或自行管理虚拟环境（virtualenv）的情况，请使用 `pip`：```bash
# Install into an active Python 3.14 virtualenv or user site
python3.14 -m pip install orewatch

# Pin a version for reproducible CI builds
python3.14 -m pip install orewatch==1.3.0

# If you want the macOS menu bar app on a fresh install, use this instead:
# python3.14 -m pip install 'orewatch[mac-menubar]'

# Verify
orewatch --help

升级：```bash python3.14 -m pip install --upgrade orewatch

#### 选项 4 — 源码检出（贡献者）```bash
# Clone the repository
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector

# Create and activate a Python 3.14 virtual environment (recommended)
python3.14 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode for development
python -m pip install -e .

# Verify
orewatch --help

安装后验证

使用任意方法安装后，确认 OreWatch 正在运行：```bash

Check the CLI is accessible

orewatch --help

List supported manifest filenames

orewatch --list-supported-files

Run a quick scan on the current directory

orewatch .

#### 平台说明

| 平台 | Python 来源 | 备注 |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | 推荐 Homebrew 用户使用 |
| **macOS** (pyenv) | `pyenv install 3.14` | 适合多版本管理 |
| **Ubuntu / Debian** | `sudo apt install python3.14` 或 pyenv | 请确认你的发行版提供了 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` 或 pyenv | — |
| **Windows (WSL)** | pyenv 或系统包 | 原生 Windows 未经测试 |

> **需要 Python 3.14。** OreWatch 使用了 Python 3.14 引入的语言特性。旧版本在导入时会失败。

#### 安装故障排除