- 印刷する
- PDF
File Filter の開発
- 印刷する
- PDF
Classic/VPC環境で利用できます。
File Filterの REST APIを使用して File Filterコードを作成する方法について説明します。
File Filterの開発に先立ち、File Saferのご利用の申し込み、API Gatewayのご利用の申し込みおよび API Keyの作成が必要です。詳細は、File Safer を開始するをご参照ください。
File Filterの実装シナリオ
File Filterを適用するシナリオは、次の通りです。
1. ファイル検査のリクエスト(inputFile)
1-1. マルウェアと疑われるファイルを区分
1-2. 認証値作成
1-3. リクエスト Body作成
1-4. リクエストパラメータ追加
1-5. APIリクエスト
2. 検査結果確認(getInputFileLog)
2-1. 検査結果を確認する Hash値の区分
2-2. 認証値作成
2-3. リクエストパラメータ追加
2-4. APIリクエスト
2-5. レスポンス値確認および遮断有無の判断
File Filterでマルウェアとして確認された場合、Hash Filterの Hash値を更新するため、検査結果を Hash Filterで照会しても同じ結果を得ることができます。
File Filterコード作成
File Filterの実装シナリオに従ってコードを作成します。
1. ファイル検査のリクエスト(inputFile)
File Filter APIのうち、inputFileを使用してファイル検査をリクエストします。
inputFile APIの仕様は、inputFile(File Filter)をご参照ください。
1-1. マルウェアと疑われるファイルを区分
Hash Filterでは確認できないファイルや、悪性有無の確認が必要なファイルを切り分けます。ファイル制約事項は、次の通りです。
- ファイル数の制限: inputFile APIの呼び出し時、リクエストごとに1つのファイルのみ処理。ファイルが2つ以上送信される場合、1つのファイルのみランダムに選択されて処理。
- ファイルサイズの制限: APIの呼び出し当たりのファイル容量を10MBに制限
1-2. 認証値作成
NAVERクラウドプラットフォーム APIの使用認証に必要な IAM認証値を作成します。認証に必要なヘッダは、次の通りです。
x-ncp-iam-access-key
: NAVERクラウドプラットフォームポータルのマイページ > API認証キー管理メニューから Access Keyを発行x-ncp-apigw-signature-v2
: Access Keyとマッピングされる Secret Keyを HmacSHA256暗号化して signature値を作成(改行文字は\nを使用)x-ncp-apigw-api-key
: API Gatewayを通じて API Keyを発行x-ncp-apigw-timestamp
: 認証値ではないが、リクエストヘッダに含まれる。API明細を参照。
signature値を作成する方法とサンプルコードは、NAVERクラウドプラットフォーム APIガイド > API の概要 > 基本 API > Ncloud API > 2.ヘッダ作成をご参照ください。
1-3. リクエスト Body作成
Multipartで Bodyにファイルを含むリクエストを作成します。
- Key: file
- Value: binary
1-4. リクエストパラメータ追加
送信するファイルが、パスワードが設定された圧縮ファイルの場合、以下のパラメータをリクエストに追加します。
- Key: archivePassword
- Value: 圧縮ファイルのパスワード String
以下はパラメータが追加された POSTリクエスト Bodyのフォーマットです。boundary値はエンティティ区切り文字として使用し、boundary設定値の前には「--」を入れる必要があります。各エンティティの末尾には、crlf('\r\n')を使う必要があります。
Content-Type: multipart/form-data; boundary=----AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="file"; filename="suspicious-file.zip"
Content-Type: application/x-zip-compressed
... contents of 'suspicious-file.zip'
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="archivePassword"
password
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA--
1-5. APIリクエスト
File Filter inputFile URIでリクエストを送信します。以下は inputFileリクエストのサンプルコードです。
public static void request(String fileName, String password) throws Exception
{
String boundary = "----AAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
String crlf = "\r\n";
String apiDomain = "https://filesafer.apigw.ntruss.com";
String apiURL = "/filefilter/v1/inputFile";
String method = "POST";
long timestamp = System.currentTimeMillis();
// step 2: Create Authentication Value
String signature = makeSignature(method, apiURL, timestamp);
// step 3: Create request with the identified file added
var path = (Path) Paths.get(fileName);
byte[] separator = ("--" + boundary + "\r\nContent-Disposition: form-data; name=").getBytes(StandardCharsets.UTF_8);
var byteArrays = new ArrayList<byte[]>();
byteArrays.add(separator);
byteArrays.add(("\"file\"; filename=\"" + path.getFileName() + crlf).getBytes(StandardCharsets.UTF_8));
byteArrays.add(("Content-Type: " + Files.probeContentType(path) + crlf + crlf).getBytes(StandardCharsets.UTF_8));
byteArrays.add(Files.readAllBytes(path));
byteArrays.add(crlf.getBytes(StandardCharsets.UTF_8));
// step 4: If the file you want to transfer is a zip file with a password, add the following parameters to the request
if (password != null && !password.isEmpty()) {
byteArrays.add(separator);
byteArrays.add(("\"archivePassword\"\r\n\r\n" + password + "\r\n").getBytes(StandardCharsets.UTF_8));
}
byteArrays.add(("--" + boundary + "--").getBytes(StandardCharsets.UTF_8));
// step5: Request API
HttpRequest request = HttpRequest.newBuilder()
.POST(BodyPublishers.ofByteArrays(byteArrays))
.uri(URI.create(apiDomain + apiURL))
.setHeader("x-ncp-apigw-timestamp", Long.toString(timestamp))
.setHeader("x-ncp-iam-access-key", ACCESSKEY)
.setHeader("x-ncp-apigw-signature-v2", signature)
.setHeader("x-ncp-apigw-api-key", APIKEY)
.headers("Content-Type", "multipart/form-data; boundary=" + boundary)
.build();
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
// Check the response value
int responseCode = response.statusCode();
String responseBody = response.body().toString();
// do next step (ex, check to transfer succeeded)
...
}
2. 検査結果確認(getInputFileLog)
File Filter APIのうち、getInputFileLogを使用してマルウェアの検査結果を確認します。
getInputFileLog APIの仕様は、getInputFileLog(File Filter)をご参照ください。
2-1. 検査結果を確認する Hash値の区分
ファイル検査リクエストのシナリオを通じて、File Filterに検査をリクエストしたファイルの Hash値を切り分けます。
2-2. 認証値作成
NAVERクラウドプラットフォーム APIの使用認証に必要な IAM認証値を作成します。認証に必要なヘッダは、次の通りです。
x-ncp-iam-access-key
: NAVERクラウドプラットフォームポータルのマイページ > API認証キー管理メニューから Access Keyを発行x-ncp-apigw-signature-v2
: Access Keyとマッピングされる Secret Keyを HmacSHA256暗号化して signature値を作成(改行文字は\nを使用)x-ncp-apigw-api-key
: API Gatewayを通じて API Keyを発行x-ncp-apigw-timestamp
: 認証値ではないが、リクエストヘッダに含まれる。API明細を参照。
signature値を作成する方法とサンプルコードは、NAVERクラウドプラットフォーム APIガイド > API の概要 > 基本 API > Ncloud API > 2.ヘッダ作成をご参照ください。
2-3. リクエストパラメータ追加
getInputFileLog APIのリクエストパラメータ値を追加します。リクエストパラメータは次の通りです。
- hashCode: Hash値を文字列に追加
- hashType: Hash値のアルゴリズムを表記(MD5または SHA-1)
以下は作成されたパラメータの例です。
hashCode=00010efc49b7174d18400710eed1642a7d4b12db&hashType=sha1
2-4. APIリクエスト
File Filter getInputFileLog URIでリクエストを送信します。以下は getInputFileLogリクエストのサンプルコードです。
public static void main(String[] args)
{
String apiDomain = "https://filesafer.apigw.ntruss.com";
String method = "GET";
String apiURL = "/filefilter/v1/getInputFileLog?hashCode=FILE_HASH&hashType=sha1"; // step 3: add required parameter
long timestamp = System.currentTimeMillis();
// step 2: Create Authentication Value
String signature = makeSignature(method, apiURL, timestamp);
// step 4: Request API
URL url = new URL(apiDomain + apiURL);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod(method);
con.setRequestProperty("x-ncp-apigw-timestamp", Long.toString(timestamp));
con.setRequestProperty("x-ncp-iam-access-key", ACCESSKEY); // access key (from portal or sub account)
con.setRequestProperty("x-ncp-apigw-signature-v2", signature);
// step5: Check the response value and determine whether to block
int responseCode = con.getResponseCode();
BufferedReader br = null;
if(responseCode == 200) {
br = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = br.readLine()) != null) {
response.append(inputLine);
}
// do next step (ex, determine whether to block)
...
br.close();
}
}
2-5. レスポンス値確認および遮断有無の判断
getInputFileLogのレスポンスに応じて遮断または許可有無を判断します。
inputFileLogList
の数が0の場合はリクエストした結果がない場合であり、inputFileLogList
が2つ以上の場合は2回以上解析された場合です。inputFileLogList
の analysisStatusCode
のフィールド値を読み取り、検査の進捗状況をご確認ください。
analysisStatusCodeコード | 値 | 説明 |
---|---|---|
IPRG | Analyzing | 解析中 |
CMPL | Analysis completed | 解析済み |
RDY | Ready | 解析待機 |
ERR | Analysis error | エラー |
EXCN | Exclude analysis | 例外 |
inputFileLogList
の analysisResultCode
のフィールド値を読み取り、検査結果をご確認ください。
analysisResultCode | 値 | 説明 |
---|---|---|
M | Malware detected | マルウェアの検出 |
N | Malware not detected | 正常ファイル |
E | Detection error | エラー |
マルウェアが検出された場合は、ファイルをシステムから削除するか安全に隔離します。
以下は、検査解析が完了した状態でありながらマルウェアが検出された場合のレスポンス例です。
{
"returnCode": "0",
"returnMessage": "success",
"inputFileLogList": [
{
"fileType": "application/x-msdownload; format=pe32",
"fileSize": 740544,
"md5": "a69acb01b99959efec7c0a2a8caa7545",
"sha1": "f093e7767bb63ac973b697d3fd1d40a78b87b8bf",
"sha256": "470a75fe3da2ddf9d27fb3f9c96e6c665506ea7ba26ab89f0c89606f678ae4a2",
"analysisStatusCode": "CMPL",
"analysisResultCode": "M",
"notifyYmdt": 1544005507000,
"registrationYmdt": 1544005472000,
"serviceCode": null,
"applicationCode": null
},
{
"fileType": "application/x-msdownload; format=pe32",
"fileSize": 740544,
"md5": "a69acb01b99959efec7c0a2a8caa7545",
"sha1": "f093e7767bb63ac973b697d3fd1d40a78b87b8bf",
"sha256": "470a75fe3da2ddf9d27fb3f9c96e6c665506ea7ba26ab89f0c89606f678ae4a2",
"analysisStatusCode": "CMPL",
"analysisResultCode": "M",
"notifyYmdt": 1544006407000,
"registrationYmdt": 1544006150000,
"serviceCode": null,
"applicationCode": null
},
]
}