目次

旧バージョンのREST API

元のバージョンのDeep Securityで元々リリースされていたREST APIは引き続き使用できますが、非推奨となっており、新機能は追加されません。可能な場合は、 Workload Security APIを使用して、新機能と継続的なサポートを利用する必要があります。

関連項目:従来のREST APIリファレンスドキュメント

レガシーREST API

レガシーREST APIで必要な機能が提供され、それらの機能がWorkload Security APIでまだ提供されていない場合、引き続きレガシーREST APIを使用する必要があります。次の表は、Workload Security APIにおけるREST APIの機能の概要を示しています。

エンドポイントが Workload Security APIに継続して追加されています。定期的にこのテーブルの変更を確認してください。

カテゴリ 能力 Workload Security APIのサポート
認証 ログインしてログアウトする はい- レガシーAPIキー および Trend Micro Cloud One APIキー
セッションを記述して終了する 使用不可
管理者 管理者の作成、記述、一覧表示、変更、および削除 はい - APIリファレンスの 管理者 を参照してください。
ポリシー設定 ポリシーの 不正プログラム対策 設定を記述、変更、および削除する はい - APIリファレンスの ポリシーの変更 を参照
ポリシーの検索設定をリセット、記述、および変更する 使用不可
ポリシーの アプリケーションコントロール 設定の説明と変更 はい - APIリファレンスの ポリシーの変更 を参照
ホスト(コンピュータ) コンピュータの 不正プログラム対策 設定を記述、変更、および削除する はい - を参照APIリファレンス内のコンピュータ を変更する
コンピュータのスキャナ設定をリセット、記述、および変更する 使用不可
スマートフォルダの作成、削除、説明、リスト作成、変更、および同期 使用不可
スマートフォルダ内のコンピュータを一覧表示する 使用不可
リレーおよびリレーグループの表示、無効化、説明、および変更 使用不可
ホストグループのツリーをリストします。 はい - APIリファレンスの リストのコンピュータグループ を参照
コンピュータの検索設定を記述、変更、および削除する 使用不可
不正プログラム検索設定 不正プログラム検索設定の作成、記述、表示、変更、および削除 はい - APIリファレンスの 不正プログラム対策 の設定 をレファレンス/参照情報。
予約タスク 予約タスクの作成、削除、記述、変更、およびリスト表示 はい - APIリファレンスの Scheduled Tasks を参照してください。
予約タスクの受信者リストを変更する はい - APIリファレンスのScheduled Tasks > Modify a Scheduled Task > Request Body > generateReportTaskParametersを参照してください
スクリプト リストスクリプト はい - APIリファレンスの スクリプト を参照してください。
レポート レポートテンプレートのリスト表示 はい - APIリファレンスの レポートテンプレート を参照してください。
アラート アラートの説明とリスト 使用不可
アラートの種類の説明、表示、変更、およびリセット 使用不可
アラートを消去して、1つのターゲットに対してアラートを閉じます。 使用不可
イベントベースタスク イベントベースのタスクの作成、削除、およびリスト表示 はい - APIリファレンスの イベントベースのタスク を参照してください。
役割 役割のホスト、ホストグループ、およびポリシーへのアクセスの追加、削除、および変更 使用不可
役割の追加と削除権限 使用不可
ロールの作成、削除、記述、変更、およびリスト表示 使用不可
課金 AWS Marketplace請求レコードとインスタンスレートのリスト 使用不可
クラウド AWSアカウントへの接続、削除、変更、および接続の説明 使用不可
クラウドアカウントのリスト表示、作成、削除、記述、変更、および同期(非AWS) 使用不可
アプリケーションコントロール 決定ログの説明、リスト、および元に戻す 使用不可
ルールセットの作成、削除、記述、およびリスト表示 使用不可
グローバルルールセットを記述し、グローバルルールセットルールを追加および削除します。 使用不可
アプリケーションのドリフトとコンピュータのドリフトを記述、リスト表示、およびレビューする 使用不可
ソフトウェアインベントリの作成、削除、記述、およびリスト表示 使用不可
信頼済みアップデートモードの説明と変更(メンテナンスモード) 使用不可
侵入防御 SSL設定の作成、削除、変更、記述、およびリスト表示 使用不可
接続された脅威の防御 不審オブジェクトのリストをクリアして変更する 使用不可
イベント リストと説明不正プログラム対策、セキュリティログ監視、ログ検査、Webレピュテーション、およびアプリケーションコントロールイベント 使用不可
Syslog設定の表示、作成、削除、記述、および変更 使用不可
SAML SAMLサービスプロバイダの説明 使用不可
SAML IDプロバイダのリスト作成、作成、削除、記述、および変更 使用不可
SAMLを使用するロールを仮定する 使用不可
診断 マネージャとエージェントの診断パッケージを取得する 使用不可
ライセンス ライセンスのステータスの説明とアクティベーションコードのアップデート 使用不可
ニュースフィード ニュースフィード項目の説明、表示、および消去 使用不可
環境 プロキシのリスト作成、削除、記述、および変更 使用不可

REST APIを使用するように環境を設定する

次のタスクを実行して、REST APIを使用した開発環境を準備します。

  1. Deep Security WebサービスSDKのダウンロード
  2. REST APIクライアントで使用できるユーザアカウントを作成する

WebサービスSDKのダウンロード

WebサービスSDK ZIPファイルをダウンロードして解凍します。

Deep Security WebサービスSDK

ZIPファイルには、REST APIのドキュメント、Javaクライアントアプリケーションの開発に役立つJavaクライアントライブラリ、およびこのライブラリを使用するサンプルが含まれています。別の言語を使用する場合、またはJavaを使用して独自のRESTクライアントテクノロジを使用する場合は、REST APIリファレンスドキュメントを使用してAPI呼び出しの構文を学習してください。各操作について、HTTPパスと操作 (GET、PUTなど)、およびAPI呼び出しとの間でやりとりされるデータの構造の説明などを含むHTTP構文がリファレンスに提供されます。

コンテンツの完全なリストやその他の重要な情報については、ZIPのReadmeファイルを参照してください。

Webサービスの役割とユーザを作成する

Deep Security WebサービスAPIエンドポイント(SOAPおよびRESTの両方)にアクセスするための権限と、REST APIで使用するその他の機能を持つ役割を作成します。セキュリティ上の理由から、API呼び出し専用の役割とユーザを作成する必要があります。

REST APIでは、コンピュータ権限、セキュリティプロファイル権限、およびユーザ権限など、すべての役割アクセスコントロールが適用されます。たとえば、特定のコンピュータを表示できるWebサービスAPIの役割を作成する場合、そのユーザとして認証されるREST APIクライアントは指定されたコンピュータのみを表示できます。

  1. Workload Security コンソールで、 [管理]→[ユーザ管理]→[ロール]の順に選択します。
  2. [新規] をクリックします。
  3. [ Workload Security Managerユーザインタフェース へのアクセスを許可]の選択を解除し、[ WebサービスAPIへのアクセスを許可]を選択します。
  4. 他の設定がすべて完了したら、[保存] をクリックします。
  5. アカウントに参加するようにユーザーを招待します。詳細については、 こちらをご覧ください。
  6. ユーザに必要なプロパティを指定します。[Role]プロパティで、作成した役割を選択します。
  7. 新しいユーザアカウントのユーザ名とパスワードを書き留めておきます。

REST APIクライアントアプリケーションの開発

APIのドキュメントに従って、任意のプログラミング言語を使用して、REST APIを呼び出すコードを記述します。XMLまたはJSONエンコードをサポートするプログラミング言語、およびHTTPプロトコルとHTTPSプロトコルを使用できます。

関連項目:従来のREST APIリファレンスドキュメント

Basic APIへのアクセス

REST APIへのすべてのアクセスは、REST APIエンドポイント https://app.deepsecurity.trendmicro.com/restによって行われます。

REST APIでは標準のHTTPメカニズムが使用されるため、HTTP GETを使用した認証を行わずに一部の操作にアクセスできるため、Webブラウザからこれらのメソッドにアクセスできます。たとえば、次のURLはREST APIバージョンをブラウザに返します。

https://dsm.example.com:4119/rest/apiVersion

ただし、ほとんどのREST APIコールでは認証が必要です。呼び出しを認証するには、セッション識別子(SID)をGETメソッドとDELETEメソッドのクエリパラメータとして、またはPUTメソッドとPOSTメソッドのメッセージ本文として指定します。セッションIDを取得するには、APIへのアクセスが許可されたユーザのユーザ名とパスワードを使用して /rest/authentication/login URLを呼び出します。

セッションを管理する

セッションを管理するには、次の処理を実行します。

  • APIセッションが不要になった場合にAPIセッションを終了します。Workload Security では、一度にアクティブにできるセッションの数を制限します。最大同時セッション数に達するのを避けるために、アプリケーションはセッションを終了する必要があります。セッションを終了するには、 /rest/authentication/logout URLを呼び出します。
  • セッションは、設定可能な期間が経過した後にタイムアウトします。ユーザごとに許可される同時セッション数とセッションタイムアウトを変更するには、 [管理]→[システム設定]→[セキュリティ]を選択します。

Javaコードの例 は、このプロセスを示しています。

提供されているJava REST APIクライアント

提供されるJava REST APIクライアントは、 RESTEasy Client Framework および Apache HTTPComponentsプロジェクトに基づいています。このフレームワークは、JAX-RSアノテーションでマークアップされたJavaインタフェースを使用し、 Workload Securityと通信できるインタフェースの実装を生成します。Java REST APIクライアントは、すべてのオブジェクトのシリアル化と非シリアル化、HTTP URL、およびHTTPメソッドを処理します。

Java REST APIクライアントを使用するには、アプリケーションのクラスパス上のlibフォルダにJARファイルを含めます。JARファイルは他のサードパーティのライブラリに依存しています。詳細については、samplesディレクトリ内のEclipseプロジェクトのpom.xmlファイルを参照してください。

すべてのAPIのインタフェースは、Javaパッケージ com.trendmicro.ds.platform.rest.apiにあります。APIとの間で送受信されるすべてのオブジェクトは、Javaパッケージ com.trendmicro.ds.platform.rest.object とサブパッケージにあります。

Javaコードの例

次のサンプルコードでは、Java REST APIクライアントを使用して Workload Securityで認証を行います。

import javax.ws.rs.core.Response.Status;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ClientResponseFailure;
import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor;
import org.jboss.resteasy.plugins.providers.RegisterBuiltin;
import org.jboss.resteasy.spi.ResteasyProviderFactory;

import com.trendmicro.ds.platform.rest.api.IAuthenticationAPI;
import com.trendmicro.ds.platform.rest.message.error.ErrorMessage;
import com.trendmicro.ds.platform.rest.object.DSCredentials;

public class AuthenticateSample {

    public static void main(String[] args) {
        // URL for the REST API. Change this as appropriate. 
        String restApiUrl = "https://10.0.0.5:4119/rest";

        // The user name to use for authentication. Change this as appropriate.
        String username = "admin";

        // The user's password. Change this as appropriate.
        String password = "supersecretpassword";

        // Variable to store the session identifier (SID).
        String sID = null;

        // RESTEasy client framework initialization that only needs to be done once per VM
        RegisterBuiltin.register(ResteasyProviderFactory.getInstance());

        // An object that will execute HTTP requests
        ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();

        // Create the object that will communicate with the authentication API.
        IAuthenticationAPI authClient = ProxyFactory.create(IAuthenticationAPI.class, restApiUrl, executor);

        // Create the object to pass to the authentication call.
        DSCredentials credentials = new DSCredentials();
        credentials.setUserName(username);
        credentials.setPassword(password);

            try {
                System.out.println("Attempting to authenticate to Workload Security REST API...");
                sID = authClient.login(credentials);

                System.out.println("Authentication successful.");
                System.out.println("Authentication session ID string received: " + sID);

            } catch (ClientResponseFailure e) {
                // This is a special type of exception that means the server threw
                // an exception because there was a problem with the credentials.
                // It's important to handle these exceptions explicitly or the
                // connection to the server won't be released back in to the
                // underlying connection pool, meaning any subsequent API calls would fail.
                // See the RESTEasy Client Framework documentation for more details. 
                ClientResponse<?> clientResponse = e.getResponse();

                // Try to parse the error response in to an instance of the special
                // ErrorMessage class and display the result.
                Status status = clientResponse.getResponseStatus();
                System.out.println("Server returned error status code " + status.getStatusCode() + " (" + status + ")");
                ErrorMessage errorMessage = clientResponse.getEntity(ErrorMessage.class);
                System.out.println("Returned error message: " + errorMessage.getMessage());

            } catch (Exception e) {
                // Some other error happened, most likely related to network communication problems.
                System.out.println("There was an error during authentication.");
                e.printStackTrace();

            } finally {
                if (sID != null) {
                    // Make sure to always log out.
                    System.out.println("");
                    System.out.println("Ending session...");
                    authClient.endSession(sID);
                    System.out.println("End session successful.");
                    // make sure the session ID isn't accidentally re-used.
                    sID = null;
                }
            }

            // Cleanup: force the HTTP Client to close any open sockets
            executor.close();

    }

}

サンプルJavaコードの使用

Sample Javaコードはsamplesフォルダに含まれています。サンプルは、EclipseワークスペースにインポートできるEclipseプロジェクトの一部です。

  1. Eclipseで、[File]→[Import]の順にクリックします。
  2. インポート元として [General]→[Existing Projects into Workspace]を選択します。
  3. [Browse]をクリックし、 Deep Security Web Services SDKのサンプルフォルダをルートとして選択します。
  4. REST API Samples プロジェクトが選択されていることを確認し、[ Finish ]をクリックします。

Eclipse内でサンプルファイルを実行するには、ファイルを開き、[Run]→[Run As]→[Java Application] をクリックします。サンプルには、[Run Configurations]画面で設定する必要があるコマンドライン引数が必要です。

HTTPステータスコード

REST APIでは、標準HTTPステータスコードを使用してリクエストのステータスが返されます。次の表は、使用されるレスポンスコードと、それらが返される状況を示しています。

HTTPステータスコード 意味
200 OK 要求が正常に終了しました。
400 Bad Request 呼び出し元が、呼び出しに必要なすべてのデータを指定していませんでした。
401 Unauthorized 呼び出し元のSIDが非アクティブなためタイムアウトしました。認証プロセスを繰り返す必要があります。
403 Forbidden 次のいずれかの理由が考えられます。
  • 呼び出しには、WebサービスAPIへのアクセス権がありません。
  • 呼び出し元のユーザは、失敗したAPIを呼び出すためのアクセス権を持っていません。
  • 発信者のSIDが無効です。
  • 呼び出し元はテナント内のユーザですが、APIはプライマリテナントユーザのみに制限されています。
404 Not Found 次のいずれかの理由が考えられます。
  • 呼び出し元がREST APIに含まれていない無効なURLにアクセスしました。
  • 呼び出し側が存在しないリソースを指定しました。たとえば、IDごとにテナントを削除しようとしましたが、指定されたIDが既存のテナントに一致しません。
405 Method Not Found 呼び出し側が、指定されたURLに対して許可されていないHTTPメソッドを指定しました。たとえば、HTTP POSTを使用してGETアクセスを提供するAPIにアクセスします。
500 Internal Server Error 次のいずれかの理由が考えられます。
  • データベースエラーが発生しました。
  • 未処理のエラーが発生しました。

エラー応答

APIコールが 200 OK以外のステータスコードを返す場合、レスポンス本文には通常、次の例のようなJSONコードが含まれます。

{
   "error": {
      "message": "The Activation Code KA47-R947M-KDLUZ-A8WLF-WM6A3-LOL is invalid."
   }
}

一部のコールには、次の例のようにJSONではなくXMLコードが含まれます。

<error>
    <message>Error message string</message>
</error>

XMLレスポンス本文を強制的に使用するには、 リクエストにapplication/xmlの値とともにAccept ヘッダを追加します。

このエラーメッセージは、問題のデバッグに役立ちますが、アプリケーションのエンドユーザにプレゼンテーションするのには適していません。

javax.ws.rs.core.Responseを返すAPI呼び出し

いくつかのAPIコールは、javax.ws.rs.core.Response型のオブジェクトを返すものとしてドキュメント化されています。これらのコールは、HTTPステータスコード以上のものを返すものと考えることができます。

提供されたJava REST APIクライアントを使用する場合、そのようなコールを無視するのではなく、その結果を取得することが重要です。Response オブジェクトを取得したら、RESTEasy Client Frameworkの説明に従って、サーバとの接続を手動で接続プールに解放する必要があります。たとえば、次のとおりです。

org.jboss.resteasy.client.ClientResponse&lt;?> clientResponse = (ClientResponse&lt;?>)apiObject.methodThatReturnsResponse(methodParameters);
clientResponse.releaseConnection();

特別な考慮事項

クエリパラメータ

検索クエリで日付を指定する場合は、 RFC 822のセクション5に記載されている日付エンコードルールを使用してエンコードします。ただし、年は、 RFC 1123のセクション5.2.14に従って、2桁ではなく4桁でエンコードする必要があります。たとえば、 November 31 2012 at 3:45 PM Eastern Standard Time31 Nov 2012 15:45:00 -0500としてエンコードします。

Javaでは、 java.text.SimpleDateFormat と日付形式パターン dd MMM yyyy HH:mm:ss zzzを使用してこれらの日付をエンコードできます。

たとえば、セッションIDが DC5A4AA79326DF3E149A26EA2DA6B0C7の場合、 November 31 2012 at 3:45 PM Eastern Standard Timeの後に次のURLがすべてのホスト保護情報を照会します。ここで、日付エンコードの空白は %20でURLエンコードされています。

https://dsm.example.com:4119/rest/monitoring/usages/hosts/protection?sID=DC5A4AA79326DF3E149A26EA2DA6B0C7&from=31%20Nov%202012%2015:45:00%20-0500