createJob
    • PDF

    createJob

    • PDF

    Article Summary

    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

    Request

    MethodRequest URI
    PUThttps://wsc.apigw.ntruss.com/api/v1/job

    Path Variables

    ParameterRequirement statusTypeDescription
    StartUrlYesstringDiagnosis target URL
    (e.g., "https://www.ncloud.com")
    ExcludeUrlYeslistList of URLs to exclude from diagnosis
    (e.g., [ "https://www.ncloud.com/events," "https://www.ncloud.com/product/security/webSecurityChecker"])
    HeadersNoobjectHTTP header information for authentication
    (ex. { "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs...")
    VulnItemsYeslistList of diagnosis categories
    (e.g., [ "ALL" ], ["XSS", "SSI Injection", ...])
    UserAgentYesstringSelect the browser (User-Agent) information to use for a diagnosis task
    (Choose one of the reserved words "Android", "iPhone", "PC Chrome", and "PC IE")
    SpeedYesstringAdjust the speed of the diagnosis task
    (Choose one of the options "1" - Normal, "2" - A bit fast, and "3" - Fast)
    MemoNostringNote
    (e.g., "Security diagnosis in the first half")
    MasterInstanceNoNostringThe 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.

    HeaderDescription
    x-ncp-apigw-timestampThis 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-keyAccessKey issued by IAM on NAVER Cloud Platform.
    x-ncp-apigw-signature-v2The 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 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

    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 wordsDescription
    ALLDiagnoses with all diagnosis categories supported by Web Security Checker (Recommended option).
    LFIA vulnerability where a malicious file located on the inner web server is included to execute this file.
    SQL InjectionA 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.
    XSSA vulnerability where an attacker is able to insert malicious scripts into the webpage.
    RFIA vulnerability where a malicious file located on the attacker server in a remote area is included to execute this file.
    SSRFA 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 UploadA 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 DownloadA vulnerability that causes files on the server to be inadvertently downloaded to the client.
    XXEA vulnerability that exploits the External Entity feature to dynamically include resources from external URIs in an XML document, resulting in unintended behavior.
    Command InjectionA vulnerability through which an attacker can directly deliver and execute commands to the server.
    Insufficient AuthorizationAn item that checks for accessibility on certain web applications that should not be generally exposed to users.
    Specific VulnerabilityAn item 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 ListingA vulnerability that can expose a list of files in a directory.
    Source Code DisclosureA vulnerability where the source code is exposed because the web server fails to properly process the script file.
    Information DisclosureA vulnerability that exposes information on the web service that the attacker can exploit, such as server or error information.
    URL RedirectionA vulnerability that allows the users to move to an unintended page.
    Insecure SSL/TLSAn item to check for possible vulnerabilities caused by using unsafe SSL/TLS versions.
    Mixed ContentA vulnerability where critical content that needs to be protected is delivered using HTTP.
    HTTP Request SmugglingA 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 ExposureThis vulnerability has the risk of exposing personal information, such as resident registration number and credit card number, as plaintext in a web service.
    SSI InjectionA 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)

    1. Call the list of diagnoses with getJobs (Web Security Checker) API.
    2. Find categories marked with "rescan_button": "possible" among the categories with the resources > record_data property in the response.
    3. 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
    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.