はじめに
Universal Cloud REST API プロトコルをXML定義ファイルでカスタマイズして、特定の DSM やプロトコルがないデータ・ソースなど、さまざまな REST API からイベントを収集できます。
QRadar SIEMには、既にAWSやAzureなどメジャーなクラウドサービスのREST APIに対応した様々なプロトコルが提供されていますが、対象サービスごとに仕様が異なるため、それぞれ専用のモジュールが配布されています。
一方で、SOAPのようなカッチリした決まりはないものの、REST APIという１つの一般的な手法で作られているため、対象サービスの各種API間に共通する部分が多いことも事実です。
Universal Cloud REST API プロトコルは、一般的なREST APIからデータを取得するために必要なコア機能を提供し、その動作をカスタマイズすることで、様々なREST APIに対応したログの取得を可能にしています。
あまり一般的ではない(例えば日本だけで提供されているような)サービスのAPIはどうしても開発の優先順位が下がり、なかなかプロトコル・モジュールが提供されないこともあります。
従来であれば、プロトコル・モジュールが提供されていないREST APIからログを取得するためには、何らかのスクリプト等を開発してREST APIからデータを引き出し、それをSyslogやLogFileなどの既存の一般的なプロトコルで扱えるデータに変換していました。
Universal Cloud REST API プロトコルを使用することで、コーディングの量を減らし、QRadar SIEMのコレクターから直接REST APIを発行してログを取得できるようになります。
トップに戻る
プロトコルとDSMの関係
ここで、「プロトコル」と「DSM (Device Support Module)」の関係を整理しておきたいと思います。
一般的な技術用語にもプロトコルという言葉は存在しますが、QRadar における「プロトコル」は、モジュールとしてインストールしたり構成を行う対象となるモジュールの名前です。
DSMは、プロトコルが処理した後のペイロードに対して、パーシングや正規化を行います。
Universal Cloud REST API プロトコルは、任意のREST APIからログのペイロード部分を取り出す機能を提供します。
しかし、QRadar SIEMでログのセキュリティー分析を最大限に行うためには、パーシングや正規化を行うDSMを用意する必要があります。
そのため、Universal Cloud REST API プロトコルを使用する場合は、同時にカスタムDSMも作成することになります。
カスタムDSMの作成については、「
QRadar CE (Community Edition) 7.3.3 にカスタム・ログを取り込んで分析しましょう (カスタムDSM) 」をぜひご確認ください。
トップに戻る
Universal Cloud REST API プロトコルの概要
ログ収集で一般的に使用されているSyslogが、QRadar SIEMのコレクターが受け身で受信するパッシブなプロトコルであるのに対して、Universal Cloud REST API プロトコルは、QRadar SEIMコレクターから外部に対してPULL動作を行うアクティブなプロトコルです。
Universal Cloud REST API プロトコルの動作は、ワークフローの XML 文書によって定義されます。
XML 文書は、独自に作成することも、Github から入手することもできます。
Universal Cloud REST API プロトコルのXML実装例については、GitHub (
https://github.com/ibm-security-intelligence/IBM-QRadar-Universal-Cloud-REST-API) を参照してください。
Github 上のワークフローは参考になりますが、IBMサポート窓口では取り扱っていないことにご注意ください。
トップに戻る
Universal Cloud REST API プロトコル使用の準備
Universal Cloud REST API プロトコルは、QRadar 7.3.2 以降でサポートされています。
使用するためには、QRadar Log Source Management (LSM) アプリケーション (
App Exchange から入手可能) がインストールされている必要があります。
また、Universal Cloud REST API プロトコル・モジュールを
IBM Fix Central から入手してインストールする必要があります。
インストール方法は他のプロトコルと同じですので、例えば「
QRadar コンソールへの MSRPC プロトコルのインストール - IBM Documentation」の記述と同じように、
yum -y install PROTOCOL-UniversalCloudRESTAPI-XXXX.rpm でインストールします。
注意：比較的新しいモジュールであるため、前提となる
PROTOCOL-Common モジュールも更新する必要があるかもしれません。
PROTOCOL-Commonは他の多くのプロトコルの前提条件でもあるため、更新する場合はAWS用やOffice365用など他のプロトコルも同時に更新が必要になる可能性があります。
プロトコルの追加後は、QRadar SIEMのWeb管理コンソールにログインし、管理タブの「拡張 > すべての構成のデプロイ」を行います。
トップに戻る
Universal Cloud REST API プロトコルの用語と基本構造
| 用語 |
説明 |
| Workflow |
–イベント取得プロセスを記述するXMLドキュメントで、1つ以上のパラメーターを定義します。
–パラメーターの値は、Workflow XML内で明示的に割り当てるか、Workflow Parameter Value XMLから取得できます。
–順番に実行される複数のアクションから構成されます。
–ワークフローを実行すると、パラメーター値が「状態」に追加されます。
–「状態」は、ワークフローの実行中にアクションからアクセスや変更ができます。
|
| アクション |
–アクションは、ワークフローの構成要素です。
–各アクションには、HTTP エンドポイントの呼び出しや QRadarへのイベントのポストなど、固有の目的があります。
|
| Workflow Parameter Value |
–ワークフローの入力パラメーターであり、XMLファイルに保存されています。
–キーと値のペアのセットで表され、キーは、ワークフローで定義されているパラメーター名と一致する必要があります。
|
状態
|
–実行中のワークフローのデータを表すJSONオブジェクトです。
–状態は厳密に定義されておらず、データは動的に「状態」に格納されます。
|
Universal Cloud REST API プロトコルのロジックは、「Workflow」XMLに「アクション」を記述することで作成します。
Workflow XMLは、様々なアクションを組み合わせてロジックを実現する、プログラミング言語のような位置付けです。
利用可能なアクションの一覧については、「
アクション - IBM Documentation」を参照してください。
ロジックから初期パラメーターを分離したものが「Workflow Parameter Value」XMLで、例えば接続先のIPアドレスやアカウント、パスワードなどを記述します。QRadar SIEMのLSM画面でログソースを定義する際、Workflow XMLは平文のまま画面に表示されますが、Workflow Parameter Value XMLは ****** に置き換えられて表示されます。
「状態」はキーと値を格納しておくことができるストレージで、ロジックが動作する際の一時データを保存しておく場所になります。
一時データにはロジックの動作をコントロールするためのポインターのようなものや、REST APIから戻されるログデータのペイロードそのものなどがあり、どのように使用するのかは実装するロジックに依存します。
REST APIから前回からの増分を取得してQRadarに取り込むシンプルな Workflow XML文書の例は、以下のようなものになります。
–Workflow Parameter Values (抜粋)
<Value name="host" value="REST APIサーバーIPアドレス" />
–Workflow (抜粋)
:
<Initialize path="/bookmark" value="0" />
:
<CallEndpoint url="http://${/host}/movies?_start=${/bookmark}&_limit=10" method="GET" savePath="/get_events" >
</CallEndpoint>
:
<PostEvents path="/get_events/body/name" source="${/host}" />
:
<Set path="/bookmark" value="${/bookmark + count(/get_events/body/id)}" />
:
トップに戻る
ワークフローの開発環境と開発ステップ
Universal Cloud REST API プロトコルのWorkflow XML文書は、GitHub (
https://github.com/ibm-security-intelligence/IBM-QRadar-Universal-Cloud-REST-API) に置かれている
Workflow-v1.xsd スキーマファイルで定義されています。
ご使用のXMLエディターが補完機能を備えている場合、このXSDファイルを設定することで、編集画面にヒントを表示したり文法チェックを行うなどの支援を得られる場合があります。
例えば、Eclipseを使用している場合、「Window > Preference」でダイアログ画面を開き、「XML > XML Catalog」を開いて「User Specified Entries」で「Add」をクリックすることで、Workflow XMLのスキーマを定義した XSDを追加できます。
これにより、Eclipse上でWorkflow XMLを編集する際に、ヒントや自動補完の効果が得られます。
このように開発環境から一定の支援はありますが、やはりXMLはプログラミング言語ではないため、いきなりREST APIを処理するためのロジックを書き起こすのに向いているとは言えません。
QRadar SIEM上で動作検証を行う支援コマンドラインツールもありますが、開発環境から直接呼び出せるものではなく、一旦Workflow XML文書を完成させてから使用するものとなっています。
そのため、対象サービスのREST APIに対してPython のrequestsライブラリーやcurlコマンド を使って動作検証を行い、その結果をもとにWorkflow XML文書に移植する方法をおすすめします。
各種REST APIは説明文書の中でPythonやcurlのサンプルを載せている場合もありますので、動作するコードを速やかに作成しやすくなります。
トップに戻る
具体的なサンプルWorkflow XML
ここで、具体的なサンプルとなるWorkflow XMLとWorkflow Parameter Value XMLを紹介します。
とはいっても全く新しいものを書き起こすのではなく、GitHub (
https://github.com/ibm-security-intelligence/IBM-QRadar-Universal-Cloud-REST-API) に公開されているArielの例を少しだけ修正して使用します。
ArielはQRadar SIEMのログDBの名前で、保管されているログに対してREST APIで内容を取得できます。
QRadar SIEM自身に備わっているログソースであるため、準備の手間が少なく開発サンプルとして適しています。
※今回は 図中のQRadar SIEM(A)と(B)は同じ1台のマシンです。
GitHubのサンプル
Ariel は、Ariel DB から
deviceType = 368 Health Metrics のログだけを取り出しているため、これを少し汎用化して任意のイベントを取り出せるようにしてみます。
GitHubから Ariel-Workflow.xml と Ariel-Workflow-Parameter-Values.xml をローカルにコピーし、それぞれ Ariel-
Filtered-Workflow.xml と Ariel-
Filtered-Workflow-Parameter-Values.xml にリネームします。
変更箇所はわずかで、以下の引用箇所で
黄色でマーカーを付けた部分です。
–Ariel-Filtered-Workflow-Parameter-Values.xml
<?xml version="1.0" encoding="UTF-8" ?>
<WorkflowParameterValues xmlns="http://qradar.ibm.com/UniversalCloudRESTAPI/WorkflowParameterValues/V1">
<Value name="host" value="" />
<Value name="username" value="" />
<Value name="password" value="" />
<Value name="aql_where" value="" />
</WorkflowParameterValues>
–Ariel-Filtered-Workflow.xml (抜粋)
<?xml version="1.0" encoding="UTF-8" ?>
<Workflow name="Ariel" version="1.0" xmlns="http://qradar.ibm.com/UniversalCloudRESTAPI/Workflow/V1">
<Parameters>
<Parameter name="host" label="Host" required="true" />
<Parameter name="username" label="Username" required="true" />
<Parameter name="password" label="Password" required="true" secret="true" />
<Parameter name="aql_where" label="AQL Where clause" required="true" />
</Parameters>
<Actions>
<!--
/////////////////////
// Post the Search //
/////////////////////
-->
<!-- Initialize the Bookmark -->
<Initialize path="/bookmark" value="${time() - 60000 * 60}" />
<!-- Post the Search -->
<FormatDate pattern="yyyy-MM-dd HH:mm Z" timeZone="UTC" time="${/bookmark}" savePath="/start" />
<CallEndpoint url="https://${/host}/api/ariel/searches" method="POST" savePath="/post_search">
<SSLConfiguration allowUntrustedServerCertificate="true" />
<BasicAuthentication username="${/username}" password="${/password}" />
<QueryParameter name="query_expression" value="SELECT endTime, Base64(payload) FROM events WHERE endTime > ${/bookmark} AND ${/aql_where} order by endTime START '${/start}'" />
<QueryParameter name="query_language_version" value="3" />
<RequestHeader name="Accept" value="application/json" />
<RequestHeader name="Content-Type" value="text/xml" />
<RequestHeader name="Version" value="5.0" />
</CallEndpoint>
(後略)
修正した Ariel-
Filtered-Workflow.xml と Ariel-
Filtered-Workflow-Parameter-Values.xml の全体は、GitHub の
Ariel Filtered から確認できます。
トップに戻る
UniversalCloudRESTAPITest コマンドラインツール によるテスト
実際にQRadar SIEMのログソースを定義する前に、正しくREST APIからログのペイロードが取得できることを、UniversalCloudRESTAPITest コマンドラインツールで確認します。
まだ Ariel-
Filtered-Workflow-Parameter-Values.xml に必要な値が入っていませんから、必要な値を入れた別のファイルを用意します。
<?xml version="1.0" encoding="UTF-8" ?>
<WorkflowParameterValues xmlns="http://qradar.ibm.com/UniversalCloudRESTAPI/WorkflowParameterValues/V1">
<Value name="host" value="172.30.34.90" />
<Value name="username" value="khirayama" />
<Value name="password" value="パスワード" />
<Value name="aql_where" value="LOGSOURCENAME(logsourceid) ilike '%win%'" />
</WorkflowParameterValues>
この例では、AQLの
Whereに
LOGSOURCENAME(logsourceid) ilike '%win%' を指定し、ログソース名にwin が含まれている全てのログをREST APIから取得するように指定しています。
2つのXMLファイルをQRadar SIEM環境にscpで転送し、UniversalCloudRESTAPITest コマンドラインツールを呼び出します。
パラメーターに
--helpを与えると、使い方が表示されます。
[root@QRadar UCRA]# java -cp "/opt/ibm/si/services/ecs-ec-ingress/current/bin/*:/opt/ibm/si/services/ecs-ec-ingress/eventgnosis/lib/q1labs/*" com.q1labs.semsources.sources.universalcloudrestapi.UniversalCloudRESTAPITest --help
usage: test-workflow
Test a Universal Cloud REST API protocol workflow.
-h,--help Displays the usage and exits.
-p <[user@]server:port> Specifies the proxy to use.
-r <seconds> Runs the workflow continuously (every 5 seconds by default).
-s <file> Specifies the file for state persistence.
-u Specifies that untrusted server certificates are allowed.
-v Displays more logging.
-w <file> Specifies the workflow to load.
-wp <file> Specifies the workflow parameter values to load.
Visit IBM Knowledge Center for more information about this protocol.
ツールの使用中に取得したイベントは、QRadar SIEMのイベント・パイプラインに渡されず、すべてQRadarコンソールに出力されます。
以下はコマンドの出力例です。
[root@QRadar UCRA]# java -cp "/opt/ibm/si/services/ecs-ec-ingress/current/bin/*:/opt/ibm/si/services/ecs-ec-ingress/eventgnosis/lib/q1labs/*" com.q1labs.semsources.sources.universalcloudrestapi.UniversalCloudRESTAPITest -w Ariel-Filtered-Workflow.xml -wp Ariel-Filtered-Workflow-Parameter-Values.xml
SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:file:/opt/ibm/si/services/ecs-ec-ingress/2020.7.2.20210120225428/bin/slf4j-log4j12-1.7.13.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:file:/opt/ibm/si/services/ecs-ec-ingress/2020.7.2.20210120225428/bin/slf4j-simple-1.7.6.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
2021-09-19 16:17:15 [INFO ][UniversalCloudRESTAPITest] Received 28 events from 172.30.34.90
2021-09-19 16:17:15 [INFO ][UniversalCloudRESTAPITest] <13>Sep 19 15:14:16 ISSMGMT01 LEEF:1.0|IBM|WinCollect|7.2.8.145|2|src=ISSMGMT01 os=Windows Server 2008 R2 (Build 7600 64-bit) dst= sev=3 log=Code.SSLConfigServerConnection msg=ApplicationHeartbeat
2021-09-19 16:17:15 [INFO ][UniversalCloudRESTAPITest] <13>Sep 19 15:17:19 ISSLABDC LEEF:1.0|IBM|WinCollect|7.2.8.145|2|src=ISSLABDC os=Windows Server 2008 R2 (Build 7601 SP1 64-bit) dst=172.30.34.90 sev=3 log=Code.SSLConfigServerConnection msg=ApplicationHeartbeat
2021-09-19 16:17:15 [INFO ][UniversalCloudRESTAPITest] <13>Sep 19 15:19:17 ISSMGMT01 LEEF:1.0|IBM|WinCollect|7.2.8.145|2|src=ISSMGMT01 os=Windows Server 2008 R2 (Build 7600 64-bit) dst= sev=3 log=Code.SSLConfigServerConnection msg=ApplicationHeartbeat
2021-09-19 16:17:15 [INFO ][UniversalCloudRESTAPITest] <13>Sep 19 15:22:19 ISSLABDC LEEF:1.0|IBM|WinCollect|7.2.8.145|2|src=ISSLABDC os=Windows Server 2008 R2 (Build 7601 SP1 64-bit) dst=172.30.34.90 sev=3 log=Code.SSLConfigServerConnection msg=ApplicationHeartbeat
(中略)
[root@QRadar UCRA]#
トップに戻る
Universal Cloud REST API プロトコルを使用したログソースの追加
REST APIからペイロードが取得できることが確認できたら、実際にQRadar SIEMにログソースを定義します。
ログ・ソース・タイプには任意のプロトコルを選択できるカスタムのログソース・タイプ(DSMエディターから作成可能)を指定し、プロトコルとして Universal Cloud REST APIを指定してログ・ソースを作成します。その際に、Workflow XML と Workflow Parameter Values XMLの内容を コピー・アンド・ペーストで入力します。
まず、Log Source Management (LSM) アプリを起動します。
「ログ・ソース」または「Disconnected Log Collector」を選択する画面が表示された場合は、「ログ・ソース」を選択します。
右上の「+新規のログソース」をクリックし、「単一のログ・ソース」を選択します。
「ログ・ソース・タイプの選択」では、「Universal DSM」を選択し、「ステップ2：プロトコル・タイプの選択」をクリックします。
注意：この例では「Universal DSM」というタイプをそのまま指定するように示してしますが、フィルターの柔軟性やパフォーマンス・チューニングの観点で、推奨ではありません。前述のようにDSMエディターであらかじめ「カスタム・ログ・ソース・タイプ」を作成し、それを指定してください。
「プロトコル・タイプの選択」では「Universal Cloud REST API」を選択し、「ステップ3：ログ・ソース・パラメーターの構成」をクリックします。
「ログ・ソース・パラメーターの構成」では「名前」などの必須項目を入力し、「ステップ4：プロトコル・パラメーターの構成」をクリックします。
「プロトコル・パラメーターの構成」では「ログ・ソースID」になんらかの値、「Workflow」に 「Ariel-Filtered-Workflow.xml」の内容、「Workflow Parameter Values」にパスワードなどの値を入れた「Ariel-Filtered-Workflow-Parameter-Values.xml」の内容を入力(またはコピー・アンド・ペースト)します。
テスト環境であるため、「Allow Untrusted Certificates」はONにしておきます。
最後に、「ステップ5：プロトコル・パラメーターのテスト」をクリックします。
「テストの開始」をクリックすると、与えたパラメーターに従って対象サービスからREST API経由でペイロードの取得を行います。
正しくペイロードが取得できていることが確認できたら「終了」をクリックします。
しばらく経過すると、「ログ・アクティビティー」タブから新たに追加したログソース経由 (つまり、Universal Cloud REST APIプロトコル経由) で、ログの収集が行われていることが確認できます。
今回の例では単にペイロードの取り込みを確認しただけですが、実際にログを継続的に分析するためには、カスタムDSMを作成してプロパティーを切り出したりイベント・マッピングを行うなど、「QRadar CE (Community Edition) 7.3.3 にカスタム・ログを取り込んで分析しましょう (カスタムDSM) 」で説明した内容も実施する必要があります。
トップに戻る
参考文献
#QRadar