こんにちは、セキュリティ事業部の山田です。
Carbon Black CloudはAPIでほとんどの操作を行うことができます。しかし、いざ使用しようと思っても「APIの情報ってどこにあるの？どうやって使うの？」と思われる方も多いでしょう。そこで今回はAPIの使いかたの基本をご紹介します。
まず、APIの仕様はこちらのDevelopper Network で公開しています。
はい、全部英語です。「めんどくさい」と思われた方、大丈夫です。ポイントだけ理解してしまえば長文を読む必要はありません。
APIを使う上でのポイントとは何か？それは
- 認証の方法
- アクセスレベル
- APIキー
- HTTPリクエストメソッド
- 各APIのURL
といったものです。
これらは個別に説明するより、具体的な手順の中で紹介した方が分かりやすいでしょう。本記事では端末情報取得を例に挙げ、APIの使いかたをご紹介します。
1)対象のAPI
端末情報取得のAPIはこちらです。これはDevice IDを指定すると、その端末の詳細情報が返ってくるAPIです。
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を用いて色々な操作の自動化を試してみてください。
