IBM TechXchange Japan QRadar User Group

 View Only

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

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

  

 

はじめに

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

トップに戻る

Ansible連携アプリの概要

QRadar SOARAnsibleの連携については、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_pathsearch_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 Playbookfind_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_servertarget_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 Playbookfind_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