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

#はじめに
この記事はシスコの同志による <font color="DarkSlateBlue"><B>Cisco Systems Japan Advent Calendar 2021</B></font> の <font color="Red">8 日目</Font>として投稿しました。今年もカレンダーが<font color="Red"><B>２つ</B></font>あります！！


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

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

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

- <B><font color="DarkSlateBlue">SecureX オーケストレーターでできること (まとめ)</B>
- <B><font color="DarkSlateBlue">Secure Endpoint 用 REST API モジュールの目標とステップ</B>
- <B><font color="DarkSlateBlue">Secure Endpoint 用 REST API ワークフローの作成</B>
- <B><font color="DarkSlateBlue">SecureX オーケストレーターの例</B>

Cisco SecureX とは何か？については昨年のエントリーの中でも少し説明しています。[無償で使えるセキュリティプラットフォーム：Cisco SecureX](https://qiita.com/sig666/items/05c46d75571c46a7ab34)

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

![01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/ade38d18-858c-5edc-744e-fbca619a7ba4.png)

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

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

<img width="400" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/83763dcb-2dd9-886c-b2e6-a3284a8e1d67.png">


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

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

#<B>Secure Endpoint 用 REST API ワークフローの作成</B>

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


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

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

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

[Cisco AMP for Endpoints API](https://api-docs.amp.cisco.com/api_actions/details?api_action=GET+%2Fv1%2Fcomputers&api_host=api.apjc.amp.cisco.com&api_resource=Computer&api_version=v1)

```bash:Request
 GET /v1/computers
```
 
```bash: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'
```

```json: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"
      }
    },
    :
    :
```

###<B>ステップ3 : Secure Endpoint API ワークフローの構成</B>
 オーケストレーションワークフローをGUIで構成し、ワークフロープロパティを指定します。

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

![03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/69cdeeba-1043-8186-d88c-63f41471bd5f.png)

ワークフロー<B>本体のプロパティ</B> (中央ウィンドウの任意の場所をクリック)、ワークフローを構成する "<B>HTTP Request</B>" と "<B>Execute Python Script</B>" の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: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
```

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

<img width="300" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/e1fdf404-1d60-bd1a-bc97-8ba45a889ebd.png">


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

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

- <font color="DarkSlateBlue"><B>Cisco SecureX ダッシュボードログイン</B></font> 
- "<B>Orchestration</B>" タブ選択
- 作成したワークフローを選択
- ワークフロー上部から "<B>Run</B>" 実行

<img width="400" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/f970cfd1-c37d-5d7c-5594-cd52155023b4.png">

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

![06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/8eece443-9a14-a02e-71d2-9c2541dbf4c0.png)

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

<img width="300" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/e6d0501a-2885-a2b2-8a0b-0f241d86944a.png">

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

![08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/3018918b-a6f9-168d-a291-dc4edcef5ec1.png)

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

![09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/e0e5fe8d-28d8-ab8a-71fc-a180dff062a8.png)

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

```python: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
```


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

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

[MX L3 Outbound Firewall Block](https://ciscosecurity.github.io/sxo-05-security-workflows/workflows/umbrella/0019-l3-firewall-block)

![10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/9c8c5029-5fa1-86d6-bd49-758eab3ab5f9.png)

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

![11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/be4389a4-fd3b-2445-9463-d4de8f264115.png)

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

![12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/311200/cda6af80-fb79-a040-bd6e-94781adcef2d.png)


# 参照
[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/