createJob

Available in Classic and VPC

Caution

Please note the following when using the createJob API.

You will have civil and criminal responsibilities for obstruction of business, violation of the Act on Promotion of Information and Communications Network Utilization and Information Protection, Etc. that may arise when running diagnostic tasks for web servers other than the customer's own. Using the API is considered to have been agreed upon by the customer.
Fees are charged when calling the createJob API. Make sure to check the pricing policy in the Web Security Checker introduction page before calling.

Note

Please note the following when using the createJob API.

createJob API only supports diagnostics for servers created on NAVER Cloud Platform.
- For external servers not created on NAVER Cloud Platform, diagnose through Web Security Checker on the NAVER Cloud Platform console.
createJob API does not provide a reservation feature, so it starts diagnostics immediately after calling the API.
- For the reservation feature, use it through Web Security Checker on the NAVER Cloud Platform console.
- If you need the reservation feature, call the createJob API at the reservation time in your API implementation.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
PUT	/job

Request headers

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

Request path parameters

The following describes the parameters.

Field	Type	Required	Description
`StartUrl`	String	Required	Diagnostic target URL Example: `"https://www.ncloud.com"`
`ExcludeUrl`	List	Optional	List of URLs to exclude from diagnostics Example: `[ "https://www.ncloud.com/events", "https://www.ncloud.com/product/security/webSecurityChecker"]`
`Headers`	Object	Optional	HTTP header information for authentication Example: `{ "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs..."`
`VulnItems`	List	Required	List of diagnostic items Example: `[ "ALL" ]`, `["XSS", "SSI Injection", ...]` See List of reserved words for diagnostic items
`UserAgent`	String	Required	Select the browser (User-Agent) information to use for the diagnostic job `"Android"` \| `"iPhone"` \| `"PC Chrome"` \| `"PC IE"` See List of UserAgent reserved words
`Speed`	String	Required	Adjust the speed of the diagnostic job `"1"` \| `"2"` \| `"3"` `"1"`: normal `"2"`: a bit faster `"3"`: fast
`Memo`	String	Optional	Notes for the diagnostic job Example: `"H1 security audit"`
`MasterInstanceNo`	String	Optional	Instance number (InstanceNo) of the completed diagnostic for which the re-diagnostic task will be created Check the instance number for re-diagnostics through getJobs Example: `"1234111231"`

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.

Reserved words	Description
`PC Chrome`	Chrome browser in PC environments
`PC IE`	Internet Explorer browser in PC environments
`iPhone`	iPhone browser in mobile environments
`Android`	Android browser in mobile environments

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.

Note

You can also check Web Security Checker introduction page > Diagnostic items for more information on 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.

Reserved words	Description
`ALL`	Diagnose with all diagnostic items supported by Web Security Checker (recommended option).
`LFI`	Vulnerability that allows a user to include a malicious file located inside a web server and execute that file
`SQL Injection`	Vulnerability that allows an attacker to inject arbitrary statements into the SQL statement used in a web application to leak or tamper with data in the internal database
`XSS`	Vulnerability where an attacker is able to insert malicious scripts into the web page
`RFI`	Vulnerability where a malicious file located on the attacker server in a remote area is included to execute this file
`SSRF`	Vulnerability that causes the internal server to perform unintended actions by intervening in the requests of other internal servers that are not accessible from outside
`File Upload`	Vulnerability that causes malicious script files to be executed with web server user's rights if the files are uploaded to a web server and accessed
`File Download`	Vulnerability that causes files on the server to be inadvertently downloaded to the client
`XXE`	Vulnerability that exploits the External Entity feature to dynamically include resources from external URIs in an XML document, resulting in unintended behavior
`Command Injection`	Vulnerability through which an attacker can directly deliver and execute commands to the server
`Insufficient Authorization`	Item that checks for accessibility on certain web applications that should not be generally exposed to users
`Specific Vulnerability`	Item that checks the most influential vulnerabilities regarding certain applications
`File Management`	All files that are unnecessary for operating the web server must be deleted or managed on a different system.
`Directory Listing`	Vulnerability that can expose a list of files in a directory
`Source Code Disclosure`	Vulnerability where the source code is exposed because the web server fails to properly process the script file
`Information Disclosure`	Vulnerability that exposes information on the web service that the attacker can exploit, such as server or error information
`URL Redirection`	Vulnerability that allows the users to direct to an unintended page
`Insecure SSL/TLS`	Item to check for possible vulnerabilities caused by using unsafe SSL/TLS versions
`Mixed Content`	Vulnerability where critical content that needs to be protected is delivered using HTTP
`HTTP Request Smuggling`	Vulnerability where attackers send manipulated HTTP packets to a web server to let random remote users manipulate HTTP packets sent to the web server
`Personal Information Exposure`	Vulnerability in a web service that exposes personal information, such as resident registration numbers or credit card numbers, in plain text
`SSI Injection`	Vulnerability in the Server-Side Includes (SSI) setting that could allow malicious dynamic HTML code to be executed

Request example (new)

The request example is as follows:

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 request example is as follows:

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".

# 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
            },
        ]
    }
}

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

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.

# 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"

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

Create re-diagnostic job

The following is an example of creating a re-diagnosis job.

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"
}'

The masterInstanceNo input value must be entered as a string type.
- e.g., "MasterInstanceNo": "12311231"
The VulnItems input value must be entered as a list type.
- e.g., "VulnItems": ["ALL"]

Response

This section 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 response example is as follows:

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

This section describes 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)

Note

The sample code is written in Python 3. See Call API in the API Gateway user guide for sample code written in other languages, such as Java and Node.js.