Umbrella: Enforcement API の使用例 (活用編)

[tkitahar]

• 1. はじめに
• 2. セキュリティ イベントの送信
• 3. その他のアクション
• 4. 参考情報

※ 2018 年 4 月 13 日現在の情報をもとに作成しています

1. はじめに

前回の記事では Umbrella Enforcement API の概要と事前準備を取り上げました。今回の記事では、実際に Umbrella Enforcement API に対してセキュリティ イベントを送信し、その中に含まれるドメインがブロックされるまでの流れを説明します。

2. セキュリティ イベントの送信

では、Linux 端末から下記の curl コマンドを実行し、実際に Umbrella Enforcement API に対してセキュリティ イベントを送信します。

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '{
    "alertTime": "2018-04-13T09:00:00Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "■■■.com",
    "dstUrl": "http://■■■.com/a-bad-url",
    "eventTime": "2018-04-13T09:00:00Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}'

上記のコマンドを簡単に説明すると、引数に Umbrella Dashboard からコピーした URL を指定し、-v で詳細な出力を設定し、-X で POST メソッドを指定し、-H で JSON 形式を指定し、-d で実際のイベントの内容を指定しています。

なお、イベント内の各項目の詳細については、以下の公開文書に情報があります。

Umbrella Enforcement API - Generic Event Format Field Descriptions

https://enforcement-api.readme.io/reference#generic-event-format-field-descriptions2

以下は実際の実行結果 (一部抜粋) ですが、レスポンス コードとして 202 Accepted が返っており、サーバーが問題なく受信できたことが分かります。

* upload completely sent off: 338 out of 338 bytes
< HTTP/1.1 202 Accepted

その後、Umbrella はこのセキュリティ イベントに含まれるドメインが条件を満たしているかを確認し、問題がなければ登録を行います。

Umbrella Enforcement API – Domain Acceptance Process

https://enforcement-api.readme.io/reference#domain-acceptance-process2

なお、無事に登録されたドメインは、Umbrella Dashboard の Settings の Integrations に作成した「Security Product」のエントリーから確認できます。

最後に今回のテスト用のポリシーが適用されたクライアント PC で Web ブラウザを開き、当該のドメインにアクセスすると、以下のようにブロック ページが表示されます。

また、Security Activity レポートにもブロックされた旨が記録されます。

3. その他のアクション

API に対して行うことができるアクションは、セキュリティ イベントの送信を含め 3 つあると前回述べました。本項では、残りの 2 つの実行例についても紹介します。

(ドメインの一覧表示)

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X GET

セキュリティ イベントの送信では URL の中に events という文字列が含まれていましたが、ドメインの一覧表示では、そこが domains に変わっています。また、GET メソッドを使用しているため、-d オプションは使われません。

正常に処理が行われるとレスポンス コード 200 OK が返ります。詳細については以下の公開文書に情報があります。

Umbrella Enforcement API – GET /Domains

https://enforcement-api.readme.io/reference#domains2

(ドメインの削除)

curl 'https://s-platform.api.opendns.com/1.0/domains/■■■.com?customerKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X DELETE

URL には実際に削除したいドメインを含めます。また、DELETE メソッドを指定し、これも -d オプションを使いません。

正常に処理が行われるとレスポンス コード 204 No Content が返ります。詳細については以下の公開文書に情報があります。

Umbrella Enforcement API – DELETE /Domains 

https://enforcement-api.readme.io/reference#domain2

4.      参考情報

Cisco Umbrella: The Umbrella Enforcement API for Custom Integrations

https://support.umbrella.com/hc/en-us/articles/231248748