API 개요

네이버 클라우드 플랫폼 API에 대해서 설명 합니다.

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

네이버 클라우드 플랫폼은 NAVER의 최신 컴퓨팅 기술과 운영 노하우가 축적된 클라우드 서비스입니다.

네이버 클라우드 플랫폼에서 제공하는 여러 가지 상품군 중에 솔루션 상품을 이용할 수 있도록 제공하는 응용 프로그램 인터페이스(API)를 네이버 클라우드 플랫폼 API라고 합니다.

네이버 클라우드 API는 API Gateway를 이용한 RESTFUL형태로 제공되며, HTTP 방식의 GET / POST 메소드 호출을 통해서 이루어집니다.

API Gateway

File Safer의 API는 네이버 클라우드 플랫폼의 API Gateway를 이용하여 제공됩니다.

아래의 내용에서 확인 가능한 hashfilter, filefilter API는 Public 구동 방식으로 가입 절차 없이 이용 가능하며, Published APIs에서 아래의 Procduct 이름으로 확인 가능합니다.

  • Product 이름: File Safer
  • 설명: NAVER CLOUD PLATFORM FILE-SAFER

Auth

IAM Auth

네이버 클라우드 플랫폼에서 제공하는 Rest-API는 API Gateway를 이용하며 IAM 인증이 필요 합니다. 아래 IAM 인증이 필요한 API 호출하기 링크의 인증값 생성 및 API 호출하기 내용을 참조 합니다.

Hash Filter

checkHash

API 요청 구성

API URL + 액션 + 액션 파라미터 + AUTHPARMS

구분 설명
API URL 네이버 클라우드 플랫폼 File Safer (Hash Filter) API URL
https://filesafer.apigw.ntruss.com/hashfilter/v1/checkHash
전송 방식 GET
액션 Hash Filter는 Hash 조회 액션을 제공합니다.
액션 파라미터 Hash 값을 지정하는 hash 파라미터와 Hash 알고리즘을 지정하는 hashType 파라미터를 지원합니다.
AUTHPARAMS x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}

API 요청 액션 파라미터

이름 (Key) 타입 설명
hash String 조회하려는 Hash 값입니다.
hashType String 조회하려는 Hash를 추출한 알고리즘 구분 값으로 md5, sha1을 지원합니다.
responseFormatType String 응답 포맷 타입 구분 값으로 json을 지원 합니다.

API 요청 Sample

https://filesafer.apigw.ntruss.com/hashfilter/v1/checkHash?hashType=sha1&hashCode=00010efc49b7174d18400710eed1642a7d4b12dc

x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}

API 응답 포맷

json 포맷을 지원합니다.

구분 응답
탐지 되었을 경우 {
    "returnCode": "0",
    "returnMessage": "success",
    "totalRows": 1,
    "hashCheckResultList": [
        {
            "hashType": "sha1",
            "hashCode": "213ce10c4298c7617aac93615c3c3b0a783fd304",
            "group": "file",
            "result": "1",
            "regDateTime": "2018-11-06 16:05:26.0"
        }
    ]
}
탐지 되지 않았을 경우 {
    "returnCode": "0",
    "returnMessage": "success",
    "totalRows": 0,
    "hashCheckResultList": []
}

API 응답 구성

항목 설명
returnCode 요청에 대한 처리 결과 코드입니다.
returnMessage 요청에 대한 처리 결과 메시지입니다.
totalRows hashCheckResultList의 object 개수입니다.
hashCheckResultList 질의한 Hash에 해당하는 탐지건에 대한 정보이며, 리스트에 object가 있을 경우 악성코드로 처리합니다.
hashType hashcode의 알고리즘 구분이며 MD5, SHA-1을 지원 합니다.
hashCode 탐지된 Hash 값입니다.
group 탐지된 Hash 값이 File object의 값인 경우 ‘file’로 표기되며, URL의 스트링인 경우에는 ‘url’로 표기됩니다.
result 질의한 Hash가 탐지된 경우에는 “1” 탐지되지 않은 경우에는 “0”의 값을 가집니다.
regDatetime Hash 값이 등록된 시간입니다.

File Filter

inputFile

API 요청 구성

API URL + 분석 대상 파일 + 압축 패스워드 + AUTHPARMS

항목 설명
API URL 네이버 클라우드 플랫폼 File Safer (File Filter) API URL
https://filesafer.apigw.ntruss.com/filefilter/v1/inputFile
전송 방식 POST
요청 포맷 Multipart-form
분석 대상 파일 POST 요청 Body에 file을 추가합니다.
hashType hashcode의 알고리즘 구분이며 MD5, SHA-1을 지원 합니다.
AUTHPARMS x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}

API 요청 헤더

요청 헤더는 Key, Value 쌍으로 구성되어 있으며, 아래의 값을 가질 수 있습니다.

이름 (Key) 타입 설명
file File 분석 요청 대상 파일 (전송 대상 파일)
archivePassword String 압축 패스워드

API 요청 Sample

https://filesafer.apigw.ntruss.com/filefilter/v1/inputFile

x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}
archivePaaword: password
file: File

API 응답 포맷

JSON 형식의 포맷을 지원합니다.

구분 응답 예제
전송 성공 {
    "returnCode": "0",
    "returnMessage": "success"
}
전송 실패 {
    "returnCode": "9",
    "returnMessage": “fail"
}

API 응답 구성

항목 설명
returnCode 요청에 대한 처리 결과 코드입니다.
returnMessage 요청에 대한 처리 결과 메시지입니다.

getInputFileLog

API 요청 구성

API URL + Hash 값 + Hash 알고리즘 구분 + AUTHPARMS

항목 설명
API URL 네이버 클라우드 플랫폼 File Safer (File Filter) API URL
https://filesafer.apigw.ntruss.com/filefilter/v1/getInputFileLog
전송 방식 GET / POST
요청 포맷 POST 전송의 경우 Multipart-form을 이용합니다.
액션 File Filter는 분석 결과 확인을 위해 getInputFileLog 액션을 제공합니다.
액션 파라미터 Hash 값을 지정하는 hash 파라미터와 Hash 알고리즘을 지정하는 hashType 파라미터를 지원합니다.
AUTHPARMS x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}

API 요청 헤더

액션 헤더는 Key, Value 쌍으로 구성되어 있으며, 아래의 값을 가질 수 있습니다.

이름 (Key) 타입 설명
hash String 해시 값
hashType String md5, sha1

API 요청 Sample

(GET)
https://filesafer.apigw.ntruss.com/filefilter/v1/getInputFileLog?hash=789ccf3e15a58245f5c1ee07b7cd0597a6791a6f&hashType=sha1


(POST)
https://filesafer.apigw.ntruss.com/filefilter/v1/getInputFileLog

hash=789ccf3e15a58245f5c1ee07b7cd0597a6791a6f
hashType=sha1

API 응답 포맷

json 형식의 포맷을 지원합니다.

구분 응답
분석된 파일이 있는 경우 {
    "returnCode": "0",
    "returnMessage": "success",
    "inputFileLogList": [
        {
            "fileType": "application/octet-stream",
            "fileSize": 827968,
            "md5": "8201b5633ab1862a2b116568477a3747",
            "sha1": "5f075447e8413d059e85017953670e8cc2c1f1f1",
            "analysisStatusCode": "CMPL",
            "analysisResultCode": "N",
            "notifyYmdt": null,
            "registrationYmdt": "2018-11-06 16:05:26.0"
        }
    ]
}
분석된 파일이 없는 경우 {
    "returnCode": "0",
    "returnMessage": "success",
    "inputFileLogList": []
}

API 응답 구성

항목 설명
returnCode 요청에 대한 처리 결과 코드입니다.
returnMessage 요청에 대한 처리 결과 메시지입니다.
inputFileLogList 질의한 Hash에 해당하는 탐지건에 대한 정보이며, 동일한 Hash의 파일이 2회 이상 분석 되었을 경우 리스트로 표기됩니다.
fileType 분석된 파일의 포맷이며 MIME 형태로 표기가 됩니다.
fileSize 분석된 파일의 크기입니다.
md5 분석된 파일의 MD5 Hash 값입니다.
sha1 분석된 파일의 SHA-1 Hash 값입니다.
analysisStatusCode 분석 상태 코드입니다. 아래의 값을 가집니다.

[ Code : Desc : Status ]
IPRG : Analyzing : 분석 중
CMPL : Analysis completed : 분석 완료
ERR : Analysis error : 에러
EXCN : Exclude analysis : 예외
analysisResultCode 분석 결과 코드입니다. 아래의 값을 가집니다.

[ Code : Desc : Status ]
M : Malware detected : 악성 코드 (Hash Filter에 업데이트됩니다.)
N : Malware not detected : 정상 파일
E : Detection error : 에러
notifyYmdt 알림을 설정했을 경우 알림이 발송된 시간입니다.
registrationYmdt 파일이 인입된 시간입니다.

응답 코드

API 요청에 대한 처리 결과를 응답으로 전달하며, 응답 코드는 File Safer에 의한 응답과 API Gateway에 의한 응답으로 구분됩니다.

File Safer에서 요청이 처리된 경우의 응답 코드 이며 140000 번대 returnCode는 에러가 발생한 경우입니다.

HTTP 응답 코드 returnCode returnMessage
200 0 success
200 140000 Unknown Error
200 140001 Parameter is invalid
200 140002 Not existent user
200 140003 Already in use
200 140004 Not allowed user
200 140005 Not existing the required parameter
200 140006 invalid request
200 140007 file size exceeds the limit
200 140009 Input file has a problem
200 140010 Unzip failed

File Safer에서 사용하는 API Gateway에서 에러가 발생했을 경우의 에러 코드입니다.

HTTP 응답 코드 ErrorCode ErrorMessage
400 100 Bad Request Exception
401 200 Authentication Failed
401 210 Permission Denied
404 300 Not Found Exception
429 400 Quota Exceeded
429 410 Throttle Limited
429 420 Rate Limited
413 430 Request Entity Too Large
503 500 Endpoint Error
504 510 Endpoint Timeout
500 900 Unexpected Error

참고 사항

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

연관 정보 바로가기

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

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

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

    처리중...