createJob

English

createJob

Article summary

Did you find this summary helpful?

Thank you for your feedback

Caution

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.

Summary

createJob API is a feature provided by "Web Security Checker," which is an API that allows the user to register a diagnosis.

Range of support and precautions

You can use createJob API after the Request subscription for Web Security Checker in NAVER Cloud Platform Console.
You will be charged when calling createJob API. It is important that you read the pricing policy in the Web Security Checker service page.
createJob API only supports a diagnosis for servers created in NAVER Cloud Platform.
- For external servers not created in NAVER Cloud Platform, please diagnose through NAVER Cloud Platform console (Web Security Checker).
createJob API does not provide a schedule feature, so it starts a diagnosis immediately after calling API.
- For the schedule feature, please use it through NAVER Cloud Platform Console (Web Security Checker).
- Please call createJob API at a scheduled time while implementing the API if required.

Request

Method	Request URI
PUT	`https://wsc.apigw.ntruss.com/api/v1/job`

Path Variables

Parameter	Requirement status	Type	Description
StartUrl	Yes	string	Diagnosis target URL (e.g., `"https://www.ncloud.com"`)
ExcludeUrl	Yes	list	List of URLs to exclude from diagnosis (e.g., `[ "https://www.ncloud.com/events," "https://www.ncloud.com/product/security/webSecurityChecker"]`)
Headers	No	object	HTTP header information for authentication (ex. `{ "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs..."`)
VulnItems	Yes	list	List of diagnosis categories (e.g., `[ "ALL" ]`, `["XSS", "SSI Injection", ...]`)
UserAgent	Yes	string	Select the browser (User-Agent) information to use for a diagnosis task (Choose one of the reserved words `"Android"`, `"iPhone"`, `"PC Chrome"`, and `"PC IE"`)
Speed	Yes	string	Adjust the speed of the diagnosis task (Choose one of the options `"1"` - Normal, `"2"` - A bit fast, and `"3"` - Fast)
Memo	No	string	Note (e.g., `"Security diagnosis in the first half"`)
MasterInstanceNo	No	string	The instance number (InstanceNo) of the completed diagnosis to create a re-diagnosis task You can check the instance number for re-diagnosis through getJobs (Web Security Checker) API. (e.g., `"1234111231"`)

Request header

The following table lists the request headers for IAM authentication.

Header	Description
x-ncp-apigw-timestamp	This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. If the time difference compared to the API Gateway server is more than 5 minutes, then the request is considered invalid.
x-ncp-iam-access-key	AccessKey issued by IAM on NAVER Cloud Platform.
x-ncp-apigw-signature-v2	The signature used to encrypt the request directory and the header with the SecretKey that maps with the AccessKey. The HMAC encryption algorithm is HmacSHA256.

Reserved words description

List of UserAgent reserved words

Web Security Checker provides diagnostic options that allow users to choose the browser that their websites optimally support.

API users refer to the description on reserved words in the table below, select one of them, and call the API.

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

Diagnosis creation API provides features for selective diagnosis by specifying diagnosis categories.

You can check the [Web Security Checker service page > Diagnosis categories]{target="_blank"} for more information about the diagnosis categories.

Please use the ALL keyword if you diagnose with all diagnosis categories.
Please select the desired keywords in the table below if you want to diagnose with only some of the diagnosis categories.

Reserved words	Description
`ALL`	Diagnoses with all diagnosis categories supported by Web Security Checker (Recommended option).
`LFI`	A vulnerability where a malicious file located on the inner web server is included to execute this file.
`SQL Injection`	A 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`	A vulnerability where an attacker is able to insert malicious scripts into the webpage.
`RFI`	A vulnerability where a malicious file located on the attacker server in a remote area is included to execute this file.
`SSRF`	A 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`	A 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`	A vulnerability that causes files on the server to be inadvertently downloaded to the client.
`XXE`	A vulnerability that exploits the External Entity feature to dynamically include resources from external URIs in an XML document, resulting in unintended behavior.
`Command Injection`	A vulnerability through which an attacker can directly deliver and execute commands to the server.
`Insufficient Authorization`	An item that checks for accessibility on certain web applications that should not be generally exposed to users.
`Specific Vulnerability`	An 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`	A vulnerability that can expose a list of files in a directory.
`Source Code Disclosure`	A vulnerability where the source code is exposed because the web server fails to properly process the script file.
`Information Disclosure`	A vulnerability that exposes information on the web service that the attacker can exploit, such as server or error information.
`URL Redirection`	A vulnerability that allows the users to move to an unintended page.
`Insecure SSL/TLS`	An item to check for possible vulnerabilities caused by using unsafe SSL/TLS versions.
`Mixed Content`	A vulnerability where critical content that needs to be protected is delivered using HTTP.
`HTTP Request Smuggling`	A 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`	This vulnerability has the risk of exposing personal information, such as resident registration number and credit card number, as plaintext in a web service.
`SSI Injection`	A vulnerability where malicious dynamic HTML code can be executed through Server-Side Includes (SSI) settings.

Example

Please use API by referring to the example.

Request example 1 (Create a diagnosis task)

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://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 2 (Create a re-diagnosis task)

Request example 2-1. Search diagnoses that can be re-diagnosed (Manual)

Call the list of diagnoses with getJobs (Web Security Checker) API.
Find categories marked with "rescan_button": "possible" among the categories with the resources > record_data property in the response.
Copy instanceNo of the categories found in Step 2.

Note: Re-diagnosis is impossible if the rescan_button value is either null or expired.

curl -X GET "https://wsc.apigw.ntruss.com/api/v1/jobs?limit=10&page=1"
   -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}"
{
    "returnCode": "0",
    "returnDesc": "Request Success",
    "returnMessage": "Success",
    "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
            },
        ]
    }
}

Request example 2-1-1. Search diagnoses that can be re-diagnosed (Using a utility)

Use getJobs (Web Security Checker)
API and the jq utility to check the list of instanceNos that can be re-diagnosed.
- In this example, the instanceNo is "12311231."
- If there is no instanceNo, it means that there is no possible diagnosis task that can be re-diagnosed.

curl -X GET "https://wsc.apigw.ntruss.com/api/v1/jobs?limit=10&page=1"
   -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}" | jq '.resources.record_data[] | select( .rescan_button == "possible" ) | .instanceNo'
%"12311231"

Request Example 2-2. Call re-diagnosis tasks

Enter "12311231" that you obtained before in the masterInstanceNo parameter.
- It is important that you enter the number as a string type.

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://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"
}'
%{
    "returnCode": "0",
    "returnDesc": "Request Success",
    "returnMessage": "Success",
    "resources": null
}

Response example 1 (Complete creating a diagnosis task)

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

Response Example 2 (Case of error in entering reserved words)

If a keyword that is not in the list of reserved words for diagnosis categories exists in the VulnItems parameter of the user request, then the following error occurs.

Also, if the reserved word ALL is used with reserved words such as XSS, then the following error occurs.

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

Response Example 2-1 (Error in entering reserved words)

Other reserved words are not available when the reserved word ALL is used.

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://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",
        "XSS"
    ],
    "UserAgent": "Android",
    "Speed": "1",
    "Memo": "OPEN API TEST"
}'
%{
    "error": {
        "errorCode": 160433,
        "message": "Param Value Not Define - VulnItems"
    }
}

Response Example 2-2 (Error in parameter types)

The VulnItems parameter only allows the list type.
An error occurs if it is entered as VulnItems: "ALL".

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://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"
}'
%{
    "error": {
        "errorCode": 160431,
        "message": "VulnItems should be list"
    }
}

Response Example 3 (Check for server ownership)

If customers request a diagnosis of a server that is not their own asset, then the following error occurs.

Please check the permissions for the server of the account using API.

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

Was this article helpful?

What's Next

KMS Overview

Table of contents

Summary
Range of support and precautions
Request
Reserved words description
Example