---
title: "File Filter 개발"
slug: "filesafer-programming-file"
tags: ["api", "File Safer"]
updated: 2026-09-17T09:09:33Z
published: 2026-09-17T09:09:33Z
canonical: "guide-fin.ncloud-docs.com/filesafer-programming-file"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide-fin.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Filter 개발

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

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

참고

File Filter 개발에 앞서 File Safer 이용 신청, API Gateway 이용 신청 및 API Key 생성을 해야 합니다. 자세한 내용은 [File Safer 시작](/docs/filesafer-start)을 참고해 주십시오.

## File Filter 구현 시나리오

File Filter를 적용하는 시나리오는 다음과 같습니다.

![filesafer-programming-file_scenario_ko](https://cdn.document360.io/0406ed95-101f-4cde-8dd8-308d03444a94/Images/Documentation/filesafer-programming_file-scenario_ko.png)

[1. 파일 검사 요청(inputFile)](/docs/filesafer-programming-file#1%ED%8C%8C%EC%9D%BC%EA%B2%80%EC%82%AC%EC%9A%94%EC%B2%ADinputFile) [1-1. 악성 코드로 의심되는 파일을 구분](/docs/filesafer-programming-file#11%EC%95%85%EC%84%B1%EC%BD%94%EB%93%9C%EB%A1%9C%EC%9D%98%EC%8B%AC%EB%90%98%EB%8A%94%ED%8C%8C%EC%9D%BC%EC%9D%84%EA%B5%AC%EB%B6%84) [1-2. 인증값 생성](/docs/filesafer-programming-file#12%EC%9D%B8%EC%A6%9D%EA%B0%92%EC%83%9D%EC%84%B1) [1-3. 요청 Body 생성](/docs/filesafer-programming-file#13%EC%9A%94%EC%B2%ADBody%EC%83%9D%EC%84%B1) [1-4. 요청 파라미터 추가](/docs/filesafer-programming-file#14%EC%9A%94%EC%B2%AD%ED%8C%8C%EB%9D%BC%EB%AF%B8%ED%84%B0%EC%B6%94%EA%B0%80) [1-5. API 요청](/docs/filesafer-programming-file#15API%EC%9A%94%EC%B2%AD)

[2. 검사 결과 확인(getInputFileLog)](/docs/filesafer-programming-file#2%EA%B2%80%EC%82%AC%EA%B2%B0%EA%B3%BC%ED%99%95%EC%9D%B8getInputFileLog) [2-1. 검사 결과를 확인할 Hash 값 구분](/docs/filesafer-programming-file#21%EA%B2%80%EC%82%AC%EA%B2%B0%EA%B3%BC%EB%A5%BC%ED%99%95%EC%9D%B8%ED%95%A0Hash%EA%B0%92%EA%B5%AC%EB%B6%84) [2-2. 인증값 생성](/docs/filesafer-programming-file#22%EC%9D%B8%EC%A6%9D%EA%B0%92%EC%83%9D%EC%84%B1) [2-3. 요청 파라미터 추가](/docs/filesafer-programming-file#23%EC%9A%94%EC%B2%AD%ED%8C%8C%EB%9D%BC%EB%AF%B8%ED%84%B0%EC%B6%94%EA%B0%80) [2-4. API 요청](/docs/filesafer-programming-file#24API%EC%9A%94%EC%B2%AD) [2-5. 응답 값 확인 및 차단 여부 판단](/docs/filesafer-programming-file#25%EC%9D%91%EB%8B%B5%EA%B0%92%ED%99%95%EC%9D%B8%EB%B0%8F%EC%B0%A8%EB%8B%A8%EC%97%AC%EB%B6%80%ED%8C%90%EB%8B%A8)

참고

File Filter에서 악성 코드로 확인되는 경우 Hash Filter의 Hash 값을 업데이트하기 때문에 검사 결과를 Hash Filter에서 조회하여도 동일한 결과를 얻을 수 있습니다.

## File Filter 코드 작성

[File Filter 구현 시나리오](/docs/filesafer-programming-file#FileFilter%EA%B5%AC%ED%98%84%EC%8B%9C%EB%82%98%EB%A6%AC%EC%98%A4)에 따라 코드를 작성해 주십시오.

### 1. 파일 검사 요청(inputFile)

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

참고

inputFile API 사양은 [inputFile (File Filter)](https://api-fin.ncloud-docs.com/docs/security-filesafer-inputfile)를 참고해 주십시오.

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

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

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

#### 1-2. 인증값 생성

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

- `x-ncp-iam-access-key`: 네이버 클라우드 플랫폼 솔의 우측 상단 **My Account** > **계정 및 보안 관리** > **보안 관리** > **접근 관리** > **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 값을 생성하는 방법과 예제 코드는 [네이버 클라우드 플랫폼 API 가이드 > API 개요 > 기본 API > Ncloud API > 2.헤더 생성](https://api-fin.ncloud-docs.com/docs/common-ncpapi)를 참조하시기 바랍니다.

#### 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.fin-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)](https://api-fin.ncloud-docs.com/docs/security-filesafer-getinputfilelog)를 참고해 주십시오.

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

[파일 검사 요청 시나리오](/docs/filesafer-programming-file#1%ED%8C%8C%EC%9D%BC%EA%B2%80%EC%82%AC%EC%9A%94%EC%B2%ADinputFile)를 통해 File Filter에 검사를 요청했던 파일의 Hash 값을 구분해 주십시오.

#### 2-2. 인증값 생성

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

- `x-ncp-iam-access-key`: 네이버 클라우드 플랫폼 콘솔의 **My Account** > **계정 및 보안 관리** > **보안 관리** > **접근 관리** > **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 값을 생성하는 방법과 예제 코드는 [네이버 클라우드 플랫폼 API 가이드 > API 개요 > 기본 API > Ncloud API > 2.헤더 생성](https://api-fin.ncloud-docs.com/docs/common-ncpapi)를 참조하시기 바랍니다.

#### 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.fin-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
    },
  ]
}
```