File Filter 개발

Classic/VPC 환경에서 이용 가능합니다.

File Filter REST API를 사용하여 File Filter 코드를 작성하는 방법을 설명합니다.

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 코드 작성

File Filter 구현 시나리오에 따라 코드를 작성해 주십시오.

1. 파일 검사 요청(inputFile)

File Filter API 중 inputFile을 사용하여 파일 검사를 요청합니다.

1-1. 악성 코드로 의심되는 파일을 구분

Hash Filter로 확인이 안되는 파일이거나 악성 여부 확인이 필요한 파일을 구분해 주십시오. 파일 제약 사항은 다음과 같습니다.

• 파일 개수 제한: inputFile API 호출 시 요청당 파일 한 개만 처리. 파일이 2개 이상 전송되는 경우 파일 한 개만 임의로 선택되어 처리
• 파일 크기 제한: API 호출당 파일 용량 10 MB로 제한

1-2. 인증값 생성

네이버 클라우드 플랫폼 API 사용 인증에 필요한 IAM 인증값을 생성해 주십시오. 인증에 필요한 헤더는 다음과 같습니다.

• x-ncp-iam-access-key: 네이버 클라우드 플랫폼 포털의 마이페이지 > 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 명세 참고

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://gov-filesafer.apigw.gov-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를 사용하여 악성 코드 검사 결과를 확인합니다.

2-1. 검사 결과를 확인할 Hash 값 구분

파일 검사 요청 시나리오를 통해 File Filter에 검사를 요청했던 파일의 Hash 값을 구분해 주십시오.

2-2. 인증값 생성

네이버 클라우드 플랫폼 API 사용 인증에 필요한 IAM 인증값을 생성해 주십시오. 인증에 필요한 헤더는 다음과 같습니다.

• x-ncp-iam-access-key: 네이버 클라우드 플랫폼 포털의 마이페이지 > 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 명세 참고

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://gov-filesafer.apigw.gov-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 필드 값을 읽어서 검사 진행 상황을 확인해 주십시오.

inputFileLogList의 analysisResultCode 필드 값을 읽어서 검사 결과를 확인해 주십시오.

악성 코드가 검출된 경우에는 파일을 시스템에서 삭제하거나 안전하게 격리해 주십시오.
다음은 검사 분석 완료 상태이면서 악성 코드가 검출된 경우의 응답 예시입니다.

{
  "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
    },
  ]
}