MENU
      createJob

        createJob


        Article summary

        Available in Classic and VPC

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

        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.

        Note

        Range of support and precautions

        Request

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

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

        FieldTypeRequiredDescription
        StartUrlStringRequiredDiagnostic target URL
        • <E.g.> "https://www.ncloud.com"
        ExcludeUrlListRequiredList of URLs to exclude from diagnostics
        • <E.g.> [ "https://www.ncloud.com/events", "https://www.ncloud.com/product/security/webSecurityChecker"]
        HeadersObjectOptionalHTTP header information for authentication
        • <E.g.> { "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs..."
        VulnItemsListRequiredList of diagnostic items
        UserAgentStringRequiredSelect the browser (User-Agent) information to use for the diagnostic job
        SpeedStringRequiredAdjust the speed of the diagnostic job
        • "1" | "2" | "3"
          • "1": normal
          • "2": a bit faster
          • "3": fast
        MemoStringOptionalNotes for the diagnostic job
        • <E.g.> "H1 security audit"
        MasterInstanceNoStringOptionaInstance number (InstanceNo) of the completed diagnostic for which the re-diagnostic task will be created
        • Check the instance number for re-diagnostics through getJobs
        • <E.g.> "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 wordsDescription
        PC ChromeChrome browser in PC environments
        PC IEInternet Explorer browser in PC environments
        iPhoneiPhone browser in mobile environments
        AndroidAndroid 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 wordsDescription
        ALLDiagnose with all diagnostic items supported by Web Security Checker
        LFIVulnerability that allows a user to include a malicious file located inside a web server and execute that file
        SQL InjectionVulnerability 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
        XSSVulnerability where an attacker is able to insert malicious scripts into the web page
        RFIVulnerability where a malicious file located on the attacker server in a remote area is included to execute this file
        SSRFVulnerability 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 UploadVulnerability 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 DownloadVulnerability that causes files on the server to be inadvertently downloaded to the client
        XXEVulnerability that exploits the External Entity feature to dynamically include resources from external URIs in an XML document, resulting in unintended behavior
        Command InjectionVulnerability through which an attacker can directly deliver and execute commands to the server
        Insufficient AuthorizationItem that checks for accessibility on certain web applications that should not be generally exposed to users
        Specific VulnerabilityItem that checks the most influential vulnerabilities regarding certain applications
        File ManagementAll files that are unnecessary for operating the web server must be deleted or managed on a different system
        Directory ListingVulnerability that can expose a list of files in a directory
        Source Code DisclosureVulnerability where the source code is exposed because the web server fails to properly process the script file
        Information DisclosureVulnerability that exposes information on the web service that the attacker can exploit, such as server or error information
        URL RedirectionVulnerability that allows the users to direct to an unintended page
        Insecure SSL/TLSItem to check for possible vulnerabilities caused by using unsafe SSL/TLS versions
        Mixed ContentVulnerability where critical content that needs to be protected is delivered using HTTP
        HTTP Request SmugglingVulnerability 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 ExposureVulnerability in a web service that exposes personal information, such as resident registration numbers or credit card numbers, in plain text
        SSI InjectionVulnerability in the Server-Side Includes (SSI) setting that could allow malicious dynamic HTML code to be executed

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

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

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

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

        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
        }
        JSON
        • Diagnostic job creation error: Invalid InstanceId entered
        {
            "error": {
                "errorCode": 901,
                "message": "API Call Fail"
            }
        }
        JSON
        • 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"
            }
        }
        JSON
        • Diagnostic job creation error: Invalid parameter type entered
        {
            "error": {
                "errorCode": 160433,
                "message": "Param Value Not Define - VulnItems"
            }
        }
        JSON
        • 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"
            }
        }
        JSON

        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)
        Python

        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)
        Python
        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.


        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.