네이버 클라우드 플랫폼 API 시작 가이드 개요

자세한 내용은 네이버 클라우드 플랫폼 File Safer API reference를 참고하시기 바랍니다.

API 시작 가이드에서는 간단한 시나리오를 통해 파일의 악성여부를 탐지하는 내용을 포함하고 있으며, 해당 시나리오를 따라 해 봄으로써 네이버 클라우드 플랫폼 File Safer API 사용법을 익힐 수 있습니다.

File Safer API(Published API) 이용하기

시작하기에 앞서, File Safer의 API는 API Gateway를 통해 제공되므로 API Gateway의 이용 신청 및 API Key가 필요합니다.

아래의 가이드를 참조하여 API Gateway의 이용을 신청합니다.

API Gateway의 API Keys 메뉴로 이동하여 API Key를 생성합니다.

생성된 API Key를 이용하여 File Safer의 API를 이용하게 되며, API에 대한 설명은 문서 하단의 연관정보인 File Safer API 사용 가이드 및 API reference 내용을 참고하시기 바랍니다.

File Safer의 API의 Subscription Type은 공개-자율구독(Public)이므로 별도의 구독과정없이 생성하신 API Key를 이용하여 사용 가능합니다.

의심파일 Hash 값 확인하여 차단하기

사용자로부터 업로드/다운로드되는 파일의 Hash 값을 추출하여 악성여부를 확인하고 이를 차단하는 과정을 시나리오로 알아 보겠습니다.

Hash 값을 이용하여 악성여부를 확인하는 기능은 File Safer의 Hash Filter에서 제공하는 API를 이용하며, 해당 API는 네이버 클라우드 플랫폼에서 사용하는 IAM인증 및 API Gateway를 통해 사용하실 수 있습니다.

아래의 시나리오에 따라 인증 값을 생성하고 필요한 액션 파라미터를 추가하여 API를 호출 합니다.

시나리오

시나리오는 아래의 순서로 진행됩니다.

① 악성코드로 의심되는 파일을 구분

② 인증 값 생성

③ 구분된 파일의 Hash 값 추출

④ Hash 값을 포함하여 액션 파라미터 값 추가

⑤ API 요청

⑥ 응답 값 확인 및 차단 여부 판단

시나리오 수행

시나리오 순서에 따라 아래와 같이 수행합니다.

① 악성코드로 의심되는 파일을 구분

새로이 업로드되거나 사용자가 다운로드하려는 파일 등 악성 부의 확인이 필요한 파일을 구분 합니다.

② 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다.

세부 내용은 아래의 내용을 참조 합니다.

네이버 클라우드 플랫폼 포털 > 마이페이지 > API 인증키 관리 화면에서 Access Key, Secret Key를 발급받고 진행한 후 Signature를 생성합니다. (개행문자는 \n을 사용합니다.)

요청에 맞게 StringToSign를 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다. 이 값을 x-ncp-apigw-signature-v1로 사용합니다.

③ 구분된 파일의 Hash 값 추출

악성여부를 확인하려는 파일의 Hash 값을 추출 합니다.

아래는 Hash 값을 추출하는 java sample code이며, 추출된 Hash 값은 아래와 같이 표기 합니다. (현재는 SHA-1과 MD5를 지원하며, SHA-1의 사용을 권고 드립니다.)

  • SHA-1: 16진수 40bytes String으로 표기 합니다. (ex 3ec625cb2277d7334406ab712b69c4ceaf38bd82)
  • MD5: 16진수 32bytes String으로 표기 합니다. (ex. 8072fd6da170738c905cf362f787442b)
import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOUtils;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;

public abstract class MessageDigestUtils {
    public static String md5Hex(File file) throws IOException {
        InputStream inputStream = null;
        try {
            inputStream = getInputStream(file);
            return DigestUtils.md5Hex(inputStream);
        } finally {
            IOUtils.closeQuietly(inputStream);
        }
    }

    public static String shaHex(File file) throws IOException {
        InputStream inputStream = null;
        try {
            inputStream = getInputStream(file);
            return DigestUtils.shaHex(inputStream);
        } finally {
            IOUtils.closeQuietly(inputStream);
        }
    }

    public static String sha256Hex(File file) throws IOException {
        InputStream inputStream = null;
        try {
            inputStream = getInputStream(file);
            return DigestUtils.sha256Hex(inputStream);
        } finally {
            IOUtils.closeQuietly(inputStream);
        }
    }

    private static InputStream getInputStream(File file) throws IOException {
        return FileUtils.openInputStream(file);
    }
}

④ Hash 값을 포함하여 파라미터 값 추가

추출된 Hash 값을 포함하여 API에 필요한 액션 파라미터 값들을 추가합니다.

‘hash’ 키를 이용하여 파라미터를 생성합니다.

  • Key: hash
  • Value: 추출한 Hash 값 String

    Ex, hash=00010efc49b7174d18400710eed1642a7d4b12db

Hash 값을 추출한 알고리즘을 String 타입으로 구분 하여 HashType 파라미터를 생성합니다.

  • SHA-1을 사용했을 경우: sha1
  • MD5를 사용했을 경우: md5

  • Key: hashType

  • Value: 추출한 Hash 알고리즘의 구분 값 String

    Ex, hashType=sha1

⑤ API 요청

Hash Filter에서 제공하는 URI로 생성한 인증 + 액션 파라미터를 이용하여 요청 합니다.

⑥ 응답 값 확인 및 차단 여부 판단

Hash Filter에 의해 탐지된 Hash의 파일은 악성코드이므로 운영 하시는 시스템에서 삭제 또는 안전하게 격리를 수행합니다.

의심 파일 전송하여 악성 여부 확인하기

악성코드로 의심되는 파일을 전송하여 검사를 요청 하고, 전송한 파일의 검사 결과를 확인하여 악성여부를 구분하는 과정을 시나리오로 알아 보겠습니다.

파일을 전송하여 악성여부를 확인하는 기능은 File Safer의 File Fiter에서 제공하는 API를 이용하며, 해당 API는 네이버 클라우드 플랫폼에서 사용하는 IAM인증 및 API Gateway를 통해 사용하실 수 있습니다.

File Filter에서는 2개의 API를 제공하며 각각의 용도는 아래와 같습니다.

① 파일 검사 요청 (inputFile)

Multipart 형태로 파일을 전송하여 검사를 요청 합니다.

② 검사 결과 확인 (getInputFileLog)

검사를 요청한 파일의 Hash 값을 이용하여 검사 결과를 확인합니다.

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

File Filter로는 파일을 전송(inputFile)하고 확인은 Hash Filter(checkhash)로 하도록 구성하는 것이 File Safer의 특징에 좀 더 맞는 방법입니다.

시나리오

시나리오는 아래의 순서로 진행됩니다.

파일 검사 요청

① 악성코드로 의심되는 파일을 구분

② 인증 값 생성

③ 구분된 파일을 추가한 요청 생성

④ 필요한 파라미터 추가

⑤ API 요청

검사 결과 확인

① 검사 결과를 확인해야 하는 Hash 값 구분

② 인증 값 생성

③ 필요한 파라미터 추가

④ API 요청

⑤ 응답 값 확인 및 차단 여부 판단

시나리오 수행

시나리오 순서에 따라 아래와 같이 수행합니다.

파일 검사 요청

① 악성코드로 의심되는 파일을 구분

Hash Filter로 확인이 안되거나 악성여부 확인이 필요한 파일을 구분 하며, 아래의 제약이 따릅니다.

  • 파일 개수 제한: 1번의 전송에는 1개의 파일만 처리되며, 2개 이상의 파일이 전송되는 경우 전송된 파일 중 1개의 파일이 임의선택되어 처리됩니다.

  • 파일 크기 제한: 1번의 전송 시 스트림 기준으로 10MB의 용량 제한이 적용됩니다.

② 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다.

세부 내용은 아래의 내용을 참조 합니다.

네이버 클라우드 플랫폼 포털 > 마이페이지 > API 인증키 관리 화면에서 Access Key, Secret Key를 발급받고 진행한 후 Signature를 생성합니다. (개행문자는 \n을 사용합니다.)

요청에 맞게 StringToSign를 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다. 이 값을 x-ncp-apigw-signature-v1로 사용합니다.

③ 구분된 파일을 추가한 요청 생성

Multipart로 Body에 파일을 포함한 요청을 생성합니다.

  • Key: file
  • Value: binary

④ 필요한 파라미터 추가

전송하려는 파일이 패스워드가 설정된 압축 파일인 경우 아래의 파라미터를 요청에 추가합니다.

  • Key: archivePassword
  • Value: 압축파일 패스워드 String

파라미터가 모두 추가된 POST 요청의 Body는 아래의 형태를 가집니다.

Content-Type: multipart/form-data; boundary=----AAAAAAAAAAAAAAAAAAAAAAAAAAAAA

------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="file"; filename="suspicious-file.zip"
Content-Type: application/x-zip-compressed

------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="archivePassword"

password
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA--

⑤ API 요청

File Filter에서 제공하는 URI로 생성한 요청을 전송합니다.

검사 결과 확인

① 검사 결과를 확인해야 하는 Hash 값 구분

File Filter에 검사를 요청했던 파일의 Hash 값을 구분 합니다. (MD5, SHA-1을 지원 합니다.)

② 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다. “파일 검사 요청”의 내용을 참조 합니다.

③ 필요한 파라미터 추가

결과 확인에 필요한 조건을 json 포맷으로 생성하여 추가하며, 필수 파라미터는 아래와 같습니다.

  • hash: 확인하려는 Hash 값을 스트링으로 추가합니다.

  • hashType: 추가한 Hash 값의 알고리즘을 표기 합니다. (MD5, SHA-1)

파라미터가 추가된 POST 요청의 Body의 예제는 아래와 같습니다.

{
    "hash":"a7bbc4b4f781e04214ecebe69a766c76681aa7eb",
    "hashType":"sha1"
}

④ API 요청

File Filter에서 제공하는 URI로 생성한 요청을 전송합니다.

⑤ 응답 값 확인 및 차단 여부 판단

File Filter의 결과 값에 따라서, 차단 또는 허용여부를 판단하고 진행합니다.

응답 값은 json 포맷이며, inputFileLogList의 리스트의 개수가 0일 경우는 확인한 Hash의 파일의 결과가 없는 경우입니다. 반면, 리스트의 개수가 2개 이상일 경우 2번 이상 분석이 된 경우이며 ‘analysisResultCode’를 확인 후 운영 하시는 시스템에서 삭제 또는 안전하게 격리를 수행합니다.

참고 사항

본 상품은 글로벌 리전 서비스로도 제공됩니다.

연관 정보 바로가기

아래 가이드에서 연관 정보를 확인할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...