createJob

Available in Classic and VPC

Register a new diagnostic job or create a diagnosed job as a re-diagnostic job.

Request

The following describes the request format for the endpoint. The request format is as follows:

Request headers

For headers common to Web Security Checker, see Web Security Checker common request headers.

Request path parameters

The following describes the parameters.

List of reserved words

The list of reserved words is as follows.

List of UserAgent reserved words

Web Security Checker provides diagnostic options that allow users to choose the browser that their websites optimally support.
See the following description of the UserAgent reserved words to specify the required UserAgent value when generating diagnostics.

List of reserved words for diagnosis categories

The Create diagnostics API provides the ability to selectively create the diagnostics you want by specifying the diagnostic items.

See the following description of reserved words for diagnostic items to specify the required VulnItems value when generating diagnostics.

• When diagnosing with all diagnostic items: Select the ALL keyword.
• When diagnosing with only some diagnostic items: Select only desired keywords.

Request example (new)

The following is a sample request.

curl --location --request GET 'https://wsc.apigw.ntruss.com/api/v1/job'
--header 'x-ncp-apigw-timestamp: {Timestamp}'
--header 'x-ncp-iam-access-key: {Access Key}'
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--header 'Content-Type: application/json'
--data-raw '{
"StartUrl": "https://www.ncloud.com",
"ExcludeUrl": [
    "https://www.ncloud.com/event",
    "https://www.ncloud.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": "OPEN API TEST"
}'

Request example (re-diagnostic)

The following is a sample request.

Search diagnostics that can be re-diagnosed (manual)

In the response of a call to the getJobs (Web Security Checker) API, as shown in the following example, check the instanceNo of the entry in the resources > record_data property labeled "rescan_button": "possible".

• If the value of rescan_button is null or expired, it can't be re-diagnosed.

# Request example
curl --location --request GET "https://wsc.apigw.ntruss.com/api/v1/jobs?limit=10&page=1"
--header 'Content-Type: application/json'
--header 'x-ncp-iam-access-key: {x-ncp-iam-access-key}'
--header 'x-ncp-apigw-timestamp: {x-ncp-apigw-timestamp}'
--header 'x-ncp-apigw-signature-v2: {x-ncp-apigw-signature-v2}'

# Response example
{
    "returnCode": "0",
    "returnDesc": "Request Success",
    "returnMessage": "Succeeded",
    "resources": {
        "total_cnt": 1,
        "total_page_cnt": "1",
        "current_start_page": "1",
        "current_end_page": "10",
        "record_data": [
            {
                "instanceNo": "12311231",
                "start_date": "2020-12-02 23:34:54",
                "end_date": "2020-12-02 23:36:43",
                "status": "Complete",
                "start_url": "http://ncloud.com",
                "crawl_cnt": "10",
                "scan_cnt": "1",
                "memo": "OPEN API test (#1)",
                "result_button": "report",
                "result_desc": null,
                "rescan_button": "possible",
                "slave_data": null
            },
        ]
    }
}

Search diagnostic that can be re-diagnosed (using jq utility)

You can use the getJobs (Web Security Checker) API and the jq utility to get a list of re-diagnosable instanceNos, as shown in the following example.

• If there is no instanceNo, it means that there is no possible diagnosis task that can be re-diagnosed.

# Request example
curl --location --request GET "https://wsc.apigw.ntruss.com/api/v1/jobs?limit=10&page=1"
--header 'Content-Type: application/json'
--header 'x-ncp-iam-access-key: {x-ncp-iam-access-key}'
--header 'x-ncp-apigw-timestamp: {x-ncp-apigw-timestamp}'
--header 'x-ncp-apigw-signature-v2: {x-ncp-apigw-signature-v2}' | jq '.resources.record_data[] | select( .rescan_button == "possible" ) | .instanceNo'

# Response example
%"12311231"

Create re-diagnostic job

• The masterInstanceNo input value must be entered as a string type.
  • <Example> "MasterInstanceNo": "12311231"
• The VulnItems input value must be entered as a list type.
  • <Example> "VulnItems": ["ALL"]

curl --location --request GET 'https://wsc.apigw.ntruss.com/api/v1/job'
--header 'x-ncp-apigw-timestamp: {Timestamp}'
--header 'x-ncp-iam-access-key: {Access Key}'
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--header 'Content-Type: application/json'
--data-raw '{
 "StartUrl": "https://www.ncloud.com",
    "ExcludeUrl": [
        "https://www.ncloud.com/event",
        "https://www.ncloud.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": "OPEN API TEST",
    "MasterInstanceNo": "12311231"
}'

Response

The following describes the response format.

Response status codes

For error codes common to Web Security Checker APIs, see Common Web Security Checker error codes.

Response example

The following is a sample example.

• Diagnostic job created

{
    "returnCode": "0",
    "returnDesc": "Request Success",
    "returnMessage": "Success",
    "resources": null
}

• Diagnostic job creation error: Invalid InstanceId entered

{
    "error": {
        "errorCode": 901,
        "message": "API Call Fail"
    }
}

• Diagnostic job creation error: If the VulnItems parameter contains a keyword that is not in the List of reserved words for diagnostic items, or if the ALL reserved word is used in combination with another reserved word

{
    "error": {
        "errorCode": 160433,
        "message": "Param Value Not Define - VulnItems"
    }
}

• Diagnostic job creation error: Invalid parameter type entered

{
    "error": {
        "errorCode": 160433,
        "message": "Param Value Not Define - VulnItems"
    }
}

• Diagnostic job creation error: When requesting diagnostics for a server that is not your own (requires permission checks on the server for the account using API)

{
    "error": {
        "errorCode": 160451,
        "message": "Assets_Check_Fail"
    }
}

Sample code

Create new diagnostic

The following is a sample code that generates a signature with the make_signature function to create a request head, and then creates a new diagnostic job based on the request parameters entered, outputting the result if the response code is 200.

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

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 = 'PUT'
uri = '/api/v1/job'
payload = {
"StartUrl": "https://www.ncloud.com",
"ExcludeUrl": [
    "https://www.ncloud.com/event",
    "https://www.ncloud.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": "OPEN API TEST"
}

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)
    'Content-Type': 'application/json'
}

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)

Create re-diagnostic

To create a re-diagnostic job, you need to extract the value of the instanceNo of the diagnostic that can be re-diagnosed, and use it to call the Create re-diagnostic API.

• In the response of a call to the getJobs or searchJobs API, check the instanceNo of the entry in the resources > record_data property labeled "rescan_button": "possible".
• See Search diagnostic that can be re-diagnosed (using jq utility) for how to extract the value of instanceNo of re-diagnosable diagnostics using the jq utility. If there is no instanceNo, it means that there is no possible diagnosis task that can be re-diagnosed.

The following is a sample code that generates a signature with the make_signature function to generate a request head, and then creates a re- diagnostic job based on the request parameters entered, outputting the result if the response code is 200.

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

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 = 'PUT'
uri = '/api/v1/job'
payload = {
 "StartUrl": "https://www.ncloud.com",
    "ExcludeUrl": [
        "https://www.ncloud.com/event",
        "https://www.ncloud.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": "OPEN API TEST",
    "MasterInstanceNo": "12311231"
}

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)