Deep Security REST APIの使用方法

Deep Securityには、その機能を他のアプリケーションと統合するためのREST (REpresentational State Transfer) WebサービスAPIが含まれています。そのため、プログラミング言語に依存しない簡単な方法で外部からデータやプログラミング設定にアクセスできます。REST APIは、GETやPUTなどの標準のHTTPメカニズムと、JSONやXMLなどの一般的なデータエンコード手法を使用します。

RESTインタフェースで使用できるすべてのAPI呼び出し、APIへのアクセスに必要なHTTP構文 (HTTPパス、GET/PUTメソッドなど)、API呼び出しでやり取りされるデータの構造についての説明などは、次のドキュメントを参照してください。

• Deep Security 10.0 APIのドキュメント

このAPIのドキュメントは組み込みのJava REST APIクライアントに基づいていますが、特定のプログラミング言語に限定されるわけではありません。

組み込みのJava REST APIクライアントはRESTEasyプロジェクトに基づいており、HTTPトランスポートにはApache HttpComponents™を使用します。これらのプロジェクトのドキュメントは、RESTEasyプロジェクトとApache HttpComponents™プロジェクトで入手できます。

REST APIには次の機能が含まれます。

• 認証 - ユーザのログイン/ログアウト。
• クラウドアカウント - Deep Security Managerを同期するクラウドアカウントの作成、表示、アップデート、および削除と、クラウドの強制同期。
• イベント - 不正プログラム対策イベントとWebレピュテーションイベントの表示。
• ステータス監視 - Deep Security Managerノードのステータス (さまざまな状態チェックなど) の表示。
• テナント管理 - テナントアカウントの作成、表示、アップデート、および削除と、テナントによって使用されるデータベースサーバの作成と表示。
• 使用状況の監視 - Deep Security Managerがどのテナントに対してどの処理を行ったかを示す統計情報の取得。

はじめに

REST APIの基本的な使用開始手順は次のとおりです。

1. ステータス監視APIを有効にします (オプション)。
2. 外部のWebサービスクライアントが利用できるユーザアカウントを作成します。
3. Deep Security ManagerのSSL証明書を入手します。
4. Deep Security Managerと通信するREST APIクライアントを開発します。

ステータス監視APIを有効にする (オプション)

REST APIのほとんどの機能は、Deep Security Managerをインストールして起動すると使用できるようになります。追加の設定は必要ありません。ただし例外として、ステータス監視APIについては、使用する前に有効にする必要があります。このAPIはアクセスに認証を必要としないため、初期設定では無効になっています。

1. Deep Security Managerで、[管理]→[システム設定]→[詳細] の順に選択します。
2. [ステータス監視API] セクションで、[有効] を選択し、[保存] をクリックします。

Webサービスユーザアカウントを作成する

Deep Security Managerには強力な役割に基づいたアクセス機能が備わっており、これには、あるユーザアカウントがWebサービスAPIまたはManagerユーザインタフェースにアクセスできるかどうかを制御する設定も含まれます。セキュリティ上の理由から、新しいユーザアカウントと、Webサービス固有の新しい役割を作成することをお勧めします。

REST APIとSOAP WebサービスAPIは、どちらもすべての役割アクセス制御 (コンピュータの権限、セキュリティプロファイル権限、ユーザ権限など) を強制します。特定のコンピュータグループのコンピュータの表示のみを許可する役割をWebサービスAPI用に作成すると、その役割を使用するWebサービスクライアントは指定されたコンピュータグループにのみアクセスできます。

Webサービスアクセス専用の新しい役割を作成するには、以下の手順を実行します。

1. Deep Security Managerで、[管理]→[ユーザ管理]→[役割] の順に選択します。
2. [新規] をクリックします。
3. [Deep Security Managerユーザインタフェースへのアクセスを許可] チェックボックスをオフにし、[WebサービスAPIへのアクセスを許可] チェックボックスをオンにします。
4. 他の設定がすべて完了したら、[保存] をクリックします。
5. [管理]→[ユーザ管理]→[ユーザ] に進み、[新規] をクリックします。
6. WebサービスAPIでのみ使用する新しいユーザを作成します。先に作成した新しい役割をこのユーザに割り当てます。
   新しいユーザアカウントのユーザ名とパスワードを書き留めてください。

Deep Security ManagerのSSL証明書を入手する

すべてのREST APIクライアントは、HTTPS通信を使用してDeep Security Managerと通信する必要があります。したがって、既知の認証局によって発行された証明書を使用してDeep Security Managerが実行されている場合を除いて、一般にはRESTクライアントで使用されている信頼されたX.509証明書ストアにDeep Security Manager SSL証明書をインポートする必要があります。Javaプログラムの場合、カスタムトラストストアを使用するか、または初期設定のトラストストアに証明書をインポートできます。JavaのSSL設定オプションについての詳細は、『Java™ Secure Socket Extension (JSSE) Reference Guide』を参照してください。

インストール済みのDeep Security Managerの公開鍵を取得する方法は複数あります。以下はFirefoxを使用する場合の方法です。

1. Firefoxを起動し、Deep Security Manager Webページに接続します。
2. アドレスの横の鍵アイコンをダブルクリックします。
3. [詳細を表示] をクリックします。
4. [証明書を表示] をクリックします。
5. [詳細] タブをクリックします。
6. [エクスポート] をクリックします。
7. 証明書を「X.509 Certificate (DER)」としてエクスポートします。
8. これをManager.cerという名前で保存します (例: c:\work\DeepSecurityWebServices\Manager.cer)。

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

XMLまたはJSONエンコードとHTTPおよびHTTPSプロトコルをサポートするプログラミング言語は、すべてDeep Security Manager REST APIクライアントアプリケーションの開発に使用できます。SOAPベースのWebサービスと異なり、REST Webサービスでは、すべての処理と処理の入出力を記載したWSDLファイルを公開しません。クライアントアプリケーション開発者が、APIのドキュメントに従ってAPIを呼び出すコードを記述する必要があります。

Javaを使用した開発用には、Javaアプリケーションで使用できるJavaクラス一式がlibフォルダに用意されており、Javaクライアントアプリケーションの開発をより簡単に進めることができます。これらのクラスの使用方法を説明したサンプルコードはsamplesフォルダにあります。

その他の言語を使用する場合や、Java開発で独自のRESTクライアント技術を使用する場合は、RESTインタフェースで使用できるすべてのAPI呼び出しとアクセスに必要なHTTP構文 (HTTPパス、GET/PUT処理など)、API呼び出しでやり取りされるデータの構造についてDeep Security 10.0 APIのドキュメントを参照してください。

REST APIを使用する

このセクションでは、REST APIの使用方法に関する基本情報を示します。

基本的なAPIアクセス

REST APIへのアクセスは、すべてDeep Security Manager URL (https://<ホスト名/IP>:<ポート>/rest) を介して行います。たとえば、Deep Security Managerがdsm.example.comという名前のコンピュータにインストールされ、かつREST APIポート番号で待機している場合、URLは次のようになります。

REST APIは標準のHTTPメカニズムを使用しており、一部の処理にはHTTP GETを使用して認証なしでアクセスでき、この場合、正しいアドレスを入力すればWebブラウザからアクセスできます。次に例を示します。

上記のURLを入力すると、ブラウザにREST APIのバージョンが表示されます。

しかし、ほとんどのREST API呼び出しは認証を必要とします。認証は、セッションID (SID) の形で指定され、GETおよびDELETEメソッドの場合はクエリパラメータとして、PUTおよびPOSTメソッドの場合はメッセージ本文のどこかに挿入されて呼び出しに渡されます。セッションIDを取得するには、そのAPIへのアクセスが許可されたユーザのユーザ名とパスワードを使用して/rest/authentication/login URLを呼び出します。アプリケーションが完了するかセッションIDが不要になった時点で、/rest/authentication/logout URLを呼び出してセッションを終了する必要があります。このプロセスは、以下のサンプルアプリケーションに示されています。

組み込みのJava REST APIクライアントを使用する

組み込みのJava REST APIクライアントは、RESTEasyクライアントフレームワークに基づいています。このフレームワークは、JAX-RSのアノテーションでマークアップされたJavaインタフェースを受け取り、受け取ったインタフェースのDeep Security Managerと通信可能な実装を生成します。このクライアントコードを使用すると、オブジェクトのシリアライズとデシリアライズ、HTTP URL、およびHTTPメソッドをすべて処理できます。

Java REST APIクライアントを使用するには、libフォルダ内のJARファイルをすべてアプリケーションのclasspathに追加します。これらのJARファイルの一部 (commons-loggingなど) は広く使用されているため、アプリケーションにすでに含まれている場合もあります。その場合、もう一度追加する必要はありません。

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

Javaコード例

以下に、Java REST APIクライアントコードを使用してREST APIにユーザを認証するコード例を示します。

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 Deep Security Manager 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サンプルコードを使用する

いくつかのJavaサンプルコードが samples フォルダに含まれています。これらのサンプルは、Eclipseプロジェクトの一部で、次の手順でEclipseワークスペースにインポートできます。

1. Eclipseで [File] メニューを開き、[Import] を選択します。
2. インポートソースとして、[General]→[Existing Projects into Workspace] を選択します。
3. [Browse] をクリックし、ルートとしてrestapi\samplesフォルダを選択します。
4. REST APIサンプルプロジェクトが選択されていることを確認し、[Finish] をクリックします。

サンプルファイルを実行するには、Eclipse内でファイルを開いて [Run]→[Run As]→[Java Application] を選択します。サンプルには、コマンドライン引数 ([Run Configurations] 画面で設定) が必要です。

APIのドキュメント

REST APIで使用できる各メソッドの説明は、Deep Security 10.0 APIのドキュメントで確認できます。このドキュメントは、特定のプログラミング言語に固有のものではありません。

Java REST APIクライアントのユーザ向けに、javadoc形式のドキュメントも提供されています。

応答処理

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メソッドを指定しました。たとえば、GETアクセスが必要と指定されているAPIへのアクセスにHTTP POSTを使用したという場合が考えられます。
500 Internal Server Error	データベースエラーが発生しました。 その他の処理されないエラーが発生しました。

エラー応答

APIコールから200 OK以外のステータスコードが返されると、応答本文には通常、次の例のようなJSONコードが含まれます。

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

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

<エラー><メッセージ>エラーメッセージ文字列</ message></ error>;

XML応答本文を強制的に使用するには、 application/xmlの値を使用して Accept ヘッダを要求に追加します。

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

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

API呼び出しの中には、タイプがjavax.ws.rs.core.Responseのオブジェクトを返すとドキュメント内で説明されているものがあります。これらの呼び出しで返されるのは、HTTPステータスコードだけです。

組み込みのJava REST APIクライアントを使用するときには、これらの呼び出しの結果を無視するのではなく、取得することが重要です。RESTEasyクライアントフレームワークで説明されているように、応答オブジェクトを取得した時点でサーバへのベース接続を手動で開放し、接続プールに戻す必要があります。たとえば、次のとおりです。

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

その他の考慮事項

クエリパラメータに日付を指定する

検索クエリに日付を指定するときには、RFC 822のセクション5に規定された日付エンコードルールを使用してエンコードする必要があります。ただし、年はRFC 1123のセクション5.2.14に従い、2桁ではなく4桁としてエンコードします。たとえば、11月31日の2012 at 3:45 PM（東部標準時）は、 31 Nov 2012 15:45:00 -0500としてエンコードされます。

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

例:セッションIDがDC5A4AA79326DF3E149A26EA2DA6B0C7の場合、次のURLを使用して東部標準時の2012年11月31日、3:45 PM以降のすべてのホスト保護情報を照会できます。ただし、日付エンコード内のスペースはURLでは「%20」でエンコードされています。
https://dsm.example.com:4119/rest/monitoring/usages/hosts/protection?sID=DC5A4AA79326DF3E149A26EA2DA6B0C7&from=31%20Nov%202012%2015:45:00%20-0500

マルチテナント権限

REST APIの多くは、マルチテナント環境の管理に使用されるものです。これらのAPIでは、通常の役割権限に加えて、API呼び出しを行うユーザがプライマリテナントアカウントのユーザであることが必要です。テナントのユーザがこれらのAPIの呼び出しを試みると、ステータスコード「403 Forbidden」が返されます。プライマリテナントユーザのみが呼び出すことができるAPIを次に示します。

• /monitoring - 監視API
• /multitenantconfiguration - マルチテナント設定API
• /tenants - テナントAPI
• /tenantdatabaseservers - テナントデータベースサーバAPI
• /tenanttemplate - テナントテンプレートAPI