VMware Carbon Black クラウド セキュリティ

Carbon Black Cloud – API入門

こんにちは、セキュリティ事業部の山田です。

Carbon Black CloudはAPIでほとんどの操作を行うことができます。しかし、いざ使用しようと思っても「APIの情報ってどこにあるの?どうやって使うの?」と思われる方も多いでしょう。そこで今回はAPIの使いかたの基本をご紹介します。

まず、APIの仕様はこちらのDevelopper Network で公開しています。

 

はい、全部英語です。「めんどくさい」と思われた方、大丈夫です。ポイントだけ理解してしまえば長文を読む必要はありません。

APIを使う上でのポイントとは何か?それは

  • 認証の方法
  • アクセスレベル
  • APIキー
  • HTTPリクエストメソッド
  • 各APIのURL

といったものです。

これらは個別に説明するより、具体的な手順の中で紹介した方が分かりやすいでしょう。本記事では端末情報取得を例に挙げ、APIの使いかたをご紹介します。

 

1)対象のAPI

端末情報取得のAPIはこちらです。これはDevice IDを指定すると、その端末の詳細情報が返ってくるAPIです。

https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/devices-api/#specific-device-information

 

2) アクセスレベルの設定

まずはアクセスレベルの設定が必要です。アクセスレベルとはAPIの権限のことであり、Developper NetworkにはPermission、Operation部分に記載されています。
今回の場合は以下画像のようにdevice、READですね。これはつまり「端末情報を取得するにはdeviceのREAD権限が必要だよ」といっています。

 

ではこのdevice, READをCarbon Black Cloudに設定しましょう。
設定 > APIアクセス > アクセスレベル タブ >  アクセスレベルの追加 を開き、Device読み取り(つまりREAD)にチェックを入れ保存します。

 

3) APIキーの作成

設定 > APIアクセス > APIキー タブ >  APIキーを追加 にてAPIキーを作成します。

「アクセスレベルのタイプ」 は「カスタム」を選択し、手順2で作成したアクセスレベルを選択し保存します。

<補足>
「アクセスレベルのタイプ」 プルダウンには以下の4つの選択肢があります。
SIEM、API、Live Response、カスタム

このうち、SIEM、API、Live Responseは古い機能です。これからAPIを使用される方は基本的に「カスタムを使う」と考えて頂いた方がよいでしょう。

 

 

4) 認証

認証は、HTTPリクエストにX-Auth-Tokenヘッダを付けることで行います。このヘッダの値は、APIシークレットキーとAPI IDを「/」でつなげたものになります。
こんな感じですね。

X-Auth-Token:APIシークレットキー/API ID

「APIシークレットキー」と「API ID」は各行の右側プルダウンで「API認証情報」を選ぶと表示されます。これらをメモしておきましょう。

また、各インスタンス固有の「組織キー(Org Key)」も必要です。APIキーページの左上に表示されているので、これもメモしておきましょう。

 

5) HTTPリクエストメソッド & URL

メソッドとURLは手順1)で紹介したページに記載があります。以下の赤囲み部分です。

GETメソッドだと分かります。

URLの{}部分は環境に合わせて書き換えてください。

  • cbc-hostname : Carbon Black Cloud管理コンソールのホスト名
  • org_key: 手順4で取得した組織キー
  • device_id: 端末固有のDevice ID

完成したURLはこのようになります。
https://defense-prodnrt.conferdeploy.net/appservices/v6/orgs/XXXXXX/devices/2065645

 

<補足>
古くからのCBユーザは「API専用のAPI URLはどこにいった?」と思われるかも知れません。その点は現在気にする必要はありません。APIでも管理コンソールと同じホスト名が使用可能です。

 

6)curlでリクエスト

curlを用いてリクエストを出してみましょう。

curlの引数はこれまでに準備したX-Auth-TokenヘッダとURLを組み合わせるだけです。
curl -H “X-Auth-Token:AAAAAAAAAAAAAA/BBBBBB” https://defense-prodnrt.conferdeploy.net/appservices/v6/orgs/XXXXXXX/devices/2065645

では実行してみます。

端末情報のJsonが返ってきました。大成功!

 

最後に

いかがでしたでしょうか?他のAPIを利用する際も認証の仕方は同じです。APIごとにURL、メソッド、アクセスレベルが違う点を意識しておけば、ほとんどのAPIを簡単に利用することができます。APIを用いて色々な操作の自動化を試してみてください。

関連記事