マニュアル - NAVER CLOUD PLATFORM

NAVERクラウドプラットフォームの商品の使用方法をより詳しく提供し、様々なAPIの活用をサポートするために[説明書]と[APIリファレンス]を分けて提供しています。

Web Security Checker APIリファレンス >>
Web Security Checker API使用ガイド >>
Web Security Checkerマニュアル >>

Web Security Checker API使用ガイドの概要

Web Security Checker API使用ガイドでは、Web Security CheckerのAPIを使用する方法を説明しています。

Web Security Checker APIを利用する

Web Security Checker APIはAPI Gatewayを通して提供されます。API Gatewayを使用するために、サブアカウント（Sub Account）が必要です。サブアカウントを作成するには、以下のリンクをご参照ください。

サブアカウントやAccess Keyを作成する

サブアカウント(Sub Account)を作成した後、このアカウントにWeb Security Checkerの使用権限を追加する必要があります。

作成したサブアカウントを選択して「サブアカウント詳細」ページに移動します。
ポリシータブで(1)追加ボタンをクリックします。
(2) NCP_WEB_SECURITY_CHECKER_MANAGERポリシーを検索した後、追加ボタンをクリックします。

サブアカウントとAccess Key発行が完了すると、Web Security Checker APIを使用する準備が完了します。APIの具体的な内容は、Web Security Checker APIリファレンスでご参照ください。

Web Security Checker API Support

Web Security Checker APIは以下のようにWeb Security Checkerの一部の機能を提供しています。

順番	メソッド	URL	機能
1	GET	`/jobs`	診断リスト
2	POST	`/jobs/search`	診断リストを検索
3	PATCH	`/jobs/{instanceId}/cancel`	登録した診断をキャンセル（診断の実行前）
4	PATCH	`/jobs/{instanceId}/stop`	進行中の診断を停止（診断の実行中）
5	GET	`/jobs/{instanceId}/report`	診断レポート
6	PUT	`/job`	診断作成

Web Security Checker API利用例

このガイドでは、1. 診断リストを照会する、2. 診断リストを検索する方法を説明します。

1.診断リストを照会する

Web Security Checker APIを使用すると、コンソールを通して登録した診断リストをAPIで照会できます。開始する前に、サブアカウントのAccess KeyとSecret Keyを準備してください。

このガイドはPython3に基づいて作成されました。Java、Node.jsなどのサンプルをご希望の場合、API呼び出しリンクから他の言語の同じサンプルコードを参照することができます。

1.1 URIの設定

診断リスト照会APIは、以下のようにURIが構成されます。

順番	タイプ	値	説明
1	Method	GET	GETメソッド
2	URL	/api/v1/jobs	作業リスト照会URLのパス
3	Query String	page	リストのページ番号
4	Query String	limit	リストのページごとの出力項目数

1.2サンプルコード

このサンプルコードは、診断リストを照会するPythonコードです。

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

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

2.診断を検索する

2.1 URIの設定

診断リスト検索APIは、以下のようにURIが構成されます。

順番	タイプ	値	説明
1	Method	POST	POSTメソッド
2	URL	/api/v1/jobs/search	作業リスト検索URLのパス

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サンプルコード

このサンプルコードは、診断リストを検索するPythonコードです。

make_signature関数の場合は、1.3節のサンプルコードを使用してください。

# 省略 、1.3節をご参照ください。

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.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を使用すると、登録された診断をキャンセルすることができます。開始する前に、サブアカウントのAccess KeyとSecret Keyを準備してください。

3.1.診断をキャンセル/停止/レポートする

診断は待機、進行、完了段階に区分され、段階に応じて異なる機能が適用されます。

診断状態	提供機能
待機/予約	キャンセル可能
進行	中断可能
完了	レポート出力可能

3.2.診断を作成する

createJob APIを通じて診断作業を作成します。APIの詳細な使用方法は、Web Security Checker APIリファレンスに移動するから確認してください。

curl -X PUT "https://wsc.apigw.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"
    ],
    "Cookies": "JSESSIONID=AB123123123123ASAS; Login_Ok=true; Role=admin;",
    "VulnItems": [
        "ALL"
    ],
    "UserAgent": "Android",
    "Speed": "1",
    "Memo": "sample"
}'

3.3 URIの設定

診断キャンセルAPIは以下のようにURIが構成されます。

順番	タイプ	値	説明
1	Method	PATCH	PATCHメソッド
2	URL	/api/v1/jobs/{instanceId}/cancel	診断キャンセルURLのパス

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

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

ポータルのショートカット  NAVERクラウドプラットフォームのマニュアル

NAVERクラウドプラットフォームの商品の使用方法をより詳しく提供し、様々なAPIの活用をサポートするために[説明書]と[APIリファレンス]を分けて提供しています。