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 統合
• トラブルシューティング
• FAQ
• コントリビューション
• セキュリティポリシー
• ロードマップ
• ライセンス
• サポート
• 謝辞

問題

サプライチェーン攻撃は今やソフトウェア侵害の主要な脅威ベクターです。 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 パッケージをスキャンし、プロジェクト構造から自動的にエコシステムを検出します。

統合脅威インテリジェンスデータベース 信頼できるセキュリティ研究ソースから動的に収集された悪意パッケージデータベースと照合します。

自動エコシステム検出 ディレクトリ構造、ファイル名からインテリジェントにエコシステムを特定し、1 回の実行で複数のエコシステムをスキャン可能。

侵害指標 (IoC) 検出 Shai-Hulud 攻撃パターン (オリジナルおよび 2.0 亜種)、悪意フック、不審なワークフロー、既知のペイロードファイルをスキャンします。

Shai-Hulud 統合 OreNPMGuard の包括的な Shai-Hulud 影響パッケージリストと npm パッケージを相互参照します。

構造化 JSON レポート 脅威データメタデータと SARIF スタイルのファイル位置を含む、機械可読な JSON レポートを生成します。

柔軟な入力形式 標準の依存関係ファイル (package.json、requirements.txt など) と汎用パッケージリスト (テキスト、JSON、YAML) をサポートします。

プロダクション対応のログ出力 --verbose および --debug フラグで設定可能な詳細レベル、トラブルシューティングと監査証跡に対応。

安全で高速 コードを変更しない読み取り専用操作。大規模コードベースの効率的なスキャンに最適化。

OreWatch を選ぶ理由

vs. 単一エコシステムツール ほとんどのセキュリティスキャナーは 1 つのパッケージマネージャに焦点を当てています。OreWatch は 6 つの主要エコシステムにわたる統合保護を提供し、現代のポリグロット開発環境に不可欠です。

vs. 手動脅威リスト 静的な悪意パッケージリストはすぐに古くなります。自動化コレクターが複数の信頼できるソースから毎日新鮮な脅威インテリジェンスを取得します。

vs. パッケージ名のみの検出 パッケージ名のチェックだけでは高度な攻撃を見逃します。IoC 検出はブロックリストにまだないパッケージでも悪意コードパターンを識別します。

vs. 手動セキュリティ監査 手動の依存関係レビューは時間がかかりエラーが発生しやすいです。自動スキャンにより、すべてのビルドで継続的なセキュリティ検証が可能になります。

vs. 商用ブラックボックスツール プロプライエタリツールは検出ロジックの透明性に欠けます。オープンソースプロジェクトとして、すべての検出ルールとデータソースが監査可能です。

誕生の背景 OreWatch は OreNPMGuard の開発から生まれました。これは Shai-Hulud npm 攻撃に特化したスキャナーです。そのプロジェクトにおいて、npm を超えたより広範なマルチエコシステムカバレッジの必要性を認識しました。2025 年 12 月、マルチエコシステム検出機能をこのスタンドアロンツールに抽出・強化し、OreNPMGuard の npm への焦点を維持しつつ、OreWatch がすべての主要パッケージエコシステムにわたるより広い開発者コミュニティにサービスを提供できるようにしました。

ここから始める

初めて OreWatch を導入する場合、ワークフローに最も適した最小のパスを選んでください:

ほとんどの開発者におすすめの初回実行シーケンス:

1. pip install . または公開パッケージで OreWatch をインストールします。
2. orewatch monitor quickstart /path/to/project --client <your-client> を実行します。
3. orewatch monitor status でデーモンを確認します。
4. macOS を使用している場合、通知とローカル UI のために 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

If you already installed `orewatch` with pipx and want to add the macOS menu bar app later, inject the Cocoa bindings into the same pipx environment:```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のFormulaには、`orewatch monitor menubar`が必要とするCocoaバインディングが含まれています。古いHomebrewのインストールで`ModuleNotFoundError: No module named 'AppKit'`と表示される場合は、`brew update && brew reinstall rapticore/tap/orewatch`を実行して、Formulaがメニューバーサポート付きで隔離されたPython環境を再構築するようにしてください。

#### オプション 3 — pip

CIパイプライン、Dockerイメージ、または独自の仮想環境を管理する場合は、`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 で導入された言語機能を使用します。古いバージョンではインポート時に失敗します。

#### インストールのトラブルシューティング

| 症状 | 修正方法 |
|---|---|
| `command not found: orewatch` | インストール先が `PATH` に含まれていることを確認してください。pipx の場合: `pipx ensurepath` を実行してシェルを再起動してください。 |
| `ModuleNotFoundError` on import | 複数の Python バージョンが存在する可能性があります。`orewatch` の背後にあるランタイムが Python 3.14+ であることを確認し、対応するインタプリタで再インストールしてください。 |
| pipx install がリゾルバエラーで失敗する | pipx をアップグレード: `python3.14 -m pip install --upgrade pipx` |
| Homebrew でインストール後に `orewatch` が見つからない | 最初に `brew tap rapticore/tap` を実行し、その後インストールを再試行してください。 |
| pip install 中に Permission denied | `pip install --user orewatch` を使用するか、virtualenv 内にインストールしてください。 |

_注: ローカルの脅威データが欠落または古い場合、パッケージスキャンはライブアップデート候補をステージングし、異常ゲートを通過した後にのみ昇格します。候補が疑わしい場合、OreWatch は最後に既知の良好なデータセットを保持します。_

_インストール済み CLI:_ `orewatch`
_互換性エイリアス:_ `ore-mal-pkg-inspector`

### 初回スキャン

**プロジェクトディレクトリをスキャン:**```bash
# Auto-detect ecosystem and scan current directory
orewatch .

# Scan specific project path
orewatch /path/to/your/project

# With verbose output to see progress
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

HTML report saved to: scan-output/malicious_packages_report_20251231_120000.html JSON report saved to: scan-output/malicious_packages_report_20251231_120000.json

If you want OreWatch to keep watching the project after this first scan, continue with [Background Monitoring](#background-monitoring) or jump straight to [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/adoption-guide.md).

---

## 使い方

### 基本コマンド

**ディレクトリのスキャン（エコシステム自動検出）:**```bash
# Current directory
orewatch .

# Specific directory
orewatch /home/user/projects/my-app

# With an absolute path
orewatch /home/user/projects/backend-api

特定の依存関係ファイルをスキャンする:```bash

Ecosystem auto-detected from filename

orewatch --file package.json orewatch --file requirements.txt orewatch --file pom.xml orewatch --file Gemfile orewatch --file go.mod orewatch --file Cargo.toml

**特定エコシステムの強制:**```bash
# Override auto-detection
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

汎用パッケージリストのスキャン：```bash

Text file (one package per line) - must specify ecosystem

orewatch --file packages.txt --ecosystem pypi

JSON file with package array

orewatch --file packages.json --ecosystem npm

YAML file

orewatch --file packages.yaml --ecosystem npm

### 高度な使用法

**カスタム出力パス:**```bash
# Save to custom location
orewatch /path/to/project --output /tmp/scan_report.json

# Save to specific subdirectory
orewatch /path/to/project --output reports/security/$(date +%Y%m%d).json

IoC Scanning Control:```bash

Full scan (packages + IoCs) - default behavior

orewatch /path/to/project

Skip IoC scanning for faster package-only checks

orewatch /path/to/project --no-ioc

Only scan for IoCs, skip package database checking

orewatch /path/to/project --ioc-only

**静音モード:**```bash
# Generate report without console summary (useful for scripts)
orewatch /path/to/project --no-summary

脅威データコントロール：```bash

Force a staged live refresh of the default core sources before scanning

orewatch /path/to/project --latest-data

Fail if any requested ecosystem only has partial or missing threat data

orewatch /path/to/project --strict-data

Include experimental sources during collection

orewatch /path/to/project --latest-data --include-experimental-sources

Print the exact dependency filenames the scanner recognizes

orewatch --list-supported-files

**バッチスキャン:**```bash
# Scan multiple projects
for dir in ~/projects/*/; do
    echo "Scanning $dir"
    orewatch "$dir" --output "reports/$(basename $dir).json"
done

コマンドラインリファレンス

スキャンオプション

バックグラウンドモニタリング

このリポジトリには、脅威データを最新に保ち、オプトインしたプロジェクトのマニフェストとワークフローの変更を監視し、デバウンス処理されたスキャンを実行し、新規または重要度が上がった発見に対する通知を記録するローカルバックグラウンドモニタが含まれています。モニタが所有する設定と状態は、リポジトリ外のユーザー所有ディレクトリに保存されるため、クローンされたリポジトリがモニタの動作を事前設定することはできません。

OreWatchは現在、モニタをユーザーごとのシングルトンとして扱います。1つのデーモンでディスク上の多くのプロジェクトを監視し、多数の同時接続クライアント（Claude Code、Codex、Cursor、VS Code、JetBrains / PyCharm、Xcode）にサービスを提供できます。

エンドツーエンドのモニタ設定

1. シングルトンモニタのインストールとブートストラップ```bash

First project + first client

orewatch monitor quickstart /path/to/project --client claude_code

`monitor quickstart` は推奨される初回実行フローです。これにより：

- シングルトンモニターサービスのインストールまたは更新
- 必要に応じてモニターを起動
- 対象プロジェクトをウォッチリストに追加
- 選択したクライアントのブートストラップブロックを出力

先にモニターをインストールし、後からクライアントを設定する場合は：```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

2. モニターが正常であることを確認する```bash orewatch monitor status orewatch monitor connection-info orewatch monitor doctor

Use these commands for slightly different jobs:

- `monitor status` は、シングルトンのデーモンとAPIが実行中かどうかを表示します
- `monitor connection-info` は、ループバックAPIのURL、トークンパス、モニターホーム、およびサポートされているブートストラップクライアントを表示します
- `monitor doctor` は、正確な設定、状態データベース、ログ、および共有脅威データのパスを表示します

**3. シングルトンに監視させたいすべてのプロジェクトを追加する**```bash
orewatch monitor watch add /path/to/project-a
orewatch monitor watch add /path/to/project-b
orewatch monitor watch list
orewatch monitor watch remove /path/to/project-b

1つのOreWatchデーモンで、これらのプロジェクトすべてを同時に監視できます。リポジトリごとやIDEワークスペースごとに個別のモニターを用意する必要はありません。

クライアント統合レシピ

OreWatchは2つの統合トランスポートをサポートしています:

ブートストラップコマンドは以下のいずれかの形状を出力します:```json { "mcpServers": { "orewatch": { "command": "/absolute/path/to/orewatch", "args": [ "monitor", "mcp" ] } } }

`orewatch monitor ide-bootstrap --client <client>` がローカルのコンソールスクリプトを解決できる場合、現在はその絶対パスを出力し、ベアの `orewatch` は出力しません。古いMCP設定でまだ `"command": "orewatch"` と記述されている場合は、再生成して古いエントリを置き換えてください。```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Cursor, Claude Code, and Codex

これらのクライアントはすべて同じローカルMCPブリッジを使用します:```bash orewatch monitor mcp

Recommended setup:

1. `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` を一度実行します。
2. 表示されたMCPブロックを、対応するMCPクライアントにコピーします。
3. そのクライアントで監視対象のプロジェクトを開きます。
4. クライアントがMCP経由でOreWatchを呼び出すようにします。具体的には以下の操作です：
   - `orewatch_health`
   - `orewatch_check_dependency_add`
   - `orewatch_check_manifest`
   - `orewatch_override_dependency_add`
   - `orewatch_list_active_findings`
   - `orewatch_list_notifications`

Notes:

- `monitor mcp` は stdio サーバーです。手動で起動した場合、MCP クライアントが接続するまでアイドル状態で表示されます。
- MCP ブリッジは起動時にローカル API をチェックし、`auto_start_on_client` が有効な場合、シングルトンモニターを自動起動できます。
- IDE の起動を確実にするには、`monitor install` でバックグラウンドモニターを一度インストールし、MCP ブリッジが起動する前にデーモンが利用可能になるようにしてください。

##### VS Code

VS Code の統合では、MCP ブリッジではなく、シングルトンの localhost API を使用する必要があります。

Recommended setup:

1. `orewatch monitor quickstart /path/to/project --client vscode` を実行します。
2. `orewatch monitor ide-bootstrap --client vscode` から `baseUrl` と `tokenPath` をコピーします。
3. それらの値をローカルの VS Code 拡張機能、タスク、またはヘルパーに設定します。
4. 依存関係追加、マニフェスト保存、アラート更新のイベントでAPIを呼び出します。

VS Code 統合での推奨API使用法:

- パッケージマネージャーのインストール/追加フローの前に `POST /v1/check/dependency-add` を呼び出す
- サポートされているマニフェストが保存されたとき、または明示的に再チェックするときに `POST /v1/check/manifest` を呼び出す
- `GET /v1/findings/active` と `GET /v1/notifications` をポーリングして、バックグラウンドで検出された結果を表示する

##### JetBrains / PyCharm

JetBrains および PyCharm は、VS Code と同じ localhost API コントラクトを使用します。

Recommended setup:

1. `orewatch monitor quickstart /path/to/project --client jetbrains` を実行します。
2. `orewatch monitor ide-bootstrap --client jetbrains` から API ブロックをコピーします。
3. 返された `baseUrl` と `tokenPath` を JetBrains プラグイン、外部ツール、またはローカルヘルパーで使用します。
4. 同期型の依存関係判定と、保存されたバックグラウンドアラートの両方を IDE 内に表示します。

JetBrains 統合での推奨API使用法:

- `POST /v1/check/dependency-add` で依存関係の追加をチェックする
- `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` および関連するサポート対象マニフェストを `POST /v1/check/manifest` で再チェックする
- `GET /v1/findings/active` と `GET /v1/notifications` を取得して、永続的なアラートパネルやツールウィンドウに表示する

##### Xcode

Xcode の統合でもシングルトンの localhost API を使用する必要がありますが、重要なスコープの境界があります。OreWatch は現在、`Package.resolved`、`Podfile.lock`、`Cartfile` などのネイティブ Apple 依存関係マニフェストを解析しません。現在、Xcode 統合は以下の用途に最適です:

- ヘルパー、スクリプト、またはコンパニオンアプリでのバックグラウンド検出結果と通知の表示
- Xcode で開かれた、`package.json`、`pyproject.toml`、`Cargo.toml` などのサポート対象マニフェストも含む複数言語のリポジトリ
- Xcode で作業中に macOS メニューバーアプリと通知センターアラートを利用したいチーム

Recommended setup:

1. `orewatch monitor quickstart /path/to/project --client xcode` を実行します。
2. `orewatch monitor ide-bootstrap --client xcode` から API ブロックをコピーします。
3. 返された `baseUrl` と `tokenPath` をビルドフェーズスクリプト、ヘルパープロセス、またはカスタム Xcode 統合で使用します。
4. `GET /v1/findings/active` と `GET /v1/notifications` をポーリングして、ユーザーに表示するアラートを取得します。
5. Xcode ワークスペースにサポート対象の非 Apple マニフェストが含まれている場合は、ワークフローの一部としてそれらのファイルに対して `POST /v1/check/manifest` を呼び出します。

現在の統合状況:

- Claude Code、Codex、Cursor: このリポジトリに含まれるファーストクラスの MCP ブリッジ
- VS Code: ローカル API コントラクトは文書化されているが、公式拡張機能はまだバンドルされていない
- JetBrains / PyCharm: ローカル API コントラクトは文書化されているが、公式プラグインはまだバンドルされていない
- Xcode: ローカル API とメニューバー統合は文書化されているが、公式 Xcode 拡張機能はなく、ネイティブ Apple マニフェストパーサーもまだない

#### OreWatch が何かを検出した場合

バックグラウンドモニターが監視対象プロジェクト内で侵害されたパッケージまたはIoCを検出すると、OreWatch は以下を実行します:

- シングルトンモニターの `reports/` ディレクトリにモニター管理の JSON および HTML レポートを書き込む
- アクティブな検出結果をモニター状態 DB に保存する
- アクション可能なメッセージを含む通知エントリを保存する
- 端末通知が有効な場合、端末に警告を表示する
- macOS では、シングルトンメニューバーアプリが動作している場合、それをポップアップチャネルとして優先する
- 最新の注目すべきアラートをメニューバードロップダウンの上部に固定し、素早く確認できるようにする
- それ以外の場合、デスクトップ通知が有効であれば、ベストエフォートで直接デスクトップ通知を送信する
- リモート環境やヘッドレス環境向けに、オプションの Webhook 通知を送信できる

組み込みのCLIレビュー画面を使用して、これらのアラートを確認できます:```bash
orewatch monitor findings
orewatch monitor findings --project /path/to/project --min-severity high
orewatch monitor notifications
orewatch monitor notifications --project /path/to/project
orewatch monitor package-updates
orewatch monitor package-updates --check

The local API and MCP bridge expose the same data for IDEs and agents:

• API:
  • GET /v1/findings/active
  • GET /v1/notifications
  • GET /v1/package-updates
  • POST /v1/package-updates/check
• MCP:
  • orewatch_list_active_findings
  • orewatch_list_notifications
  • orewatch_list_package_updates
  • orewatch_check_package_updates

これは、元のスキャン完了後にバックグラウンド検出結果を表示するための、IDE、MCPクライアント、コーディングエージェント向けのサポートパスです。

パッケージ更新アドバイザリは通知のみです。OreWatchは、監視対象プロジェクトの依存関係とOreWatch自体の新しいバージョンを報告しますが、マニフェスト、ロックファイル、インストール済みパッケージを変更することはありません。

ネイティブmacOSメニューバーアプリ

OreWatchには、CLIコマンド、MCPポーリング、ベストエフォートのNotification Centerポップアップだけに依存するのではなく、可視的なローカルUIを求めるユーザーのために、macOSネイティブのメニューバーアプリが含まれるようになりました。

オプションのCocoaバインディングを、orewatch コマンドを提供する同じランタイムにインストールします。インストール方法に応じたコマンドを選択してください。```bash

pip / source-checkout install

python3.14 -m pip install 'orewatch[mac-menubar]'

existing pipx install

pipx inject orewatch pyobjc-framework-Cocoa

Homebrew install

brew install rapticore/tap/orewatch

次に、メニューバーアプリを起動してください：```bash
orewatch monitor menubar

デフォルトでは、monitor menubarはバックグラウンドでアプリを再起動し、すぐにシェルプロンプトを返します。デバッグのために明示的にターミナルにアタッチしたい場合のみ、orewatch monitor menubar --foregroundを使用してください。

メニューバーアプリは、同じシングルトンモニターにアタッチします。2つ目のモニターインスタンスを開始することはありません。モニターがまだインストールおよび実行されていない場合、アプリは初回起動時にインストール/起動します。

HomebrewはCocoaバインディングをOreWatchの隔離されたlibexec環境にインストールします。orewatch monitor menubarがNo module named 'AppKit'を報告した場合は、brew update && brew reinstall rapticore/tap/orewatchでフォーミュラを更新してください。pip、pipx、およびソースインストールの場合、オプションのバインディングは、orewatchコマンドを提供する同じPython環境に追加する必要があります。

macOSでデスクトップ通知が有効な場合、シングルトンウォッチャーは1つのシングルトンメニューバーアプリを起動し続け、それをプライマリポップアップサーフェスとして使用します。これにより、デーモンからの切り離されたosascript呼び出しだけに依存することを避け、新しい検出結果に対する永続的なネイティブUIを提供します。

現在のメニューバービルドはアイコンファーストです。古いOWの省略形や以前のOreWatchアイコンの表現はレガシー参照として扱うべきです。アプリはバンドルされたブランドアイコンを優先し、macOSが画像をレンダリングできない場合やアラート数を表示する必要がある場合にのみ、コンパクトなテキストやバッジにフォールバックします。

macOSのメニューバーアプリが提供するものは次のとおりです。

• バンドルされたブランドアイコンを優先し、必要に応じてコンパクトなテキストフォールバックまたはアラートバッジを備えた永続的なメニューバーステータスアイテム
• 新たに検出されたアラートに対するコンパクトな赤/太字のアラート状態。メニューを開くまで表示されたままになります
• アクティブな検出結果と最高重要度のライブサマリー
• プロジェクトの依存関係の更新、OreWatchの自己更新状態、最終チェックステータス、コピー可能な推奨コマンドを含むファーストクラスのパッケージ更新セクション
• ネイティブのドロップダウンメニューでの最近の通知
• 新しく保存されたモニターアラートのネイティブ通知センターポップアップ
• プロジェクトをシングルトンウォッチャーに登録し、初期クイックスキャンを実行するワークスペースフォルダを追加...アクション
• デスクトップ通知、ターミナル通知、メニューバーキープアライブ、メニューバー駆動のポップアップ用の組み込み設定トグル
• レポート、モニターホーム、モニターログを開くためのワンクリックアクション
• モニター設定ファイルと設定フォルダを開くためのワンクリックアクション
• パッケージ更新の確認、脅威インテリジェンスの更新、クイック/フルスキャンの実行、シングルトンモニターの開始/再起動/停止を行うメニューアクション

推奨されるMacフロー:

1. 一度 orewatch monitor quickstart /path/to/project --client claude_code を実行します。
2. orewatch と同じ環境にオプションのバインディングをインストールします。
3. orewatch monitor menubar を起動します。
4. IDEsやコーディングエージェントがMCPまたはローカルAPIを使用し続けている間、メニューバーアプリを実行したままにして、永続的なネイティブレビューサーフェスを維持します。

導入ガイド

より簡単に展開するには、README全体を最初から最後まで読む代わりに、焦点を絞ったドキュメントを使用してください：

• docs/adoption-guide.md: ローカル開発者向けの最短パス
• docs/local-api.md: 正確なローカルホストAPIおよびMCPコントラクト
• docs/e2e-testing.md: コントリビューターおよび検証ワークフロー

推奨される導入順序:

1. 1つのリポジトリと1人のユーザーから始めます。
2. monitor quickstart でシングルトンモニターを有効にします。
3. 1つのクライアント（Cursor、Claude Code、Codex、VS Code、PyCharm、またはXcode）を接続します。
4. orewatch monitor findings および orewatch monitor notifications に検出結果が表示されることを確認します。
5. macOSでは、ユーザーが永続的なレビューサーフェスとポップアップ配信を得られるように monitor menubar を追加します。
6. ローカル導入が安定したら、CIスキャンとオプションのwebhookを追加します。

日常業務

一般的な運用コマンド:```bash

Background service lifecycle

orewatch monitor start orewatch monitor restart orewatch monitor stop orewatch monitor uninstall

Run the daemon in the foreground

orewatch monitor run

Launch the native macOS menu bar UI

orewatch monitor menubar

Trigger immediate scans

orewatch monitor scan-now orewatch monitor scan-now /path/to/project

Review detections and alerts

orewatch monitor findings orewatch monitor notifications

Reclaim disk space — prune accumulated backup manifests and orphaned staging

orewatch monitor cleanup orewatch monitor cleanup --keep-backups 5 --staging-max-age-seconds 3600

**手動スナップショットと署名アクション:**```bash
# Generate a signing keypair
orewatch monitor snapshot keygen /tmp/ore-keys

# Build and apply local threat-data snapshots
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

# Publish a hosted snapshot channel
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検出を含み、毎晩、手動リクエスト時、およびワークフローやペイロードファイルの変更後に実行されます。
• Linuxでは、設定のデフォルトは~/.config/orewatch/singleton/、状態のデフォルトは~/.local/state/orewatch/singleton/です。
• macOSでは、設定のデフォルトは~/Library/Application Support/OreWatch/singleton/、状態のデフォルトは~/Library/Application Support/OreWatch/State/singleton/です。
• 共有脅威データは、singleton状態ディレクトリのthreat-data/final-data/に置かれるようになりました。
• monitor doctorは、singletonモニターの正確なconfig_path、state_db、log_file、final_data_dir、およびサービス・テンプレート・ディレクトリを出力します。
• プロジェクトごとのポリシーオーバーライドは、プロジェクトルートの.ore-monitor.ymlに保存できます。
• monitor installは、利用可能な場合はユーザーレベルのまたはサービスをインストールし、それ以外の場合はローカルバックグラウンドモードにフォールバックします。

ローカル統合インターフェース:

• OreWatchは、モニターデーモンが実行中の場合、デフォルトで127.0.0.1:48736上のローカルホストのみのAPIを公開します。
• APIは、モニター設定ディレクトリのapi.tokenに保存され、所有者のみの権限を持つユーザーごとのベアラートークンを使用します。
• Authorization: Bearer <token>なしで127.0.0.1:48736に直接リクエストすると、正しく401 Unauthorizedが返ります。
• エージェントおよびIDEクライアントは、パスを推測するのではなく、orewatch monitor connection-infoを介してモニターを検出し、依存関係チェックリクエスト内で実際に操作しているproject_pathを送信する必要があります。
• Claude Code、Codex、Cursorは、バンドルされているMCPブリッジを使用できます。このブリッジは、orewatch_health、orewatch_check_dependency_add、orewatch_check_manifest、orewatch_override_dependency_add、orewatch_list_active_findings、orewatch_list_notifications、、を公開します。

オプションの異常検知ゲート付きライブアップデート設定:```yaml live_updates: enabled: true mode: gated bootstrap_from_live: true block_on_core_source_failure: false max_drop_ratio: 0.40 max_drop_absolute: 200 max_removal_ratio: 0.25 max_removal_absolute: 100 warn_growth_ratio: 5.0 warn_growth_absolute: 2000

主な動作:
- ライブ候補はまずステージングエリアで構築され、収集中にアクティブなデータベースを上書きしません。
- 大幅な減少、エコシステムの退行、空のエコシステム、大量削除はプロモーションをブロックします。
- コアソースの停止は、オープンソースのライブリフレッシュではデフォルトで警告のみです。エコシステムレベルの減少と削除は依然として不正なプロモーションをブロックします。
- 警告のみの異常はステータスとレポートに記録されますが、プロモーションを妨げません。
- 却下された候補は、既存のものが存在する場合、最後に正常と確認されたデータセットをアクティブに保ちます。
- ライブフィードからの初回ブートストラップは、少なくとも1つのコアソースが成功し、候補が使用可能なエコシステムデータを生成する場合に許可されます。

**オプションの通知Webhook設定:**```yaml
notifications:
  desktop: true
  terminal: true
  webhook_url: https://hooks.example.com/orewatch
  webhook_format: generic
  webhook_timeout_ms: 5000
  webhook_headers:
    Authorization: Bearer change-me

Slack の受信 Webhook を対象とする場合は、webhook_format: slack を設定します。このモードでは、OreWatch はシンプルな text ペイロードを送信します。

配布

このプロジェクトには、2 つの異なる配布対象があります:

1. CLI とモニターコード
2. モニターが消費する脅威データスナップショット

これらは別々に配布されるべきです。

推奨パッケージ配布方法

開発者にとっての最良のデフォルト: スキャナーを通常の Python パッケージとして PyPI に公開し、pipx でのインストールを推奨します。

これが最適な理由:

• プロジェクトは Python CLI とバックグラウンドモニターであるため、ユニバーサル wheel とソース配布が最も直接的なリリースアーティファクトです。
• pipx は、プロジェクトの仮想環境を汚染することなく、開発者に分離されたユーザーレベルのインストールを提供します。
• CI でも同じバージョンを python3.14 -m pip install orewatch==<version> でインストールできます。
• これにより、CLI のアップグレードパスをシンプルに保ちつつ、脅威データの更新は署名済みスナップショットチャネルに委ねられます。

推奨リリース形態:

• sdist とユニバーサル wheel アーティファクトを PyPI に公開します。
• orewatch コンソールエントリポイントを公開します。
• ore-mal-pkg-inspector を一時的な互換性エイリアスとして保持します。
• ローカル開発者のインストールのために、pipx install --python python3.14 orewatch を文書化します。
• CI および固定自動化のために、python3.14 -m pip install orewatch==<version> を文書化します。

利用可能なセカンダリチャネル: Brew 管理のインストールを好む macOS ユーザー向けに、Homebrew tap が利用可能になりました:```bash brew install rapticore/tap/orewatch

Homebrewは公開されたPyPIリリースに対する便利なラッパー層であり、主要なリリース成果物ではありません。

**寄稿者にとって最良の選択肢:** 現在のソースチェックアウトフローを維持すること:```bash
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

管理されたmacOSの展開

Kandji、Jamf Pro、Intune、Munki、またはその他のmacOSソフトウェア配信システムでOreWatchを展開する場合、推奨モデルは開発者向けの pipx パスとは異なります。

現在の製品の実情:

• 現在、このリポジトリはPythonパッケージを提供しており、ファーストパーティ製の公証済みmacOSインストーラパッケージではありません。
• 管理対象のフリート向けには、公開されたOreWatch wheelをベースに構築された署名済みのフラット .pkg が推奨アーティファクトです。
• 脅威データスナップショットは、アプリ/ランタイムパッケージとは別に配布する必要があります。

推奨されるエンタープライズ展開モデル:

1. デバイスインストール
   • 署名済みの .pkg を展開し、OreWatchランタイムと安定版の orewatch CLIシムをインストールします。
   • 管理対象のMacでネイティブメニューバーアプリが必要な場合は、オプションで mac-menubar 拡張機能を含めます。
2. ユーザーアクティベーション
   • orewatch monitor quickstart /path/to/project --client <client> または同等のユーザーコンテキストブートストラップを実行します。
   • OreWatchのモニターは意図的にユーザーごとであり、ユーザーのLaunchAgentとユーザー所有の設定/トークン/状態を使用するため、この手順は分離されています。
3. 継続的な更新
   • 通常のソフトウェアライフサイクルでランタイムパッケージを更新します。
   • 署名済みスナップショットチャネルまたはライブアップデートパスを通じて、脅威データスナップショットを独立して更新します。

なぜこの分割が重要なのか:

• MDMツールはコードをマシンにインストールするのが得意です。
• OreWatchのモニター、APIトークン、launchdサービスはユーザースコープであるため、マシンスコープのパッケージインストールから強制されるのではなく、ログインユーザーコンテキストで作成されるべきです。

管理対象macOS向けの推奨パッケージ形状:

• /Library/Application Support/OreWatch/runtime のような安定したパスにある専用ランタイム。
• /usr/local/bin/orewatch のような安定したシム。
• MDMプラットフォームがアップグレードをクリーンに検出できるように、バージョン管理されたパッケージメタデータ。
• コード署名、およびフリートポリシーが期待する場合は公証。

ベンダー固有のガイダンス:

• Kandji
  • インストーラパッケージ (.pkg) を使用したカスタムアプリを使用します。
  • OreWatchのランタイムはドラッグアンドドロップアプリではないため、 .dmg や .zip よりも .pkg を推奨します。
  • 初回モニターアクティベーションには、Self Serviceまたはユーザー向けのオンボーディング手順を使用します。
• Jamf Pro
  • .pkg をパッケージとしてアップロードし、ポリシーまたはSelf Serviceで展開します。
  • 意図的なユーザーコンテキストブートストラップ手順がない限り、ユーザーアクティベーションはマシンパッケージ展開から分離してください。
• Microsoft Intune
  • 署名済み .pkg を使用してmacOS LOBアプリを使用します。
  • Intuneは他のチャネルよりも厳格で、実際の .pkg であり、Developer ID Installer 証明書で署名され、ペイロードを含む必要があります。
• Munki
  • .pkg とパッケージメタデータを公開し、OreWatchを他の管理対象macOSソフトウェアと同様に扱います。
  • Munkiは、パッケージリポジトリとオプションのSelf Service形式の採用を希望する場合に適しています。
• その他のシステム
  • 通常のmacOSフラットパッケージを展開し、オプションでユーザーブートストラップ手順を実行できるパッケージ配信システムは、OreWatchを扱うことができます。

より完全な展開プレイブックについては、docs/managed-rollout.md を参照してください。

推奨スナップショット配信

脅威データスナップショットはPythonパッケージ内にバンドルすべきではありません。これらは異なる周期で変更され、署名済みホストアーティファクトとしてすでにサポートされています。

オープンソース/コミュニティデフォルト: 異常ゲート付きライブアップデートパスを通じて openssf と osv を直接消費します。 エンタープライズデフォルト: バージョン管理された署名済みスナップショットを静的HTTPSホスティングに公開し、クライアントが独立して更新できるようにします。

推奨ホスティングターゲット:

• GitHub Releasesのアセット
• HTTPS下のS3またはCloudflare R2
• 不変のバージョン管理ファイルを提供する静的CDN対応バケット

推奨スナップショットレイアウト:

• versions/<version>/manifest.json
• versions/<version>/*.db
• channels/stable.json

推奨信頼モデル:

• 秘密署名キーはオフラインで保管します。
• 公開検証キーのみをクライアント設定またはパッケージと共に配布します。
• ダウンロード/適用前に、すべてのチャネル記述子とマニフェストを検証します。

推奨全体モデル

プロダクションリリースでは、最もクリーンな設定は次のとおりです。

• アプリケーションをPyPIパッケージとして配布します。
• ローカルでは pipx でインストールします。
• CIでは pip でインストールします。
• 脅威データをHTTPS経由で署名済みスナップショットチャネルとして配布します。
• ソースチェックアウトは開発パスとして扱い、主要なエンドユーザーインストールとしては扱いません。

ログ記録とデバッグ

デフォルトでは、スキャナーは警告、エラー、および最終サマリーのみを表示します。トラブルシューティングや詳細な進捗追跡には、ログフラグを使用してください。

詳細モード

進捗メッセージと収集統計を表示:```bash 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

デバッグモード

トラブルシューティングのための詳細な診断情報を確認する:```bash orewatch /path/to/project --debug

**出力内容:**
- すべてのINFOレベルのメッセージ
- スキャン対象のファイルパス
- SQLクエリ実行の詳細
- ハッシュ計算
- パターンマッチング結果
- 内部状態情報

**使用例:**
- パッケージが検出されなかった理由の調査
- エコシステム自動検出の問題のデバッグ
- 詳細なコンテキストを含む問題の報告
- スキャナの動作の監査

### コレクターのログ出力

脅威インテリジェンスコレクターは、verboseモードとdebugモードもサポートしています:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

# Debug data source issues
python3 orchestrator.py --debug

注記: すべてのログはstderrに出力され、stdoutはJSONレポート出力用にクリーンな状態が保たれます。これにより、ログメッセージの干渉なしにスキャン結果を他のツールにパイプで渡すことができます。

出力とレポート

レポートの構造

レポートはデフォルトでscan-output/ディレクトリ（または--outputでカスタムパス）に保存されます。OreWatchは、機械可読なJSONレポートと、同じベースネームを持つスタイル付きHTMLコンパニオンレポートを書き込みます。JSONアーティファクトには脅威データの可用性メタデータが含まれ、パッケージ検出結果にはSARIFスタイルのphysicalLocationオブジェクトを使用しますが、完全なSARIF 2.1.0ドキュメントではありません。

レポート例:```json { "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`: 有効なパッケージ脅威データベースが存在しなかった要求エコシステム
- `promotion_decision`: 既存データスキャンの場合は空、それ以外は`promoted`、`bootstrapped`、または`rejected`
- `kept_last_known_good`: ライブ候補が拒否されたが、以前のアクティブデータセットが引き続き使用可能だった場合に`true`
- `anomalies`: ライブリフレッシュ試行中に発生した警告/ブロックの異常

### 結果の理解

**重要度レベル:**
- **CRITICAL:** アクティブなエクスプロイトやデータ流出を伴う既知の悪意のあるコード
- **HIGH:** 悪意のある意図やタイポスクワッティングの強い兆候
- **MEDIUM:** 疑わしいパターンや潜在的な脆弱性
- **LOW:** 軽微な懸念事項や情報提供

**推奨アクション:**
1. **Critical/Highの検出結果:** 影響を受けるパッケージを直ちに削除し、影響を調査
2. **IoCの確認:** 悪意のあるコードが実行されたかどうかを確認（ログ、ネットワークアクティビティ）
3. **依存関係の更新:** 悪意のあるパッケージを正当な代替品に置き換え
4. **再スキャン:** フォローアップスキャンで修正を確認
5. **報告:** パッケージレジストリメンテナへの報告を検討

---

## CI/CD統合

### GitHub Actions

**基本セキュリティスキャン:**```yaml
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/

検出失敗時の高度なモード:```yaml - 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```yaml
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```groovy

pipeline { agent any

stages {
    stage('Setup Scanner') {
        steps {
            sh '''
                git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner
                cd scanner
                python3.14 -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` に追加してください:```bash
#!/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

**原因:** 脅威データの収集に失敗した、メタデータが不完全である、または要求されたエコシステムにまだ使用可能なローカルデータベースがない。

**解決策:**```bash
# Force recollection and require a complete result for the requested ecosystems
orewatch /path/to/project --latest-data --strict-data

注意: この問題が続く場合は、ネットワーク接続、ファイルシステムのアクセス権限、および実験的なソースを意図的にリクエストしたかどうかを確認してください。

「パッケージが検出されません」という警告

症状:``` WARNING: No packages detected in /path/to/project

**考えられる原因と解決方法：**

1. **間違ったディレクトリ:** 正しいプロジェクトディレクトリをスキャンしていることを確認してください。   ```bash
   ls /path/to/project  # Verify package.json or requirements.txt exists

2. サポートされていない、または予期しないマニフェスト: サポートされている正確なファイル名を表示する ```bash orewatch --list-supported-files
   root@kitploit:~

3. ファイルのパーミッション: ファイルが読み取り可能であることを確認してください ```bash ls -la /path/to/project/package.json
   root@kitploit:~

アップデート中の接続エラー

症状:``` ERROR: Error downloading npm: <urlopen error [Errno -3] Temporary failure in name resolution>

**解決策:**

1. **インターネット接続を確認:**   ```bash
   ping google.com

2. タイムアウト増加での再試行: collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
   root@kitploit:~

3. キャッシュデータを使用する: 以前にデータをダウンロードした場合: ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache
   root@kitploit:~

許可拒否エラー

症状:``` ERROR: Error creating directory collectors/raw-data: Permission denied

**解決策:**```bash
# Ensure proper ownership
sudo chown -R $USER:$USER /path/to/ore-mal-pkg-inspector

# Or run from user-writable location
cd ~/
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector

OreWatch がディスクを大量に使用している

症状: ~/Library/Application Support/OreWatch (macOS) または $XDG_STATE_HOME/orewatch (Linux) が数十ギガバイトに増加している。

原因 (1.2.3 以前): ライブアップデートのプロモーションごとに、以前の脅威データベースの完全なコピーが （約300 MB）保存され、保持期間が設定されていませんでした。長期実行されている モニターは、サイクルごとに1つのスナップショットを無制限に蓄積していました。

修正: 1.2.3 以降 にアップグレードしてください。バックアップは現在約1 KBの SHA-256 マニフェストになり、保持期間はデフォルトで最新の30個となり、明示的な クリーンアップコマンドが利用可能です:```bash

Apply the configured retention policy now (default: keep 30 manifests,

remove staging entries older than 1 hour).

orewatch monitor cleanup

Reclaim everything except the most recent 5 backups and purge staging.

orewatch monitor cleanup --keep-backups 5 --staging-max-age-seconds 0

Tune retention in monitor config (live_updates section):

retain_backups: # how many backup manifests to keep

staging_max_age_seconds: # stale candidate-* staging cutoff

#### 誤検知

**症状:** 正当なパッケージが悪意のあるものとしてフラグ付けされました。

**手順:**

1. **調査結果の確認:** 重要度と説明を含むレポートの詳細を確認します

2. **バージョンの確認:** フラグ付けされたバージョンが特定のものである可能性があります:   ```bash
   orewatch /path/to/project --verbose

3. 誤検出の報告: 誤りと確認された場合:
   • 詳細を添えて https://github.com/rapticore/ore-mal-pkg-inspector/issues にIssueを開く

調査用のデバッグモード

詳細ログを有効にする:```bash

Scanner debug mode

orewatch /path/to/project --debug 2> debug.log

Collector debug mode

cd collectors python3 orchestrator.py --debug 2> collector-debug.log

**ログの確認:** 詳細な実行トレースについては `debug.log` を確認してください。以下を含みます:
- スキャンされたファイルパス
- 実行されたSQLクエリ
- パターンマッチングの結果
- エラーのスタックトレース

---

## FAQ

### 脅威インテリジェンスはどのくらいの頻度で更新すべきですか？

**推奨:**
- **本番/CI環境:** 毎日の自動更新
- **開発用ワークステーション:** 最低でも毎週の更新
- **セキュリティニュース後:** 新たな脅威が発表されたらすぐに更新

悪意のあるパッケージは継続的に公開されています。毎日の更新で最新の保護を確保できます。

### 脅威インテリジェンスデータを更新するにはどうすればよいですか？

スキャナーを `--latest-data` フラグ付きで実行して、強制的に更新します:```bash
orewatch /path/to/project --latest-data

CI/CDでの自動更新のために、定期的なスキャンを--latest-dataフラグ付きでスケジュールしてください（例：毎日）。--include-experimental-sourcesは、リビルドにPhylum由来のデータを明示的に含めたい場合のみ追加してください。

注意: 初回スキャンでは自動的にデータが収集されるため、手動での更新は既存のデータベースをリフレッシュする場合のみ必要です。

脅威データはどこから来るのですか？

デフォルトのデータベースは、プロジェクトのコア脅威ソースから構築されます：

• openssf
• osv

スキャナーは、プロジェクトの実験的ソースセットも含めることができます：

• phylum を --include-experimental-sources と共に

socketdev はリポジトリ内に無効化されたプレースホルダーとして存在しており、デフォルトの収集パスには含まれていません。

データソース、収集、処理に関する技術的な詳細は、ARCHITECTURE.mdを参照してください。

このツールはコードや依存関係を変更しますか？

いいえ。 OreWatchは読み取り専用の操作を実行します。それは：

• ✅ 依存関係ファイルを読み取ります
• ✅ 脅威データベースに問い合わせます
• ✅ ファイルパターンをスキャンします
• ✅ レポートを生成します

それは決してしません：

• ❌ パッケージファイルを変更する
• ❌ パッケージをインストールまたは削除する
• ❌ プロジェクト設定を変更する
• ❌ パッケージコードを実行する

パッケージが悪意があるとフラグが立てられた場合は？

取るべき手順：

1. 発見内容を確認する： レポートで詳細と深刻度を確認する
2. 証拠を確認する： 説明と検出された動作を確認する
3. バージョンを確認する： 影響を受ける特定のバージョンを特定する
4. 正当な場合：
   • 誤検出をデータソースのメンテナーに報告する
   • 詳細を含むIssueをGitHubで開く
5. 本当に悪意がある場合：
   • すぐにパッケージを削除する
   • 最近のコードコミットに損害がないか確認する
   • ログで不審なアクティビティを確認する
   • 安全な代替に更新する

オフラインで使用できますか？

部分的に可能です。

オフラインでのスキャン： ✅ はい、データベースが初期化されていれば可能です```bash

Online: Initial setup (one-time - runs automatically on first scan)

orewatch /path/to/project

Offline: Subsequent scans work with local databases

orewatch /path/to/project

**オフライン更新:** ❌ いいえ、脅威インテリジェンスの収集にはセキュリティソースから取得するためのインターネットアクセスが必要です。

**エアギャップ環境:** 可能な方法:
1. インターネットに接続されたマシンでデータベースをダウンロードする
2. SQLiteファイルを `orewatch monitor doctor` が示す唯一の `final_data_dir` に転送する
3. オフラインでスキャンを実行する（データは古くなっている可能性あり）

### npm audit や pip-audit との比較は？

**目的の違い:**

**npm audit / pip-audit:**
- 既知のCVE脆弱性に焦点を当てる
- パッケージバージョンをアドバイザリデータベースと照合する
- パッケージレジストリチームによって維持されている

**OreWatch:**
- 悪意のあるパッケージ（脆弱なものだけでなく）に焦点を当てる
- タイポスクワッティング、マルウェア、サプライチェーン攻撃を検出する
- クロスエコシステムのカバレッジ
- アクティブな脅威のIoC検出

**ベストプラクティス:** **両方**を使用する:```bash
# Check for vulnerabilities
npm audit
pip-audit

# Check for malicious packages
orewatch /path/to/project

プライベートパッケージレジストリでも動作しますか？

依存関係スキャン: ✅ はい、パッケージの出所に関係なく、依存関係ファイルを読み取ります。

脅威インテリジェンス: ⚠️ 限定的です。データベースは公開レジストリ（npmjs.com、pypi.org など）を対象としています。カスタム脅威データを追加しない限り、プライベートレジストリ上の悪意のあるパッケージは検出されません。

カスタム脅威データ: 独自の悪意のあるパッケージリストでデータベースを拡張できます。この高度なユースケースについては、お問い合わせください。

パフォーマンスへの影響は？

スキャン時間:

• 小規模プロジェクト（50パッケージ未満）: 5秒未満
• 中規模プロジェクト（50～500パッケージ）: 5～30秒
• 大規模プロジェクト（500パッケージ以上）: 30～120秒

要因:

• IoC スキャンによりオーバーヘッドが10～50％増加します（不要な場合は --no-ioc で無効化可能）
• 初回実行時はデータベースがメモリにロードされるため、遅くなることがあります

最適化のヒント:```bash

Scan specific files instead of entire directory

orewatch --file package.json

---

## コントリビューション

コントリビューションを歓迎します！バグ報告、機能提案、コード提供など、皆様のご協力がOreWatchをより良いものにします。

**バグ報告や機能リクエスト:**
- GitHub Issues: https://github.com/rapticore/ore-mal-pkg-inspector/issues

**コードの提供:**
- 開発環境のセットアップ、コードスタイル、テスト、プルリクエストプロセスに関する詳細なガイドラインについては、[CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/CONTRIBUTING.md)をご覧ください

**質問や議論:**
- GitHub Discussions: https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## セキュリティポリシー

セキュリティは最優先事項です。OreWatchはセキュリティツールであり、私たちは脆弱性を真剣に受け止めています。

### セキュリティ脆弱性の報告

**セキュリティ脆弱性については、公開のGitHub Issueを開かないでください。**

代わりに、非公開で報告してください:

**メール:** [email protected]

**含める内容:**
- 脆弱性の説明
- 再現手順
- 潜在的な影響
- 修正案（該当する場合）
- フォローアップのための連絡先情報

### 対応スケジュール

- **確認:** 48時間以内
- **初期評価:** 7日以内
- **修正スケジュール:** 深刻度により異なります
  - 重大: 7～14日
  - 高: 14～30日
  - 中/低: 30～60日

### セキュリティベストプラクティス

OreWatchを使用する際の注意点:

**推奨事項:**
- ✅ 最小権限で実行（root/管理者は不要）
- ✅ 脅威インテリジェンスを定期的に更新
- ✅ スキャンレポートを速やかに確認
- ✅ CI/CDに統合して継続的保護を実現
- ✅ ツールを最新バージョンに更新

**禁止事項:**
- ❌ 調査なしでスキャン結果を無視
- ❌ 本番環境でIoCスキャンを無効化
- ❌ 信頼できないソースからのデータベースファイルを共有
- ❌ 不必要に昇格された権限で実行

### 脆弱性開示

私たちは調整された開示に従います:
1. 脆弱性を非公開で報告
2. 修正を開発・テスト
3. セキュリティアドバイザリを公開
4. 修正が利用可能になった後に公開開示

### セキュリティ殿堂

責任ある開示を行ったセキュリティ研究者を表彰します:

*レポートが届き次第、リストを維持します*

---

### コミュニティリクエスト

機能の投票や提案:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **機能リクエスト:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### ロードマップへの貢献

以下の基準に基づいて機能の優先順位を決定します:
- セキュリティへの影響
- コミュニティの需要
- メンテナンスの持続可能性
- プロジェクト目標との整合性

ロードマップに影響を与えるには:
1. 詳細なユースケースを含む機能リクエストを開く
2. ディスカッションに参加する
3. 実装に貢献する（PR歓迎！）

---

## ロードマップ

OreWatchは現在、以下の用途で利用可能です:

- npm、PyPI、Maven、RubyGems、Go、CargoのローカルCLIスキャン
- 多くのプロジェクト向けのユーザーごとのバックグラウンドモニター1つ
- Cursor、Claude Code、Codex向けのMCP統合
- VS Code、JetBrains / PyCharm、Xcodeヘルパー向けのlocalhost API統合
- macOSメニューバーレビューとポップアップ通知

短期優先事項:
- ファーストパーティのVS CodeおよびJetBrains / PyCharm統合のサンプルまたは薄いプラグイン
- ローカルポップアップを超えた、より強力なユーザー向け通知ワークフロー
- CLIとUIからの明確なプロジェクトポリシー管理
- より充実したモニターレポートと導入ドキュメント

中期優先事項:
- モニターとMCPサーフェスからのより広範なプロジェクトスキャンワークフロー
- より優れた組織レベルのロールアウトガイダンス
- より堅牢な外部アラート配信およびエスカレーションチャネル
- APIのみの統合ガイダンスではなく、より深いIDE固有のUX

現在の既知の境界:
- Xcode統合は現在、アラート表示と多言語リポジトリに最適です。OreWatchはまだ`Package.resolved`、`Podfile.lock`、`Cartfile`などのネイティブAppleマニフェストを解析しません。

長期的な方向性:
- ネイティブAppleエコシステムのマニフェストサポート
- より強力なファーストパーティエディタ統合
- 現在のmacOSメニューバーパスを超えた、より広範なOS UXのパリティ

詳細な導入重視のロードマップビューについては、[docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md)を参照してください。

---

## ライセンス

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

**メール:** セキュリティ脆弱性や非公開のお問い合わせのために:
- [email protected]

### プロフェッショナルサポート

以下を必要とする組織向け:
- カスタム統合
- SLA付きサポート
- プライベートデプロイ支援
- カスタム脅威インテリジェンスフィード

連絡先: [email protected]

---

## 謝辞

### プロジェクトの起源

このプロジェクトは、プロジェクトの焦点を明確に保ちながら機能を拡張するために、[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)リポジトリから抽出されました。

**OreNPMGuard**（2025年12月）は、738以上の影響を受けるパッケージと深いIoC分析を備えたShai-Hulud npm攻撃検出に特化しています。開発中に、より広範なマルチエコシステム保護の必要性を認識し、OreWatchをすべての主要パッケージエコシステムにわたるより広い開発者コミュニティにサービスを提供するスタンドアロンツールとして作成しました。

### 関連プロジェクト

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - 特殊なShai-Hulud npmスキャナー
---

**Rapticoreセキュリティ研究チームによる開発**

*ソフトウェアサプライチェーンを守り、スキャンごとに安全を。*