HTTP APIの説明

このセクションの内容:

Dr.Web for UNIX Internet Gatewaysの管理

概要

ユーザー認証と承認

Dr.Web for UNIX Internet Gatewaysの管理

脅威のリストの管理

隔離の管理

HTTP APIの使用例

1.概要

HTTP APIは、HTTPプロトコルを介してDr.Web for UNIX Internet Gatewaysを制御および管理する手段として提供されます(セキュリティを確保するために、HTTPSプロトコルが使用されます)。

APIは、HTTPプロトコルの標準メソッドであるGETPOSTを使用します。APIは、HTTPプロトコルのバージョン1.0を使用します。HTTP APIのコマンドのパラメータまたはそのようなコマンドの実行結果を表すデータは、HTTPリクエストの本文でJSONオブジェクトとしてテキスト形式で送信されます(コマンドの説明で特に明記されていない場合)。HTTP POSTリクエストの本文でJSONオブジェクトを送信する場合は、このようなリクエストのヘッダーのContent-Type:フィールドでapplication/jsonをその値として指定する必要があります。

HTTPリクエストに対するHTTPレスポンスのフォーマット

HTTP APIコマンドを処理した結果、後で個別に説明するいくつかの特別な例を除き、レスポンスでJSONオブジェクト(行われたリクエストに固有のJSONオブジェクトか、このAPI呼び出しの処理中に例外が発生した場合はError JSONオブジェクト)が返されます。

レスポンスとして送信されたJSONオブジェクトにArrayタイプのフィールドがあり、この配列に要素が1つも含まれていない場合、このフィールドはサーバーからのレスポンスから省略されます。

サーバーレスポンスのContent-Type:ヘッダーフィールドは、個別に説明するいくつかの例を除きapplication/jsonに設定されます。

クライアントがHTTP APIにないコマンドを呼び出した場合、EC_UNEXPECTED_MESSAGEを値として保持するcodeという名前のフィールドを持つError JSONオブジェクトを含むレスポンスが返されます。

SCSが使用される場合(下記を参照)、レスポンスにはSCS cookieが含まれます。

JSONオブジェクト内の文字列のエンコード

文字列は、UTF-8エンコーディング(BOMなし)で送信されます。ASCII表の一部ではない記号は、送信JSON文字列内で\uXXXXのようなシーケンスでエスケープされませんが、UTF-8エンコードで送信されます。

受信JSONオブジェクトの文字列には、UTF-8でエンコードされた記号と\uXXXXのようなエスケープシーケンスの両方を含めることができます。

データ転送に関する一般的な制限

本文内のJSONオブジェクトを待つリクエスト(POSTメソッドによるリクエスト)では、RFC 7159の観点から正しいシンボルであれば、どんなシンボルでも許可されます。

RESTアーキテクチャスタイルの要件に従って情報を送信するGETメソッドによるリクエストの場合は、RFC 1945に抵触しないシンボルであれば、どんなシンボルでもURIに含めることができます。

RFC 1945に抵触しないシンボルは、リクエストの他の場所(ヘッダー、本文)に含めることもできます。

2.ユーザー認証と承認

クライアントがHTTPコマンドにアクセスするには、サーバーによってこのようなアクセスが許可されている必要があります。次の2つの認証/承認方法が用意されています。

1.RFC 6896に準拠したSCS(Secure Cookie Sessions for HTTP)を使用する

2.Dr.Web HTTPDが信頼できるCAの証明書と見なす特別な証明書で署名されたクライアントのSSL証明書を使用する。この場合、クライアントは、認証を受けるためにrootの認証情報を正しく入力したかのように扱われます(X.509クライアント証明書が使用されます)

Secure Cookie Sessionが使用される場合、クライアントがAPIの使用を許可されていることを確認するCookie(以下では単にSCS cookieと呼びます)が従来の方法、つまりHTTPリクエスト/レスポンスのヘッダー(Cookie:はクライアントからサーバーに送信されるCookieを指定し、Set-Cookie:はサーバーからクライアントに送信されるCookieを指定します)で送信されます。クライアントの証明書に基づく認証が使用される場合は、SCS-cookieがクライアントから送信されても無視されます。

Secure Cookie Sessionを使用する場合、クライアントとDr.Web HTTPD間の対話は、クライアントがAPIのloginコマンドを送信し、APIをさらに使用するための認証を受けることから始まる必要があります。この場合、クライアントは認証に成功すると、クライアントが認証されたことを確認するSCS cookieを受け取ります。クライアント証明書に基づく認証が使用される場合は、loginコマンドを送信する必要はありません。また、このコマンドを使用して認証を受けようとすると、認証が拒否されレスポンスでエラー(Error JSONオブジェクト)が返されます。

2.1.ログインとパスワードを指定する(SCS)

認証コマンドのloginおよびlogoutは、SCSによる認証方法が使用される場合にのみ使用されます。そうでない場合は、これら2つのコマンドを呼び出そうとすると、呼び出しが拒否され、エラーが返されます(より正確には、エラーコードを含むErrorオブジェクトが返されます)。

ユーザー認証および承認コマンド:

APIコマンド

説明

login

アクション:指定されたユーザー名とパスワードに基づいてクライアントを認証し、HTTP APIのコマンドを使用することをクライアントに許可します。認証が成功すると、SCS-cookieが返されます。

URI: /api/10.2/login

HTTPメソッド:POST

入力パラメータ:AuthOptionsオブジェクト

正常に実行された結果:空のオブジェクト、SCS cookie

logout

アクション:提供されたSCS cookieを取り消します。その後、取り消されたSCS cookieを含むHTTP API呼び出しへのレスポンスとして、「EC_NOT_AUTHORIZED」エラーコードを含むErrorオブジェクトが返されます。

URI: /api/10.2/logout

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:空のオブジェクト

whoami

アクション:認証されたユーザーの名前を調べます。

URI: /api/10.2/whoami

HTTPメソッド:GET

入力パラメータ:SCS cookie)*

正常に実行された結果: whoamiオブジェクト、(SCS cookie

*)SCS cookieは、SCSによる認証が使用される場合にのみ送受信する必要があるため、これ以降は括弧に入れて表記します。

使用中のオブジェクトの説明:

1)AuthOptions - 完全なHTTP APIを使用するために認証および承認される必要があるユーザーのログインデータを含むオブジェクト:

{
"user": string, //User name
"password": string //User’s password
}

2)whoami - HTTP APIを使用することを許可されたユーザーの名前を含むオブジェクト:

{
"whoami" :
{
"user": string //User name
}
}

3)Error - 発生したエラーに関する情報を含むオブジェクト:

{
"error" :
{
"code" : string, //A string specifying an error code that looks like EC_XXX
*"what": string //Description of the error
}
}

リクエストの処理中にエラーが発生した場合にHTTP APIコマンドへのレスポンスとして返されるError JSONオブジェクトには、数値のエラーコードではなく、Dr.Web for UNIX Internet Gatewaysのコンポーネントによって使用される内部文字列型コードを含むcodeフィールドがあります。このコードは、EC_XXXのような文字列です。対応する数値コードを見つけてエラーに関する詳細情報を入手するには、「エラーの内部カタログ」を参照してください。

2.2.個人証明書を使用する認証

個人証明書を使用して認証する場合、loginおよびlogoutコマンドは使用されません。代わりに、HTTPS接続を確立するときに個人認証証明書が使用されます。個人証明書は、Dr.Web HTTPD設定で信頼できるものとして指定された認証局証明書で署名されます。このメカニズムを使用すると、受信したリクエストはrootユーザーの代わりに実行されるリクエストと見なされます。

個人証明書を使用する認証の場合:

1.認証局証明書で署名された個人証明書を作成します。

2.Dr.Web HTTPD設定(パラメータAdminSslCA)で、個人証明書に署名する認証局証明書へのパスを指定します。

3.Dr.Web HTTPDに接続するたびに、署名付き証明書を使用します。

必要に応じて、の付録E. SSL証明書を生成するセクションを参照してください。

3.Dr.Web for UNIX Internet Gatewaysを管理する

設定パラメータの現在の値を取得し、設定を変更するためのAPIコマンド:

APIコマンド

説明

設定を管理するコマンド

get_lexmap

アクション:現在の設定(ここではパラメータの語彙マップと呼ばれます)のパラメータ値を取得します。

URI: /api/10.2/get_lexmap

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:LexMapsオブジェクト、(SCS-cookie

set_lexmap

アクション:現在の設定の指定されたパラメータを設定または(デフォルトに)リセットします(パラメータの「語彙マップ」として送信されます)。

URI: /api/10.2/set_lexmap

HTTPメソッド:POST

入力パラメータ:SCS cookie)、LexMapオブジェクト

正常に実行された結果:SetOptionResultオブジェクト、(SCS cookie

コマンドの更新

start_update

アクション:更新を起動します。

URI: /api/10.2/start_update

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:StartUpdateオブジェクト、(SCS-cookie

stop_update

アクション:アクティブな更新プロセスを停止します。

URI: /api/10.2/stop_update

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:空のオブジェクト、(SCS cookie

ライセンス管理コマンド

install_license

アクション:指定されたキーファイルをインストールします。

URI: /api/10.2/install_license

HTTPメソッド:POST

入力パラメータ:SCS-cookie)、キーファイル本体(またはキーファイルを含むアーカイブ)

正常に実行された結果:空のオブジェクト、(SCS cookie

集中管理サーバーに接続するためのコマンド

esconnect

アクション:集中管理モードを有効にします。

URI: /api/10.2/esconnect

HTTPメソッド:POST

入力パラメータ:SCS cookie)、ESConnectionオブジェクト

正常に実行された結果:空のオブジェクト、(SCS cookie

esdisconnect

アクション:集中管理モードをオフにします。

URI: /api/10.2/esdisconnect

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:空のオブジェクト、(SCS cookie

製品のコンポーネントの設定が返され、いわゆる語彙マップ、つまり一連のパラメータと値のペアとして設定されます。LexMapsオブジェクトには、3つの語彙マップである以下の3つのフィールドが常に含まれます(つまり、3つのLexMapsオブジェクトが含まれます)。

active - 設定パラメータのアクティブ値、つまり現在有効な値のマップ。

hardcoded - 値が欠落しているか許可されていない場合に設定パラメータに割り当てられるデフォルト値のマップ。

master - クライアントによって設定された設定パラメータの値のマップ。

get_lexmapコマンドは、実際にインストールされて実行されているコンポーネントだけでなく、Dr.Web for UNIX Internet Gatewaysに含めることができるすべてのコンポーネントについて、常に3つすべての設定パラメータ値を返します。

使用されるJSONオブジェクトの説明:

1)LexMaps - パラメータ値のアクティブ、デフォルト、およびユーザー設定の語彙マップを含むオブジェクト

{
"active":LexMap, //Active (current) values of configuration parameters
"hardcoded":LexMap, //Default values of configuration parameters
"master":LexMap //Configuration parameter values set by the user
}

これらの各フィールドは、次にLexOptionオブジェクトの配列が格納されるLexMapオブジェクトです。

2)LexMap - パラメータの語彙マップを含むオブジェクト

{
"option":LexOption[] //Array of configuration options
}

3)LexOption - 単一のパラメータまたは設定のセクション(パラメータのグループ)を含むオブジェクト

{
"key": string, //Name of the option (configuration parameter/section)
*"value":LexValue, //If this option is a single parameter
*"map":LexMap //If this option is a section
}

LexOptionオブジェクトは、Dr.Web for UNIX Internet Gatewaysの設定のセクションまたは単一のパラメータを表します。このオブジェクトには、常にセクションの名前または単一のパラメータの名前に対応するkeyフィールドがあります。これに加えて、このオブジェクトが表すもの(単一のパラメータまたはセクション)に応じて、valueフィールド(単一のパラメータを表す場合)またはmapフィールド(セクションを表す場合)もあります。セクションもまた、LexMapタイプのオブジェクトです。一方、単一のパラメータの値は、パラメータの値を文字列形式で指定するitemフィールドを含むLexValueタイプのオブジェクトです。

4)LexValue - パラメータに割り当てられた値の配列を含むオブジェクト

{
"item": string[] //Array of parameter values
}

set_lexmapコマンドは、その入力としてLexMapオブジェクトを受け取ります。これには、値を新しい値に変更するか、デフォルトにリセットするすべてのパラメータを含める必要があります。デフォルト値にリセットするパラメータには、valueフィールドを含めないでください。ユーザーがset_lexmapコマンドで指定した語彙マップに記載されていないパラメータは変更されません。set_lexmapコマンドは、その実行の結果として、コマンドで指定されたすべてのパラメータの変更結果を含むSetOptionResultオブジェクトを返します。

5)SetOptionResult - itemフィールドにパラメータの変更結果の配列を含むオブジェクト

{
"item":SetOptionResultItem[] //Array of results
}

このオブジェクトには、コマンドで指定されたすべてのパラメータの変更結果を表すSetOptionResultItemオブジェクトの配列が含まれています。

6)SetOptionResultItem - あるパラメータの値を変更することに関する情報を含むオブジェクト。

{
"option": string, //Name of the parameter
"result": string, //Result of changing the value (error code)
*"lower_limit": string, //The lowest permitted value
*"upper_limit": string //The highest permitted value
}

optionフィールドには、アクションが適用されたパラメータの名前が含まれており、resultフィールドには、このパラメータの値を変更しようとした結果が含まれています。このフィールドは、指定された値を割り当てようとしたときに発生したエラーに関する文字列タイプのコードです。新しい値がパラメータに正常に割り当てられた場合、このフィールドにはEC_OKが含まれます。エラーの場合(このフィールドがEC_OKに等しくない場合)、このオブジェクトには、このパラメータの最大許容値と最小許容値を保持するlower_limitフィールドとupper_limitフィールドをオプションで含めることができます。

7)StartUpdateオブジェクトには、開始された更新プロセスに関するデータが含まれています

{
"start_update":
 {
   "attempt_id" : number //Identifier of a launched updating process
 }
}

8)ESConnectionオブジェクトには、開始された更新プロセスに関するデータが含まれています

{
*"server": string,    //<Host address>:<port>
"public_key": string, //Base64 server key
*"newbie": boolean,   //False by default
*"login": string,     //User name
*"password": string   //Password
}

パラメータloginpasswordは、newbie = trueの場合にのみ指定されます。

4.オブジェクトのスキャン

オブジェクトをスキャンするためのAPIコマンド:

APIコマンド

説明

ファイルスキャン(Dr.Web Network Checkerコンポーネント呼び出しを使用)

scan_request

アクション:必要なパラメータを使用してファイルをスキャンする接続(endpoint)の順序。

URI: /api/10.2/scan_request

HTTPメソッド:POST

入力パラメータ:SCS cookie)、ScanOptionsオブジェクト

正常に実行された結果:ScanEndpointオブジェクト、(SCS-cookie

scan_endpoint

アクション:作成されたendpoint接続でのデータスキャン(ファイル本体など)の起動。

URI: /api/10.2/scan_endpoint/<endpoint>

HTTPメソッド:POST

入力パラメータ:SCS-cookie)、検証可能なデータ

正常に実行された結果:ScanReportオブジェクト、(SCS-cookie

WebページカテゴリーデータベースのURLの確認

categorize_address

アクション:サーバーアドレスがWebページカテゴリーデータベースにリストされているかどうかを確認します。

URI: /api/10.2/categorize_address

HTTPメソッド:POST

入力パラメータ:SCS cookie)、CategorizeAddressオブジェクト

正常に実行された結果:CategorizedResourceオブジェクト、(SCS-cookie

categorize_url

アクション:URLがWebページカテゴリーデータベースにリストされているかどうかを確認します。

URI: /api/10.2/categorize_url

HTTPメソッド:POST

入力パラメータ:SCS cookie)、CategorizeURLオブジェクト

正常に実行された結果:CategorizedResourceオブジェクト、(SCS-cookie

Dr.Web CloudクラウドのURLとファイルのスキャン

cloud_check_url

アクション:Dr.Web Cloudで、WebページカテゴリーデータベースにリストされているURLに関するデータを確認します。

URI: /api/10.2/cloud_check_url

HTTPメソッド:POST

入力パラメータ:SCS cookie)、CheckUrlRequestオブジェクト

正常に実行された結果:UrlResultオブジェクト、(SCS-cookie

cloud_check_file

アクション:Dr.Web Cloudで、ファイルの悪質性に関するデータを確認します。

URI: /api/10.2/cloud_check_file

HTTPメソッド:POST

入力パラメータ:SCS cookie)、CheckFileRequestオブジェクト

正常に実行された結果:FileResultオブジェクト、(SCS-cookie

使用されるJSONオブジェクトの説明:

1)ScanOptionsは、ファイルスキャン用のエンドポイントを作成するために使用されるパラメータを含むオブジェクトです。

{
"scan_timeout_ms": number, //A time-out to scan one file, in ms
"cure": boolean, //Apply cure to infected file
"heuristic_analysis": boolean, //Use heuristic analysis
"packer_max_level": number, //Max packed object nesting level
"archive_max_level": number, //Max archive nesting level
"mail_max_level": number, //Max email object nesting level
"container_max_level": number, //Max container nesting level
"max_compression_ratio": number //Max archive compression value
}

2)ScanEndpointは、ファイルスキャン用に作成されたエンドポイントに関するデータを含むオブジェクトです。

{
"endpoint": string //Unique identifier of the created endpoint
}

オブジェクト本体で返されるendpoint文字列は、scan_endpointコマンド(URIの一部)でファイルスキャンを開始するために使用されます。

3)ScanReportは、脅威が検出されたファイルに関する情報を含むオブジェクト。

{
"scan_endpoint": string, //File system object that contains the threat
"size": number, //Size (in bytes) of the file that contains the threat
*"virus":VirusInfo[], //List of details about the found threats
*"error": string, //An error message
"heuristic_analysis": bool //Flag that shows whether heuristic analysis was used
}

* virusフィールドとerrorフィールドは、スキャン中に脅威が検出されず、エラーが発生しなかった場合には、存在しない可能性があります。scan_endpointを呼び出すため、scan_endpointフィールドでは、Dr.Web Network Checkerコンポーネントによってローカルサーバーファイルシステムに作成され、スキャンに関するデータを含み、scan_endpointリクエストの本文で送信される一時ファイルを必ず指定します。

4)VirusInfoは、検出された脅威に関する情報を含むオブジェクトです。

{
"type": string, //Type of the detected threat
"name": string  //Name of the threat
}

5)CategorizeAddressは、検証されるURLに関するデータを含むオブジェクトです。

{
"address" : string //IP address for verification
}

6)CategorizeURLは、検証されるURLに関するデータを含むオブジェクトです。

{
"url" : string //URL for verification
}

7)CategorizedResourceは、Webページの検証結果(ページがWebページカテゴリーデータベースにリストされているかどうかなど)を含むオブジェクトです。

{
*"category": string,    //The main category
"categories": string[], //List of all categories the resource falls under
*"legal_url": string    //URL of the copyright owner
}

legal_urlフィールドは、リソースカテゴリーが「UC_OWNERS_NOTICE」の場合にのみ存在します。categoryフィールドは存在しない場合があります。リソースカテゴリーは文字列「UC_XXX」です。

UC_INFECTION_SOURCE - 脅威のソース。

UC_NOT_RECOMMENDED - アクセスが推奨されないWebページ。

UC_ADULT_CONTENT - アダルトコンテンツ。

UC_VIOLENCE - 暴力。

UC_WEAPONS - 武器。

UC_GAMBLING - ギャンブル。

UC_DRUGS - 薬物。

UC_OBSCENE_LANGUAGE - 卑猥な表現。

UC_CHATS - チャット。

UC_TERRORISM - テロリズム。

UC_FREE_EMAIL - 無料メールサービス。

UC_SOCIAL_NETWORKS - ソーシャルネットワーク。

UC_ONLINE_GAMES - オンラインゲーム。

UC_ANONYMIZERS - アノニマイザー。

UC_CRYPTOCURRENCY_MINING_POOL - 仮想通貨マイニングプール。

UC_JOBS - 求人検索リソース。

UC_OWNERS_NOTICEは、著作権者からの申し立てによってリストに登録されたWebページ。

8)CheckUrlRequestは、Dr.Web Cloudによる検証の対象となるURLに関するデータを含むオブジェクトです。

{
"url": string //URL to be verified
}

9)UrlResultは、Dr.Web CloudによるURL検証の結果に関するデータを含むオブジェクトです。

{
"result": string,      //Error code EC_XXX
"categories": string[] //List of all categories the resource falls under (see above)
}

リソースが正常に検証されると、エラーコード「EC_OK」が返されます。リソースが既知のどのカテゴリーにも属していない場合、categories配列は空になります。

10)CheckFileRequestは、Dr.Web Cloudによって検証されるURLに関するデータを含むオブジェクトです。

{
"sha1": string,       //SHA1 checksum of the scanned file, a hexadecimal number
"path": string,       //Path to a file
"size": number,       //File size, in bytes
*"source_url": string //URL of the file source (optional field)
}

11)FileResultは、Dr.Web CloudによるURL検証の結果に関するデータを含むオブジェクトです。

{
"result": string,   //Error code EC_XXX
*"virus":VirusInfo //Information on a threat
}

ファイルが正常に検証されると、エラーコード「EC_OK」が返されます。脅威が検出されない場合、virusフィールドはありません。

12)VirusInfoは、検出された脅威に関する情報を含むオブジェクトです。

{
"type": string, //Type of the detected threat
"name": string //Name of the threat
}

typeフィールド(脅威タイプ)は文字列「SE_XXX」です。

SE_KNOWN_VIRUSは既知のウイルスです。

SE_VIRUS_MODIFICATIONは既知のマルウェアの亜種です。

SE_UNKNOWN_VIRUSは未知のウイルス(疑わしいオブジェクト)です。

SE_ADWAREはアドウェアです。

SE_DIALERはダイアラープログラムです。

SE_JOKEはジョークプログラムです。

SE_RISKWAREは潜在的に危険なプログラムです。

SE_HACKTOOLはハッキングツールです。

5.脅威のリストの管理

スキャン中またはファイルシステムモニター(SpIDer Guard)によって検出された脅威のリストを管理できるように、HTTP APIには次のコマンドが用意されています。

APIコマンド

説明

threats

アクション:検出されたすべての脅威のIDを一覧表示します。

URI: /api/10.2/threats/

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:脅威IDの配列

site_threats

アクション:<site ID>というIDを持つ、Webサイトによって占有されているディレクトリで見つかったすべての脅威の脅威IDのリストを取得します。

URI: /api/10.2/threats/<site ID>

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:脅威IDの配列

threat_info

アクション:脅威に関する情報を脅威のIDである<threat ID>で取得します。

URI: /api/10.2/threat_info/<threat ID>

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:SCS-cookie)、FileThreatオブジェクト

cure_threat

アクション:脅威のIDである<threat ID>で指定された脅威の修復を試みます。

URI: /api/10.2/cure_threat/<threat ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

delete_threat

アクション:脅威のIDである<threat ID>で指定された脅威を含むファイルを削除します。

URI: /api/10.2/delete_threat/<threat ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

ignore_threat

アクション:脅威のIDである<threat ID>で指定された脅威を無視します。

URI: /api/10.2/ignore_threat/<threat ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

quarantine_threat

アクション:脅威のIDである<threat ID>で指定された脅威を隔離します。

URI: /api/10.2/quarantine_threat/<threat ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

検出された脅威のリストを要求するコマンド内のURIの<site ID>部分は、保護されたWebサイトを含むディレクトリへのパスに置き換える必要があります。このようなディレクトリは、SpIDer Guardの設定(LinuxSpider.Space.<ID>.Pathパラメータ)でも指定されます。パスは、URLエンコードの規則に従って指定する必要があります。脅威ID<threat ID>は、指定されたアプリケーションで見つかった脅威のID(非負の整数)です。threat_infocure_threatdelete_threatignore_threatquarantine_threatコマンドでは、threatsコマンドとsite_threatsコマンドによって返される配列に含まれている脅威IDのみを使用できます。

アクション履歴を含む脅威に関するすべての情報は、threat_infoリクエストを使用して取得できます。情報はFileThreatオブジェクトとして返されます。

1)FileThreatは、次のデータを含むオブジェクトです。

{
"threat_id": number, //Threat identifier
"detection_time":UNIXTime, //Time when the threat was detected
"report":ScanReport, //Report about scanning the file
"stat":FileStat, //Information about the file
"origin": string, //Name of the component that detected the threat
"origin_pid": number, //PID of the component that detected the threat
"task_id": number, //Identifier of the scanning task in the scan engine
"history":ActionResult[] //History of actions applied to the threat (an array)
}

reportフィールドにはScanReportオブジェクトが含まれます。statフィールドにはFileStatオブジェクトが含まれ、historyフィールドにはActionResultオブジェクト(ファイルに適用されたアクションの履歴)の配列が含まれます。

2)ScanReport - 脅威が検出されたファイルに関する情報を含むオブジェクト。

{
"object": string, //File system object that contains the threat
"size": number, //Size (in bytes) of the file that contains the threat
"virus":VirusInfo[], //List of details about the found threats
*"error": string, //An error message
"heuristic_analysis": bool //Flag that shows whether heuristic analysis was used
}

virusフィールドは、検出されたすべての脅威に関する情報を含むVirusInfoオブジェクトの配列です。errorフィールドは、エラーが発生した場合にのみ表示されます。

3)FileStatは、ファイル統計を含むオブジェクトです。

{
"dev": number, //Device containing the file
"ino": number, //The file inode number
*"size": number, //Size of the file
*"uid":User, //User ID of the file's owner
*"gid":Group, //Group ID of the owning group
*"mode": number, //The mode of access to the file
*"mtime":UNIXTime, //Date/time when the file was last modified
*"ctime":UNIXTime //Date/time when the file was created
*"rsrc_size": number, //
*"finder_info": string, //
*"ext_finder_info": string, //
*"uchg": string, //
*"volume_name": string, //Volume name
*"volume_root": string, //Root (mount point) of the volume
*"xattr":XAttr[] //Extended information about the file
}

xattrフィールドには、XAttrオブジェクトの配列が含まれています。このブジェクトには、nameおよびvalueの2つの文字列タイプのフィールドがあります。uidフィールドとgidフィールドにはそれぞれユーザーオブジェクトとグループオブジェクトが含まれており、これらのオブジェクトにはそれぞれファイルの所有者とファイルを所有しているグループに関する情報が含まれています。これらのオブジェクトにはそれぞれ次の2つのフィールドがあります。

uidgid) - ユーザー(グループ)のID(数値)。

usernamegroupname) - ユーザー(グループ)の名前(文字列)。

4)ActionResultは、ファイルに適用されたアクションとその結果に関する情報を含むオブジェクトです。

{
"action": string, //The action applied
"action_time":UNIXTime, //Date/time when the action was applied
"result": string, //Result of applying the action
"cure_report":ScanReport //Report about applying the action
}

cure_threatdelete_threatignore_threatquarantine_threatコマンドは、正常に実行された場合は空のオブジェクトを返します。脅威に対して要求されたアクションがエラーのために失敗した場合(たとえば、脅威が駆除されなかった場合)、空のオブジェクトの代わりにErrorオブジェクトが返されます。

6.隔離の管理

隔離されている脅威を管理するため、HTTP APIには次のコマンドが用意されています。

APIコマンド

説明

quarantine

アクション:隔離されたオブジェクトのIDの一覧を表示します。

URI: /api/10.2/quarantine/

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、QuarantineIdオブジェクト(隔離内のオブジェクト)の配列

site_quarantine

アクション:<site ID>というIDを持つWebサイトのディレクトリで検出された後に隔離に移動されたすべての脅威について、隔離オブジェクトのIDの一覧を取得します。

URI: /api/10.2/quarantine/<site ID>

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、QuarantineIdオブジェクト(隔離内のオブジェクト)の配列

qentry_info

アクション:隔離オブジェクトのIDである<entry ID>で指定された隔離オブジェクトに関する情報を取得します。

URI: /api/10.2/qentry_info/<entry ID>

HTTPメソッド:GET

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、QEntryオブジェクト

cure_qentry

アクション:隔離オブジェクトのIDである<entry ID>で指定された隔離オブジェクトの修復を試みます。

URI: /api/10.2/cure_qentry/<entry ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

delete_qentry

アクション:隔離オブジェクトのIDである<entry ID>で指定された隔離オブジェクトを削除します。

URI: /api/10.2/delete_qentry/<entry ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

restore_qentry

アクション:隔離オブジェクトのIDである<entry ID>で指定された隔離オブジェクトを元の場所に復元します。

URI: /api/10.2/restore_qentry/<entry ID>

HTTPメソッド:POST

入力パラメータ:SCS cookie

正常に実行された結果:SCS cookie)、空のオブジェクト

quarantineコマンドとsite_quarantineコマンドは、QuarantineId型のオブジェクトの配列を返します。各オブジェクトには、隔離オブジェクトのIDが含まれています。IDは、chunk_identry_idの2つの部分で構成されています。

1)QuarantineIdは、隔離オブジェクトの2つの部分からなるIDの両方の部分を含むオブジェクトです。

{
"chunk_id": string,
"entry_id": string
}

これら2つのフィールドが一体となって隔離オブジェクトの一般的なIDを構成します。qentry_infocure_qentrydelete_qentry、またはrestore_qentryコマンドを使用して隔離オブジェクトにアクションを適用するには、隔離オブジェクトの一般的なIDである<entry ID><entry_id>@<chunk_id>の形式で指定する必要があります。qentry_infoコマンドを使用すると、隔離オブジェクトのIDで指定された隔離オブジェクトに関する詳細情報を取得できます。このコマンドはQEntryタイプのオブジェクトを返します。

2)QEntry - 隔離オブジェクトに関する情報を含むオブジェクト

{
"entry_id": string, //Parts of the identifier of
*"chunk_id": string, //this quarantined object
*"quarantine_dir": string, //Quarantine directory
"restore_path": string, //path where the quarantined object will be restored
"creation_time": number, //Date/time of moving to quarantine (in UNIX time)
"report":ScanReport, //Report about scanning the object (see ScanReport described above)
"stat":FileStat, //Statistical information about the file (see FileStat described above)
*"history":QEntryOperation[], //History of operations performed on the object
*"who":RemoteUser, //The remote owner of the file (if the file was quarantined from a file server storage)
*"detection_time": number, //Date/time of detecting the threat
*"origin": string, //Component that detected the threat
}

reportフィールドにはScanReportオブジェクトが含まれます。statフィールドにはFileStatオブジェクトが含まれ、historyフィールドには隔離オブジェクトに適用されたアクションの履歴が含まれます。各アクションエントリは、QEntryOperationオブジェクトによって記述されます。オプションの「who」フィールドには、削除されたユーザーに関する情報がRemoteUserオブジェクトの形式で含まれます。

3)QEntryOperationは、隔離オブジェクトに適用された操作に関するデータを含むオブジェクトです

{
"action": string, //Operation performed on the object (see the possible values below)
"action_time": number, //Date/time when the operation was performed (UNIX Time)
"result": string, //Error when trying to perform the operation (a code EC_XXX)
*"restore_path": string, //path for restoring the quarantined object (if action = "QENTRY_ACTION_RESTORE")
*"rescan_report":ScanReport //Report about rescanning (if action = "QENTRY_ACTION_RESCAN")
}

actionフィールドには、以下の値を指定できます。

QENTRY_ACTION_DELETEは、隔離オブジェクトの削除を試みます。

QENTRY_ACTION_RESTOREは、隔離オブジェクトの復元を試みます。

QENTRY_ACTION_RESCANは、隔離オブジェクトの再スキャンを試みます。

QENTRY_ACTION_CUREは、隔離オブジェクトの修復を試みます。

4)RemoteUserは、ファイルを所有するリモートユーザーに関する情報を含むオブジェクトです(ファイルがファイルサーバーストレージから隔離に再配置された場合)。

{
*"ip": string, //IP-address of the user
*"user": string, //User name
*"domain": string //Domain of the user
}

cure_qentrydelete_qentryrestore_qentryコマンドの実行が成功すると、空のオブジェクトが返されます。隔離オブジェクトに対して要求された操作がエラーで終了した場合(たとえば、ファイルを復元できなかった場合)、空のオブジェクトの代わりにErrorオブジェクトが返されます。

7.HTTP APIの使用例

HTTP APIの動作をテストするには、curlユーティリティを使用します。API呼び出しの一般的なフォーマットは以下のとおりです。

$ curl https://<HTTPD.AdminListen>/<HTTP API URI> -k -X <HTTP method name>
[-H 'Content-Type: application/json' --data-binary '@<file of the JSON object>']
[-c <cookie file> [-b <cookie file>]] [> <file of the result>]

ここで、-kコマンドラインパラメータは、使用されるSSL証明書が有効であるかどうかをcurlがチェックしないことを許可するために使用され、-Xパラメータは、使用するHTTPメソッド(GETまたはPOST)を指定するために使用されます。JSONオブジェクトがこのHTTPリクエストの本文で渡される場合は、-Hパラメータを使用してリクエストのヘッダーセクションにContent-Type: application/jsonヘッダーフィールドを追加できます。また、--data-binaryパラメータを使用すると、JSONオブジェクト自体をリクエストの本文に追加し、テキストファイルからJSONオブジェクトを取得できます。SCSを使用して認証を受ける場合は、送受信されるSCS cookieを格納するファイルをそれぞれ-bパラメータと-cパラメータで指定する必要があります。このユーティリティとその引数に関する詳細な説明を表示するには、curl --helpコマンドとman curlコマンドを使用してください。

1.ユーザー名とパスワード(SCS用)を指定して、クライアントを認証および承認する

JSON形式のAuthOptionsオブジェクトがあらかじめuser.jsonというファイルに書き込まれている必要があります。例:

{"user":"<ユーザー名>","password":"<パスフレーズ>"}

$ curl https://127.0.0.1:4443/api/10.2/login -k -X POST -H 'Content-Type: application/json' --data-binary '@user.json' -c cookie.file

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:2
Set-Cookie:DWToken=6QXy4wn_JGov9A1GohWP_kvMK3dN6ccKegjNgKcmHpb_AqSrHg9cNX_yFJhxPDgr|MTQ2Mjg3Mzg4NQ==|cWd4Ow==|GywBUVOhU4w2LF_BKT5frg==|kR_rip5nrpxWjJ2dfZ7Xfmvi3rE=; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{}

Set-Cookieヘッダーフィールドには、HTTP APIに次のコマンドを送信するために使用する必要がある SCS-cookieが含まれています。認証と承認が成功した場合、レスポンスの本文には空のオブジェクトが含まれています。ユーザーが承認されなかった場合は、次のようなErrorオブジェクトが返されます。

HTTP/1.0 403 Forbidden
Content-Type: application/json
Content-Length:35
Pragma: no-cache
 
{"error":{"code":"EC_AUTH_FAILED"}}

2.Webサイトのディレクトリで検出された脅威のリストを取得する(ここではサイトのルートディレクトリとして/sites/site1ディレクトリが指定されています):

$ curl https://127.0.0.1:4443/api/10.2/threats/%2Fsites%2Fsite1 -k -X GET -c cookie.file -b cookie.file

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:80
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
["1", "2", "3", "4"]

3.IDが1である脅威に関する情報を取得する

$ curl https://127.0.0.1:4443/api/10.2/threat_info/1 -k -X GET -c cookie.file -b cookie.file

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:574
Set-Cookie:DWToken=<...>;
Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"threat_id":1,"detection_time":1462881660,
"report":{"object":"/sites/site1/eicar.com.txt","size":68,"packer":[],
"virus":[{"type":"SE_KNOWN_VIRUS","name":"EICAR Test File (NOT a Virus!)"}],
"heuristic_analysis":true,"core_fingerprint":"0D2DD5A869DAB7AE354153A4D5F70F45",
"item":[],"log":[],"user_time":0,"system_time":0},"stat":{"dev":2049,"ino":898,
"size":68,"uid":{"uid":1000,"username":"user"},"gid":{"gid":1000,"groupname":"user"},
"mode":33204,"mtime":1441028214,"ctime":1460738554,"xattr":[]},
"origin":"APP_COMMAND_LINE_TOOL","origin_pid":2726,"task_id":1,"history":[]}

4.IDが1である脅威を隔離に移動する

$ curl -v -c cookie.jar -b cookie.jar -k -X POST -H 'Content-Type:application/json' https://127.0.0.1:4443/api/10.2/quarantine_threat/1

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:2
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{}

5.指定されたWebサイトの隔離のコンテンツを表示する

$ curl -v -k -X GET -c cookie.jar -b cookie.jar https://127.0.0.1:4443/api/10.2/quarantine/%2Fsites%2Fsite1

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:76
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
[{"entry_id":"3070d3ce-7b6e-4143-9d9f-89ba3473a781","chunk_id":"801:2108d"}]

6.隔離(分離)オブジェクトに関する情報を表示する

$ curl -v -k -X GET -c cookie.jar -b cookie.jar https://127.0.0.1:4443/api/10.2/qentry_info/3070d3ce-7b6e-4143-9d9f-89ba3473a781@801:2108d

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:781
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"entry_id":"3070d3ce-7b6e-4143-9d9f-89ba3473a781","chunk_id":"3830313A3231303864",
"quarantine_dir":"2F686F6D652F757365722F2E636F6D2E64727765622E71756172616E74696E65",
"restore_path":"2E2E2F7473742F65696361722E636F6D2E747874","creation_time":1462888884,
"report":{"object":"/home/user/tst/eicar.com.txt","size":68,"packer":[],
"virus":[{"type":"SE_KNOWN_VIRUS","name":"EICAR Test File (NOT a Virus!)"}],
"heuristic_analysis":true,"core_fingerprint":"467CD4C6D423C55448B71CD5B8152776",
"item":[],"log":[],"user_time":0,"system_time":0},"stat":{"dev":2049,"ino":898,
"size":68,"uid":{"uid":1000,"username":"user"},"gid":{"gid":1000,"groupname":"user"},
"mode":33204,"mtime":1441028214,"ctime":1462888421,"xattr":[]},"history":[],
"detection_time":1462888667,"origin":"APP_COMMAND_LINE_TOOL"}

7.設定の変更:SpIDer Guardをオフにする。

JSON形式のLexMapオブジェクトがあらかじめlexmap_ls_off.jsonというファイルに書き込まれている必要があります。

{"option":[{"key":"LinuxSpider","map":{"option":[{"key":"Start","value":{"item":["no"]}}]}}]}

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_ls_off.json' https://127.0.0.1:4443/api/10.2/set_lexmap

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:58
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"item":[{"option":"LinuxSpider.Start","result":"EC_OK"}]}

8.設定の変更:SpIDer Guardをオンにする。

JSON形式のLexMapオブジェクトがあらかじめlexmap_ls_on.jsonというファイルに書き込まれている必要があります。

{"option":[{"key":"LinuxSpider","map":{"option":[{"key":"Start","value":{"item":["yes"]}}]}}]}

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_ls_on.json' https://127.0.0.1:4443/api/10.2/set_lexmap

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:58
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"item":[{"option":"LinuxSpider.Start","result":"EC_OK"}]}

9.設定の変更:ホストされているWebサイトをSpIDer Guardの保護下に置く。

このアクションは2つのステップで実行されます。まず、個別のサイト(SpIDer Guardでは「保護スペース」)のセクションを追加する必要があります。次に、サイトを保護するためのパラメータを指定する必要があります(少なくとも、サイトのファイルを格納するディレクトリへのパスを指定する必要があります)。

1)Webサイトを追加する。JSON形式のLexMapオブジェクトがあらかじめlexmap_site.jsonというファイルに書き込まれている必要があります。

{"option":[{"key":"LinuxSpider","map":{"option":[{"key":"Space","map":{"option":[{"key":"<SITE_ID>","map":{"option":[]}}]}}]}}]},
ここで、<SITE_ID>は目的のWebサイトのIDです。

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_site.json' https://127.0.0.1:4443/api/10.2/set_lexmap

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:11
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"item":[]}

設定ファイルに新しく作成されたセクションにはまだパラメータが設定されていないため、このリクエストに対するレスポンスでは空のオブジェクトが返されます。

2)Webサイトのディレクトリへのパスを設定する。JSON形式のLexMapオブジェクトがあらかじめlexmap_site_path.jsonというファイルに書き込まれている必要があります。

{"option":[{"key":"LinuxSpider","map":{"option":[{"key":"Space","map":{"option":[{"key":"<SITE_ID>","map":{"option":[{"key":"Path","value":{"item":["<PATH>"]}}]}}]}}]}}]},
ここで、<SITE_ID>は保護するWebサイトのID、<PATH>はこのサイトを格納しているディレクトリへのフルパスです。

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_site_path.json' https://127.0.0.1:4443/api/10.2/set_lexmap

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:65
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"item":[{"option":"LinuxSpider.Space.s2.Path","result":"EC_OK"}]}

この例では、s2は、SpIDer Guardによって保護されるディレクトリへのパスを指定したWebサイトのIDです。

10.設定の変更:Webサイトの保護をオフにする。

JSON形式のLexMapオブジェクトがあらかじめlexmap_site_off.jsonというファイルに書き込まれている必要があります。

{"option":[{"key":"LinuxSpider","map":{"option":[{"key":"Space","map":{"option":[{"key":"<SITE_ID>","map":{"option":[{"key":"Enable","value":{"item":["No"]}}]}}]}}]}}]},
ここで、<SITE_ID>は目的のWebサイトのIDです。

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_site_off.json' https://127.0.0.1:4443/api/10.2/set_lexmap

レスポンス:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length:67
Set-Cookie:DWToken=<...>; Secure; HttpOnly; Max-Age:900; Path=/
Pragma: no-cache
 
{"item":[{"option":"LinuxSpider.Space.s2.Enable","result":"EC_OK"}]}

この例では、s2は保護が無効になっている目的のWebサイトのIDです。