Umbrella: Reporting API について

[tkitahar]

※ Reporting API は 2023 年 9 月 1 日 (UTC) でサポート終了する予定です。それまでに新しい API へ移行することが推奨されています。

Introducing the new Cisco Umbrella Open API

https://support.umbrella.com/hc/en-us/articles/8989122216340-Introducing-the-new-Cisco-Umbrella-Open-API

• 1. はじめに
• 2. Reporting API V1
• 3. Reporting API V2

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

1. はじめに

本記事では、Reporting API の二つのバージョン (V1 と V2) について紹介します。

2. Reporting API V1

API を介して Umbrella Dashboard の各種レポートから情報を取得するために、2018 年に Reporting API のバージョン 1 がリリースされました。このバージョンでは以下の情報を取得することが可能です。

• Destinations: Most recent requests
• Destinations: Top Identities
• Security Activity Report

※ サブスクリプションの種類により取得が制限されている場合があります

このバージョン 1 の Reporting API は現在も利用可能で、以下に簡単な手順を紹介します。

まずは、クラウド上の Umbrella API に対して認証をおこなうための情報を取得するために、Umbrella Dashboard の Admin -> API Keys を開きます。

API Keys 画面で Umbrella Reporting にチェックを入れて、CREATE ボタンを押します。

Umbrella Reporting という項目が追加され、API Key と API Secret がそれぞれ Your Key と Your Secret の箇所に表示されますので、これらを記録します。これで準備完了です。

では、HTTPS リクエストを生成する curl コマンドを使って Security Activity Report のデータを取得してみます。

curl -X GET -u 'XXXXXX:YYYYYY' 'https://reports.api.umbrella.com/v1/organizations/ZZZZZZZ/security-activity?limit=2&start=1539097200&end=1539874800'

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

実際には、XXXXXX を API Key に、YYYYYY を API Secret に、ZZZZZZZ を Org ID (Umbrella Dashboard の URL に含まれている数字) に置き換えてください。また、URL パラメーターの limit には最大取得件数を、start と end にはデータの取得期間を Unix 時間で指定します。以下は出力結果例です。

{"requests":[
{"originId":99999999,"originType":"Sites","internalIp":"172.16.0.1",
"externalIp":"122.210.96.187","categories":["Phishing","Computer Security"],
"tags":[],"destination":"www.internetbadguys.com","originLabel":"Default Site",
"actionTaken":"BLOCKED","datetime":"2018-10-17T03:11:08.404Z"},
{"originId":99999999,"originType":"Sites","internalIp":"172.16.0.1",
"externalIp":"122.210.96.187","categories":["Phishing","Computer Security"],
"tags":[],"destination":"www.internetbadguys.com","originLabel":"Default Site",
"actionTaken":"BLOCKED","datetime":"2018-10-17T03:11:08.320Z"}
]}

3. Reporting API V2

Reporting API V1 を改良し、より安全に、より制限なく利用できるようになったものが Reporting API V2 です。

Reporting API V2 でも Reporting API V1 で使用した API Key と API Secret を使用しますが、安全を増すために以下の手順で事前認証を行うようになりました。

まずは、https://management.api.umbrella.com/auth/v2/oauth2/token にアクセスし、ユーザー名に API Key を、パスワードに API Secret を入力して、「サインイン」をクリックします (画像のボタン名などは Web ブラウザによって異なります)。

認証に成功すると、以下のようなフォーマットの情報が表示されます。

{"token_type":"bearer","access_token":"(英数字の長い文字列)","expires_in":3600}

そして、この (英数字の長い文字列) を curl コマンドの認証のために指定することになります。なお、expires_in はこのアクセス トークンの有効期限で、通常 1 時間です。

Reporting API V2 では認証情報の指定に HTTP ヘッダの Authorization を使用します。curl コマンドを使って Activity Search Report のデータを取得してみます。

curl -X GET -H 'Authorization: Bearer (英数字の長い文字列)' 'https://reports.api.umbrella.com/v2/organizations/ZZZZZZZ/activity?limit=10&from=1613035102000&to=1615454302000'

※ ZZZZZZZ を Org ID で置き換えます