createJob

Classic/VPC 환경에서 이용 가능합니다.

신규 진단 작업을 등록하거나 진단 완료한 작업을 재진단 작업으로 생성합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 헤더

Web Security Checker에서 공통으로 사용하는 헤더에 대한 자세한 내용은 Web Security Checker 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

예약어 목록

예약어 목록은 다음과 같습니다.

UserAgent 예약어 목록

Web Securtiy Checker는 사용자의 웹 사이트가 최적으로 지원하는 브라우저를 선택할 수 있도록 진단 옵션을 제공합니다.
다음 UserAgent 예약어에 대한 설명을 참고해, 진단 생성 시 필요한 UserAgent 값을 지정해 주십시오.

진단 항목 예약어 목록

진단 생성 API는 진단 항목을 명시하여 원하는 진단을 선택적으로 할 수 있는 기능을 제공합니다.

다음 진단 항목 예약어에 대한 설명을 참고해, 진단 생성 시 필요한 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"
}'

요청 예시(재진단)

요청 예시는 다음과 같습니다.

재진단 가능한 진단 검색(수동)

다음 예와 같이 getJobs (Web Security Checker) API를 호출한 응답에서 resources > record_data 속성의 항목 중 "rescan_button": "possible"로 표기된 항목의 instanceNo를 확인해 주십시오.

• rescan_button의 값이 null 혹은 expired인 경우는 재진단할 수 없습니다.

# 요청 예시
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}'

# 응답 예시
{
    "returnCode": "0",
    "returnDesc": "Request Success",
    "returnMessage": "성공",
    "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 테스트 (#1)",
                "result_button": "report",
                "result_desc": null,
                "rescan_button": "possible",
                "slave_data": null
            },
        ]
    }
}

재진단 가능한 진단 검색(jq 유틸 사용)

다음 예와 같이 getJobs (Web Security Checker) API와 jq 유틸을 이용해 재진단 가능한 instanceNo 목록을 확인할 수 있습니다.

• 만약, instanceNo가 없다면 재진단 가능한 진단 작업이 없음을 의미합니다.

# 요청 예시
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'

# 응답 예시
%"12311231"

재진단 작업 생성

• masterInstanceNo 입력 값은 반드시 문자열 타입으로 입력해 주십시오.
  • <예시> "MasterInstanceNo": "12311231"
• VulnItems 입력 값은 반드시 리스트 타입으로 입력해 주십시오.
  • <예시> "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"
}'

응답

응답 형식을 설명합니다.

응답 상태 코드

Web Security Checker API에서 공통으로 사용하는 오류 코드에 대한 자세한 내용은 Web Security Checker 공통 오류 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

• 진단 작업 생성 완료

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

• 진단 작업 생성 오류: 잘못된 InstanceId를 입력한 경우

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

• 진단 작업 생성 오류: VulnItems 파라미터에 진단 항목 예약어 목록에 없는 키워드가 존재하거나 ALL 예약어를 다른 예약어와 함께 사용할 경우

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

• 진단 작업 생성 오류: 파라미터를 잘못된 타입으로 입력한 경우

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

• 진단 작업 생성 오류: 고객 본인의 자산이 아닌 서버에 대해 진단을 요청할 경우(API를 이용하는 계정의 서버에 대한 권한 확인 필요)

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

샘플 코드

신규 진단 생성

make_signature 함수로 시그니처를 생성하여 요청 헤드를 생성한 후 입력한 요청 파라미터에 따라 신규 진단 작업을 생성하여 응답 코드가 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)

재진단 생성

재진단 작업을 생성하려면 재진단 생성이 가능한 진단의 instanceNo의 값을 추출하고, 이 값을 이용하여 재진단 생성 API를 호출해야 합니다.

• getJobs 또는 searchJobs API를 호출한 응답에서 resources > record_data 속성의 항목 중 "rescan_button": "possible"로 표기된 항목의 instanceNo를 확인해 주십시오.
• jq 유틸 사용하여 재진단 가능한 진단의 instanceNo의 값을 추출하는 방법은 재진단 가능한 진단 검색(jq 유틸 사용)을 참조해 주십시오. 만약, instanceNo가 없다면 재진단 가능한 진단 작업이 없음을 의미합니다.

make_signature 함수로 시그니처를 생성하여 요청 헤드를 생성한 후 입력한 요청 파라미터에 따라 재진단 작업을 생성하여 응답 코드가 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)