Blackpoint Cyber

blackpoint-mcp

Blackpoint Cyber CompassOne（マネージド検知・対応（MDR）プラットフォーム）向けの Model Context Protocol（MCP）サーバーです。

機能

この MCP サーバーでは、意思決定ツリー形式のナビゲーションインターフェースを通じて、CompassOne のセキュリティ機能を利用できます。

利用可能なドメイン

• 🏢 テナント：顧客テナントの管理
• 💻 アセット：文書化されたクラス（CONTAINER、DEVICE、FRAMEWORK、NETSTAT、PERSON、PROCESS、SERVICE、SOFTWARE、SOURCE、SURVEY、USER）別のインベントリ。CLOUD はアセットクラスではありません。
• 🔍 検知：GET /alert-groups のアラートグループ（OPEN / RESOLVED、skip / take）
• 🛡️ 脆弱性：脆弱性管理、ダークウェブ監視、外部露出スキャン

ドメイン構成

実装済みのツールはすべて、単一の tools/list 呼び出しでまとめて一覧表示されるため、 ナビゲーションは必要ありません。blackpoint_status は現在の稼働状態と 利用可能なドメインを報告します。また、ガイド付きメニューを好む クライアント向けに blackpoint_navigate／blackpoint_back も引き続き利用できますが、 これらは任意です。各ドメインのツール（blackpoint_tenants_*、blackpoint_assets_*、blackpoint_detections_*、 blackpoint_vulnerabilities_*）は、最初から直接呼び出せます。

（以前のバージョンでは、blackpoint_navigate の呼び出し後に ドメインのツールを利用できるようにしていました。 これは Conduit ゲートウェイ経由では機能しません。Conduit はセキュリティ上の理由から、 すべてのベンダーのツール一覧で _navigate／_back を非表示にするため、 すべてのドメインツールにアクセスできなくなっていました。現在は一覧がフラットになり、 どこでも同じように機能します。）

ツールの命名規則

すべてのツールは次のパターンに従います：blackpoint_{domain}_{action}

例：

• blackpoint_assets_list - クラス別にアセットを一覧表示
• blackpoint_detections_list - セキュリティ検知を一覧表示
• blackpoint_vulnerabilities_scans_list - 脆弱性スキャンを一覧表示

インストール

npm install blackpoint-mcp

設定

環境変数

変数	説明	必須
BLACKPOINT_API_TOKEN	CompassOne API トークン	stdio の場合は必須
BLACKPOINT_BASE_URL	API のベース URL。デフォルトは https://api.blackpointcyber.com/v1 です。/v1 の有無を問わず、この URL に正規化されます。また、従来の api.compassone.blackpointcyber.com ホストも同様に正規化されます。その他のホストでは、オリジンを維持し、末尾に /v1 を 1 つ追加します。	いいえ
MCP_TRANSPORT	トランスポートモード：stdio または http	いいえ（デフォルト：stdio）
MCP_HTTP_PORT	ゲートウェイモードで使用する HTTP ポート	いいえ（デフォルト：8080）
MCP_HTTP_HOST	HTTP のバインドアドレス。未設定の場合は 127.0.0.1 にバインドします。コンテナーイメージでは 0.0.0.0 が設定されます。	いいえ（デフォルト：127.0.0.1）
CONDUIT_S2S_SECRET	HTTP 用のサービス間シークレット。/mcp には有効な X-Gateway-S2S ヘッダーが必要です。この値が空の場合、HTTP サーバーはゼロ以外の終了コードで終了します。	HTTP の場合は必須
MCP_ALLOW_INSECURE_DEV	1 に設定すると、CONDUIT_S2S_SECRET がなくても HTTP を起動します。警告をログに記録し、S2S チェックをスキップします。ローカル開発専用です。	いいえ
AUTH_MODE	ヘッダーベース認証を使用する場合は gateway に設定します	いいえ
LOG_LEVEL	ログレベル：debug、info、warn、error	いいえ（デフォルト：info）

ゲートウェイモード

AUTH_MODE=gateway の場合、サーバーは HTTP ヘッダーから認証情報を読み取り、process.env にはフォールバックしません。

• X-Blackpoint-API-Token → API トークン（必須。ヘッダーがない場合は HTTP 401）
• X-Blackpoint-Base-Url → リクエストごとのベース URL（BLACKPOINT_BASE_URL と同じ方法で正規化されます）。ヘッダーがない場合、プロセス環境は使用されません。

これにより、マルチテナントゲートウェイでリクエストごとの認証が可能になります。

HTTP では CONDUIT_S2S_SECRET も必要です。すべての /mcp リクエストには、そのシークレットに対する有効な X-Gateway-S2S ヘッダーが必要です。ヘッダーがない、または無効な場合、ベンダーの認証情報を読み取る前に HTTP 401 が返されます。CONDUIT_S2S_SECRET が空の場合、プロセスはエラーをログに記録し、/mcp を提供せずにゼロ以外の終了コードで終了します。MCP_ALLOW_INSECURE_DEV=1 を設定すると、警告をログに記録して起動します。ローカル開発以外では使用しないでください。シークレットがログに記録されることはありません。

GET /、GET /health、GET /healthz は認証不要の稼働確認エンドポイントのままで、認証情報を読み取りません。stdio トランスポートでは S2S シークレットを使用しません。

使用方法

スタンドアロンモード（stdio）

# Set credentials
export BLACKPOINT_API_TOKEN="your-api-token"

# Run the server
blackpoint-mcp

ゲートウェイモード（HTTP）

export AUTH_MODE=gateway
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8080
export CONDUIT_S2S_SECRET="your-s2s-secret"
# Optional. Unset binds to 127.0.0.1.
# export MCP_HTTP_HOST=127.0.0.1

blackpoint-mcp

シークレットを使用しないローカル開発（安全ではありません。警告がログに記録されます）：

export MCP_TRANSPORT=http
export MCP_ALLOW_INSECURE_DEV=1

blackpoint-mcp

ツール呼び出しの例

// Start by checking available domains
await tools.call("blackpoint_status");

// Navigate to assets domain
await tools.call("blackpoint_navigate", { domain: "assets" });

// List device assets for one tenant (tenantId is sent as x-tenant-id)
await tools.call("blackpoint_assets_list", { 
  class: "DEVICE",
  tenantId: "tenant_123",
  pageSize: 10 
});

// Get specific asset details
await tools.call("blackpoint_assets_get", { 
  id: "asset_12345",
  tenantId: "tenant_123"
});

// Return to navigation
await tools.call("blackpoint_back");

API の対応状況

✅ 実装済み

ドメイン	ツール	説明
tenants	list, get	顧客テナント管理
assets	list, get, relationships, search	資産のインベントリと関係
detections	list, get	アラートグループ（GET /alert-groups、skip/take、ステータスは OPEN または RESOLVED）。ツール名に変更はありません。
vulnerabilities	list, scans_list, darkweb_list, external_list	脆弱性管理、ダークウェブ、外部公開

📋 実装予定

ドメイン	ステータス	備考
partners	SDK 対応済み	アカウント管理 - 実装準備完了
alerts	モデルのみ	CompassOne ラッパーでは API ハンドラーを利用できません
tickets	モデルのみ	CompassOne ラッパーでは API ハンドラーを利用できません
cloud_security	SDK 対応済み	M365/Google/Cisco のオンボーディング - 実装準備完了
notifications	SDK 対応済み	連絡先グループとチャネル - 実装準備完了

パートナーとテナントのスコープ

CompassOne は階層型のスコープを使用します：パートナー → テナント → 資産

• パートナートークンは、関連するすべてのテナントにアクセスできます
• テナントスコープのトークンは、特定の顧客に限定されます
• テナントをまたぐ操作を避けるため、常に tenantId パラメーターを指定してください

エラー処理

サーバーは構造化されたエラーレスポンスを提供します。

{
  "content": [{ 
    "type": "text", 
    "text": "Failed to list assets: Authentication failed" 
  }],
  "isError": true
}

よくあるエラーの状況：

• 401 / 403：API キーが無効であるか、そのアカウントに対象リソースへのアクセス権がありません
• 404：ベース URL またはパスが間違っています（稼働中の API は https://api.blackpointcyber.com/v1 です）
• レート制限：指数バックオフによる自動再試行
• 検証：パラメーターが無効であるか、必須フィールド（class、tenantId）がありません

失敗時には、HTTP ステータス、メソッド、パス、レスポンス本文がログに記録されます。ベアラートークンはログから伏せられます。

レート制限

基盤となる SDK は自動レート制限を実装しています。

• デフォルト：API キーごとに 15 分間で 2000 リクエスト
• 429 の処理：Retry-After ヘッダーに従います
• バックオフ：後続のリクエストでは指数バックオフを行います

Docker

# Build
docker build -t blackpoint-mcp .

# Run in gateway mode. The image sets MCP_HTTP_HOST=0.0.0.0 and refuses to
# start until CONDUIT_S2S_SECRET is set. Publish the port on loopback.
docker run -p 127.0.0.1:8080:8080 \
  -e AUTH_MODE=gateway \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_PORT=8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  blackpoint-mcp

開発

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test
npm test

# Lint
npm run lint

セキュリティに関する考慮事項

API アクセス要件

• API アクセスには CompassOne パートナー契約が必要です
• マルチテナント操作には パートナーティアの認証情報が必要です
• テナント固有のアクセスには スコープ付きトークンを推奨します

破壊的な操作

以下の操作には、実装時に確認が必要です。

• 資産の隔離／対応アクション
• アクションを伴うチケットステータスの変更
• アラートの確認／クローズ
• 修復ワークフロー

これらは、誤操作を防ぐために elicitConfirmation パターンを使用します。

トラブルシューティング

よくある問題

ツールが表示されない：

• BLACKPOINT_API_TOKEN が設定されていることを確認してください
• トークンに適切なスコープがあることを確認してください
• CompassOne API へのネットワーク接続を確認してください

ゲートウェイモードが動作しない：

• AUTH_MODE=gateway が設定されていることを確認してください
• CONDUIT_S2S_SECRET が設定されていることを確認してください（空の場合、MCP_ALLOW_INSECURE_DEV=1 が設定されていない限り、HTTP は終了します）
• X-Gateway-S2S と X-Blackpoint-API-Token が渡されていることを確認してください
• クライアントがバインドアドレス（デフォルトでは 127.0.0.1）に接続できることを確認してください

レート制限：

• ログで 429 レスポンスを監視してください
• リクエスト頻度を下げることを検討してください
• トークンが複数のインスタンスで共有されていないことを確認してください

デバッグログ

export LOG_LEVEL=debug
blackpoint-mcp

ヘルスチェック

GET /、GET /health、GET /healthz は認証不要で、認証情報を読み取りません：

curl -f http://127.0.0.1:8080/health

認証済み MCP 呼び出し

CONDUIT_S2S_SECRET が設定されている場合、/mcp には X-Gateway-S2S が必要です。ゲートウェイモードでは、X-Blackpoint-API-Token も必要です：

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: <gateway-signed header>" \
  -H "X-Blackpoint-API-Token: your-token" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "id": 1, "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl", "version": "0.0.0"}}}'

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature-name
3. 変更を加え、テストを追加します
4. 新しい機能にはドメインハンドラーパターンに従ってください
5. プルリクエストを送信します

詳しいガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

Apache-2.0 — 詳細については LICENSE をご覧ください。