CBC Slack App

Carbon Black

日常業務の合間に 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 から出れなくなってしまう今日この頃でした．