CBC Slack App

日常業務の合間に PoC をするとなると,Alert 通知を活用したくなります. 通知先,やっぱり Slack かな?と GitHub をうろうろしていたら,ピッタリなものがありました.しかも Dev 専では無い私レベルでも動かせそう!

github.com

という訳で,早速試してみたいと思います.


1. CbAPI の設定
CbAPI の Install 手順は以下で公開されています.

cbapi.readthedocs.io

PoC なので,負荷の低い VM (CentOS 8.2) に venv で環境用意する事にしました. /usr/local/vmug の下に cbapi ディレクトリを作成して進めて行きます.

[root@jpvmug vmug]# mkdir cbapi
[root@jpvmug vmug]# cd /usr/local/vmug/cbapi/
[root@jpvmug vmug]# python3 -m venv /usr/local/vmug/cbapi
[root@jpvmug vmug]# source bin/activate

pip を upgrade しておきます.

(cbapi) [root@jpvmug cbapi]# pip3 install --upgrade pip
Cache entry deserialization failed, entry ignored
Collecting pip
  Downloading https://files.pythonhosted.org/packages/de/47/58b9f3e6f611dfd17fb8bd9ed3e6f93b7ee662fb85bdfee3565e8979ddf7/pip-21.0-py3-none-any.whl (1.5MB)
    100% |████████████████████████████████| 1.5MB 809kB/s 
Installing collected packages: pip
  Found existing installation: pip 9.0.3
    Uninstalling pip-9.0.3:
      Successfully uninstalled pip-9.0.3
Successfully installed pip-21.0

CbAPI の最新バージョンを pip 経由で Install すれば完了です.

(cbapi) [root@jpvmug cbapi]# pip install cbapi
Collecting cbapi
  Downloading cbapi-1.7.3-py2.py3-none-any.whl (208 kB)
     |████████████████████████████████| 208 kB 23.8 MB/s 
・・・
(長いので省略)
・・・
Installing collected packages: wcwidth, urllib3, six, idna, decorator, chardet, certifi, validators, solrq, requests, pyyaml, python-dateutil, pygments, protobuf, prompt-toolkit, pika, cachetools, attrdict, cbapi
Successfully installed attrdict-2.0.1 cachetools-4.2.1 cbapi-1.7.3 certifi-2020.12.5 chardet-4.0.0 decorator-4.4.2 idna-2.10 pika-1.1.0 prompt-toolkit-3.0.14 protobuf-3.14.0 pygments-2.7.4 python-dateutil-2.8.1 pyyaml-5.4.1 requests-2.25.1 six-1.15.0 solrq-1.1.1 urllib3-1.26.3 validators-0.18.2 wcwidth-0.2.5

GitHub から CBC_slack_api_showcase.py を忘れずに Download しておきましょう.


2. CBC API Key の作成
次は,CBC Console で API Key を作ります.
Settings -> API Access メニューから "+ Add API Key" をクリックします. f:id:tcpninja:20210129181650p:plain

表示された Add API Key ダイアログで必須項目を入力して Save します.Name は任意,Access Level type は "SIEM" を選択です. f:id:tcpninja:20210129182325p:plain

API ID と API Secret Key をしっかりメモして,次に進みましょう. f:id:tcpninja:20210129182803p:plain


3. CBC Notification
続いて,CBC Console で通知の設定をします.
Settings -> Notifications メニューから "+ Add Notification" をクリックします. f:id:tcpninja:20210130152124p:plain

Add Notification ダイアログで必須項目を入力して Add します.今回は Name を Slack,Policy はとりあえず "All policies" を選択し,通知手段として API Keys で先程作成した API Key を選択します.Alert の Severity も選択できるので,とりあえず 1 にして全部受けてみます. f:id:tcpninja:20210130152919p:plain CBC Console 側での操作はこれで完了です.


4. API Credentials File の準備
さぁ,python script を稼働させる VM に戻って設定を続けて行きましょう.CbAPI では Script 中に CB の Credentials を埋め込まずに済むよう,Profile に紐づけた File に保存する事を推奨しています.これは cbapi-response configure コマンドで簡単に出来ます.

(cbapi) [root@jpvmug cbapi]# cbapi-defense configure
Welcome to the CbAPI.
URL to the Cb Defense API server (do not include '/integrationServices') [https://hostname]: https://defense-prod05.conferdeploy.net/ <-  API サーバーの URL
Connector ID: YOUR_API_ID  <-   2 で作成した API ID
API key: YOUR_API_KEY  <-   2 で作成した API key
Successfully wrote credentials to /root/.carbonblack/credentials.defense.

/root/.carbonblack/ の下に Credentials File が生成されるので,拡張子を .defense から .psc に変更し,中身を確認して Profile 名をメモしておきます.

(cbapi) [root@jpvmug cbapi]# cat /root/.carbonblack/credentials.psc 
[default] <-   これが Profile 名
url = https://defense-prod05.conferdeploy.net/
token = YOUR_API_KEY/YOUR_API_ID
ssl_verify = True

忘れないうちに CBC_slack_api_showcase.py 中の profile を確認してください.デフォルトは profile="default" になっているようです.異なっている場合は Profile 名を合わせてください.

###### Creds #######

# Input your cbapi profile here - make sure the connector type is 'SIEM'
cb = CbDefenseAPI(profile="default")


5. Slack Workspace の準備
ここは Slack 側での作業です.
'cb_alerts' channel を作成します. CBC_slack_api_showcase.py 内の channel 名を変更して別の channel に通知する事も出来ます.

# Specify the channel you would like alerts to be sent to (create channel for cb_alerts if not)
channel = "cb_alerts"


6. Slack Developer Kit for Python の Install
↓これですね. python-slackclient.readthedocs.io
また VM に戻って,pip でサクッと Install します.

(cbapi) [root@jpvmug cbapi]# pip install slackclient
Collecting slackclient
  Downloading slackclient-2.9.3-py2.py3-none-any.whl (96 kB)
     |████████████████████████████████| 96 kB 8.4 MB/s 
・・・
(長いので省略)
・・・
Installing collected packages: typing-extensions, multidict, yarl, idna-ssl, chardet, attrs, async-timeout, aiohttp, slackclient
    Running setup.py install for idna-ssl ... done
  Attempting uninstall: chardet
    Found existing installation: chardet 4.0.0
    Uninstalling chardet-4.0.0:
      Successfully uninstalled chardet-4.0.0
Successfully installed aiohttp-3.7.3 async-timeout-3.0.1 attrs-20.3.0 chardet-3.0.4 idna-ssl-1.1.0 multidict-5.1.0 slackclient-2.9.3 typing-extensions-3.7.4.3 yarl-1.6.3


7. Slack App の作成
ここからは Slack で操作して行きます.
https://api.slack.com/apps から新しい App を作成します. f:id:tcpninja:20210130164432p:plain

Create a Slack App ダイアログで App Name をつけて,通知先の Workspace を選択します. f:id:tcpninja:20210130164843p:plain

CB 用の App が作成されたら,
Settings -> Basic Information の Add features and functionality で Incoming Webhooks を選択して設定します. f:id:tcpninja:20210130170035p:plain

Activate Incoming Webhooks を On にし,"Add New Webhook to Workspace" をクリックしましょう. f:id:tcpninja:20210130170410p:plain

前述の 5 で通知先として決めた channel を選択して許可します. f:id:tcpninja:20210130170920p:plain

生成された Webhook URL を Copy ボタンで取得します. f:id:tcpninja:20210130171318p:plain

この Webhook URL をCBC_slack_api_showcase.py 内の 27 行目で指定します.

# This is the webhook associated with your Slack Bot, to post the actions in response to the alert content
webhook = 'https://hooks.slack.com/services/YOUR_WEBHOOK_URL'

Slack の画面ショットばかりで長くなりましたが,もうちょっとです(苦笑).
Features -> OAuth & Permissions の Scopes で,Bot Token Scopes を確認してください. 先程 Incoming Webhooks を設定しているので,既に incoming-webhook の Scope が存在していると思いますが,これだけでは足りないので,"Add an OAuth Scope" をクリックして chat:write を追加します. f:id:tcpninja:20210130173854p:plain

ちなみに,API リクエストに必要な Scope が足りない場合はエラーで確認できるので,環境や利用する機能に応じて追加してください.

slack.errors.SlackApiError: The request to the Slack API failed.
The server responded with: {'ok': False, 'error': 'missing_scope', 'needed': 'chat:write:bot', 'provided': 'incoming-webhook'}

Copy ボタンで Token を取得しましょう. f:id:tcpninja:20210130174309p:plain

この Token は CBC_slack_api_showcase.py 内 15 行目の slack_token の値として使います.

# Input in your Slack Token, which ideally is stored as an environmental variable
slack_token = 'xoxb-YOUR_SLACK_APP_TOKEN'

作成された Bot ユーザーを "cb_alerts" channel に追加すれば準備は完了です!


8. いよいよ実行
VM 上で Background 実行します.
Severity 毎のリアクション変更したり,通知の項目名を日本語にしたりとソースを弄ったので CBC_slack.py とファイル名は変えています.

(cbapi) [root@jpvmug cbapi]# python ./CBC_slack.py &

30 秒毎で Alert の check をしているとの事なので暫く待っていると,目出たく Slack に通知が届きました! f:id:tcpninja:20210130180054p:plain

秀逸な事に,通知された Alert の Investigate ボタン 1 Click で Slack から CBC Console を表示できるのです.そのまま Triage を進められるので超絶便利. f:id:tcpninja:20210130180940p:plain

ますます Slack から出れなくなってしまう今日この頃でした.