はじめに
Cisco Secure Accessには、設定情報やイベント情報を取得・操作できるAPIが用意されています。これらのAPIを活用することで、定型的な運用作業の自動化や、監視・通知の効率化など、日々の運用を大きく改善できます。
本シリーズでは、Cisco Secure Access APIを利用した運用自動化をテーマに、Pythonなどを用いた実践的な活用方法を紹介します。「APIを使うと何ができるのか」「実際の運用でどのように活用できるのか」を、サンプルコードを交えながらわかりやすく解説していきます。
全4回の構成は以下のとおりです。
- 第1回：Cisco Secure Access APIを試してみる
- 第2回：PythonでCisco Secure Accessを操作してみる
- 第3回：APIで運用を自動化してみる
- 第4回：Cisco XDRと連携してみる
まず第1回では、Cisco Secure Access APIの概要や利用するための準備を行い、実際にAPIを呼び出して動作を確認するところまでを紹介します。
この記事を読むとできること
- Cisco Secure Access APIの概要が理解できる
- APIを利用するための準備ができる
- API認証の流れが理解できる
- 実際にAPIを呼び出してレスポンスを確認できる
Cisco Secure Access とは
Cisco Secure Accessは、ゼロトラストを基盤としたクラウド提供型のSSE（Security Service Edge）ソリューションで、あらゆる場所のユーザーやデバイスからインターネットや社内アプリケーションへのアクセスを安全に保護するサービスです。
Cisco Secure Access API とは
Cisco Secure Accessでは、REST APIを利用して各種設定やイベント情報をプログラムから取得・操作できます。
GUIで実施している運用作業の一部をAPIに置き換えることで、定期的な情報取得やレポート作成、アラート通知などを自動化でき、運用負荷の軽減につながります。
Cisco Secure Access APIでは、認証後にアクセストークンを取得し、そのトークンを利用して各種APIを呼び出します。レスポンスは主にJSON形式で返されるため、Pythonなどのプログラミング言語で簡単に扱うことができます。
Cisco Secure Access APIでできること
Cisco Secure Access APIでは、例えば次のような操作が可能です。
| 利用例 | 活用シーン |
|---|---|
| ユーザー/グループ情報の取得 | ユーザー情報の棚卸しや管理 |
| ポリシー情報の取得 | 設定内容のバックアップや変更管理 |
| 設定投入 | 許可ドメイン、ブロックドメインの追加 |
| セキュリティイベントの取得 | インシデント監視やアラート通知 |
| 監査ログの取得 | 運用状況の確認や監査対応 |
| 各種設定の操作 | 運用の自動化や他システムとの連携 |
本シリーズでは、これらのAPIの中でも、運用現場で利用する機会が多い「情報取得」を中心に紹介し、最終的にはPythonを利用した通知やCisco XDRとの連携まで実装していきます。
APIを利用するメリット
APIを利用する最大のメリットは、GUIで行っている定型的な作業を自動化できることです。
ここでは、「セキュリティイベントのレポート（CSV）を作成する」作業を例に、GUIでの運用とAPIを利用した運用を比較してみます。
従来は、管理画面へログインし、イベントを検索・絞り込み、CSVをダウンロードするといった作業を繰り返す必要がありました。一方、APIを利用すれば、プログラムからイベント情報を取得し、そのままCSVファイルを生成できます。さらに、定期実行や通知機能と組み合わせることで、レポート作成や監視業務を自動化することも可能です。
ポイント
APIを活用することで作業時間の短縮だけでなく、手作業によるミスの削減や運用品質の向上にもつながります。
APIを利用するために必要なもの
APIを利用するために以下のものが必要となります。
- Cisco Secure Access 環境
- APIキー（Client ID / Client Secret）
- API Client（PythonやPostmanなど）
APIキーは、Cisco Secure Accessの管理コンソールから作成します。
補足
APIキーにはアクセス可能な機能（スコープ）を設定できます。セキュリティの観点から、利用目的に応じて必要最小限の権限を付与することをおすすめします。
また、Cisco Secure Access APIの異常や重要イベントを監視し、発生時にメールやWebhookで通知するアラート機能が用意されています。本記事では詳しく説明していませんが、API利用時には合わせて設定することをおすすめします。
https://securitydocs.cisco.com/docs/csa/olh/160553.dita
APIキーの作成方法については、Cisco Developerの公式ドキュメントでも紹介されています。
API Authentication
https://developer.cisco.com/docs/cloud-security/secure-access-api-authentication/#manage-api-keys
APIキー作成手順
1.管理コンソールから Admin > API Keys に移動し、右上の「Add」をクリック
2.APIキーの名前と説明を入力
運用時に識別しやすい名前と説明を設定します。
3.APIキーのスコープを設定
利用するAPIに応じて、アクセス可能なスコープと権限（Read / Write）を設定します。
情報取得のみの場合は、読み取り権限（Read）のみを設定するなど、必要最小限の権限を割り当てるようにします。
APIスコープの詳細については、以下の公式ドキュメントを参照してください。
OAuth Scopes
https://developer.cisco.com/docs/cloud-security/secure-access-api-oauth-scopes/#secure-access-oauth-20-scopes
4.APIキーの有効期限を設定
運用ポリシーに合わせて有効期限を設定します。
長期間利用するAPIキーであっても、定期的に更新することをおすすめします。
5.利用可能なネットワークを設定（任意）
必要に応じて、APIキーを利用できる送信元ネットワークを制限できます。
運用端末やサーバーからのみ利用する場合は、この機能を利用することでセキュリティを向上できます。
6.APIキーとシークレットを保存
APIキー（Client ID）とシークレット（Client Secret）が表示されます。
シークレットはこの画面でしか表示されません。 必ず安全な場所に保管してください。
API認証からAPIリクエスト送信までの流れ
ここでは、Cisco Secure Access APIを利用する際の認証からAPIリクエスト送信までの流れを簡単に説明します。
Cisco Secure Access APIを利用するには、最初に アクセストークン（Access Token） を取得する必要があります。APIリクエスト時に、このアクセストークンをHTTPヘッダーのAuthorizationに含めることで、認証されたユーザーとしてAPIを実行できます。
アクセストークンの取得には、事前に作成した APIキー（Client ID）とシークレット（Client Secret） を使用します。認証に成功するとアクセストークンが発行され、そのトークンを利用して各種APIを呼び出すことができます。
なお、アクセストークンの有効期限は 1時間（3,600秒） です。有効期限が切れた場合は、再度APIキーとシークレットを使用して新しいアクセストークンを取得する必要があります。
APIの利用手順をまとめると、以下の流れになります。
- APIキー（Client ID）とシークレット（Client Secret）を用意する
- 認証APIを呼び出し、アクセストークンを取得する
- APIリクエストのAuthorizationヘッダーにアクセストークンを設定する
- Cisco Secure Access APIを呼び出す
- JSON形式のレスポンスを取得する
実際にAPIを呼び出してみる
それでは、実際のAPIを例にアクセストークンの取得からAPIの実行までの流れを確認してみます。
1. アクセストークンを取得する
まずは認証APIを呼び出し、アクセストークンを取得します。
エンドポイント
POST https://api.sse.cisco.com/auth/v2/token
cURLサンプル
curl --user '<key>:<secret>' --request POST --url 'https://api.sse.cisco.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
このリクエストでは、事前に作成した Client ID（APIキー）とClient Secret（シークレット） を使用して認証を行います。
レスポンス
認証に成功すると、以下のようなJSONが返されます。
{
"token_type": "bearer",
"access_token": "xxxxxx",
"expires_in": 3600
}
access_tokenに表示されている文字列が、以降のAPI呼び出しで使用するアクセストークンです。また、expires_inからアクセストークンの有効期限が 3,600秒（1時間） であることが分かります。
2. APIを呼び出す
取得したアクセストークンをAuthorizationヘッダーに設定して、Cisco Secure Access APIを呼び出します。
今回は例として、VPNユーザーの接続状態を取得するAPIを実行します。
cURLサンプル
curl -L --location-trusted --request GET --url 'https://api.sse.cisco.com/deployments/v2/vpn/userConnections' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'
ポイントは、取得したアクセストークンを以下の形式でAuthorizationヘッダーに設定することです。
Authorization: Bearer
認証に成功すると、VPNユーザーの接続情報がJSON形式で返されます。
APIのベースURL
ベースURL
Cisco Secure Access APIは、機能ごとにベースURLが分かれています。
| ベースURL | 用途 |
|---|---|
| /auth/v2 | 認証・アクセストークン取得 |
| /admin/v2 | 管理情報 |
| /deployments/v2 | ネットワークトンネルやデバイスなどの設定・管理 |
| /policies/v2 | ポリシー管理 |
| /reports/v2 | レポート取得 |
| /investigate/v2 | 調査・分析機能 |
APIリクエストを実際に試してみる（Postman編）
ここまではcURLを使用してAPIの呼び出し方法を説明しましたが、APIの動作確認や開発時にはAPIクライアントを利用すると、より手軽にAPIを実行できます。
今回は、代表的なAPIクライアントであるPostmanを使用して、Cisco Secure Access APIを実行してみます。
Postmanは、HTTPリクエストの送信やレスポンスの確認をGUIで簡単に行えるツールです。リクエストヘッダーやパラメータを編集しながら動作を確認できるため、APIの学習や開発、トラブルシューティングで広く利用されています。
Cisco Secure Accessでは、Cisco DevNetがサンプルのPostman Collectionを公開しており、認証や各種APIをすぐに試すことができます。
サンプルのPostman Collectionはこちらから入手できます。
Cisco DevNet - Cisco Secure Access Postman Collection
https://github.com/CiscoDevNet/cloud-security/tree/master/Cisco%20Secure%20Access/PostmanExamples
Postman Collectionには認証APIや各種サンプルAPIがあらかじめ登録されているため、一からリクエストを作成する必要がなく、Cisco Secure Access APIを簡単に試すことができます。
1.Postman Collectionをインポートする
まずはCisco DevNetから、以下の2つのファイルをダウンロードします。
- Collection
- Environment
実際にダウンロードしたファイル
ダウンロードしたファイルをPostmanへインポートします。
ファイルが正しく読み込まれたことを確認し、「Import」をクリックします。
インポートが完了すると、左側メニューのCOLLECTIONSとENVIRONMENTSにCisco Secure Access用の項目が表示されます。
2.アクセストークンを取得する
続いて、APIを利用するためのアクセストークンを取得します。
COLLECTIONSから以下を開きます。
Cisco Secure Access
└─ 1.Auth - Start Here
└─ Get Access Token
Authorizationタブで、以下を入力します。
Username：Client ID
Password：Client Secret
入力後、Sendをクリックします。
レスポンスに200 OKが表示され、access_tokenが返ってくれば認証は成功です。
3. Environmentを設定する
取得したアクセストークンをEnvironmentへ設定します。
ENVIRONMENTSからCisco Secure Accessを開きます。
AccessTokenのValueへ、先ほど取得したaccess_tokenの値を設定します。
これで、Collection内のAPIから共通してアクセストークンを利用できるようになります。
4. APIリクエストを送信する
今回は例として、アクセス数の多い宛先ドメインを取得するレポートAPIを実行します。
以下のAPIを開きます。
Cisco Secure Access
└─ Reports
└─ Destinations
└─ Get Top Destinations Proxy
Query Paramsには、取得条件を指定します。
from：取得開始日時
to：取得終了日時
limit：取得件数
offset：取得開始位置
入力した値は、そのままAPIリクエストのクエリパラメータとして送信されます。
Sendをクリックし、200 OKとレスポンスが返ってくればAPIの実行は成功です。
5.レスポンスを確認する
このAPIでは、アクセス数の多い宛先ドメインを取得できます。
レスポンスには以下のような情報が含まれます。
ドメイン名
カテゴリ
リクエスト総数
許可されたリクエスト数
ブロックされたリクエスト数
レスポンス全体を見ると、リクエスト数の多い順に各ドメインの情報がJSON形式で返されていることが分かります。
同じ情報はCisco Secure Accessの管理コンソールでも確認できますが、GUIからデータを取得する場合は、検索条件の設定やCSVのダウンロードなどの操作が必要になります。
- Cisco Secure Access のコンソールで確認した場合
一方、APIを利用すれば必要なデータを直接取得できるため、CSVの自動生成や通知処理など、さまざまな運用自動化につなげることができます。第3回では、この仕組みを利用してレポート作成や通知の自動化を紹介する予定です。
次回予告
今回は、Cisco Secure Access APIの基本的な仕組みと、アクセストークンの取得からAPIの実行までの流れを紹介しました。
次回は 「PythonでCisco Secure Accessを操作してみる」 をテーマに、今回紹介したAPIをPythonから実行する方法を解説します。
Pythonの開発環境の準備から、アクセストークンの取得、APIの実行、レスポンスの取得までを、サンプルコードを交えながら順を追って説明します。Python初心者の方でも試せる内容を目指していますので、ぜひ次回もご覧ください。