HTTP APIの説明

このセクションの内容

•概要

•ユーザー認証と承認

•Dr.Web for UNIX Internet Gatewaysの管理

•脅威のリストの管理

•隔離の管理

•HTTP APIの使用例

1. 概要

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

HTTPプロトコルのバージョン1.0が使用されます。APIは、HTTPプロトコルの標準メソッドであるGETとPOSTを使用します。特に指定がない限り、すべてのデータはJSONオブジェクトの形式で送信されます。HTTP POSTリクエストの本文でJSONオブジェクトを送信する場合は、Content-Type:ヘッダーをapplication/jsonの値で使用します。

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

•特に指定のない限り、すべてのリクエストへのレスポンスとしてJSONオブジェクトが返されます。リクエストの処理中にエラーが発生した場合、Error JSONが返されます。

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

•特に指定のない限り、すべてのレスポンスのContent-Type:ヘッダーフィールドにはapplication/json値があります。

•存在しないエンドポイントをクライアントが要求した場合、コードフィールドにEC_UNEXPECTED_MESSAGEが含まれるError JSONオブジェクトが返されます。

•SCS（Secure Cookie Sessions for HTTP）が使用されている場合（以下を参照）、レスポンスにはSCS cookieが含まれます。

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

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

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

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

•本文にJSONオブジェクトが含まれるPOSTリクエストでは、RFC 7159に準拠するすべての記号が許可されます。

•GETリクエストでは、RFC 1945に準拠するすべての記号がURIで許可されます。

•RFC 1945に準拠する記号は、リクエストの他のどの部分（ヘッダーまたは本文）でも使用できます。

2. ユーザー認証と承認

APIの使用を開始するには、サーバーによる認証が必要です。承認の手段は2つ用意されています。

1.RFC 6896に準拠したSCSを使用する。

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

SCSを使用する場合、認証を確認するcookieは、リクエストではCookie:、レスポンスではSet-Cookie:がヘッダーで送信されます。
SSL証明書による承認の場合、cookieは使用されません。

SCSで承認する場合、loginコマンドを送信することでAPIの使用が始まります。このコマンドが正常に実行されると、レスポンスとしてSCS cookieがクライアントに送信されます。
クライアント証明書で承認する場合、loginコマンドを実行する必要はありません。実行しようとすると、レスポンスにError JSONオブジェクトが返されます。

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

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

APIコマンド

説明

アクション：指定されたユーザー名とパスワードに基づいてクライアントを認証し、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による認証が使用される場合にのみ送受信する必要があるため、これ以降は括弧に入れて表記します。

SCSで認証する場合にのみ、loginとlogoutコマンドが使用されます。

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

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

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

管理者グループ（DebianとUbuntuではsudoers、CentOSとFedoraではwheel、Astra Linuxではastra-adminなど）のメンバーであるユーザーを指定できます。ユーザーが管理者グループのメンバーでない場合、レスポンスにEC_NOT_AUTHORIZEDエラーが返されます。

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のような文字列です。対応する数値コードやエラーの詳細情報を確認するには、『管理者マニュアル』の付録Fにある「既知のエラー」セクションを参照してください。

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

SSL証明書による認証は、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）
baseinfo	アクション：ダウンロードしたウイルスベースに関する情報を表示します。 URI: /api/10.2/baseinfo HTTPメソッド：GET 入力パラメータ：（SCS cookie）正常に実行された結果：VirusBaseInfoオブジェクトを含むBaseInfoResultオブジェクト（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つの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> (without the http/https prefix)
"certificate": string, //Base64 server key
*"newbie": boolean, //False by default
*"login": string, //User name
*"password": string //Password
}

アスタリスク（*）のパラメータは任意です。

パラメータloginとpasswordは、newbie = trueの場合にのみ指定されます。
接続前に、集中管理サーバーから証明書ファイルをダウンロードし、次のコマンドを実行します。

$ cat certificate.pem |base64

このコマンドを実行して得られた文字列がcertificateのパラメータ値として使用されます。

9）BaseInfoResultオブジェクトには、ダウンロードしたウイルスベースのデータが含まれます。

{
"vdb_base_stamp" : number //Timestamp of the base
"vdb_bases" : VirusBaseInfo[] //Detailed information upon the base
}

10）VirusBaseInfoオブジェクトには、各ウイルスベースに関する情報が含まれます。

{
"path" : string //Path to the base file
"virus_records" : number //The number of records in the base
"version" : number //Base version
"timestamp" : number //Base timestamp
"md5" : string //base MD5-hash
"load_result" : string //The result of downloading the base (EC_OK if the base has been downloaded successfully)
*"sha1" : string - base SHA1-hash
}

アスタリスク（*）のパラメータは任意です。

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）、検証可能なデータ正常に実行された結果：ScanResultオブジェクト、（SCS cookie）
scan_path	アクション：指定されたパスにあるファイルまたはディレクトリをスキャンします。 URI: /api/10.2/scan_path HTTPメソッド：POST 入力パラメータ：（SCS cookie）、ScanPathOptionsオブジェクト正常に実行された結果：ScanPathResultオブジェクト、（SCS cookie）
scan_stat	アクション：スキャン統計の表示。 URI: /api/10.2/scan_stat HTTPメソッド：GET 入力パラメータ：（SCS cookie）、統計のフォーマット（JSONまたはCSV）正常に実行された結果：ScanStatオブジェクト（JSON形式が選択されている場合）、（SCS cookie） CSV形式が選択されている場合、ScanStatのフィールドに対応するテーブルが返されます。

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, //Maximum nesting level for packed objects
"archive_max_level": number, //Maximum nesting level for archives
"mail_max_level": number, //Maximum nesting level for email messaged
"container_max_level": number, //Maximum nesting level for other compound objects (containers)
"max_compression_ratio": number, //Maximum a compression value
"min_size_to_scan" : number, //Minimal size of an object to be scanned
"max_size_to_scan" : number, //Maximum size of an object to be scanned
"threat_hash" : boolean //Return SHA1 and SHA256 of all threats
}

2）ScanPathOptionsは、指定されたパスにあるファイルまたはディレクトリをスキャンするために使用されるパラメータを含むオブジェクトです。

{
"path" : string //Absolute path to the file or the directory to be scanned
*"exclude_path" : string[] //List of the paths excluded from scanning (it is allowed to use masks)
*"scan_timeout_ms" : number //Scan timeout for an object
*"archive_max_level" : number//Maximum nesting level for archived objects
*"packer_max_level" : number //Maximum nesting level for packed objects
*"mail_max_level" : number //Maximum nesting level for email messages
*"container_max_level" : number//Maximum nesting level for other compound objects (containters)
*"max_compression_ratio" : number//Maximum compression value
*"heuristic_analysis" : bool //Use heuristic analysis (true by default)
*"follow_symlinks" : bool //Follow symbolic links
*"min_size_to_scan" : number //Minimal size of an object to be scanned
*"max_size_to_scan" : number //Maximal size of an object to be scanned
*"timeout_ms" : number - //Scan timeout for all objects
*"threat_hash" : bool - //Return SHA1 and SHA256 of all threats
}

アスタリスク（*）のパラメータは任意です。

3）ScanPathResultは、指定されたパスにあるオブジェクトのスキャン結果を含むオブジェクトです。

{
ScanPathResult:
"results": ScanResult[] //Scan results
*"error": string //Error if the scanning process terminated (the scanning timeout is expirer, for instance)
}

アスタリスク（*）のパラメータは任意です。

スキャンが成功した場合、レスポンスにはerror文字列は含まれません。

4）ScanResultは、スキャンの結果を含むオブジェクトです。

{
ScanResult:
"scan_report" : ScanReport //The information upon the threat found
*"sha1" : string //The SHA1 hash of the threat
*"sha256" : string //The SHA256 hash of the threat
}

アスタリスク（*）のパラメータは任意です。

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

{
ScanReport:
"object" : string //Name of the object scanned
For a file //The absolute path, for a nested object - the name of the file
Always points to temporary file when calling scan_endpoint
*"size" : number //Object size
*"compressed_size" : number //Object size before extraction
*"core_fingerprint" : string //Scan engine fingerprint
*"packer" : string[] //The list of packers used to pack the object
*"compression_ratio" : number //Archive compression ratio
*"archive" : Archive //Information on the archive or container type, if the object scanned was identified as an archive or a container
*"virus" : Virus[] //Viruses detected in the objects (if found)
*"item" : ScanReport[] //Reports on scanning of the nested objects (if there were some)
*"error" : string //Scanning error (if occured)
*"heuristic_analysis" : bool //Indicates if heuristic analysis was used
*"cured" : bool //The object was cured
*"cured_by_deletion" : bool //The object was deleted.
*"new_path" : string //The new path to the object renamed when being cured
*"user_time" : number //Type spent for syscalls when scanning
*"system_time" : number //Time spent in the userspace
}

アスタリスク（*）のパラメータは任意です。

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

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

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

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

7）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はハッキングツールです。

8）Archiveは、アーカイブ、圧縮されたオブジェクト、メールメッセージ、およびその他のコンテナに関する情報を含むオブジェクトです。

{
"type" : string - the type of the archive:
"SE_ARCHIVE" - archive
"SE_MAIL" - e-mail message
"SE_CONTAINER" - other container
"name" : string - archive format
}

9）ScanStatは、スキャン統計を含むオブジェクトです。

{
"origin": string //The application by the request of which the scanning was initialized
#Counters for infected objects:
"known_virus": number //Number of objects infected by known viruses
"virus_modification": number //Number of objects infected by modifications of known viruses
"unknown_virus": number //Number of objects infected by unknown viruses
"adware": number //Number of objects with SE_ADWARE
"dialer": number //Number of objects with SE_DIALER
"joke": number //Number of objects with SE_JOKE
"riskware": number //Number of objects with SE_RISKWARE
"hacktool" : number //Number of objects with SE_HACKTOOL
"cured": number //Number of cured threats
"quarantined": number //Number of quarantined threats
"deleted": number //Number of deleted threats
}

5. 脅威のリストの管理

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

APIコマンド	説明
threats	アクション：検出されたすべての脅威のIDを一覧表示します。 URI: /api/10.2/threats/ 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）、空のオブジェクト

指定されたアプリケーションで見つかったそれぞれの脅威には、一意の整数で表されたID<threat ID>があります。すべてのIDのリストはthreatsコマンドによって返されます。threat_info、cure_threat、delete_threat、ignore_threat、およびquarantine_threatコマンドでは、threatsコマンドが返すIDのみが許容されます。

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

JSONオブジェクトの説明

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つのフィールドがあります。

•uid（gid） - ユーザー（グループ）のID（数値）

•username（groupname） - ユーザー（グループ）の名前（文字列）

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_threat、delete_threat、ignore_threat、およびquarantine_threatコマンドは、正常に実行されると空のオブジェクトを返します。リクエストされたアクションが失敗した場合は、Errorオブジェクトが返されます。

6. 隔離の管理

隔離オブジェクトを管理するため、HTTP APIには次のコマンドが用意されています。

APIコマンド	説明
quarantine	アクション：隔離されたオブジェクトのIDの一覧を表示します。 URI: /api/10.2/quarantine/ 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）、空のオブジェクト

それぞれの隔離オブジェクトには一意のIDがあります。QuarantineIdとして表されるIDのリストは、quarantineコマンドによって返されます。IDはchunk_idとentry_idの2つの部分で構成されます。

JSONオブジェクトの説明

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

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

これら2つのフィールドが一体となって隔離オブジェクトのIDを構成します。qentry_info、cure_qentry、delete_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_qentry、delete_qentry、restore_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オプションでは、curlがSSL証明書を確認しないように指定します。

•-Xオプションでは、使用するHTTPメソッド（GETまたはPOST）を指定します。

•-Hオプションは、Content-Type: application/jsonヘッダーの追加に使用します。

•--data-binary（または-d）オプションは、テキストファイルに保存されたJSONオブジェクトをリクエストに追加するために使用します。

•SCSを使用して承認を得る場合、送受信したSCS cookieを含むファイルをそれぞれ-bと-cのパラメータで指定する必要があります。

curlオプションの詳細な説明については、manページを参照してください（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.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":[]}

3.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

{}

4.指定されたIDを持つ隔離オブジェクトに関する情報を表示する。

リクエスト：

$ 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"}

5.設定を変更する：Dr.Web CloudDを無効にする。

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

{"option":[{"key":"Root","map":{"option":[{"key":"UseCloud","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":"Root.UseCloud","result":"EC_OK"}]}

6.設定を変更する：Dr.Web CloudDを有効にする。

JSON形式のLexMapオブジェクトがlexmap_ls_on.jsonという名前のファイルに保存されている必要があります。

{"option":[{"key":"Root","map":{"option":[{"key":"UseCloud","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

レスポンス：