Avanan MSP (Legacy SmartAPI)

avanan-legacy-mcp

smart-api-production-*.avanan.net 上のレガシー Avanan SmartAPI向け MCP サーバーです： MSP テナント管理と、テナントごとのセキュリティ（イベント、エンティティ、例外、修復）に対応しています。 Check Point Infinity Portal HEC API を対象とする avanan-mcp とは別のものです。

Avanan MSP SmartAPI Reference Guide（2026年7月22日） およびAvanan SmartAPI Reference Guide（2024年2月）を実装しています：

グループ	ツール
診断	avanan_test_connection（認証ハンドシェイク、キーのスコープ、MSP アクセスの確認。最初に実行してください）、avanan_list_scopes
セキュリティイベント	avanan_query_events、avanan_get_event
保護対象エンティティ	avanan_search_emails、avanan_get_email
例外	avanan_list_exceptions、avanan_get_exception、avanan_add_exception、avanan_update_exception、avanan_delete_exception
修復	avanan_quarantine_events、avanan_restore_events、avanan_quarantine_emails、avanan_restore_emails、avanan_get_task_status
子 MSP	avanan_list_msp_partners、avanan_create_msp_partner、avanan_delete_msp_partner
MSP ユーザー	avanan_list_msp_users、avanan_get_msp_user、avanan_create_msp_user、avanan_update_msp_user、avanan_delete_msp_user
顧客テナント	avanan_list_tenants、avanan_get_tenant、avanan_create_tenant、avanan_delete_tenant
ライセンス	avanan_list_licenses、avanan_list_addons、avanan_assign_license
使用状況	avanan_get_monthly_usage、avanan_get_daily_usage

機能

• インタラクティブなテナントカード（MCP Apps、SEP-1865）：avanan_get_tenant は MCP Apps ホスト（Claude Desktop/web）でインタラクティブなカードとして表示され、ドメイン、ステータス、デプロイモード、ライセンスパッケージ、保護対象ユーザー、PoC の日付、アドオンを示します。このカードは読み取り専用で、デフォルトでは中立的なデザインです。window.__BRAND__ の挿入または MCP_BRAND_* 環境変数（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）でブランド設定できます。他のホストでのプレーン JSON の動作に変更はありません。ui/ の編集後に npm run build:ui を実行し、埋め込みカード HTML を再ビルドしてください。

設定

環境変数	必須	説明
AVANAN_CLIENT_ID	stdio および AUTH_MODE=env の場合	SmartAPI クライアント ID（x-av-app-id として送信されます）。MSP または顧客テナントのキーです。下記を参照してください。
AVANAN_CLIENT_SECRET	stdio および AUTH_MODE=env の場合	SmartAPI クライアントシークレットです。リクエストへの署名にのみ使用され、ネットワーク上に送信されることはありません。
AVANAN_REGION	いいえ	us（デフォルト） | eu | ca | ap | euw2 | aps1。Avanan はリージョンごとに 1 つのキーを発行します。認証情報ではありません。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http。
AUTH_MODE	いいえ	env（デフォルト）または gateway。コンテナーイメージと Compose は gateway を設定します。ゲートウェイモードでは、各リクエストに X-Avanan-Client-Id と X-Avanan-Client-Secret が必要です。AVANAN_* にフォールバックすることはありません。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレスです。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合にのみ適用されます。コンテナーイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP トランスポートのポートです（デフォルトは 8080）。
LOG_LEVEL	いいえ	debug | info | warn | error（デフォルトは info）。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレットです。空の場合、または既知のプレースホルダー（changeme、secret、your-s2s-secret およびその他のサンプル値）の場合、HTTP はエラーを記録してゼロ以外の終了コードで終了します。未設定の場合、Compose は起動しません。実際の値をコミットしないでください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用に 1 を設定します。プロセスは警告を記録し、X-Gateway-S2S を強制せず、127.0.0.1 のみでリッスンします。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は無視されます。プレースホルダーのシークレットは引き続き拒否されます。

.env.example をコピーしてください。CONDUIT_S2S_SECRET は空のままにしてください。

/health は認証不要のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET や X-Gateway-S2S は使用しません。

HTTP 認証

MCP_TRANSPORT=http かつ実際の CONDUIT_S2S_SECRET が設定されている場合、/health を除くすべてのリクエストに X-Gateway-S2S を含める必要があります。

t=<unix seconds>,v1=<hex>

v1 は、ASCII 文字列 t=<unix seconds>（ヘッダーの先頭にもある同じ t= プレフィックス）に対する HMAC-SHA256 です。キーには CONDUIT_S2S_SECRET を使用し、小文字の 16 進数 64 文字としてエンコードします。タイムスタンプはサーバーの時刻から 300 秒以内である必要があります。比較はタイミングセーフです。ヘッダーがない場合や無効な場合は 401 を返し、Avanan の認証情報にはアクセスしません。シークレットがログに記録されることはありません。

AUTH_MODE=gateway の場合、リクエストには X-Avanan-Client-Id と X-Avanan-Client-Secret（X-Avanan-Region は任意）も含める必要があります。これらのヘッダーのみが認証情報の取得元です。どちらか一方でも欠けているリクエストは 401 を返し、AVANAN_CLIENT_ID／AVANAN_CLIENT_SECRET にフォールバックしません。

AUTH_MODE=env の場合も、/mcp には有効な X-Gateway-S2S ヘッダーが必要です。リクエストにクライアントヘッダーが両方とも含まれていない場合、ベンダーの認証情報は環境変数から取得されます。

Docker

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、AUTH_MODE=gateway を設定します。ポートはループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、Avanan の認証情報はリクエストごとにヘッダーとして渡され、環境変数からは読み込まれません。

docker build -t avanan-legacy-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  avanan-legacy-mcp

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。また、AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開します。さらに、サービス環境変数に AVANAN_CLIENT_ID や AVANAN_CLIENT_SECRET を設定しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、そのうえで AVANAN_CLIENT_ID と AVANAN_CLIENT_SECRET を使用します。これはゲートウェイの Compose サービスとは別のものです。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e AVANAN_CLIENT_ID=your-client-id \
  -e AVANAN_CLIENT_SECRET=your-client-secret \
  -e AVANAN_REGION=us \
  -p 127.0.0.1:8080:8080 \
  avanan-legacy-mcp

シークレットを使わないローカル HTTP は開発専用です。MCP_HTTP_HOST が 0.0.0.0 でも、127.0.0.1 にバインドされ、警告がログに記録されます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

openssl rand -hex 32 でシークレットを生成してください。CONDUIT_S2S_SECRET にプレースホルダーを残さないでください。起動時に未設定として扱われ、終了します。

サーバーはトークンのハンドシェイクを自ら実行します。GET /v1.0/auth を呼び出し、クライアント ID ごとに1時間有効な JWT をキャッシュして、有効期限の1分前に更新します。

重要

MSP 管理ツールには MSP API キーが必要です。これらはセルフサービスでは取得できません。Check Point／Avanan Support に申請し、Avanan を販売代理店経由で購入している場合はその販売代理店を通じて、リージョンごとに1つ発行してもらいます。顧客テナント内で生成したキーでも認証自体は成功しますが、その場合、すべての /msp/* エンドポイントは 403 MSP endpoint, access denied を返します。セキュリティツール（イベント、エンティティ、例外、修復）は、どちらの種類のキーでも動作します。avanan_test_connection で、どちらの種類のキーを持っているか確認できます。

MSP キーを使うと、セキュリティツールで管理対象のすべての顧客を対象にできます。特定の顧客を対象にするには、avanan_list_scopes の値を使って、scopes（クエリと検索）または scope（アクション）を渡してください。

親 MSP は、Check Point のリファレンスクライアントと同様に、オプションの MSPId 引数（使用状況ツールでは msp_ids）を指定して、一覧取得と作成の呼び出しを子 MSP に限定できます。

認証の詳細

ワイヤ形式は、2026年9月に稼働中の米国エンドポイントに対して検証され、tests/client.test.ts で固定されています。リファレンスガイドとは次の2点が異なります。

• x-av-date の末尾に Z を付けてはいけません（2026-09-09T16:49:12.123）。ドキュメントに記載されている .000Z 形式を使うと、API は HTTP 500 を返します。
• x-av-sig は、16進数形式の sha256(base64(reqId + clientId + date + path?query + secret)) です。/auth 呼び出しの場合に限りパスは省略され、/auth のレスポンス本文は JSON ではなく生の JWT です。

どちらも Check Point のリファレンス client.py と一致します。

ビルド

npm install
npm run build
npm start

リージョン別エンドポイント

リージョン	ベース URL
us	https://smart-api-production-1-us.avanan.net
eu	https://smart-api-production-1-eu.avanan.net
ca	https://smart-api-production-1-ca.avanan.net
ap	https://smart-api-production-5-ap.avanan.net
euw2（英国）	https://smart-api-production-1-euw2.avanan.net
aps1（インド）	https://smart-api-production-1-aps1.avanan.net

すべてのエンドポイントは /v1.0/msp/... 配下にあります。