itsoc-mcp

itsoc-icp — ローカル分析バックエンドを利用する MCP サーバー

mcp-name: io.github.Ankit512/itsoc-icp

itsoc-icp（Python パッケージ itsoc_mcp）は、このプロジェクトに既存のログ分析機能を Model Context Protocol ツールとして公開するため、 MCP 対応エージェント（Claude Code / Claude Desktop）から操作できます。これは 独立した関連パッケージです。anomaly_detector.py から何もインポートせず、 /api/* ルートを変更せず、コアバックエンドに依存関係を追加しません。

これは何か（そして何ではないか）

• 頭脳ではなく、クライアントです。 すべてのツールは、すでに稼働しているローカルバックエンド （デフォルトでは http://127.0.0.1:8765）にリクエストを中継します。このサーバーは判定を 一切行いません。重大度、相関関係、ルールによる判定は、バックエンド上の固定された決定論的 検出器が担います。ツールは中継するだけで、判定をやり直すことはありません。
• アクションの実行も承認権限もありません。 どのツールもアクションを承認、却下、実行、 取り消すことはできません。propose_block_ip は pending 状態の提案を作成することのみ可能です。 すべての実行権限と承認権限は、ヒューマン・イン・ザ・ループの追加認証を備えたバックエンド コンソールに厳密に留保されています。analyze_log はログ分析を開始し、explain_finding は既存の エンドポイントを通じて参考情報としての説明を要求します。説明によって判定が変更、抑制、 またはエスカレーションされることはありません。
• 設計上、常に正直です。 バックエンドの null、「0 lines parsed」、アイドル状態は、 そのまま引き継がれます。問題なしという結果や空のファイルを捏造することはありません。
• デフォルトでマスキングされます。 生のログテキストを含むフィールドは、プロジェクト既存の 外部送信時の制御ポイント（console/redact.py）を通じて、外部に送信される前にマスキングされます。 ただし、信頼できるローカルセッションを選択した場合は除きます（下記参照）。

すべてのツールの応答には provenance ブロックが含まれ、判定は決定論的でルールに基づくこと、 説明は参考情報であること、MITRE タグは導出されたもので判定ではないこと、さらに実行中の検出器の detector_sha256 が示されます。

ツール

ツール	返される内容	注意事項
analyze_log(source, compare=False)	ローカルパス または http(s) URL に対して既存の解析フローを実行し、run_id と概要（重大度別件数、解析済み／未解析の行数、未認識フラグ、検出器の sha）を返します。	未認識の形式の場合は「解析済みの行数 0」となります。これは明示的に 問題なしを意味するものではありません。
list_runs()	実行履歴に保存された実行と、現在の実行を返します。	履歴が空の場合は、空であることをそのまま返します。
get_findings(run_id='', severity='', rule='', host='', limit=50)	アクティブな実行の絞り込み済み検出結果を返します。ルールが設定する重大度、rule_id、導出された MITRE タグが含まれます。	ホスト名／タイトルはデフォルトでマスキングされます。現在の実行ではない run_id は正直にエラーとなります（このサーバーはアクティブな実行を切り替えません）。
get_evidence(finding_id, run_id='')	1 件の検出結果について、実際の証拠行、ルールの述語、タイムラインを返します。	生の行とタイムラインのラベルは デフォルトでマスキングされます。
explain_finding(finding_id, run_id='')	/api/explain を介した、助言目的の LLM による説明を返します。	助言のみを目的とします。デフォルトでマスキングされます。モデルに到達できない場合は正直にエラーとなります。
export_run(format, run_id='')	/api/export（csv|html|xml|json|md）に中継します。	アイドル状態の場合は正直に 409（「エクスポートするものがまだありません」）となり、空のファイルは生成しません。コンテンツには生のログテキストが含まれるため、デフォルトでは 提供されません（実際のサイズと sha256 を返します）。信頼できるローカル環境用のフラグを設定すると、インラインで受け取れます。
threat_intel_lookup(ip, bundle_path=None)	1 件の IPv4 アドレスに対する オフラインの STIX→MITRE 検索です。threat_intel/ を再利用し、threat_detector.py の一致結果と重大度、キャッシュされた ATT&CK DB の MITRE 情報を返します。ネットワークへの送信はありません。	バンドルが設定されていない場合は、正直に n/a を返します。一致がない場合は、問題なしではなく正直に「一致なし」と返します。
propose_block_ip(incident_id, runbook_id='rb-block-ip')	バックエンドコンソールに保留中の承認レコードを作成し、境界での IP ブロックを提案します。	提案の作成のみです。実行権限も承認権限もありません。承認／実行にはコンソールでのステップアップ認証が必要です。

すべてのツールは、4 つすべての MCP ヒント（readOnlyHint、 destructiveHint、idempotentHint、openWorldHint）を明示的なブール値として宣言するため、ホストは呼び出し前に警告でき、OpenAI のディレクトリでもこの仕様が受け入れられます。読み取りツール （list_runs、get_findings、get_evidence、export_run、threat_intel_lookup） は readOnlyHint: true です。analyze_log、explain_finding、propose_block_ip は書き込み操作です（追加のみで、破壊的ではありません）。バックエンドとやり取りするすべてのツールは openWorldHint: true です。

インストール

コアバックエンドは 標準ライブラリのみを使用します。実行にあたってインストールは不要です。このサーバーを実行する場合に限り、MCP SDK をインストールしてください。

pip install -r itsoc_mcp/requirements-mcp.txt   # the `mcp` SDK, and nothing else

実行

1. バックエンドを起動します（リポジトリのルートから）。標準ライブラリのみを使用し、追加インストールは不要です。

   python3 console/serve.py           # serves http://127.0.0.1:8765
   

2. stdio 経由で MCP サーバーを起動します（リポジトリのルートから）。

   python -m itsoc_mcp
   

設定（環境変数）

変数	デフォルト	目的
ITSOC_BASE_URL	http://127.0.0.1:8765	ローカルバックエンドの待ち受け先です。
ITSOC_MCP_TRUSTED_LOCAL	(未設定)	1 に設定すると、マスキングされていない生のログテキストとインラインのエクスポートコンテンツを返します。MCP クライアントがマシン外に中継する可能性のあるセッションでは、未設定のままにしてください。デフォルトでは IP アドレス、ユーザー名、既知のホスト名がマスキングされます。
ITSOC_STIX_BUNDLE	(未設定)	threat_intel_lookup 用のローカル STIX バンドルへのパスです。未設定の場合、ツールは正直に「n/a — 照合対象がありません」と報告します。

MCP クライアントへの登録（stdio）

MCP クライアントの設定に貼り付けます（例：Claude Desktop の claude_desktop_config.json、または Claude Code の .mcp.json）。/ABSOLUTE/PATH/TO/itsoc をリポジトリのルートに置き換えてください。

{
  "mcpServers": {
    "itsoc-icp": {
      "command": "python",
      "args": ["-m", "itsoc_mcp"],
      "cwd": "/ABSOLUTE/PATH/TO/itsoc",
      "env": {
        "ITSOC_BASE_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

信頼できるローカルマシンで生の証拠／エクスポートを許可するには、その env ブロックに "ITSOC_MCP_TRUSTED_LOCAL": "1"（および任意で "ITSOC_STIX_BUNDLE": "..."）を追加してください。バックエンド（python3 console/serve.py）が実行中である必要があります。

テスト

ネットワーク不要、SDK 不要、ATT&CK キャッシュ不要です。クライアントはフェイク化され、オフラインマッパーはスタブ化されています。

python3 itsoc_mcp/test_mcp.py

各ツールの形式に加え、get_evidence／get_findings／explain_finding がデフォルトで秘匿化され、ITSOC_MCP_TRUSTED_LOCAL=1 の場合にのみ生データを返すことを検証します。また、アイドル状態／認識されない状態／エラー状態では、空のペイロードではなく、正直なエラーが返されることも検証します。

スタンドアロンでのインストール（uvx／pipx）

pyproject.toml は、itsoc-icp 配布パッケージと、itsoc_mcp.server:main を実行する itsoc-icp コンソールスクリプトをビルドし、mcp>=1.9,<2 に固定します。MCP クライアントは安定版の 1.x API を使用します。mcp 2.0 ではサーバー API が変更されました。このパッケージは自己完結型で、リポジトリをチェックアウトせずに実行できるよう設計されています。

uvx itsoc-icp        # or: pipx run itsoc-icp   (the backend must still be running)

明確に述べておくべき点が 2 つあります。

• スタンドアロンでも、外部送信ガードが決して弱まることはありません。秘匿化の唯一の基準は console/redact.py で、リポジトリをインポートできる場合は常にこれが使われます。単体インストールでは、同じようにマスクする内容をそのまま複製したミラー（_redact_vendored.py）にフォールバックします（デフォルトで秘匿化し、ITSOC_MCP_TRUSTED_LOCAL=1 の場合にのみ生データを返します）。ドリフト防止テストにより 2 つの実装が決して食い違わないことを検証するため、複製版によってマスクがひそかに弱まることはありません。redaction.redact_source() は、どちらが有効かを報告します。どちらも読み込めない場合、テキストをそのまま通すのではなく、モジュールのインポートに失敗します。つまり、オープンではなくクローズドフェイルします。
• threat_intel_lookup の実行にはリポジトリが必要です。このツールのオフライン STIX→MITRE 処理は、リポジトリ内の隣接する threat_intel/ パッケージを再利用しますが、このパッケージは単体インストールには含まれません。スタンドアロンでインストールした場合、このツールはクローズドフェイルし、「オフラインの脅威インテリジェンスは利用できません……クリーンという判定ではなく、問題なしという判定でもありません」という正直なメッセージを返します。偽の一致や、問題なしという偽の判定は決して返しません。オフラインの脅威インテリジェンスを使うには、リポジトリから実行してください（python -m itsoc_mcp）。ほかのすべてのツールはバックエンド API のクライアントであり、スタンドアロンでもリポジトリ内でも同じように動作します。

スタンドアロンとは、MCP パッケージのためにリポジトリをチェックアウトする必要がないという意味です。バックエンド（python3 console/serve.py）は別途実行し、ITSOC_BASE_URL からアクセスできる必要があります。

ライセンス

MIT — リポジトリのトップレベルにある LICENSE を参照してください。