rapticore/ore-mal-pkg-inspector

# OreWatch **多生态恶意包检测与供应链安全扫描器**     这是一款生产级安全工具，用于检测 npm、PyPI、Maven、RubyGems、Go 和 Cargo 生态系统中的恶意包及供应链威胁。它利用来自可信安全源的自动化威胁情报收集，来识别您项目中的受损依赖。 `OreWatch` 是产品名称和 PyPI 包名。当前的源仓库路径仍然使用 `ore-mal-pkg-inspector`。 ## 目录 - [存在的问题](#the-problem) - [解决方案](#the-solution) - [核心特性](#key-features) - [为什么选择 OreWatch？](#why-orewatch) - [快速开始](#quick-start) - [前置条件](#prerequisites) - [安装说明](#installation) - [首次扫描](#first-scan) - [用法](#usage) - [基本命令](#basic-commands) - [高级用法](#advanced-usage) - [命令行参考](#command-line-reference) - [后台监控](#background-monitoring) - [分发](#distribution) - [日志与调试](#logging--debugging) - [输出与报告](#output--reports) - [CI/CD 集成](#cicd-integration) - [故障排除](#troubleshooting) - [常见问题解答](#faq) - [贡献指南](#contributing) - [安全政策](#security-policy) - [路线图](#roadmap) - [许可证](#license) - [支持](#support) - [致谢](#acknowledgments) ## 存在的问题 **供应链攻击现已成为软件受损的主要威胁途径。** 仅在 2024 年，就有成千上万个恶意包被发布到 npm、PyPI 和其他包注册中心，通过拼写抢注、依赖混淆以及像 Shai-Hulud 这样复杂的恶意软件活动来攻击开发者。 **挑战所在：** 组织和开发者需要： - 扫描跨多个编程生态系统的依赖 - 紧跟来自多个来源且快速演变的威胁情报 - 不仅检测已知的恶意包，还要检测失陷指标 - 将安全扫描集成到现有的开发工作流中 - 对新发现的威胁做出快速响应 **差距所在：** 现有的解决方案通常： - 局限于单一生态系统（仅限 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 包，并能根据项目结构自动检测生态系统。 **统一的威胁情报数据库** 与动态收集的、来自可信安全研究来源的恶意包数据库进行比对核查。 **自动生态系统检测** 智能地从目录结构、文件名中识别生态系统，并能在单次运行中扫描多个生态系统。 **失陷指标 检测** 扫描 Shai-Hulud 攻击模式（原始变体和 2.0 变体）、恶意钩子、可疑工作流以及已知的 payload 文件。 **Shai-Hulud 集成** 根据来自 OreNPMGuard 的综合 Shai-Hulud 受影响包列表，对 npm 包进行交叉比对核查。 **结构化 JSON 报告** 生成机器可读的 JSON 报告，其中包含明确的威胁数据元数据以及针对发现问题的 SARIF 风格文件位置信息。 **灵活的输入格式** 支持标准依赖文件（package.json、requirements.txt 等）和通用包列表（文本、JSON、YAML）。 **生产级日志记录** 可通过 `--verbose` 和 `--debug` 标志配置详细级别，用于故障排除和审计追踪。 **安全且快速** 只读操作，不对您的代码进行任何修改，并针对大型代码库的高效扫描进行了优化。 ## 为什么选择 OreWatch？ **对比单生态系统工具** 大多数安全扫描器只关注一个包管理器。OreWatch 为六大主流生态系统提供了统一保护，这对于现代多语言开发环境至关重要。 **对比手动威胁列表** 静态的恶意包列表很快就会过时。我们的自动化收集器每天从多个权威来源获取最新的威胁情报。 **对比仅包名检测** 仅仅检查包名无法发现复杂的攻击。IoC 检测甚至能在包尚未被列入黑名单时识别出恶意代码模式。 **对比手动安全审计** 手动依赖审查既耗时又容易出错。自动化扫描能够在每次构建中实现持续的安全验证。 **对比商业黑盒工具** 专有工具在检测逻辑上缺乏透明度。作为一个开源项目，每一条检测规则和数据源都是可审计的。 **起源故事** OreWatch 诞生于 [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) 的开发过程中，后者是一款专门针对 Shai-Hulud npm 攻击的扫描器。在那个项目期间，我们认识到需要将多生态系统覆盖扩展到 npm 之外。2025 年 12 月，我们将多生态系统检测能力提取并增强到了这款独立工具中，在保持 OreNPMGuard 专注于 npm 的同时，让 OreWatch 能够在所有主要包生态系统中服务于更广泛的开发者社区。 ## 快速开始 ### 前置条件 - **Python 3.14 或更高版本** - **pip**，用于安装依赖 - **Git**，用于克隆仓库 - **互联网连接**，用于初始威胁情报设置 - **OpenSSL**，用于在监控快照工作流中签名、发布和验证快照密钥 ### 安装说明 ``` # 克隆仓库 git clone https://github.com/rapticore/ore-mal-pkg-inspector.git cd ore-mal-pkg-inspector # 创建并激活虚拟环境（推荐） python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # 安装项目及其 CLI 入口 pip install . ``` _注意：威胁情报数据会在首次扫描时自动收集。核心来源默认启用；实验性来源采用选择启用机制。_ _注意：以上命令是通过源代码签出来安装项目的。这是目前的开发和贡献者路径。关于面向最终用户和 CI 的推荐发布模式，请参阅[分发](#distribution)。_ _已安装的 CLI：_ `orewatch` _兼容别名：_ `ore-mal-pkg-inspector` ### 首次扫描 **扫描项目目录：** ``` # 自动检测生态系统并扫描当前目录 orewatch . # 扫描指定项目路径 orewatch /path/to/your/project # 使用详细输出查看进度 orewatch /path/to/your/project --verbose ``` **预期输出：** ``` Detected multiple ecosystems: npm, pypi Scanning all detected ecosystems... Scanning npm... Found 2 dependency file(s) for npm Parsing: package.json Parsing: package-lock.json Scanning pypi... Found 1 dependency file(s) for pypi Parsing: requirements.txt Extracted 45 unique package(s) across 2 ecosystem(s) Checking 45 package(s) against malicious databases... Checking 30 npm package(s)... Checking 15 pypi package(s)... Scanning for Indicators of Compromise... Generating report... ============================================================ SCAN REPORT SUMMARY ============================================================ Ecosystem: npm, pypi Total Packages Scanned: 45 Malicious Packages Found: 0 IoCs Found: 0 ✅ No malicious packages or IoCs detected Full report saved to: scan-output/malicious_packages_report_20251231_120000.json ============================================================ ``` ## 用法 ### 基本命令 **扫描目录（自动检测生态系统）：** ``` # 当前目录 orewatch . # 特定目录 orewatch /home/user/projects/my-app # 使用绝对路径 orewatch ~/projects/backend-api ``` **扫描特定依赖文件：** ``` # 根据文件名自动检测生态系统 orewatch --file package.json orewatch --file requirements.txt orewatch --file pom.xml orewatch --file Gemfile orewatch --file go.mod orewatch --file Cargo.toml ``` **强制指定生态系统：** ``` # 覆盖自动检测 orewatch /path/to/project --ecosystem npm orewatch /path/to/project --ecosystem pypi orewatch /path/to/project --ecosystem maven orewatch /path/to/project --ecosystem rubygems orewatch /path/to/project --ecosystem go orewatch /path/to/project --ecosystem cargo ``` **扫描通用包列表：** ``` # 文本文件（每行一个包） - 必须指定生态系统 orewatch --file packages.txt --ecosystem pypi # 包含 package 数组的 JSON 文件 orewatch --file packages.json --ecosystem npm # YAML 文件 orewatch --file packages.yaml --ecosystem npm ``` ### 高级用法 **自定义输出路径：** ``` # 保存到自定义位置 orewatch /path/to/project --output /tmp/scan_report.json # 保存到特定子目录 orewatch /path/to/project --output reports/security/$(date +%Y%m%d).json ``` **IoC 扫描控制：** ``` # 完整扫描（packages + IoCs） - 默认行为 orewatch /path/to/project # 跳过 IoC 扫描以进行更快的仅包检查 orewatch /path/to/project --no-ioc # 仅扫描 IoC，跳过包数据库检查 orewatch /path/to/project --ioc-only ``` **静默模式：** ``` # 生成报告但不显示控制台摘要（适用于脚本） orewatch /path/to/project --no-summary ``` **威胁数据控制：** ``` # 强制在扫描前完全刷新默认核心源 orewatch /path/to/project --latest-data # 如果请求的任何生态系统仅有部分或缺失威胁数据，则判定为失败 orewatch /path/to/project --strict-data # 在收集期间包含实验性来源 orewatch /path/to/project --latest-data --include-experimental-sources # 打印扫描器识别的确切依赖文件名 orewatch --list-supported-files ``` **批量扫描：** ``` # 扫描多个项目 for dir in ~/projects/*/; do echo "Scanning $dir" orewatch "$dir" --output "reports/$(basename $dir).json" done ``` ### 命令行参考 #### 扫描器选项 | 选项 | 短选项 | 描述 | 默认值 | |--------|-------|-------------|---------| | `--file` | `-f` | 要扫描的特定文件路径（跳过目录检测） | 无 | | `--ecosystem` | `-e` | 强制指定生态系统：`npm`、`pypi`、`maven`、`rubygems`、`go`、`cargo` | 自动检测 | | `--output` | `-o` | JSON 报告的自定义输出路径 | `scan-output/malicious_packages_report_{timestamp}.json` | | `--no-summary` | | 跳过向控制台打印报告摘要 | False | | `--no-ioc` | | 跳过 IoC（失陷指标）扫描 | False | | `--ioc-only` | | 仅扫描 IoC，跳过包检查 | False | | `--latest-data` | | 在扫描前强制重新收集和重建威胁情报 | False | | `--strict-data` | | 如果请求的任何生态系统存在部分或缺失的威胁数据，则判定为失败 | False | | `--include-experimental-sources` | | 在威胁数据刷新期间包含实验性收集器 | False | | `--list-supported-files` | | 打印确切支持的依赖清单文件名并退出 | False | | `--verbose` | `-v` | 显示 INFO 级别日志（进度消息） | False | | `--debug` | | 显示 DEBUG 级别日志（详细诊断信息） | False | ### 后台监控 该仓库现在包含一个本地后台监控器，它可以保持威胁数据最新，监视已选择加入的项目以检测清单和工作流更改，运行防抖扫描，并记录新发现或风险升级的通知。监控器拥有的配置和状态存储在用户拥有的目录中的仓库外部，因此克隆的仓库无法预先植入监控行为。 **初始化并检查监控器：** ``` orewatch monitor install orewatch monitor install --service-manager launchd --no-start orewatch monitor status orewatch monitor doctor ``` **管理受监视的项目：** ``` orewatch monitor watch add /path/to/project orewatch monitor watch list orewatch monitor watch remove /path/to/project ``` **运行服务：** ``` # 后台 orewatch monitor start orewatch monitor restart orewatch monitor stop orewatch monitor uninstall # 前台 orewatch monitor run ``` **手动监控操作：** ``` # 触发所有受监视项目的立即扫描 orewatch monitor scan-now # 仅触发一个受监视项目 orewatch monitor scan-now /path/to/project # 生成签名密钥对 orewatch monitor snapshot keygen /tmp/ore-keys # 构建并应用本地 threat-data 快照 orewatch monitor snapshot build /tmp/ore-snapshot \ --private-key /tmp/ore-keys/snapshot_signing_private.pem \ --public-key /tmp/ore-keys/snapshot_signing_public.pem orewatch monitor snapshot apply /tmp/ore-snapshot/manifest.json \ --public-key /tmp/ore-keys/snapshot_signing_public.pem # 发布托管的快照通道 orewatch monitor snapshot publish /tmp/ore-snapshots \ --base-url https://example.com/ore-snapshots \ --channel stable \ --private-key /tmp/ore-keys/snapshot_signing_private.pem \ --public-key /tmp/ore-keys/snapshot_signing_public.pem ``` **监控器行为：** - 快速扫描以包为重点，按计划以及在常规清单更改后运行。 - 完整扫描包括 IoC 检测，在夜间、手动请求时，以及在工作流或 payload 文件更改后运行。 - 在 Linux 上，配置默认位于 `~/.config/orewatch/instances//`，状态默认位于 `~/.local/state/orewatch/instances//`。 - 在 macOS 上，配置默认位于 `~/Library/Application Support/OreWatch/instances//`，状态默认位于 `~/Library/Application Support/OreWatch/State/instances//`。 - `monitor doctor` 会为当前仓库实例打印确切的 `config_path`、`state_db`、`log_file` 和服务模板目录。 - 特定项目的策略覆盖可以存储在项目根目录下的 `.ore-monitor.yml` 中。 - `monitor install` 现在会在可用时安装用户级别的 `launchd` 或 `systemd` 服务，否则回退到仓库本地的后台模式。 - 托管更新使用在用户拥有的监控器配置文件中通过 `snapshots.channel_url` 或 `snapshots.manifest_url` 配置的签名通道描述符或清单，监控器使用 `snapshots.public_key_path` 对其进行验证。 - 签名快照工作流目前要求本地机器上安装有 `openssl`。 ## 分发 该项目现在具有两个不同的分发面： 1. **CLI 和监控器代码** 2. **监控器所使用的威胁数据快照** 它们应该被分开分发。 ### 推荐的包分发方式 **最适合开发者的默认选项：** 将扫描器作为普通的 Python 包发布到 PyPI，并推荐使用 `pipx` 安装。 为什么这是最合适的选择： - 该项目是一个 Python CLI 和后台监控器，因此通用 wheel 加上源码分发是最直接的发布产物。 - `pipx` 为开发者提供了一个隔离的、用户级别的安装，而不会污染项目虚拟环境。 - CI 仍然可以使用 `pip install orewatch==` 安装相同版本。 - 这保持了 CLI 升级路径的简单性，同时将威胁数据更新留给签名的快照通道。 **推荐的发布形态：** - 将 `sdist` 和通用 wheel 产物发布到 PyPI。 - 暴露 `orewatch` 控制台入口点。 - 保留 `ore-mal-pkg-inspector` 作为临时的兼容性别名。 - 文档中对于本地开发者安装推荐使用 `pipx install orewatch`。 - 文档中对于 CI 和固定自动化推荐使用 `pip install orewatch==`。 **推荐的次要渠道：** 仅在 PyPI 包和控制台入口点稳定之后才添加 Homebrew formula。Homebrew 是一个便利层，而不是主要的发布产物。 **对贡献者的最佳选择：** 保留当前的源码签出流程： ``` git clone https://github.com/rapticore/ore-mal-pkg-inspector.git cd ore-mal-pkg-inspector python3 -m venv .venv source .venv/bin/activate pip install -e . ``` ### 推荐的快照分发方式 威胁数据快照不应打包在 Python 包内。它们的变化节奏不同，并且已经作为签名的托管工件受到支持。 **最佳默认选项：** 将带版本的签名快照发布到静态 HTTPS 托管服务，并让客户端独立刷新它们。 推荐的托管目标： - GitHub Releases 资产 - 位于 HTTPS 后面的 S3 或 Cloudflare R2 - 任何提供不可变的版本化文件的、由 CDN 支持的静态存储桶 推荐的快照布局： - `versions/<>/manifest.json` - `versions//*.db` - `channels/stable.json` 推荐的信任模型： - 保持私钥离线 - 仅随客户端配置或包发布公共验证密钥 - 在下载/应用之前验证每一个通道描述符和清单 ### 推荐的总体模型 对于生产发布，最清晰的设置是： - 将应用程序作为 PyPI 包分发 - 使用 `pipx` 进行本地安装 - 使用 `pip` 在 CI 中安装 - 通过 HTTPS 以签名快照通道的形式分发威胁数据 - 将源码签出作为开发路径，而不是主要的最终用户安装方式 ## 日志与调试 默认情况下，扫描器仅显示警告、错误和最终摘要。如需进行故障排除或详细的进度跟踪，请使用日志标志： ### 详细模式 **查看进度消息和收集统计数据：** ``` orewatch /path/to/project --verbose ``` **输出包含：** - 生态系统检测结果 - 文件解析进度 - 包提取计数 - 数据库查询详情 - IoC 扫描进度 **示例：** ``` INFO: Detected ecosystems: npm, pypi INFO: Loaded database for npm: 15234 malicious packages INFO: Loaded database for pypi: 8421 malicious packages INFO: Extracted 45 packages from 3 files INFO: Checking 30 npm packages against database... INFO: Checking 15 pypi packages against database... INFO: IoC scan complete: 0 indicators found ``` ### 调试模式 **查看用于故障排除的详细诊断信息：** ``` orewatch /path/to/project --debug ``` **输出包含：** - 所有 INFO 级别的消息 - 正在扫描的文件路径 - SQL 查询执行详情 - 哈希计算 - 模式匹配结果 - 内部状态信息 **适用场景：** - 调查为什么某个包未被检测到 - 调试生态系统自动检测问题 - 带有详细上下文地报告问题 - 审计扫描器行为 ### 收集器的日志记录 威胁情报收集器同样支持详细和调试模式： ``` cd collectors # 查看收集进度 python3 orchestrator.py --verbose # 调试数据源问题 python3 orchestrator.py --debug ``` **注意：** 所有日志都输出到 stderr，保持 stdout 干净以输出 JSON 报告。这使得可以将扫描器结果通过管道传递给其他工具，而不会受到日志消息的干扰。 ## 输出与报告 ### 报告结构 报告默认保存在 `scan-output/` 目录中（或通过 `--output` 指定自定义路径）。默认的报告格式为项目特定的 JSON。它包含威胁数据可用性元数据，并对包发现结果使用 SARIF 风格的 `physicalLocation` 对象，但它不是一个完整的 SARIF 2.1.0 文档。 **示例报告：** ``` { "scan_timestamp": "2025-12-31T12:00:00Z", "ecosystem": "npm", "scanned_path": "/path/to/project", "total_packages_scanned": 150, "data_status": "complete", "sources_used": ["openssf", "osv"], "experimental_sources_used": [], "missing_ecosystems": [], "malicious_packages_found": 2, "iocs_found": 3, "malicious_packages": [ { "name": "malicious-pkg", "version": "1.0.0", "severity": "critical", "sources": ["threat-intel-db", "research-community"], "description": "Malicious code executes unauthorized operations", "detected_behaviors": ["malicious_code", "data_exfiltration"] } ], "iocs": [ { "type": "malicious_bundle_js", "path": "node_modules/suspect-pkg/bundle.js", "hash": "46faab8ab153fae6e80e7cca38eab363075bb524edd79e42269217a083628f09", "severity": "CRITICAL", "variant": "original", "description": "Known malicious payload file from Shai-Hulud attack" }, { "type": "malicious_postinstall", "path": "package.json", "pattern": "node bundle.js", "severity": "CRITICAL", "variant": "original", "description": "Malicious postinstall hook executes payload" } ] } ``` **威胁数据字段：** - `data_status`：`complete`、`partial`、`failed` 或 `not_applicable` - `sources_used`：为请求的生态系统提供了可用威胁数据的来源 - `experimental_sources_used`：包含在扫描数据中的实验性来源 - `missing_ecosystems`：没有可用的包威胁数据库的请求生态系统 ### 理解结果 **严重级别：** - **CRITICAL（严重）：** 带有活跃漏洞利用或数据外泄的已知恶意代码 - **HIGH（高危）：** 强烈的恶意意图或拼写抢注指标 - **MEDIUM（中危）：** 可疑模式或潜在漏洞 - **LOW（低危）：** 轻微问题或信息性发现 **建议操作：** 1. **严重/高危发现：** 立即移除受影响的包并调查影响 2. **审查 IoC：** 检查恶意代码是否已执行（日志、网络活动） 3. **更新依赖：** 用合法的替代品替换恶意包 4. **再次扫描：** 通过后续扫描验证修复情况 5. **报告：** 考虑向包注册中心维护者报告 ## CI/CD 集成 ### GitHub Actions **基本安全扫描：** ``` name: Security Scan - Malicious Packages on: [push, pull_request] jobs: malicious-package-scan: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.14' - name: Install OreWatch run: | git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner cd scanner pip install . - name: Scan for malicious packages run: | cd scanner orewatch ${{ github.workspace }} --latest-data - name: Upload scan report uses: actions/upload-artifact@v4 if: always() with: name: security-scan-report path: scanner/scan-output/ ``` **检测到威胁时判定失败的高级配置：** ``` - name: Scan and fail on malicious packages run: | cd scanner orewatch ${{ github.workspace }} --latest-data --output report.json # Check if malicious packages were found MALICIOUS_COUNT=$(jq '.malicious_packages_found' report.json) IOC_COUNT=$(jq '.iocs_found' report.json) if [ "$MALICIOUS_COUNT" -gt 0 ] || [ "$IOC_COUNT" -gt 0 ]; then echo "🚨 SECURITY ALERT: Malicious packages or IoCs detected!" echo "Malicious packages: $MALICIOUS_COUNT" echo "IoCs found: $IOC_COUNT" exit 1 fi ``` ### GitLab CI ``` malicious-package-scan: image: python:3.14 stage: security before_script: - git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner - cd scanner && pip install . script: - orewatch $CI_PROJECT_DIR --latest-data --strict-data --output scan-report.json artifacts: paths: - scan-report.json when: always allow_failure: false ``` ### Jenkins 流水线 ``` pipeline { agent any stages { stage('Setup Scanner') { steps { sh ''' git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner cd scanner python3 -m pip install . ''' } } stage('Security Scan') { steps { sh ''' cd scanner orewatch ${WORKSPACE} --latest-data ''' } } } post { always { archiveArtifacts artifacts: 'scanner/scan-output/*.json', fingerprint: true } } } ``` ### 预提交钩子 添加到 `.git/hooks/pre-commit`： ``` #!/bin/bash echo "Running malicious package scan..." cd /path/to/ore-mal-pkg-inspector orewatch $PROJECT_DIR --no-summary if [ $? -ne 0 ]; then echo "❌ Malicious packages or IoCs detected! Commit blocked." echo "Review the scan report in scan-output/" exit 1 fi echo "✅ Security scan passed" ``` ## 故障排除 ### 常见问题 #### “未找到数据库”错误 **现象：** ``` ERROR: No usable threat data available for requested ecosystems: npm ``` **原因：** 威胁数据收集失败、元数据不完整，或者请求的生态系统尚未有可用的本地数据库。 **解决方案：** ``` # 强制重新收集并要求请求的生态系统具有完整结果 orewatch /path/to/project --latest-data --strict-data ``` **注意：** 如果这种情况仍然存在，请检查网络连接、文件系统权限，以及您是否故意请求了实验性来源。 #### “未检测到包”警告 **现象：** ``` WARNING: No packages detected in /path/to/project ``` **可能的原因和解决方案：** 1. **目录错误：** 确保您正在扫描正确的项目目录 ls /path/to/project # 验证 package.json 或 requirements.txt 是否存在 2. **不支持或意外的清单：** 打印确切支持的文件名 orewatch --list-supported-files 3. **文件权限：** 确保文件是可读的 ls -la /path/to/project/package.json #### 更新期间出现连接错误 **现象：** ``` ERROR: Error downloading npm: ``` **解决方案：** 1. **检查互联网连接：** ping google.com 2. **增加超时时间重试：** 编辑 `collectors/config.yaml`： osv: timeout: 600 # 从默认的 300 增加 3. **使用缓存数据：** 如果您之前已经下载过数据： python3 orchestrator.py --skip-build # 跳过下载，从缓存重建 #### 权限拒绝错误 **现象：** ``` ERROR: Error creating directory collectors/raw-data: Permission denied ``` **解决方案：** ``` # 确保正确的所有权 sudo chown -R $USER:$USER /path/to/ore-mal-pkg-inspector # 或从用户可写位置运行 cd ~/ git clone https://github.com/rapticore/ore-mal-pkg-inspector.git cd ore-mal-pkg-inspector ``` #### 误报 **现象：** 正常的包被标记为恶意包。 **步骤：** 1. **验证发现：** 审查报告详情，包括严重性和描述 2. **检查版本：** 被标记的版本可能是特定的： orewatch /path/to/project --verbose 3. **报告误报：** 如果确认是不正确的： - 访问 https://github.com/rapticore/ore-mal-pkg-inspector/issues 并附带详情提交 issue #### 用于调查的调试模式 **启用详细日志记录：** ``` # Scanner 调试模式 orewatch /path/to/project --debug 2> debug.log # Collector 调试模式 cd collectors python3 orchestrator.py --debug 2> collector-debug.log ``` **审查日志：** 检查 `debug.log` 以获取详细的执行跟踪信息，包括： - 扫描的文件路径 - 执行的 SQL 查询 - 模式匹配结果 - 错误堆栈跟踪 ## 常见问题解答 ### 我应该多久更新一次威胁情报？ **建议：** - **生产/CI 环境：** 每日自动更新 - **开发工作站：** 最低每周更新 - **安全新闻发布后：** 在宣布新威胁时立即更新 恶意包会不断被发布。每日更新可确保提供最新的保护。 ### 如何更新威胁情报数据？ 使用 `--latest-data` 标志运行扫描器以强制更新： ``` orewatch /path/to/project --latest-data ``` 如需在 CI/CD 中进行自动更新，请安排带有 `--latest-data` 标志的定期扫描（例如每天）。仅当您明确希望将 Phylum 派生的数据包含在重建中时，才添加 `--include-experimental-sources`。 **注意：** 首次扫描会自动收集数据，因此手动更新仅用于刷新现有数据库。 ### 威胁数据来源于何处？ 默认数据库由项目的**核心威胁来源**构建： - `openssf` - `osv` 扫描器还可以包含项目的**实验性**来源集： - `phylum` （需使用 `--include-experimental-sources`） `socketdev` 在仓库中作为一个禁用的占位符存在，不属于默认的收集路径。 有关数据源、收集和处理的技术细节，请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。 ### 这个工具会修改我的代码或依赖吗？ **不会。** OreWatch 执行的是只读操作。它会： - ✅ 读取依赖文件 - ✅ 查询威胁数据库 - ✅ 扫描文件模式 - ✅ 生成报告 它**绝对不会**： - ❌ 修改包文件 - ❌ 安装或移除包 - ❌ 更改项目配置 - ❌ 执行包代码 ### 如果我的包被标记为恶意包怎么办？ **应采取的步骤：** 1. **验证发现：** 检查报告以获取详细信息和严重性 2. **审查证据：** 检查描述和检测到的行为 3. **检查版本：** 确定是否有特定版本受到影响 4. **如果是合法的：** - 向数据源维护者报告误报 - 在我们的 GitHub 上附带详细信息提交 issue 5. **如果确实是恶意的：** - 立即移除该包 - 审查最近的代码提交以查找损害 - 检查日志以寻找可疑活动 - 更新到安全的替代方案 ### 我可以离线使用吗？ **部分可以。** **离线扫描：** ✅ 可以，前提是数据库已初始化 ``` # 在线：初始设置（一次性 - 首次扫描时自动运行） orewatch /path/to/project # 离线：后续扫描使用本地数据库 orewatch /path/to/project ``` **离线更新：** ❌ 不行，威胁情报收集需要访问互联网以从安全来源获取数据。 **物理隔离环境：** 您可以： 1. 在连接互联网的机器上下载数据库 2. 将 `collectors/final-data/*.db` 文件传输到隔离环境中 3. 使用可能过期的数据离线运行扫描 ### 这与 npm audit 或 pip-audit 相比如何？ **用途不同：** **npm audit / pip-audit：** - 专注于已知的 CVE 漏洞 - 根据咨询数据库检查包版本 - 由包注册中心团队维护 **OreWatch：** - 专注于恶意包（而不仅仅是有漏洞的包） - 检测拼写抢注、恶意软件、供应链攻击 - 跨生态系统覆盖 - 针对活跃威胁的 IoC 检测 **最佳实践：** **同时**使用两者： ``` # 检查漏洞 npm audit pip-audit # 检查恶意包 orewatch /path/to/project ``` ### 这支持私有包注册中心吗？ **依赖扫描：** ✅ 支持，无论包来自何处，扫描器都会读取您的依赖文件。 **威胁情报：** ⚠️ 有限。我们的数据库涵盖公共注册中心（npmjs.com、pypi.org 等）。除非您添加自定义威胁数据，否则无法检测到私有注册中心上的恶意包。 **自定义威胁数据：** 您可以使用自己的恶意包列表扩展数据库。请与我们联系以获取有关此高级用例的指导。 ### 性能影响是什么？ **扫描时间：** - **小型项目**（少于 50 个包）：少于 5 秒 - **中型项目**（50-500 个包）：5-30 秒 - **大型项目**（500 个以上的包）：30-120 秒 **影响因素：** - IoC 扫描会增加 10-50% 的开销（如果不需要，可使用 `--no-ioc` 禁用） - 首次运行可能会比较慢，因为数据库需要加载到内存中 **优化提示：** ``` # 扫描特定文件而非整个目录 orewatch --file package.json ``` ## 贡献指南 我们欢迎您的贡献！无论您是在报告错误、提出功能建议还是贡献代码，您的帮助都在为所有人改善 OreWatch。 **报告错误或请求功能：** - GitHub Issues：https://github.com/rapticore/ore-mal-pkg-inspector/issues **贡献代码：** - 有关开发设置、代码风格、测试和拉取请求流程的详细指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) **问题或讨论：** - GitHub Discussions：https://github.com/rapticore/ore-mal-pkg-inspector/discussions ## 安全政策 安全是我们的首要任务。OreWatch 是一款安全工具，我们非常严肃地对待漏洞问题。 ### 报告安全漏洞 **请勿为安全漏洞开启公开的 GitHub issue。** 请通过以下方式私下报告： **电子邮件：** security@rapticore.com **请包含：** - 漏洞描述 - 重现步骤 - 潜在影响 - 建议的修复方案（如果有） - 您的联系方式以便后续跟进 ### 响应时间表 - **确认：** 48 小时内 - **初步评估：** 7 天内 - **修复时间表：** 视严重程度而定 - Critical（严重）：7-14 天 - High（高危）：14-30 天 - Medium/Low（中/低危）：30-60 天 ### 安全最佳实践 使用 OreWatch 时： **应该：** - ✅ 以最低权限运行（不需要 root/admin 权限） - ✅ 定期更新威胁情报 - ✅ 及时审查扫描报告 - ✅ 集成到 CI/CD 中以实现持续保护 - ✅ 保持工具更新到最新版本 **不应该：** - ❌ 未经调查就忽略扫描发现 - ❌ 在生产环境中禁用 IoC 扫描 - ❌ 共享来自不可信来源的数据库文件 - ❌ 不必要地使用提升的权限运行 ### 漏洞披露 我们遵循协同披露原则： 1. 私下报告漏洞 2. 开发并测试修复方案 3. 发布安全咨询 4. 修复方案可用后公开披露 ### 安全名人堂 我们感谢负责任地披露漏洞的安全研究人员： *名单将随着报告的接收而维护* ### 社区请求 投票或建议功能： - **GitHub Discussions：** https://github.com/rapticore/ore-mal-pkg-inspector/discussions - **Feature Requests：** https://github.com/rapticore/ore-mal-pkg-inspector/issues ### 为路线做贡献 我们根据以下因素确定功能的优先级： - 安全影响 - 社区需求 - 维护可持续性 - 与项目目标的一致性 要影响路线图： 1. 提交带有详细用例的功能请求 2. 参与讨论 3. 贡献实现（欢迎提交 PR！） ## 许可证 MIT License Copyright (c) 2025 Rapticore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## 支持 ### 获取帮助 **文档：** 您正在阅读它！大多数问题都可以从这里开始寻找答案。 **GitHub Discussions：** 用于提问、交流和社区互动： - https://github.com/rapticore/ore-mal-pkg-inspector/discussions **GitHub Issues：** 用于错误报告和功能请求： - https://github.com/rapticore/ore-mal-pkg-inspector/issues **电子邮件：** 用于安全漏洞和私下咨询： - contact@rapticore.com ### 专业支持 对于有如下需求的组织： - 定制集成 - SLA 保障的支持 - 私有化部署协助 - 定制威胁情报订阅 联系方式：contact@rapticore.com ## 致谢 ### 项目起源 本项目从 [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) 仓库中提取，旨在保持项目关注点清晰的同时扩展其功能。 **OreNPMGuard**（2025 年 12 月）专门针对 Shai-Hulud npm 攻击检测，涵盖了 738 个以上的受影响包并具有深度的 IoC 分析能力。在其开发过程中，我们意识到了更广泛的多生态系统保护需求，从而促成了 OreWatch 这款独立工具的诞生，旨在为所有主要包生态系统中更广泛的开发者社区提供服务。 ### 相关项目 - **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - 专门的 Shai-Hulud npm 扫描器 **用 ❤️ 为开源社区构建** *一次一次扫描，保护软件供应链安全。*

标签：Cargo, DevSecOps, Go, Homebrew安装, LNA, Maven, npm, PyPI, Python, RubyGems, Ruby工具, typo squatting, 上游代理, 依赖安全分析, 依赖混淆, 包管理器安全, 威胁情报, 安全合规, 安全扫描工具, 安全测试工具, 开发安全, 开发者工具, 开源生态安全, 文档安全, 文档结构分析, 无后门, 漏洞验证, 网络代理, 网络安全, 自动化安全扫描, 逆向工具, 隐私保护