ProcmonMCP

ProcmonMCP

ProcmonMCP は、LLM が Process Monitor（Procmon）の XML ログファイルを自律的に分析できるようにする Model Context Protocol (MCP) サーバーです。Claude Code、Claude Desktop、Cline など、MCP 互換クライアントで利用できる包括的な分析ツール一式を提供します。

REMnux に収録 REMnux® マルウェア分析ディストリビューションに同梱されており、OpenCode 用の procmon MCP サーバーとして事前設定されています。

概要

Process Monitor は、ファイルアクセス、レジストリ操作、ネットワーク接続、プロセスの作成など、システムの詳細なアクティビティを記録します。ProcmonMCP は、これらの XML ログを最適化されたメモリ内表現に解析し、MCP ツールとして提供することで、LLM が手動でデータを整理することなくシステムの動作を調査できるようにします。

主な機能：

• 実行時にファイルを読み込み — 別のキャプチャを分析するためにサーバーを再起動する必要はありません
• 解析済みキャプチャのキャッシュ — 変更されていないファイルの再読み込みはほぼ瞬時に完了します（解析はスキップされます）
• 大きなログでメモリ使用量を抑える文字列インターニング
• 高速なフィルタリングを可能にする、プロセス名、操作、PID、ファイルパスによるインデックス付き検索
• 複数のトランスポートプロトコル — stdio（推奨）、Streamable HTTP、SSE（非推奨）
• MCP 通知を介した、ファイル読み込み中の進行状況フィードバック

このプロジェクトは、GhidraMCP の手法に着想を得ています。

セキュリティに関する警告

Process Monitor のログには、非常に機密性の高いシステム情報（キーストローク、コマンドライン内のパスワード、ファイルの内容、ネットワークトラフィックの詳細など）が含まれる場合があります。

• このツールは、スクリプトを実行するユーザーに読み取り権限がある任意のファイルパスを読み込みます。ディレクトリによるサンドボックス化はありません。
• このサーバーは、信頼できる環境でのみ実行してください。
• リスクを十分に理解し、許容できる場合を除き、機密性の高い本番データや個人データを含むシステムから取得した Procmon ログを使って、このサーバーを実行しないでください。
• このツールを使用する前に、読み込むログに機密情報が含まれていないか確認してください。

インストール

現在のリリース：v0.5.0。MCP SDK v2（mcp[cli]>=2.0.0）が必要です。以前のバージョンはリリースページに掲載されており、主な変更点はCHANGELOG.mdに記載されています。

前提条件

• Python 3.10 以降（MCP SDK が必要とします。Python 3.10～3.13 で開発・テストされています）
• pip（Python パッケージインストーラー）

ソースからインストール

git clone https://github.com/JameZUK/ProcmonMCP
cd ProcmonMCP
pip install -r requirements.txt

これはデフォルトブランチの最新の状態を取得します。現在のリリースに固定するには、次のコマンドを実行します。

git clone --branch v0.5.0 --depth 1 https://github.com/JameZUK/ProcmonMCP
cd ProcmonMCP
pip install ".[all]"

または、パッケージ自体をインストールします（procmon-mcp コンソールスクリプトが提供されます）。

pip install .            # core only (mcp[cli])
pip install ".[all]"     # core + optional lxml and psutil
pip install -e ".[dev]"  # editable install with test tooling

依存関係

パッケージ	必須	用途
mcp[cli]>=2.0.0	はい	CLI ツールと Streamable HTTP に対応した MCP SDK
lxml>=4.9.0	推奨	高速な XML 解析（存在しない場合は標準ライブラリの ElementTree にフォールバックします）
psutil>=5.9.0	任意	ファイル読み込み後のメモリ使用量の報告
google-re2	任意	ユーザーのフィルター正規表現用の線形時間で ReDoS に安全なエンジン（pip install ".[re2]"。標準ライブラリの re にフォールバックします）

一括インストール：

pip install "mcp[cli]>=2.0.0" lxml psutil

MCP SDK v2： SDK では FastMCP の名称が MCPServer に変更され、v2 では mcp.server.mcpserver に移動しました。ProcmonMCP は v2 を対象としており、互換性フォールバックにより mcp<2 でも引き続き動作します。ピン留めせずに mcp[cli] を以前インストールし、「MCP SDK を読み込めませんでした」 と表示された場合は、pip install --upgrade "mcp[cli]>=2" でアップグレードしてください。

Claude Code ですぐに始める

ProcmonMCP の使用には、Claude Code と stdio トランスポートを使う方法をおすすめします。サーバーはファイルを読み込まずに起動します。その後、load_file ツールを使って Procmon のキャプチャを開くことができます。

オプション 1：Claude Code CLI から追加する

# Add ProcmonMCP as a stdio server (user-wide)
claude mcp add procmon --scope user -- python -m procmon_mcp

# Or with a file pre-loaded at startup
claude mcp add procmon --scope user -- python -m procmon_mcp --input-file /path/to/capture.xml.gz

# Or scoped to the current project only
claude mcp add procmon --scope project -- python -m procmon_mcp

オプション 2：JSON から追加する

claude mcp add-json procmon '{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "procmon_mcp"]
}'

オプション 3：設定ファイルを直接編集する

Claude Code は、以下の場所から MCP サーバーの設定を読み込みます。

スコープ	ファイル	説明
プロジェクト（共有、バージョン管理対象）	プロジェクトルートの .mcp.json	チームで共有されます
プロジェクト（個人用）	.claude/settings.local.json	ローカルでの上書き設定です
ユーザー（グローバル）	~/.claude.json	すべてのプロジェクトで利用できます

共有プロジェクト向けの .mcp.json の例：

{
  "mcpServers": {
    "procmon": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "procmon_mcp"]
    }
  }
}

ファイルを事前に読み込み、オプションを指定する例：

{
  "mcpServers": {
    "procmon": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m", "procmon_mcp",
        "--input-file", "/path/to/capture.xml.gz",
        "--no-stack-traces"
      ]
    }
  }
}

オプション 4：Streamable HTTP トランスポート

ネットワーク経由でのアクセスや複数クライアントでの利用には、Streamable HTTP を使用してください。

# Add as an HTTP server (start the server separately first)
claude mcp add --transport http procmon http://127.0.0.1:8081/mcp

続いて、サーバーを起動します。

python -m procmon_mcp --transport streamable-http --mcp-port 8081

接続を確認する

設定したら、Claude Code から ProcmonMCP が認識できることを確認します。

claude mcp list

Claude Code のセッション中に /mcp と入力して、接続中のサーバーの状態を確認することもできます。

使用方法

一般的なワークフロー

1. サーバーを起動する（stdio サーバーの場合は Claude Code が自動的に起動します）
2. 状態を確認する：LLM が get_status を呼び出し、ファイルが読み込まれているか確認します
3. ファイルを読み込む：LLM が load_file を呼び出し、Procmon XML キャプチャのパスを指定します
4. 分析する：LLM が分析ツールを使って、ログデータを調査します

コマンドライン引数

引数	デフォルト	説明
--input-file <path>	(なし)	起動時に Procmon XML ファイルを事前に読み込みます。省略した場合は、MCP クライアントから load_file を使用します。
--transport <mode>	stdio	トランスポートプロトコル：stdio、streamable-http、または sse（非推奨）。
--mcp-host <ip>	127.0.0.1	ホストアドレス（HTTP トランスポートのみ）。
--mcp-port <port>	8081	ポート番号（HTTP トランスポートのみ）。
--no-stack-traces	off	メモリを節約するため、スタックトレースの読み込みをスキップします。
--no-extra-data	off	メモリを節約するため、不明なイベントフィールドや追加のイベントフィールドの読み込みをスキップします。
--no-cache	off	解析済みキャプチャのキャッシュを使用せず、常に再解析してキャッシュを更新します。
--clear-cache	off	キャッシュされた解析済みキャプチャをすべて削除してから終了します。
--debug	off	詳細なデバッグログを有効にします。
--log-file <path>	(コンソール)	ログをコンソールではなくファイルに書き込みます。
--profile	off	cProfile によるプロファイリングを有効にします（開発用）。

例

stdio で起動する（ファイルは事前に読み込まず、クライアントから load_file を使用）：

python -m procmon_mcp

圧縮 XML ファイルを事前に読み込む：

python -m procmon_mcp --input-file /path/to/capture.xml.gz

カスタムポートで Streamable HTTP を起動する：

python -m procmon_mcp --transport streamable-http --mcp-port 9000

非常に大きなファイルでスタックトレースの読み込みをスキップする：

python -m procmon_mcp --input-file /path/to/huge_capture.xml --no-stack-traces --no-extra-data

トランスポートプロトコル

トランスポート	用途	ステータス
stdio	Claude Code、Claude Desktop などでのローカル利用	推奨
streamable-http	ネットワークアクセス、複数のクライアント、リモートデプロイ	サポート対象
sse	Streamable HTTP をまだサポートしていない従来の MCP クライアント	非推奨（MCP spec 2025-03-26）

stdio（推奨）

最もシンプルで信頼性の高いトランスポートです。Claude Code がサーバーを子プロセスとして起動し、stdin/stdout を介して通信します。ネットワーク設定は不要です。

Streamable HTTP

すべての通信に単一の HTTP エンドポイント（/mcp）を使用します。セッション管理、長時間実行される処理のためのオプションの SSE ストリーミングをサポートし、スケーラビリティを考慮して設計されています。

python -m procmon_mcp --transport streamable-http --mcp-host 0.0.0.0 --mcp-port 8081

サーバーは http://<host>:<port>/mcp で利用できます。

SSE（非推奨）

MCP specification 2025-03-26 以降、非推奨です。 SSE は後方互換性のために維持されていますが、今後のリリースで削除される予定です。streamable-http または stdio に移行してください。

python -m procmon_mcp --transport sse --mcp-port 8081

ユーザー設定

ProcmonMCP はユーザー設定を ~/.procmonmcp/config.json に保存します。このファイルは自動的に作成され、次の内容を記憶します。

• 最後に読み込んだファイルのパス（ファイルが読み込まれていない場合に get_status のヒントとして表示されます）
• 読み込み設定（no_stack_traces、no_extra_data）

API キーや認証トークンは不要です。ProcmonMCP は完全にローカルで動作する分析ツールです。

解析済みキャプチャのキャッシュ

大きなキャプチャの解析には、数十秒から数分かかります。解析が成功すると、ProcmonMCP は最適化されたメモリ内表現（イベント、インターンナー、インデックス、プロセステーブル）を ~/.procmonmcp/cache/ にシリアライズします。キャッシュは、ソースファイルのパス、サイズ、更新日時、および読み込みオプションをキーにします。同じ変更されていないファイルを再読み込みする場合はキャッシュが使用され、ほぼ瞬時に完了します。実際には、20 秒かかっていた解析が 1 秒未満に短縮されます。

• ファイルが変更された場合（mtime/size）、またはキャッシュ形式のバージョンが変わった場合、キャッシュは自動的に無効になります。異なる no_stack_traces／no_extra_data オプションは個別にキャッシュされます。
• --no-cache（CLI）または no_cache: true（load_file ツール）でキャッシュを迂回できます。読み込みレスポンスの from_cache フィールドで、キャッシュが使用されたかどうかを確認できます。
• --clear-cache（CLI）または clear_cache ツールでキャッシュを消去できます。キャッシュのサイズには上限があり、LRU 方式で削除されます（デフォルトは 5 GiB。PROCMONMCP_CACHE_MAX_BYTES 環境変数で変更できます）。
• セキュリティ： キャッシュファイルは Python の pickle でシリアライズされ、ユーザーが所有する ~/.procmonmcp/cache ディレクトリからのみ読み戻されます（このツール自体が出力したものだけがデシリアライズされます）。ほかのユーザーが書き込み可能な場所をキャッシュ先に指定しないでください。

利用可能な MCP ツール

ライフサイクルツール

ツール	説明
get_status()	現在のサーバー状態（ファイルが読み込まれているか、読み込みの進行状況、メモリ使用量、利用可能な操作）を返します。最初に呼び出してください。
load_file(file_path, no_stack_traces?, no_extra_data?, no_cache?)	分析用の Procmon XML ファイル（.xml、.gz、.bz2、.xz）を読み込みます。解析済みキャプチャのキャッシュを使用し、再読み込みをほぼ瞬時に行います（レスポンスの from_cache でキャッシュが使用されたかどうかを確認できます）。キャッシュを迂回するには no_cache: true を設定します。進行状況を通知します。以前に読み込んだデータは置き換えられます。
close_file()	現在読み込まれているキャプチャを閉じ（アンロードし）、メモリを解放します。load_file で別のファイルを開くまで、分析ツールは利用できません。ディスク上のキャッシュは削除されません。
clear_cache()	ディスク上の解析済みキャプチャのキャッシュをすべて削除します。ディスク領域を解放し、次回読み込み時に再解析を行います。現在読み込まれているデータには影響しません。

データ取得ツール

ツール	説明
get_loaded_file_summary()	読み込まれたファイルの詳細な概要（ファイル名、件数、圧縮、インデックス統計、インターン統計、選択的読み込みフラグ）を返します。
get_metadata()	基本的なメタデータ（ファイル名、種類、イベント数／プロセス数）を返します。
list_processes()	プロセス一覧セクションから一意のプロセス（PID、名前、イメージパス、親 PID）を一覧表示します。
get_process_details(pid)	PID で指定したプロセスの詳細なプロパティを返します。
query_events(...)	柔軟なフィルター（プロセス、PID（filter_pid）、操作、結果、パス（部分一致／正規表現）、詳細（正規表現）、タイムスタンプ範囲、スタックモジュールパス）でイベントを検索します。インデックス付きのイベント概要を返します。
get_event_details(event_index)	インデックスで指定したイベントのすべてのプロパティを返します。
get_event_stack_trace(event_index)	指定したイベントのコールスタック（モジュールパス、位置、アドレス）を返します。

分析ツール

ツール	説明
count_events_by_process()	プロセス名ごとにイベント数を数えます。
summarize_operations_by_process(process_name_filter)	指定したプロセスの操作数を数えます。
get_timing_statistics(group_by)	プロセスまたは操作ごとにグループ化して、所要時間の統計を計算します。
get_process_lifetime(pid)	指定した PID のプロセス作成時刻とプロセス終了時刻を特定します。
find_file_access(path_contains, limit?)	パスの部分文字列に一致するファイルシステムイベントを検索します（大文字と小文字を区別しません）。
find_network_connections(process_name)	プロセスがアクセスしたリモートエンドポイントの拡張レコード（エンドポイント、ホスト／IP／ホスト名／ポート、操作、推定された方向（接続／送信／受信）、結果、イベント数、最初／最後に確認されたタイムスタンプ）を返します。件数順に並べられます。
list_network_connections(limit?)	キャプチャ全体のネットワークトリアージ：全プロセスを対象に、（プロセス、PID、エンドポイント）ごとに 1 件の拡張レコードを返します。イベント数順に並べられます。
get_network_top_talkers(limit?)	キャプチャ全体の一意なリモートエンドポイントをイベント数順に並べ、各エンドポイントにアクセスしたプロセスの数と名前を返します。

エクスポートツール

ツール	説明
export_query_results(...)	フィルターしたイベントを CSV または JSON ファイルにエクスポートします。query_events と同じフィルターを使用します。

MCP クライアント

ProcmonMCP は、MCP 互換のあらゆるクライアントで動作します。以下に、一般的なクライアントのセットアップ手順を示します。

Claude Code（推奨）

上記の「Claude Code を使ったクイックスタート」セクションを参照してください。

Claude Desktop

Claude Desktop の設定ファイルに次の内容を追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "procmon": {
      "command": "python",
      "args": ["-m", "procmon_mcp"]
    }
  }
}

Cline

Streamable HTTP トランスポートで Cline を使用する場合は、まずサーバーを起動します。

python -m procmon_mcp --transport streamable-http --mcp-port 8081

次に Cline で「MCP Servers」を選択し、以下を追加します。

• サーバー名： ProcmonMCP
• サーバー URL： http://127.0.0.1:8081/mcp

マルウェア分析用 LLM プロンプトの例

（Procmon XML ファイルが読み込まれていることを前提とします）

初期トリアージ

• 「読み込まれたファイルの概要を取得してください。」
• 「ログで見つかった一意のプロセスを一覧表示してください。」
• 「プロセスごとのイベント数を数えてください。」（アクティビティの多いプロセスを特定）
• 「プロセスごとにグループ化したタイミング統計を計算してください。」（所要時間の長いイベントを特定）

不審なプロセスの調査

• 「プロセス PID 4568 の詳細を取得してください。」（コマンドライン、親 PID、イメージパスを確認）
• 「プロセス suspicious.exe の操作を要約してください。」
• 「filter_process が suspicious.exe で、filter_operation が RegSetValue のイベントを、上限 10 件で検索してください。」
• 「プロセス suspicious.exe のネットワーク接続を検索してください。」（方向、結果、件数、初回／最終確認時刻を付加）
• 「キャプチャ全体のネットワーク接続を一覧表示してください。」（キャプチャ全体のトリアージ、件数の多い順）
• 「ネットワークの通信量上位を表示してください。」（イベント数でリモートエンドポイントを順位付け）
• 「temp\\suspicious_data を含むファイルアクセスを、上限 50 件で検索してください。」

永続化の調査

• 「filter_operation が RegSetValue で、filter_path_contains が CurrentVersion\\Run のイベントを、上限 20 件で検索してください。」
• 「filter_operation が CreateFile で、filter_path_contains が StartUp のイベントを、上限 10 件で検索してください。」

エラーのトラブルシューティング

• 「filter_result が ACCESS DENIED のイベントを、上限 10 件で検索してください。」
• 「filter_result が NAME NOT FOUND のイベントを、上限 10 件で検索してください。」
• 「イベント 987 の詳細を取得してください。」
• 「イベント 987 のスタックトレースを取得してください。」

データのエクスポート

• 「filter_process が suspicious.exe で、filter_operation に RegSet を含むクエリ結果を suspicious_reg_writes.csv にエクスポートしてください。」
• 「クエリ結果を json 形式で network_activity.json にエクスポートしてください。」

パフォーマンスとインデックス作成

ProcmonMCP は、フィルターによる検索を高速化するため、ファイルの読み込み中に 4 つのインデックスを構築します。

インデックス	使用箇所	計算量
プロセス名（インターン ID）	query_events、count_events_by_process	O(1) で検索
操作（インターン ID）	query_events、summarize_operations_by_process	O(1) で検索
PID	query_events（filter_pid）、get_process_lifetime	集合の積集合を使った O(1) での検索
ファイルパス（インターン ID）	find_file_access	O(unique_paths) の部分文字列スキャン

インデックスに対応していないフィルター（例：正規表現、パスに含まれる文字列、スタックのモジュールパス）では、ProcmonMCP はすべてのイベントを線形スキャンします。まずインデックス付きフィルターで結果を絞り込み、その後、よりコストの高いフィルターを適用してください。

制限事項

• メモリ使用量：文字列のインターン化によって最適化されていますが、非常に大きな XML ファイル（スタックトレースを含む数百万件のイベント）を読み込むと、相当量の RAM を消費することがあります。非常に大きなファイルでは、--no-stack-traces と --no-extra-data を使用してください。
• 読み込み時間：大きな XML ファイルの解析と最適化には時間がかかり、圧縮ファイルでは特に時間がかかります。読み込み中は進行状況が表示されます。解析済みキャプチャのキャッシュにより、変更されていないファイルの再読み込みはほぼ瞬時に完了します。全コストがかかるのは初回の解析のみです。
• XML 構造：標準的な Procmon XML エクスポート構造に依存します。不正な形式または標準外の XML では、解析エラーが発生する可能性があります。
• 非 ASCII の名前：Procmon の XML エクスポートでは、非 ASCII のプロセス名やパス名（例：日本語のファイル名）が二重にエンコードされます。ProcmonMCP は読み込み時にこれを検出して修復するため、名前を正しく読み取れ、本来の値で照合できます。プロセス名を正確に入力しにくい場合は、代わりに filter_pid で絞り込んでください。
• スタックトレース：スタックトレースの品質は、Procmon が解決し、XML エクスポートに含めた内容に左右されます。シンボルを正しく設定した状態で Procmon を実行する必要があります。
• 一度に読み込めるファイルは 1 つ：一度に読み込めるファイルは 1 つだけです。新しいファイルを読み込むと、以前のデータが置き換えられます。

変更履歴

主な変更点は CHANGELOG.md に記録されています。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信するか、GitHub で Issue を作成してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。