はじめに

この記事はシスコの同志による Cisco Systems Japan Advent Calendar 2021 の 8 日目として投稿しました。今年もカレンダーが２つあります！！

2021年版(1枚目): https://qiita.com/advent-calendar/2021/cisco
2021年版(2枚目): https://qiita.com/advent-calendar/2021/cisco2

2017年版: https://qiita.com/advent-calendar/2017/cisco
2018年版: https://qiita.com/advent-calendar/2018/cisco
2019年版: https://qiita.com/advent-calendar/2019/cisco
2020年版: https://qiita.com/advent-calendar/2020/cisco
2020年版(1枚目): https://qiita.com/advent-calendar/2020/cisco
2020年版(2枚目): https://qiita.com/advent-calendar/2020/cisco2

このエントリで取り上げるテーマは、「SecureX を使って簡易 REST API モジュールを作る」です。Cisco SecureX は昨年のエントリーにて AWS Lambda にサーバレス API ゲートウェイをデプロイし利用可能な脅威インテリジェンスを接続してみるというテーマが異なる題材として取り上げてみました。今回は SecureX のオーケストレーター機能を使って REST API をテストするシンプルなワークフローを１から作成する、これにより SecureX を API の実行プラットフォームとして利用できる情報を整理することを目的としています。以下の題材で情報をまとめます。

SecureX オーケストレーターでできること (まとめ)
Secure Endpoint 用 REST API モジュールの目標とステップ
Secure Endpoint 用 REST API ワークフローの作成
SecureX オーケストレーターの例

Cisco SecureX とは何か？については昨年のエントリーの中でも少し説明しています。無償で使えるセキュリティプラットフォーム：Cisco SecureX

SecureX オーケストレーターでできること (まとめ)

Cisco SecureX の中核的な機能として Cisco Secure 製品はもちろんのこと、セキュリティ以外のネットワークコンポーネント、クラウドコンポーネント、Cisco 以外の多数の製品やインフラコンポーネントと接続することが可能な自動化を実現する オーケストレーター を実装しています。日々起こるインシデントの調査やインシデントの発生に伴う事後処理に関わるセキュリティオペレーションは、オペレータやアナリストによってマニュアルで行われる人的タスクの繰り返し作業である事実に対して、これらの作業をワンストローク作業で実行できるワークフローによるマシンアシスト機能を用いて、作業の品質を保全しながら作業効率を大幅に改善することを目的としています。

Cisco SecureX オーケストレーターは何かしらのプログラミング言語、コーディングのナレッジは必要ではありません。このような SecureX オーケストレーターのダッシュボードの中で、左のウィンドウから各種の製品と連携する機能ごとのアダプタ ( AWSサービス, Microsoft Teams, ServiceNow, 等) やロジック (ブレーク, パラレルブロック, ループ, 等) を選択し、中央のワークフローペインターウィンドウにドラッグ＆ドロップしワークフローのパーツを連結し、右のウィンドウから必要なパラメータを入力することでワークフローを構成することが可能です。SecureX オーケストレーターのアダプタ (Atomic Action) で対応していないものは対応できない、というわけではありません。Web Service や Terminal, Python スクリプトのような汎用的な連携機能がありますので、例えば製品の REST API を利用したワークフローのような自由な開発が可能となります。

Secure Endpoint 用 REST API モジュールの目標とステップ

今回の目標はプロダクトの REST API を利用してリクエストした Input パラメータに対して Output を正しく返せる短いステップのワークフローを作成し、実行時にこのワークフローが正しく終了することをテストするステップをまとめます。REST APIを持つソフトウェアやクラウド製品であれば何でも良いのですが、今回は Cisco Secure Endpoint (旧AMP) を選択しました。Cisco Secure Endpoint は SecureX 用のAtomic Actionに対応しており、すでに Secure Endpoint がインストールされた端末からの GUID, Group 情報の取得やエンドポイントの隔離用 Atomic ワークフローを実装していますが、こちらの Atomic ワークフローを利用せず、汎用的な REST API に対応できる "Web Service" ワークフローを利用し構成します。今回作成するワークフローは Cisco Secure Endpoint と連携するさらに高度なワークフローの一部のモジュールとして利用することが可能です。

以下は、このREST APIワークフローの機能と導入ステップです。

機能 : Secure Endpoint の検出 IP アドレスからConnector ID, Hostname, Operating System 情報を検索する
ステップ1 : Secure Endpoint API Credential (Account Key) 作成
ステップ2 : Secure Endpoint API Target 作成
ステップ3 : Secure Endpoint API ワークフローの構成
ステップ4 : Secure Endpoint API ワークフローの実行

Secure Endpoint 用 REST API ワークフローの作成

ステップ1 : Secure Endpoint API Credential (Account Key) 作成

SecureX がすでに Secure Endpoint とダッシュボード連携がされている場合は、Default Account Key がすでに作成されており、そちらを利用することも可能です。（このステップで作成する Account Key を指定することも可能です）

Cisco Secure Endpoint ダッシュボードログイン
"アカウント" から "API クレデンシャル" 選択
”新しい API クレデンシャル"
- "アプリケーション名" : (任意の名前) SecureX Credential
- "範囲" : 読み取り/書き込み選択
- "作成"
"サードパーティAPIのクライアントID" と "APIキー" をテキストファイル等に保存
Cisco SecureX ダッシュボードログイン
"Orchestration" タブ選択
左メニューから "Account Keys" 選択
"New Account Key" 選択し新規クレデンシャル用 Account Keyを作成
- Account Key Type : HTTP Basic Authentication
- Display Name : (任意の名前) "AMP Credential"
- Username : (保存した) サードパーティAPIのクライアントID
- Password : (保存した) APIキー (Secure Endpoint で作成した APIクライアントID と API キーは、APIリクエストに必要なAuthorizationヘッダに正しい形式で含まれるようになります、SecureXの Account Key 設定ではこれが正しい指定となります)
- "Submit" を選択し作成

ステップ2 : Secure Endpoint API Target 作成

SecureX がすでに Secure Endpoint とダッシュボード連携がされている場合は、Default の Secure Endpoint 用 API Targetが作成されていますが、ワークフローの利用するAPI Endpoint用のパスを指定するため、新規にAPI Targetを作成します。（デフォルトのAPI Target を使用し作成するワークフロー内でパスを指定することも可能です）

Cisco SecureX ダッシュボードログイン
"Orchestration" タブ選択
左メニューから "Targets" 選択
"New Target" 選択し新規 Secure Endpoint 用 HTTP API Targetを作成
- Display Name : (任意の名前) "2021_Qiita_AMP_Target"
- No Account Keys : False
- Default Account Keys : (作成したAccount Key) "AMP Credential"
- Protocol : "HTTPS"
- Host/IPAddress : (利用しているRegionのAPI ホスト名) api.apjc.amp.cisco.com
- Path : "/v1/computers"
- "Submit" を選択し作成

Cisco AMP for Endpoints API

Request

 GET /v1/computers

cURL

 curl -X GET \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'accept-encoding: identity' \
--compressed -H 'Accept-Encoding: gzip, deflate' \
-u YOUR_API_CLIENT_ID \
'https://api.apjc.amp.cisco.com/v1/computers'

Response

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.apjc.amp.cisco.com/v1/computers"
    },
    "results": {
      "total": 49,
      "current_item_count": 49,
      "index": 0,
      "items_per_page": 500
    }
  },
  "data": [
    {
      "connector_guid": "55d4faec-9481-4686-a667-f71ec35e7a6d",
      "hostname": "Demo_AMP",
      "windows_processor_id": "1b932e70da84f65",
      "active": true,
      "links": {
        "computer": "https://api.apjc.amp.cisco.com/v1/computers/55d4faec-9481-4686-a667-f71ec35e7a6d",
        "trajectory": "https://api.apjc.amp.cisco.com/v1/computers/55d4faec-9481-4686-a667-f71ec35e7a6d/trajectory",
        "group": "https://api.apjc.amp.cisco.com/v1/groups/6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03"
      },
      "connector_version": "99.0.99.30065",
      "operating_system": "Windows 10 Enterprise",
      "internal_ips": [
        "29.185.115.160"
      ],
      "external_ip": "182.209.164.92",
      "group_guid": "6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03",
      "install_date": "2021-04-05T23:22:31Z",
      "is_compromised": false,
      "network_addresses": [
        {
          "mac": "c4:dd:c2:53:e2:cc",
          "ip": "29.185.115.160"
        }
      ],
      "policy": {
        "guid": "520c7c68-a637-43b1-b851-7830b0b336b6",
        "name": "Protect Policy"
      },
      "last_seen": "2021-05-05T23:22:31Z",
      "faults": [

      ],
      "isolation": {
        "available": false,
        "status": "not_isolated"
      },
      "orbital": {
        "status": "not_enabled"
      }
    },
    :
    :

ステップ3 : Secure Endpoint API ワークフローの構成

オーケストレーションワークフローをGUIで構成し、ワークフロープロパティを指定します。

Cisco SecureX ダッシュボードログイン
"Orchestration" タブ選択
"New Workflow" 選択
Workflow Editor の左の "Activities" メニューから "HTTP Request" と "Execute Python Script" を中央のウィンドウにドラッグ＆ドロップし、START -> "HTTP Request" -> "Execute Python Script" -> END の順で連結させる

ワークフロー本体のプロパティ (中央ウィンドウの任意の場所をクリック)、ワークフローを構成する "HTTP Request" と "Execute Python Script" のAtomic Actionのプロパティを以下のように指定します。

ワークフロー本体のプロパティ

- Display Name : (任意のワークフロー名) 2021_Qiita_AMP_Test
- Variables 1 (追加)
 - NAME : "variable_connector_guid"
 - TYPE : "String"
 - SCOPE : "Output"
- Variables 2 (追加)
 - NAME : "variable_ip_address"
 - TYPE : "String"
 - SCOPE : "Input"
- Target Type : HTTP Endpoint (選択)
 - Execute on this target (選択)
  - Target : (作成したSecure Endpoint API Target) "2021_Qiita_AMP_Target"
- Credentials
 - Use target's default keys (デフォルト)

HTTP_Requet本体のプロパティ

- HTTP Request
 - Relative Url (指定無し)
 - Method : GET (デフォルト)
 - Request Body (指定無し)

Execute_Python_Scriptのプロパティ

- Python Query
 - Script argument : "[$activity.HTTP Request.output.Body$]" (ADD)
 - Script to execute on target : (次項のPython_Script)
 - Script Output Variavles
  - Script Variable : "OS"
  - Property Name (任意の名前) "XXX"
  - Property Type : "String"

Python_Script

true = ''
false = ''
responsecomputers = [$activity.HTTP Request.output.Body$]['data']

for computer in responsecomputers:
     for ip in computer['internal_ips']:
            if ip == '[$workflow.2021_Qiita_AMP_Test.input.variable_ip_address$]':
              OS = computer['operating_system']
              break

作成したワークフローのプロパティの記述漏れ、ロジックに不備がある場合、問題のある箇所がハイライトされます。ワークフロー本体の上部のステータスが "Validated" と表示されていれば実行可能なワークフローとして作成が完了しています。

ステップ4 : Secure Endpoint API ワークフローの実行

構成したワークフローは、第一のプロセスにて Secure Endpoint の /v1/computers のAPIエンドポイントに対し GET リクエストを行い、その環境テナントで Secure Endpoint の Connector がインストールされたすべてのコンピュータリストを取得します。HTTP Response Bodyには、JSON形式で"connector_guid", "trajectory", "install_date", "network_addresses" のようなコンピュータに関連するすべての情報を含みます。第二のプロセスにて、リクエストのOutput情報を基に、ワークフローのInput情報であるIPアドレスに対するOS名を抜き出し成形してスクリプトクエリを返します。

ワークフローを実行してみます。

Cisco SecureX ダッシュボードログイン
"Orchestration" タブ選択
作成したワークフローを選択
ワークフロー上部から "Run" 実行

"Run" を実行すると、このワークフローで必要な Input Variable 情報として IP アドレス の入力が求められます。確認用にSecure Endpointで管理されたコンピュータの検出されたIP アドレスを入力します。Secure Endpoint のダッシュボードにログインし、"管理" -> "コンピュータ" から既存のコンピュータのIPアドレスをピックアップし入力、再度 "Run" を選択しワークフロー実行を決定します。

ワークフローの実行に成功すると、すべてのワークフローを構成する Atomic Action の実行ステータスとして各 Action の左側に "緑の縦帯" のようなマークが追加されてます。ワークフロー実行に失敗する場合、どこかの構成コンポーネントが緑でなく"赤の縦帯"でマークされます。この場合ワークフローの再構成やプロパティの見直しが必要になります。

ワークフローの実行ステータスから、１つ目のプロセスである、"HTTP Request" のHTTPレスポンスを確認します。JSON Output の "response_body" 内に Secure Endpoint の管理コンピュータ情報がレスポンスとして出力されていることを確認できます。

ワークフローの実行ステータスから、２つ目のプロセスである、"Execute Python Script" のScript Outputを確認します。"Script Queries" に Input Variable で入力した既存管理コンピュータの IP アドレスに対する OS 情報がレスポンスとして出力されていることを確認できます。

Pythonスクリプトの小変更により IP アドレスからの取得情報をコネクタGUIDに変更する例です。

Python_Script

true = ''
false = ''
responsecomputers = [$activity.HTTP Request.output.Body$]['data']

for computer in responsecomputers:
     for ip in computer['internal_ips']:
            if ip == '[$workflow.2021_Qiita_AMP_Test.input.variable_ip_address$]':
              connector_guid = computer['connector_guid']
              break

SecureX オーケストレーターの例

Cisco SecureX は利用コストをかけることなく誰にでもサインナップし、既存のセキュリティオペレーションの改善・効率化のためのXDR/SOAR++としての機能を利用いただけるとともに、さらに汎用的なAPI実行プラットフォームとして利用可能です。SecureXにサインナップした誰もが利用できる Cisco製のビルトインワークフローも多く提供しており、これらを簡単に利用することが可能です。

ビルトインワークフローの例を紹介します。

MX L3 Outbound Firewall Block

"MX L3 Outbound Firewall Block" ワークフローは、Cisco SecureX Native ダッシュボード、SecureXブラウザエクステンション、連携ベンダー製のSIEM製品等からのピボットメニューからの指定と実行により、選択した悪性と認識される可能性があるIOC/Observable情報を選択し、その情報に対してテナント内部の Meraki MX にFirewall Block ポリシーを生成し適用を行います。

このレスポンスアクションの結果により、連携済みテナントのすべての Meraki MX に対し、Firewallアウトバウンドの Firewall ブラックリストをワンストロークで適用が可能になります。

参照

[0] Cisco SecureX
http://security.cisco.com
[1] Cisco AMP for Endpoints API
https://api-docs.amp.cisco.com
[2] SecureX orchestration
https://ciscosecurity.github.io/sxo-05-security-workflows/

Cisco SecureX を使って簡易 REST API モジュールを作る