Umbrella: API のリニューアルについて

[tkitahar]

• 1. はじめに
• 2. 従来の Umbrella API について
• 3. 変更点
• 4. 使用例

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

1. はじめに

Umbrella Dashboard 上の情報や設定を他のシステム (サードパーティー製ソフトウェアや製品、内製のソフトウェアや Cisco の他製品など) と連携するのに使われる API 機能がリニューアルされ、Umbrella Open API (または単純に Umbrella API) という名前でリリースされました。

本記事では、この新しい Umbrella API で何が変わったのかについて解説し、簡単な使い方について紹介します。

Introducing the new Cisco Umbrella Open API

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

2. 従来の Umbrella API について

これまでの Umbrella では以下の種類の API が用意されていました。

• Management API (Umbrella管理)
• Reporting API (Umbrella レポート)
• Umbrella API (Umbrella ネットワークデバイスまたはレガシーネットワークデバイス)

※ 括弧内は Umbrella Dashboard の管理 > APIキー画面 > Legacy Keys の API キー名です

※ Investigate API 、Enforcement API は今回のリニューアルの対象外です

これらの API についても 2023 年 9 月 1 日までサポートが継続される予定となっていますが、それまでに新しい API へ移行することが推奨されています。

3. 変更点

従来の API では、各組織で前述の API キーを一つずつしか発行することができず、それぞれの API キーと Secret を組織内で共有して管理する必要がありました。

新しい API では、従来の API の枠組みに縛られることなく、自由に利用できる範囲 (Key Scope) を定義したAPI キーを複数個作成できるようになりました。

これを実現するために、まず 4 種類の API ができることを約 20 項目に細かく細分化し、「Reports」「Policies」「Deployments」「Admin」の 4 つのグループに再分類しました。そして、新しい API キーを作成する際に、グループ全体を指定したり、項目を細かく選択したりできる仕組みを導入しました。

 

また、API キーの作成の際には、以下の内容も設定できるため、より柔軟な運用が可能になります。

• 作成する API キーに対して任意の名前を設定
• 選んだ項目に対して、個別に読み取り専用 (Read Only) か読み書き (Read / Write) を指定
• API キーの有効期限または無期限を設定

 

4. 使用例

一般的な Linux 端末を用意し、curl コマンドを使って新しい Umbrella API を試してみます。

Umbrella API は OAuth 2.0 を使用しており、まずは、Umbrella Dashboard から取得した API キーと Secret を使って、Umbrella API とやり取りをするために必要なアクセス トークンを取得する必要があります。

リクエスト
curl --user '<API キー>:<Secret>' --request POST --url 'https://api.umbrella.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

レスポンス
{"token_type":"bearer","access_token":"<アクセストークン>","expires_in":3600}

Authentication

https://developer.cisco.com/docs/cloud-security/#!authentication/authentication

Umbrella API のレスポンスはすべて JSON のフォーマットで返され、access_token の値がアクセストークンになります。また、expires_in がアクセストークンの有効期間 (通常1 時間) です。

では、このアクセストークンを使って Umbrella Dashboard のレポート> アクティビティ検索レポートに記録されている直近一週間以内のデータを一件取得します。

リクエスト
curl --location --location-trusted \
--request GET --url 'https://api.umbrella.com/reports/v2/activity?from=-7days&to=now&limit=1' \
-H 'Authorization: Bearer <アクセストークン>' \
-H 'Content-Type: application/json'

レスポンス
{"meta":{},"data":[{"returncode":0,"externalip":"XXX.XXX.XXX.XXX","allapplications":[{"id":28,"label":"Do Not Decrypt Application","category":{"id":null,"label":"Sample Application Group"}}],"date":"2022-09-09","internalip":"192.168.0.211","time":"03:54:22","querytype":"A","policycategories":[],"type":"dns","categories":[{"id":23,"type":"content","label":"Search Engines","integration":false,"deprecated":true},{"id":123,"type":"content","label":"Infrastructure and Content Delivery Networks","integration":false,"deprecated":false},{"id":148,"type":"application","label":"Application","integration":false,"deprecated":false},{"id":190,"type":"content","label":"Search Engines and Portals","integration":false,"deprecated":false}],"verdict":"allowed","domain":"example.com ","timestamp":1662695662000,"blockedapplications":[],"allowedapplications":[],"identities":[{"id":XXXXXXXXX,"type":{"id":50,"type":"android","label":"Mobile Devices"},"label":"test@example.com - add2f0cdfc352c6a","deleted":false},{"id":XXXXXXXXX,"type":{"id":1,"type":"network","label":"Networks"},"label":"Test Network","deleted":false}],"threats":[]}]}

※ --location および --location-trusted オプションは、リダイレクト時に Authorization ヘッダーを保持するために必要になります

リクエストに指定できる引数やレスポンスの各項目の意味について知りたい場合は、以下の公開文書を参照してください。

Reporting

https://developer.cisco.com/docs/cloud-security/#!api-reference-reports-reporting-overview/reporting

また、その他の API の仕様については、以下の公開文書からたどることができます。

Reports

https://developer.cisco.com/docs/cloud-security/#!api-reference-reports-overview

Policies

https://developer.cisco.com/docs/cloud-security/#!api-reference-policies-overview

Deployments

https://developer.cisco.com/docs/cloud-security/#!api-reference-deployments-overview

Admin

https://developer.cisco.com/docs/cloud-security/#!api-reference-admin-overview