PentaTrail Logo
v2Updated 2026-05-02

Customer API

PentaTrail の CTEM データに REST API / MCP 経由でアクセスするためのリファレンスドキュメント。ctem:read 前提の公開 read-only API として、OpenAPI 仕様から landing を生成しています。

認証

すべてのリクエストに API Key を Bearer トークンとして含めてください。API Key は PentaTrail Dashboard の Settings > API Keys から発行できます。

リクエスト例
curl -H "Authorization: Bearer ptk_your_api_key_here" \
  "https://api.pentatrail.co/v1/ctem/domains"

スコープ

API Key には ctem:read スコープが必要です。

ctem:read

OpenAPI

OpenAPI JSON は landing と同じ source-of-truth データから自動生成されます。仕様と表示のズレを避けるため、ここで公開している内容が正本です。

OpenAPI JSON
curl -s "https://pentatrail.co/api/openapi/customer-api-v2" | jq .

この spec は landing のデータソースと同じ正本から生成されます。

MCP セットアップ

Model Context Protocol (MCP) Model Context Protocol (MCP) 対応クライアント（Claude Code、Claude Desktop 等）から PentaTrail の read-only CTEM データにアクセスできます。

起動
npx @pentatrail/mcp-server
Claude Code / Claude Desktop 設定
{
  "mcpServers": {
    "pentatrail": {
      "command": "npx",
      "args": ["@pentatrail/mcp-server"],
      "env": {
        "PENTATRAIL_API_KEY": "ptk_your_api_key_here",
        "PENTATRAIL_API_URL": "https://api.pentatrail.co"
      }
    }
  }
}

PENTATRAIL_API_URL は https://api.pentatrail.co を指定してください。

Read エンドポイント

CTEM データの読み取り。すべて ctem:read スコープが必要です。現在 9 route を公開しています。

GET/v1/ctem/domainsctem:read

監視対象ドメインの一覧を取得します。

GET/v1/ctem/hostsctem:read

ドメインに紐づくホスト一覧を取得します。ポート数・テクノロジー数・脆弱性数の集計値付き。

domain_id必須オリジンドメイン ID (UUID)
pageページ番号 (default: 1)
limit1ページあたりの件数 (default: 50, max: 100)
host_statusフィルタ: active, discovered, dns_only, inactive, third_party
searchFQDN で検索
order_byソート: fqdn, first_seen_at, last_seen_at, host_status
ascendingtrue/false (default: true)
GET/v1/ctem/findingsctem:read

脆弱性（Finding）一覧を取得します。デフォルトは脅威ディスカバリレベル（TDL）順。アクティブホスト上の Finding のみ返却されます。

domain_id必須オリジンドメイン ID (UUID)
pageページ番号
limit件数 (max: 100)
statusフィルタ: open, in_progress, closed, accepted
severityフィルタ: critical, high, medium, low, info
priority_keyTDL フィルタ: tdl5, tdl4, tdl3, tdl2, tdl1, info
target_fqdn対象 FQDN でフィルタ
source_filterall, passive_only, deep_only
vuln_id脆弱性 ID で完全一致フィルタ
searchタイトル・vuln_id・target で検索
order_byソート: effective_priority_rank, cvss, severity_order, first_seen_at, last_seen_at
ascendingtrue/false (default: true)
GET/v1/ctem/assets/countsctem:read

アセット種別ごとの件数を取得します（ホスト、IP、ポート、テクノロジー、バケット、URL、脆弱性）。

domain_id必須オリジンドメイン ID (UUID)
GET/v1/ctem/findings/severityctem:read

オープンな Finding を脅威ディスカバリレベル（TDL）別にカウントします。アクティブホスト上の Finding のみ。

domain_id必須オリジンドメイン ID (UUID)
GET/v1/ctem/scoresctem:read

ドメインのライブスコア（アセット件数 + 脆弱性の severity/status 別内訳）を取得します。

domain_id必須オリジンドメイン ID (UUID)
GET/v1/ctem/scores/trendctem:read

スコアの時系列推移（スナップショット）を取得します。

domain_id必須オリジンドメイン ID (UUID)
days遡る日数 (7-365, default: 56)
GET/v1/ctem/portsctem:read

検出されたオープンポートの一覧を取得します。

domain_id必須オリジンドメイン ID (UUID)
pageページ番号
limit件数 (max: 100)
searchホスト名・サービス名で検索
source_typesource_type でフィルタ
portポート番号でフィルタ
protocoltcp / udp
order_byソート: target, port, service, first_seen_at, last_seen_at
GET/v1/ctem/techctem:read

検出されたテクノロジースタックの一覧を取得します。

domain_id必須オリジンドメイン ID (UUID)
pageページ番号
limit件数 (max: 100)
searchテクノロジー名・ホスト名で検索
source_typesource_type でフィルタ
tech_categoryカテゴリでフィルタ
tech_nameテクノロジー名でフィルタ
order_byソート: tech_name, tech_category, target, first_seen_at, last_seen_at

エラーコード

コードHTTP説明
PT_API_AUTH_INVALID401無効または期限切れの API Key
PT_API_AUTH_IP_DENIED403許可されていない IP アドレス
PT_API_SCOPE_DENIED403API Key のスコープが不足
PT_API_FORBIDDEN403アクセス権限がないリソース
PT_API_NOT_FOUND404リソースが見つからない
PT_API_ALREADY_EXISTS409リソースが既に存在する
PT_API_RATE_LIMITED429レート制限超過（リトライ可能）
PT_API_INVALID_PARAM400パラメータが不正
PT_API_INVALID_STATUS400無効なステータス値
PT_API_INVALID_CATEGORY400無効な除外カテゴリ
PT_API_INTERNAL500サーバー内部エラー（リトライ可能）

レート制限

API Key ごとに 100 リクエスト / 分のレート制限があります。制限超過時は 429 が返却されます。

レスポンスヘッダー

X-RateLimit-Limit制限値（100）
X-RateLimit-Remaining残りリクエスト数
X-RateLimit-Resetリセットまでの秒数

Correlation ID

すべてのレスポンスに correlation_id が含まれます（形式: pt_<uuid>）。問題発生時のサポート問い合わせにご利用ください。