Telivy

Telivy MCP サーバー

MSP 向けの Telivy セキュリティ評価 API 用 MCP サーバーです。外部（サーフェス）スキャン、詳細スキャンによるリスク評価、デバイスインベントリ、M365／Google Workspace ユーザーの露出状況、PII の概要、検出事項ごとの詳細を、AI アシスタントおよび WYRE Conduit ゲートウェイ向けに提供します。

認証

Telivy は、Telivy Portal（Account > Integrations）で生成する単一の静的 API キーを使って認証します。OAuth2/Auth0 の暗黙的フローもありますが、API キーを使う方法がより簡単で、MSP の統合でも使われているため、このコネクターではその方法を使用します。キーは x-api-key HTTP ヘッダーで送信されます。

設定

.env.example をコピーし、以下の変数を設定します。例の CONDUIT_S2S_SECRET は空のままにし、openssl rand -hex 32 で実際の値を生成してください。

Env var	説明
TELIVY_API_KEY	Telivy が発行した API キーです。stdio および AUTH_MODE=env の HTTP で必須です。ゲートウェイモードでは読み込まれません。
MCP_TRANSPORT	stdio（デフォルト）または http です。
AUTH_MODE	env（Docker 外でのデフォルト。TELIVY_API_KEY を読み込みます）または gateway（認証情報はリクエストごとに X-Telivy-Api-Key で渡されます）。イメージと Compose ファイルのデフォルトは gateway です。ゲートウェイモードでは、このヘッダーがない場合に 401 を返し、TELIVY_API_KEY へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP で必須です。/mcp への X-Gateway-S2S を照合する HMAC シークレットです。値が空、または既知のプレースホルダー（changeme、secret、your-s2s-secret、および src/http.ts 内のその他の例示値）の場合、プロセスはエラーをログに記録して、ゼロ以外の終了コードで終了します。この値がログに記録されることはありません。未設定の場合、Compose は起動しません。
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしで HTTP を起動するには、正確に 1 に設定します。警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみで待ち受けます。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）が設定されている場合、起動を拒否します。既知のプレースホルダーシークレットも引き続き拒否されます。ローカル開発専用です。
MCP_HTTP_HOST	MCP_TRANSPORT=http の場合のバインドアドレスです。デフォルトは 127.0.0.1 です。シークレットが設定されている場合、この値（0.0.0.0 を含む）がそのまま適用されます。コンテナーイメージでは 0.0.0.0 が設定されています。シークレットがない場合、安全でない開発用のバイパスによって 127.0.0.1 に強制されます。
MCP_HTTP_PORT	HTTP ポートです。デフォルトは 8080 です。
LOG_LEVEL	debug | info（デフォルト）| warn | error です。

/health と /healthz は認証不要のままで、認証情報も読み込みません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。検証は src/s2s-verify.ts の verifyS2sHeader で行います。ヘッダーの値は t=<unix seconds>,v1=<hex> で、<hex> は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> をそのまま HMAC-SHA256 で処理した値（小文字の 16 進数 64 文字）です。タイムスタンプはサーバーの時刻から 300 秒以内である必要があります。ヘッダーがない、または無効な場合は、Telivy API キーを読み込む前に HTTP 401 を返します。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Telivy-Api-Key: $TELIVY_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-Telivy-Api-Key も必要です。このヘッダーのみがリクエストの認証情報として使われます。AUTH_MODE=env では、有効な X-Gateway-S2S ヘッダーが引き続き必要で、その後、環境変数の TELIVY_API_KEY が使用されます。

ツール

外部スキャン

• telivy_list_external_scans - 検索、並べ替え、ページネーションに対応して、外部（サーフェス）スキャンの一覧を取得します。
• telivy_get_external_scan - 評価 ID を指定して、単一の外部スキャンを取得します。
• telivy_list_external_scan_findings - 外部スキャンの検出事項一覧を取得します。
• telivy_get_external_scan_finding - スラッグを指定して、単一の外部スキャンの検出事項の詳細を取得します。
• telivy_get_breach_data - 外部スキャンのドメインで検出された侵害記録を取得します。

リスク評価

• telivy_list_risk_assessments - ディープスキャンのリスク評価を検索／並べ替え／ページネーション／ステータスフィルター付きで一覧表示します。
• telivy_get_risk_assessment - IDを指定して単一のリスク評価を取得します。
• telivy_list_risk_assessment_devices - リスク評価に関連するすべてのディープスキャンデバイスを一覧表示します。
• telivy_get_risk_assessment_device - IDを指定して単一のディープスキャンデバイスを取得します。
• telivy_get_risk_assessment_scan_status - すべてのデバイスのスキャン完了状況を取得します。
• telivy_list_m365_users - ログイン状況とMFA情報を含むMicrosoft 365ユーザーアカウントを取得します。
• telivy_list_gws_users - ログイン状況と2SV状況を含むGoogle Workspaceユーザーアカウントを取得します。
• telivy_get_pii_summary - すべてのデバイスにわたるPIIの露出状況の概要を取得します。

検出結果、エージェントのバージョン、リスクの進捗

• telivy_get_agent_versions - 最新のディープスキャンエージェントのバージョン（Windows／Mac）を取得します。
• telivy_get_finding - スラッグ（例：TYPO_SQUATTING、PERSONAL_EMAILS）で最上位の検出結果の詳細を取得します。
• telivy_get_risk_progress - 2つのスキャンタイムスタンプグループを比較した進捗レポート（新規／解決済み／再発／未解決の検出結果）を取得します。

対象範囲

これは読み取り専用のMSPフリート／セキュリティ可視化機能を提供するv1であり、コネクターの対象を監視／可視化に限定し、プロビジョニングに関する書き込み操作は後回しにする今回の方針に沿っています。現時点で明示的に対象外となるものは次のとおりです。

• すべての書き込みエンドポイント：外部スキャンとリスク評価の作成または更新、rescan-all、uninstall-all、単一デバイスの再スキャン、convert-to-risk-assessment、監視設定の更新。これらは読み取り専用の可視化ではなく、プロビジョニング／破壊的な操作です。
• バイナリ形式のレポートダウンロードエンドポイント（GET .../external-scans/{id}/report、GET .../risk-assessments/{id}/report） - ファイルを返すものであり、このコネクターのツールが扱う構造化JSONではありません。
• GET /api/v1/security/risk-assessments/{id}/domain-change-preview - 実行中のドメイン変更書き込み操作をプレビューするエンドポイントです。プレビュー対象の書き込み操作と同様に、対象外です。

需要があれば、後続で追加できます。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

CONDUIT_S2S_SECRETが設定されるまで、HTTPサーバーは起動しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

サービス間シークレットが設定されていない状態でローカルHTTPを使用すると、127.0.0.1のみにバインドされ、警告がログに記録されます。イメージではMCP_HTTP_HOST=0.0.0.0が設定されるため、この回避策を使うには、その変数もループバックアドレスにするか、未設定にする必要があります。ループバック以外のホストを指定すると、起動は終了します。

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

イメージはコンテナー内で0.0.0.0をリッスンし、デフォルトでAUTH_MODE=gatewayを使用します。ポートをループバックに公開し、実際のS2Sシークレットを渡してください。ゲートウェイモードでは、Telivy APIキーは各リクエストのX-Telivy-Api-Keyとして渡され、環境変数からは読み込まれません。

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

Composeは、CONDUIT_S2S_SECRETが未設定または空の場合は起動を拒否し、AUTH_MODEをデフォルトでgatewayに設定して、127.0.0.1:8080:8080を公開します。また、TELIVY_API_KEYは設定しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナントHTTP（AUTH_MODE=env）でもS2Sシークレットが必要です。そのうえで、TELIVY_API_KEYを使用します。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e TELIVY_API_KEY="$TELIVY_API_KEY" \
  -p 127.0.0.1:8080:8080 \
  telivy-mcp