IBM TechXchange Japan QRadar User Group

  • Private Group
 View Only

QRadar SOAR: Ansible呼び出しプレイブックの例

By Katsuyuki Hirayama posted Mon November 06, 2023 02:48 AM

  

 

はじめに

このブログに含まれているプレイブックは、QRadar SOARのPlaybook Designer機能で作成しています。
Playbook Designerの操作イメージについては、関連ブログである「QRadar SOAR による GUI ベースのプレイブック開発の概要」をご覧ください。

トップに戻る

Ansible連携アプリの概要

QRadar SOARとAnsibleの連携については、Ansible用とAnsible Tower用で別のアプリが用意されています。

今回は、Ansible用のAnsible for SOARを使用します。
このアプリは、SOARプラットフォームから事前に作成済みのAnsible Playbook を実行でき、パラメータ置換を使用して引数を渡すことができます。

アプリの実体となるPythonコードはEdge Gateway内のコンテナーで動作しますが、プレイブックのユーザーインターフェースから、Ansible Playbookを呼び出す「関数」にアクセスできます。(Ansible Playbookの具体的な処理は、インベントリーに定義された各ホスト上で実行されます)

NOTE: 「プレイブック」を作成するためのPlaybook Designerツールは、ここ数年で急速に機能を成熟させてきたツールです。
そのため、過去に作成されたアプリの中には、「プレイブック」形式のサンプルを含んでいないものがあります。

Ansibleアプリも、まだ「プレイブック」形式のサンプルを持っておらず、代わりに「ルール」+「ワークフロー」形式のサンプルが含まれています。
「関数」としてはどちらの形式にも対応していますので、「プレイブック」形式で作り直すことが可能です。

トップに戻る

Ansible連携アプリのファイル構造

今回使用した環境では、以下のフォルダー構造で関連ファイルを構成しています。
Web画面で編集した各ファイルが、そのままコンテナーにデプロイされます。

 

/var/rescircuits/ansible/ は、アプリのapp.configで指定しているものです。

[fn_ansible]
runner_dir = /var/rescircuits/ansible
# temporary files collected when running a module or a playbook
artifact_dir = /tmp
# change this value to trim the collection of previous process runs
artifact_retention_num = 7

このアプリの考慮点として、builtin以外のAnsibleモジュールの導入に手間がかかることがあげられます。
Dockerfileを書き換えない限り、コンテナーの構造を恒久的に変更することはできませんので、Web画面から一つ一つ必要なファイルを追加していく必要があります。

トップに戻る

プレイブックの例：Ansibleで指定したファイルを探す

今回の例では、Ansible Playbook：「find_files.yml」で指定したファイルを探し、結果をデータテーブルの行として追加します。

トップに戻る

プレイブックの全体像

トップに戻る

プレイブックのトリガー

 

  • アクティブ化のタイプ：手動
  • オブジェクト・タイプ：インシデント
  • アクティベーション・フォーム
  • 条件：なし(常に表示)
  • 自動キャンセル：なし

トップに戻る

関数呼び出し(Ansible Playbook)

 

  • 関数の出力
    • 出力名：output
  • 関数の入力：スクリプト指定
    • ansible_playbook_nameには、Ansible Playbookのファイル名を固定テキストで指定します。
    • ansible_parametersには、target_pathとsearch_patternをセミコロン(;)で区切って与えます。
      • target_pathには、探索対象のパスを固定テキストで指定します。
      • search_patternには、プレイブックのトリガーで定義したアクティベーション・フォームのエレメントのAPI名を指定します。
  • inputs.ansible_playbook_name = "find_files.yml"
inputs.ansible_parameters = "target_path=/tmp;search_pattern={}".format(playbook.inputs.filename)

 

  • 実際に呼び出されるAnsible Playbook：find_files.yml
  • - name: Find files from the given path 

  hosts: servers 
  gather_facts: false 
  vars: 
    # 値は QRadar SOARプレイブックから上書きされます。
    target_path: "/tmp" 
    search_pattern: "*" 
    
  tasks: 
    - name: Find files 
      ansible.builtin.find: 
        paths: "{{ target_path }}" 
        patterns: "{{ search_pattern }}" 
        recurse: false 
      register: files_matched 
     
    - name: Create output list 
      no_log: true 
      set_fact: 
        output: "{{ output|default([]) + [item.path] }}"         
      loop: "{{ files_matched.files }}" 
 
    - name: Return results 
      debug: 
        var: output

トップに戻る

スクリプト (Add Node: Ansible output)

 

関数の「output」を処理するためのスクリプトです。

  • ローカル・スクリプト
  • if len(playbook.functions.results.output['content'].keys()) == 0:
  incident.addNote("No results returned on parameters: {}".format(playbook.functions.results.output['inputs']))
else:
  # incident.addNote(str(playbook.functions.results.output))
  data = []

  for k, v in playbook.functions.results.output['content'].items():
    if 'output' in v['detail'] and isinstance(v['detail']['output'], list):
      for file in v['detail']['output']:
        data.append([k, file])
  # incident.addNote(str(data))

  for entry in data:
    # Add Row
    row = incident.addRow("showcase_ansible_files")
    row['host'] = entry[0]
    row['filepath'] = entry[1]
    row['status'] = 'Found'

 

  • 「showcase_ansible_files」データテーブルの定義
    • 上記スクリプトで値を書き込んでいるデータテーブルは、デモ用に作成したもので、以下のカラムを持っています。
 

トップに戻る

プレイブックの解説動画

上記で説明したプレイブック定義の内容を、実機画面でクイックに眺める動画です。(具体的な定義に踏み込んでいませんので、あくまでも雰囲気を感じていただくためのものです)

 

トップに戻る 

プレイブックの実行確認

1.       ケースを開き、「Showcase Ansible Files」データテーブルが空であることを確認します。

2.       インシデントのメニューから、先ほど作成したプレイブックの名前をクリックして呼び出します。

3.       Ansible Playbookが呼び出され、データテーブルにエントリーが追加されたことを確認します。

トップに戻る

プレイブックの例：Ansibleで特定ファイルをアーカイブする

先ほどのプレイブックが取得したファイル一覧の各エントリーに、メニューを追加することができます。
今回は、検出された個々のファイルについて、メニューからAnsible Playbook：「archive_a_file.yml」を呼び出して、ファイルをアーカイブする例をご紹介します。

トップに戻る

プレイブックの全体像

プレイブックの全体像は以下のとおりです。

 

トップに戻る

プレイブックのトリガー

 

  • アクティブ化のタイプ：手動
  • オブジェクト・タイプ：データ・テーブル: Showcase Ansible Files
  • アクティベーション・フォーム：なし
  • 条件
    •  [ステータス]  [次のいずれかを含まない]  [Archived][Deleted]
  • 自動キャンセル：なし

トップに戻る

関数呼び出し(Ansible Playbook)

 

  • 関数の出力
    • 出力名：output
  • 関数の入力：スクリプト指定
    • ansible_playbook_nameには、Ansible Playbookのファイル名を固定テキストで指定します。
    • ansible_parametersには、target_serverとtarget_file_pathをセミコロン(;)で区切って与えます。
      • target_serverには、ファイルが検知されたインベントリーのホストを与えます。
      • target_file_pathには、検知されたファイルのフルパス名を与えます。
    • inputs.ansible_playbook_name = "archive_a_file.yml"
inputs.ansible_parameters = "target_server={};target_file_path={}".format(row.host, row.filepath)

 

  • 実際に呼び出されるAnsible Playbook：find_files.yml
  • - name: Archive a file on the given path 
  gather_facts: false 
  vars: 
    # 値は QRadar SOARプレイブックから上書きされます。
    target_server: “ldap” 
    target_file_path: “/tmp/ryuk.bin” 
  hosts: “{{ target_server }}” 
    
  tasks: 
    - name: Archive a file 
      archive: 
        path: “{{ target_file_path }}” 
        dest: “{{ target_file_path + ‘.tgz’ }}”         
        force_archive: true 
        # 実際の用途では、`remove` は `true` に変更する必要があります
        remove: false 
      register: results 
     
    - name: Return results 
      debug: 
        var: results.dest 
      when: results is defined

トップに戻る

スクリプト (Update status)

関数の「output」を処理するためのスクリプトです。

  • ローカル・スクリプト
    • 成功した場合に、ステータスのカラムを「Archived」に変更します。
    • #incident.addNote(str(playbook.functions.results.output))
if playbook.functions.results.output['success'] == True:
  row.status = 'Archived'

トップに戻る

プレイブックの解説動画

上記で説明したプレイブック定義の内容を、実機画面でクイックに眺める動画です。(具体的な定義に踏み込んでいませんので、あくまでも雰囲気を感じていただくためのものです)

 

トップに戻る

プレイブックの実行確認

1.       ケースを開き、先ほどのプレイブックによって「Showcase Ansible Files」データテーブルに追加されたエントリーを確認します。

2.       各エントリーの右からメニューを開き、先ほど作成したプレイブックの名前をクリックして呼び出します。

3.       Ansible Playbookが実行され、各エントリーのステータスが「Archived」に変更されることを確認します。

トップに戻る

Ansibleとの連携が求められる場面

QRadar SOARには多数の連携アプリが存在しますので、必ずしもAnsible経由で接続する必要はないかもしれません。
しかし、Ansibleを使用することで、接続先に対するアクセス範囲を制限するなど、追加の制御ポイントを持つことができます。

これにより、サイバーセキュリティーとIT運用のギャップを仲介する存在として、Ansibleが両者を取り持つ存在になることができます。

トップに戻る

参考文献

 #qradar#soar

0 comments
4 views

Permalink