Web Security Checker API 사용 가이드

Web Security Checker API 사용 가이드 개요

Web Security Checker API 사용 가이드에서는 Web Security Checker 의 API 를 사용하는 방법을 설명하고 있습니다.

Web Security Checker API 이용하기

Web Security Checker API 를 사용하기 위해 인증키가 필요합니다. 인증키는 두 가지 방법으로 발급이 가능합니다.

1. 메인 계정의 API 인증키 발급
2. 서브 계정의 생성 및 Access Key 발급

메인 계정의 API 인증키 발급하기

메인 계정으로 네이버 클라우드 플랫폼에 로그인 합니다. 마이 페이지 > 계정 관리 > 인증키 관리 메뉴에 접근하여 [신규 API 인증키 생성] 버튼을 클릭하여 API 인증키 발급을 완료합니다.

서브 계정 생성 및 Access Key 발급하기

서브 계정을 생성하고 Access Key를 발급하는 방법이 궁금한 경우 Sub Account 사용 가이드를 참조해 주십시오.
서브 계정(Sub Account)을 생성한 후 해당 계정에 Web Security Checker의 사용 권한을 추가해야 합니다.

1. 생성한 서브 계정을 선택하여 서브 계정 상세 페이지로 이동해 주십시오.
2. 정책 탭에서 [추가] 버튼을 클릭해 주십시오.
3. NCP_WEB_SECURITY_CHECKER_MANAGER 정책을 검색하여 선택한 뒤 [추가] 버튼을 클릭해 주십시오.

인증키를 발급하면 Web Security Checker API를 사용할 준비가 되었습니다. API 에 대한 구체적인 내용은 Web Security Checker API 가이드 를 확인해 주시기 바랍니다.

Web Security Checker API Support

Web Security Checker API 는 아래와 같이 Web Security Checker 의 일부 기능을 제공하고 있습니다.

Web Security Checker API 이용 예시

이 가이드에서는 1. 진단 리스트 조회하기, 2. 진단 검색하기, 그리고 3. 진단 취소하기 기능을 이용하는 방법을 알아보겠습니다.

1. 진단 리스트 조회하기

Web Security Checker API 는 콘솔을 통해 등록한 진단 리스트를 API 를 통해 조회할 수 있습니다. 시작하기 전에 인증키를 미리 준비해주세요.

가이드는 Python3 을 기반으로 작성되었습니다. Java, Node.js 등의 샘플을 원하시는 경우 API 호출하기 링크에서 다른 언어의 동일한 샘플 코드를 참고할 수 있습니다.

1.1 URI 설정

진단 리스트 조회 API 는 아래와 같이 URI 가 구성됩니다.

1.2 샘플 코드

이 샘플 코드는 여러분의 진단 리스트를 조회하는 파이썬 코드입니다.

import sys
import os
import hashlib
import hmac
import base64
import requests
import time

def make_signature(method, uri, timestamp):

    access_key = "{accessKey}"  # access key id (from portal or sub account)
    secret_key = "{secretKey}"  # secret key (from portal or sub account)
    secret_key = bytes(secret_key, 'UTF-8')

    method = method
    uri = uri

    message = method + " " + uri + "\n" + timestamp + "\n" + access_key
    message = bytes(message, 'UTF-8')
    signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
    return signingKey

timestamp = str(int(time.time() * 1000))

method = 'GET'
uri = '/api/v1/jobs?pages=1&limit=10'

signature = make_signature(method, uri, timestamp)

headers = {
    'x-ncp-apigw-signature-v2': signature.decode('utf-8'),
    'x-ncp-apigw-timestamp': timestamp,
    'x-ncp-iam-access-key': '{accessKey}' # access key id (from portal or sub account)
}

response = requests.request(
    method,
    f"https://wsc.apigw.fin-ntruss.com{uri}",
    headers=headers
)

if respones.status_code == 200:
    print(response.text)

2. 진단 검색하기

Web Security Checker API 는 콘솔을 통해 등록한 진단 리스트를 API 를 통해 검색할 수 있습니다. 시작하기 전에 인증키를 미리 준비해주세요.

가이드는 Python3 을 기반으로 작성되었습니다. Java, Node.js 등의 샘플을 원하시는 경우 API 호출하기 링크에서 다른 언어의 동일한 샘플 코드를 참고할 수 있습니다.

2.1 URI 설정

진단 리스트 검색 API 는 아래와 같이 URI 가 구성됩니다.

POST 리퀘스트의 BODY 영역은 application/json Content-Type 만을 지원합니다. BODY 영역의 샘플은 2.1.1 진단 URL 검색 에서 확인할 수 있습니다.

2.1.1 진단 URL 검색

searchType 은 반드시 "memo", "url", "" 중의 하나입니다.

아래의 json 샘플은 여러분이 진단 대상으로 등록한 user-domain.co.kr 도메인을 검색하는 예시입니다.

{
  "searchType": "url",
  "searchKeyword": "user-domain.co.kr",
  "statusCode": null,
  "limit": 10,
  "page": 1
}

2.2 샘플 코드

이 샘플 코드는 여러분의 진단 리스트를 검색하는 파이썬 코드입니다.

# 생략, 1.2 절을 참고 하세요

method = 'POST'
uri = '/api/v1/jobs/search'
payload = {
  "searchType": "url",
  "searchKeyword": "user-domain.co.kr",
  "statusCode": None,
  "limit": 1,
  "page": 1
}

timestamp = str(int(time.time() * 1000))

signature = make_signature(method, uri, timestamp)

headers = {
    'x-ncp-apigw-signature-v2': signature.decode('utf-8'),
    'x-ncp-apigw-timestamp': timestamp,
    'x-ncp-iam-access-key': '{accessKey}' # access key id (from portal or sub account)
}

response = requests.request(
    method,
    f"https://wsc.apigw.fin-ntruss.com{uri}",
    headers=headers,
    data=json.dumps(payload), # Json format required
)

if response.status_code == 200:
    print(response.text)

3. 진단 취소하기

Web Security Checker API 는 등록한 진단을 API 를 통해 취소할 수 있습니다. 시작하기 전에 인증키를 미리 준비해주세요.

가이드는 Python3 을 기반으로 작성되었습니다. Java, Node.js 등의 샘플을 원하시는 경우 API 호출하기 링크에서 다른 언어의 동일한 샘플 코드를 참고할 수 있습니다.

3.1. 진단 취소/중지/리포트 기능

진단은 대기, 진행, 완료 단계로 구분되며 상태에 따라 기능이 다르게 적용됩니다.

3.2. 진단 생성하기

createJob API 를 통해 진단 작업을 생성합니다. API 의 상세한 사용방법은 Web Security Checker API 참조서 바로가기를 통해 확인해주세요.

curl -X PUT "https://wsc.apigw.fin-ntruss.com/api/v1/job"
   -H "accept: application/json"
   -H "x-ncp-iam-access-key: {x-ncp-iam-access-key}"
   -H "x-ncp-apigw-timestamp: {x-ncp-apigw-timestamp}"
   -H "x-ncp-apigw-signature-v2: {x-ncp-apigw-signature-v2}"
   --data-raw '{
    "StartUrl": "https://target-domain.com",
    "ExcludeUrl": [
        "https://www.target-domain.com/event",
        "https://www.target-domain.com/robot.txt"
    ],
      "Headers": {
        "Upgrade-Insecure-Requests": "1",
        "Accept": "text/html.....",
        "Accept-Encoding": "gzip, deflate",
        "Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7",
        "Cookie": "XSRF-TOKEN=eyJ.....; PHPSESSIONID=e.....",
        "X-Custom-Header": "Bar"
    },
    "VulnItems": [
        "ALL"
    ],
    "UserAgent": "Android",
    "Speed": "1",
    "Memo": "sample"
}'

3.3 URI 설정

진단 취소 API 는 아래와 같이 URI 가 구성됩니다.

3.4. 샘플 코드

진단 취소를 위해서 진단 검색 API 와 진단 취소 API 가 필요합니다. 진단 검색 API 를 통해서 취소할 진단의 instanceNo의 값을 추출하고 이 값을 이용해 취소 API 를 호출합니다.

아래는 target-domain.com 키워드를 url 로 검색한 결과입니다. 출력된 진단 리스트 중 대기(Pending) 상태인 진단의 instanceNo 값을 복사합니다.

$ python jobSearch.py "url target-domain.com"
{'resources':
    {
        'current_end_page': '10',
        'current_start_page': '1',
        'record_data': [{'crawl_cnt': None,
                        'end_date': None,
                        'instanceNo': '12341234',
                        'memo': 'Wsc Sample',
                        'rescan_button': None,
                        'result_button': 'cancel',
                        'result_desc': None,
                        'scan_cnt': None,
                        'slave_data': None,
                        'start_date': '2020-05-21 22:00:00',
                        'start_url': 'http://target-domain.com',
                        'status': 'Pending'}],
        'total_cnt': 10,
        'total_page_cnt': '1'}}

복사된 instanceNo 값을 샘플 코드의 instanceId 변수에 대입합니다.

import sys
import os
import hashlib
import hmac
import base64
import requests
import time
import json
from pprint import pprint

def make_signature(method, uri, timestamp):

    access_key = "{accessKey}"  # access key id (from portal or sub account)
    secret_key = "{secretKey}"  # secret key (from portal or sub account)
    secret_key = bytes(secret_key, 'UTF-8')

    method = method
    uri = uri

    message = method + " " + uri + "\n" + timestamp + "\n" + access_key
    message = bytes(message, 'UTF-8')
    signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
    return signingKey

method = 'PATCH'
instanceId = "{instanceId}" # instance id (from api)
uri = f'/api/v1/jobs/{instanceId}/cancel'
timestamp = str(int(time.time() * 1000))

signature = make_signature(method, uri, timestamp)

headers = {
    'x-ncp-apigw-signature-v2': signature.decode('utf-8'),
    'x-ncp-apigw-timestamp': timestamp,
    'x-ncp-iam-access-key': '{accessKey}' # access key id (from portal or sub 
}

response = requests.request(
    method,
    f"https://wsc.apigw.fin-ntruss.com{uri}",
    headers=headers
)

if response.status_code == 200:
    pprint(json.loads(response.text))
else:
    pprint(json.loads(response.text))