TISC RPZ API
TISC RPZ API は、ドメインと IP アドレスを応答ポリシーゾーン (RPZ) 形式でエクスポートするためのエンドポイントを提供します。
この API を使用して、ファイアウォール、DNS サーバー、または RPZ ポリシーをサポートするその他のセキュリティシステムで使用するために、フィルタリングされた脅威インテリジェンスデータを RPZ 形式で取得します。RPZ は、ドメインと IP アドレスをブロック、許可、またはリダイレクトするために使用されます。API 応答は、セキュリティワークフローへの簡単な統合を促進するために text/plain として提供されます。
この API には、ServiceNow Store で利用可能な 脅威インテリジェンスセキュリティセンター アプリケーションが必要です。
TISCの詳細については、「Threat Intelligence Security Center」を参照してください。
この API は sn_sec_tisc 名前空間で実行されます。呼び出し元ユーザーには sn_sec_tisc.api_obs_read_access ロールが必要です。
この API の現在のバージョンは v1 です。
TISC RPZ - 投稿 /sn_sec_tisc/rpz_export
ドメインと IP アドレスを応答ポリシーゾーン (RPZ) 形式でエクスポートします。
*.<domain_name>) を生成できます。ワイルドカードエントリを使用すると、ドメインのすべてのサブドメインを柔軟にブロックまたは許可できます。この機能を有効にするには、 脅威インテリジェンスセキュリティセンター のドメインレコードに移動します。[詳細] タブの [TISC タグと分類] セクションで、[分類] フィールドに入力します。- [ 分類を選択 ] フィールドで、[ RPZ ドメイン] を選択します。
- [ 分類値を追加 ] フィールドで、[ ワイルドカードエントリを追加] を選択します。
URL 形式
バージョニングされた URL: /api/sn_sec_tisc/{api_version}/rpz_export
デフォルト URL: /api/sn_sec_tisc/rpz_export
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| feed_type | 必須です。エクスポートする観測事象のタイプ。 有効な値 (大文字と小文字の区別なし):
データタイプ：文字列 |
| observable_filters | 観測事象に適用するフィルター。フィルター基準に一致する観測事象のみが応答に返されます。 データタイプ: オブジェクト デフォルト:空のオブジェクト (フィルターが適用されていません) |
| observable_filters.boolean_operator | フィルター条件に使用するブール演算子。 有効な値：
データタイプ：文字列 |
| observable_filters.filters | 観測事象に適用するフィルター。 各フィルターオブジェクトは、シンプルまたは複雑にすることができます。
データタイプ：オブジェクトのアレイ |
| observable_filters.filters.field_name | 観測事象のフィルタリングに使用するフィールドの名前。 有効な値：
データタイプ：文字列 |
| observable_filters.filters.field_value | フィールドの値。 選択フィールドの場合、値は表示値ではなく内部値である必要があります。日付/時刻フィールドの場合、値は UTC タイムゾーンの ISO 形式である必要があります。 注: ISEMPTY 演算子または ISNOTEMPTY 演算子を使用する場合、このパラメーターは必要ありません。 データタイプ：文字列 |
| observable_filters.filters.operator | フィルターに使用する演算子。 演算子の詳細については、「Operators available for filters and queries」を参照してください。 フィルターフィールドのデータタイプによって、有効な演算子が決まります。次の演算子は、データタイプごとに有効です。
データタイプ：文字列 |
| page_size | API 応答で返される観測事象の数を制限します。ページネーションに使用されます。 データタイプ：数値 デフォルト：1000 最大値:10,000 |
| page_token | 現在のページの観測事象データを取得するために使用されます。 最初のページを取得するには、このパラメーターを省略するか、このパラメーターの値を空の文字列にする必要があります。次の要求で次のページを取得するには、応答ヘッダーの X-Next-Page-Token 値をこのパラメーターの値として使用します。 データタイプ：文字列 デフォルト:空の文字列 |
| policy | 必須です。ドメインまたは IP アドレスに対して実行するアクション。 有効な値 (大文字と小文字の区別なし):
データタイプ：文字列 |
| soa_email | 必須です。ゾーンのアドミン連絡先メール。ユーザー名とドメインを区切るには、@ 記号の代わりにドット (.) を使用します (admin@example.com の代わりに admin.example.com. など)。このパラメーターは DNS SOA レコードに含まれています。データタイプ：文字列 |
| soa_expiry | 必須です。有効期限。プライマリサーバーが到達不能になった場合に、セカンダリサーバーがゾーンデータを使用し続ける最大時間を決定します。 データタイプ：数値 単位：秒 最小:0 最大:4294967295 |
| soa_minimum_ttl | 必須です。否定的な回答に対する最小存続時間。リゾルバーが否定的な応答をキャッシュする期間を決定します。 注:
このパラメーターは、有効な要求本文に常に必要ですが、ポリシーが NXDOMAIN、NODATA、または LOCAL-DATA の場合にのみ使用されます。他のポリシーの場合、このパラメーターは効果がありません。 データタイプ：数値 単位：秒 最小:0 最大:4294967295 |
| soa_named_server | 必須です。ゾーンのプライマリネームサーバー。ドット (.) で終わる完全修飾ドメイン名 (FQDN) (ns1.example.com など) である必要があります。このパラメーターは、DNS SOA レコードの最初のフィールドです。データタイプ：文字列 |
| soa_named_server_alt | 冗長性のための代替ネームサーバー。 データタイプ：文字列 |
| soa_refresh | 必須です。リフレッシュ間隔。セカンダリ DNS サーバーがプライマリサーバーでゾーンの更新を確認する頻度を決定します。 データタイプ：数値 単位：秒 最小:0 最大:4294967295 |
| soa_retry | 必須です。再試行間隔。セカンダリサーバーが失敗したゾーン転送を再試行するまでの待機時間を決定します。 データタイプ：数値 単位：秒 最小:0 最大:4294967295 |
| soa_ttl | 必須です。RPZ レコードの存続時間 (TTL)。更新をチェックする前にリゾルバーがレコードをキャッシュする期間を決定します。 データタイプ：数値 単位：秒 最小:0 最大:4294967295 |
| walled_garden | リダイレクトターゲットとして使用する IP アドレスまたはドメイン名。 ウォールドガーデン (通常はセキュリティ、コンプライアンス、または情報提供の目的で、制御されたページまたはネットワークの場所) にユーザーをリダイレクトするために使用されます。 注:
policyが LOCAL-DATA の場合は必須です。他のポリシータイプには、このパラメーターを使用しないでください。データタイプ：文字列 |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。サポートされるタイプ：text/plain または application/json。 成功応答はプレーンテキストとして返され、エラー応答は JSON として返されます。 デフォルト： text/plain |
| 認証 | 基本的な。 API 認証と承認の詳細については、「 REST API」の「REST API セキュリティ」セクションを参照してください。 |
| Content-Type | 要求本文のデータ形式。application/json のみをサポートします。 |
| ヘッダー | 説明 |
|---|---|
| x-next-page-token | 次の API 要求でこの値を使用して、結果の次のページを取得します。この値を要求本文の page_token パラメーターに入力します。 このヘッダーが存在しない場合、それ以上のページは使用できません。 |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 400 | 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 403 | 禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。 |
| 429 | 要求が多すぎます。API 要求の数が API のレート制限を超えています。デフォルトでは、制限は 1 時間あたり 500 要求です。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| errorCode | 要求の HTTP ステータスコード。 |
| result | 要求の詳細。このパラメーターは、要求が失敗した場合にのみ返されます。 データタイプ: オブジェクト |
| result.error | エラー情報。 データタイプ: オブジェクト |
| result.error.detail | 要求が失敗した理由に関するその他の詳細。 データタイプ：文字列 |
| result.error.message | 要求が失敗した理由を含むエラーメッセージ。 データタイプ：文字列 |
| result.status | API 要求のステータス。このパラメーターは要求が失敗した場合にのみ返されるため、使用可能な値は failure のみです。 データタイプ：文字列 |
cURL 要求
この例では、選択したドメインを RPZ 形式でエクスポートし、ポリシーを NXDOMAIN として設定します。
curl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \
--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \
--data '{
"policy": "nxdomain",
"feed_type": "DOMAIN",
"soa_retry": 85,
"soa_expiry": 1,
"soa_minimum_ttl": 7,
"soa_refresh": 3600,
"soa_ttl": 7678,
"soa_named_server": "localhost.",
"soa_email": "root.localhost.",
"page_size": 100,
"page_token": "",
"observable_filters": {
"boolean_operator": "AND",
"filters": [
{
"field_name": "status",
"operator": "=",
"field_value": "active"
},
{
"boolean_operator": "OR",
"filters": [
{
"field_name": "threat_score",
"operator": ">=",
"field_value": "70"
},
{
"field_name": "confidence",
"operator": ">=",
"field_value": "50"
}
]
}
]
}
}'フィルター基準に一致するドメインを含む応答本文。
$TTL 7678;
@ SOA localhost. root.localhost. (1759835257654 3600 85 1 7)
IN NS localhost.
; The following Domain records will be blocked (NXDOMAIN):
domain autuo.xicp.net CNAME .
microsofta.byinter.net CNAME .
www.webserver.freetcp.com CNAME .
mongoles.3322.org CNAME .
imddos.my03.com CNAME .
weile3322b.3322.org CNAME .
*.weile3322b.3322.org CNAME .cURL 要求
この例は、無効なポリシー値を使用する要求を示しています。
curl --location 'https://instance.service-now.com/api/sn_sec_tisc/v1/rpz_export' \
--header 'Authorization: Basic YWJlbC50dXRlcjpTbm93QDEyMw==' \
--data '{
"policy": "LocalData",
"feed_type": "DOMAIN",
"soa_retry": 85,
"soa_expiry": 1,
"soa_minimum_ttl": 7,
"soa_refresh": 3600,
"soa_ttl": 7678,
"soa_named_server": "localhost.",
"soa_email": "root.localhost.",
"page_size": 100,
"page_token": "",
"observable_filters": {
"boolean_operator": "AND",
"filters": [
{
"field_name": "status",
"operator": "=",
"field_value": "active"
},
{
"boolean_operator": "OR",
"filters": [
{
"field_name": "threat_score",
"operator": ">=",
"field_value": "70"
},
{
"field_name": "confidence",
"operator": ">=",
"field_value": "50"
}
]
}
]
}
}'失敗した要求のエラー情報を含む応答本文。
{
"result": {
"status": "failure",
"error": {
"message": "Error occurred while processing request body.",
"detail": "Invalid policy: 'LocalData'. Supported values are: NXDOMAIN, DROP, NODATA, PASSTHRU, LOCAL-DATA, TCP-ONLY"
}
},
"errorCode": 400
}