Web Security Checker API 사용 가이드

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

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 를 통해 조회할 수 있습니다. 시작하기 전에 인증키를 미리 준비해주세요.

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.gov-ntruss.com{uri}",
    headers=headers
)

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

2. 진단 검색하기

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

2.1 URI 설정

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

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

진단 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.gov-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 를 통해 취소할 수 있습니다. 시작하기 전에 인증키를 미리 준비해주세요.

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

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

3.2. 진단 생성하기

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

curl -X PUT "https://wsc.apigw.gov-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 로 검색한 결과입니다. 출력된 진단 리스트 중 예약(Reservation) 상태인 진단의 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': 'Reservation'}],
        '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.gov-ntruss.com{uri}",
    headers=headers
)

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