Deep Security API to automate tasks を使ってみた #DeepSecurity

Deep Security の new RESTful API を試してみたメモです。
APIサンプルをもとに、実際試していて気になったことの補足を入れています。

前提

Deep Security の環境がある (ここでは Deep Security as a Service を利用)
API Key が発行済みである
- [Administration]-[UserManagement]-[Contacts] から発行できます。
Python を利用
- API reference に java, java script のサンプルもあるので適宜

接続準備

Package の import

sdk を以下よりダウンロードします。
sdk ダウンロードページ

以下のようにpackageをimportします。

sudo pip install (ダウンロードしたzipファイル)

接続設定の作成

以下で接続できます。

import deepsecurity
from deepsecurity.rest import ApiException
import sys, warnings

# HTTPSの警告抑止
if not sys.warnoptions:
    warnings.simplefilter("ignore")

# 接続設定
self.configuration = deepsecurity.Configuration()

# URL を指定。自前の場合は 'https://ホスト名:4119/api' など
self.configuration.host = 'https://app.deepsecurity.trendmicro.com/api'

# API Key
self.configuration.api_key['api-secret-key'] = '(発行したAPIkey)'

# proxy環境の場合は、proxyのurlも追加
# self.configuration.proxy = 'http://proxyサーバのアドレス:ポート'

情報の取得、更新

システム設定の取得

api_instance = deepsecurity.SystemSettingsApi(deepsecurity.ApiClient(configuration))
api_version = 'v1'

try:
    api_response = api_instance.list_system_settings(api_version)

    # 戻りは、　{(プロパティ名): {"value": (値)}} 形式
    # dictで扱いたい場合は変換
    api_response_dict = api_response.to_dict()

except ApiException as e:
    print("An exception occurred when calling SystemSettingsApi.list_system_settings: %s\n" % e)

ポリシーなども、 list_policies など対応するものを使用すれば一覧取得できます。

システム設定の更新

# 設定用オブジェクトを作成
system_settings = deepsecurity.SystemSettings()

# 更新したいパラメータを指定する。
# 前述 list_~ で取得した結果を元に指定。
# ここでは、Agentが更新されない場合の警告日数を更新。 default 7days --> 6days。
system_settings.platform_setting_alert_agent_update_pending_threshold = {'value': '6 Days'}

try:
    # 戻りは、更新後の設定一覧
    api_response = api_instance.modify_system_settings(system_settings, api_version)

except ApiException as e:
    print("An exception occurred when calling SystemSettingsApi.modify_system_settings: %s\n" % e)

設定用オブジェクト作成のタイミングでdictをパラメータに渡すこともできます。
ただし、 list_~ で取得した dict をそのまま渡すことはできません。
(IDなど、更新できない値が含まれるため。updateに不適切な key を削除する必要があります)

update_dict = {
  "platform_setting_alert_agent_update_pending_threshold" : 
    {'value': '6 Days'}
}
system_settings = deepsecurity.SystemSettings(**update_dict)

ポリシーなども、 modify_policy など対応するものを使用すれば更新できます。
なお、 create_policy や modify_policy ではルール情報の登録は行われません。
以下メソッドなどを用いて、個別に登録する必要があります。
- set_firewall_rule_ids_on_policy
- set_integrity_monitoring_rule_ids_on_policy
- set_intrusion_prevention_rule_ids_on_policy

条件に合うポリシーの検索

search_~ の使い方については、以下に例とともに記載してあります。
Search for Resources

PolicyCriteria で検索条件を作成、PolicyFilter に配列で渡し、検索します。

# 検索条件 
# 評価パターンは前述のリンク参照 (string_test, numeric_test などに記載)
search_dict = {'fileld_name': 'name', 'string_test': 'equal', 'string_value': 'Windows%'}
search_criteria = deepsecurity.SearchCriteria(**search_dict)

# 第1引数は応答数(max_items)。 Noneの場合、デフォルト値の 5000(最大値)。
# 配列に複数の SearchCriteria を渡すことで、複合条件を設定可能。
search_filter = deepsecurity.SearchFilter(None, [search_criteria])

# windows関連のポリシー一覧を取得
api_response = api_instance.search_policies(api_version='v1', search_filter=search_filter, overrides=False)

field_name に指定する名称は、それぞれの describe~ の応答を参考にしてください。
※ Camel表記です。 pythonの場合、実際の応答と異なるので注意。(policy_id --> policyID)

なお、応答に含まれるオブジェクト内の値は検索条件に指定できません。
(search_computer での azure, ec2, esx 情報、 search_policy での　ルール情報など)

※ 2019/3/31 追記
version 12系では、search_computers に限り、一部オブジェクト内の値の検索もできるようになったようです。
[検索できる例]
* 'field_name': 'ec2VirtualMachineSummary/instanceID'
* 'field_name': 'field_name': 'interfaces/name'
[検索できない例]
* 'field_name': 'ec2VirtualMachineSummary/state'
* 'field_name': 'computer_status/agent_status'

最後に

API Reference のサンプルほぼそのままで、簡単に APIを使った操作ができました。
使う方の参考になればと思います。