Umbrella: Investigate API について

[tkitahar]

• 1. はじめに
• 2. Investigate API の使用方法
• 3. トラブルシューティング

※ 2021 年 3 月 30 日現在の情報をもとに作成しています

1. はじめに

本記事では、Umbrella Investigate のデータを API 経由で取得可能にする Investigate API について紹介します。

※ Investigate API を使用するには、Investigate API を含むサブスクリプション契約が必要となります

2. Investigate API の使用方法

Investigate API を使うと、Umbrella Investigate で確認できるいろいろな情報を取得できます。本項では、その中の「ドメインのステータスとカテゴリの取得」を通して、Investigate API の使用方法について説明します。

Umbrella Investigate REST API – Domain Status and Categorization

https://docs.umbrella.com/investigate-api/docs/domain-status-and-categorization-1

まず始めに、Investigate API を使用可能な組織に属しており、その組織の Full Admin の権限を持つアカウントを使って Umbrella Dashboard にログインします。ログイン後に別の組織の画面が表示されている場合は、当該の組織に切り替えてください。その後、メニューにある Investigate > APIキーをクリックします 。

「新しいトークンを作成」をクリックします。既に作ったものがある場合は、それをそのまま使っても問題ありません。

 

タイトルに任意の名前を入れて、「作成」をクリックします。

 

Investigate API を使用するために必要なアクセストークンが表示されますので、控えておきます。

では、cisco.com ドメインのステータスとカテゴリを API を通して取得してみます。API への HTTPS リクエストには以前の記事と同様に curl コマンドを使用します。

curl -X GET -H 'Authorization: Bearer XXXXXX' 'https://investigate.api.umbrella.com/domains/categorization/cisco.com'

※ XXXXXX は Access Token
※ Windows 版 curl の場合、(') シングルクォーテーションを (") ダブルクォーテーションにしないと動作しない場合があります

以下はこのコマンドの実行結果です。status にはドメインのステータス、具体的には -1 (悪意がある)、1 (安全)、0 (まだステータスは未設定) が入ります。また、security_categries にはセキュリティ カテゴリのコード、content_categories にはコンテンツ カテゴリのコードが入ります。

{"cisco.com":{"status":1,"security_categories":[],"content_categories":["25","32"]}}

なお、それぞれのコードの意味については、以下のリクエストで確認することが可能です。

curl -X GET -H 'Authorization: Bearer XXXXXX' 'https://investigate.api.umbrella.com/domains/categories/'

また、各カテゴリについて、コードではなく実際のカテゴリ名を表示させたい場合は、URL に ?showLabels を付けます。

curl -X GET -H 'Authorization: Bearer XXXXXX' 'https://investigate.api.umbrella.com/domains/categorization/cisco.com?showLabels'

すると、以下のように実行結果に実際のカテゴリ名が表示されます。

{"cisco.com":{"status":1,"security_categories":[],"content_categories":["Software/Technology","Business Services"]}}

上記以外の方法として、Tier 2 以上のユーザーであれば、POST メソッドで複数のドメイン情報を一度に取得できます。

curl -X POST -H 'Authorization: Bearer XXXXXX' 'https://investigate.api.umbrella.com/domains/categorization/' -d '["cisco.com","umbrella.com"]'

なお、Tier 1 ユーザーの場合、以下のエラー メッセージが表示されます。

Tier 1 does not have access to bulk endpoints

ここでいう Tier とは Investigate API のライセンスのレベルのことで、以下の公開文書にもあるとおり、Tier ごとに API に対して 1 秒間にリクエストできる回数が異なります。

Umbrella Investigate REST API – Requests

https://docs.umbrella.com/investigate-api/docs/requests-1

3. トラブルシューティング

Investigate API に限らず、API 使用時のトラブルシューティングには、HTTP レスポンスのステータス コードの確認が有効です。curl コマンドの場合、-i オプションで、HTTP レスポンスを表示させることが可能です。

例えば、Access Token が間違っている場合、ステータス コード 403 が返ります。

HTTP/1.1 403 Forbidden

また、Tier の制限を超えてリクエストを送った場合、ステータス コード 429 が返ります。

HTTP/1.1 429 Too Many Requests

以下の公開記事に Investigate API で使用されるステータス コードの一覧があります。

Umbrella Investigate REST API – Error Handling

https://docs.umbrella.com/investigate-api/docs/error-handling-1