createJob

개요

• createJob API는 "Web Security Checker"에서 제공하는 기능으로 사용자가 진단을 등록하는 API입니다.

지원 범위 및 주의 사항

• createJob API는 네이버 클라우드 플랫폼 콘솔에서 Web Security Checker 이용 신청 을 한 뒤에 사용할 수 있습니다.
• createJob API 호출 시 과금이 발생합니다. 반드시 요금 정책을 Web Security Checker 소개 페이지에서 확인해 주세요.
• createJob API는 네이버 클라우드 플랫폼에서 생성한 서버에 대한 진단만 지원합니다.
  • 네이버 클라우드 플랫폼에서 생성하지 않은 외부 서버는 네이버 클라우드 플랫폼 콘솔(Web Security Checker) 을 통해 이용해 주세요.
• createJob API는 예약 기능을 제공하지 않으므로 API 호출 즉시 진단을 시작합니다.
  • 예약 기능은 네이버 클라우드 플랫폼 콘솔(Web Security Checker) 을 통해 이용해 주세요.
  • 필요하신 경우, API를 구현하는 과정에서 예약 시간에 createJob API를 호출해 주세요.

요청

Path Variables

요청 헤더

IAM 인증을 위한 요청 헤더입니다.

예약어 설명

UserAgent 예약어 목록

Web Securtiy Checker는 사용자의 웹 사이트가 최적으로 지원하는 브라우저를 선택할 수 있도록 진단 옵션을 제공합니다.

API 사용자는 아래 테이블의 예약어에 대한 설명을 참고하여 예약어를 선택한 뒤 API를 호출합니다.

진단 항목 예약어 목록

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

진단 항목에 대한 자세한 내용은 Web Security Checker 소개 페이지 > 진단 항목 에서도 확인 가능합니다.

• 모든 점검 항목으로 진단할 경우 ALL 키워드를 사용해 주세요.
• 일부 점검 항목만으로 진단할 경우 아래의 테이블에서 원하는 키워드를 선택해 주세요.

예시

• 예시를 참고하여 API를 사용해 주세요.

요청 예시 1 (진단 작업 생성)

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

요청 예시 2 (재진단 작업 생성)

요청 예시 2-1. 재진단 가능한 진단 검색 (수동)

1. getJobs (Web Security Checker) API를 이용해 진단 목록을 호출합니다.
2. 응답에서 resources > record_data 속성의 항목 중 "rescan_button": "possible"로 표기된 항목을 찾습니다.
3. 2번 단계에서 찾은 항목의 instanceNo를 복사합니다.

• 비고: rescan_button의 값이 null 혹은 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": "성공",
    "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
            },
        ]
    }
}

요청 예시 2-1-1. 재진단 가능한 진단 검색 (유틸 사용)

• getJobs (Web Security Checker) API와 jq 유틸을 이용해 재진단 가능한 instanceNo 목록을 확인합니다.
  • 이 예시에서 instanceNo는 "12311231"입니다.
  • 만약, instanceNo 가 없다면 재진단 가능한 진단 작업이 없음을 의미합니다.

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"

요청 예시 2-2. 재진단 작업 호출

• masterInstanceNo 파라미터에 앞서 얻은 "12311231" 을 대입합니다.
  • 반드시, 문자열 타입으로 번호를 입력해 주세요.

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": "성공",
    "resources": null
}

응답 예시 1 (진단 작업 생성 완료)

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

응답 예시 2 (예약어 입력 오류 케이스)

사용자 요청의 VulnItems 파라미터에 진단 항목 예약어 목록에 없는 키워드가 존재할 경우, 아래의 에러가 발생합니다.

또한, ALL 예약어를 XSS 등의 예약어와 함께 사용할 경우, 아래의 에러가 발생합니다.

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

응답 예시 2-1 (예약어 입력 오류)

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

응답 예시 2-2 (파라미터 타입 오류)

• VulnItems 파라미터는 배열(list) 타입만을 허용합니다.
• 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"
    }
}

응답 예시 3 (서버 소유 여부 체크)

고객 본인의 자산이 아닌 서버에 대해 진단을 요청할 경우, 아래와 같은 에러가 발생합니다.

API를 이용하는 계정의 서버에 대한 권한을 확인해 주세요.

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

오퍼레이션

• getJobs (Web Security Checker)
• stopJob (Web Security Checker)
• getReport (Web Security Checker)
• cancelJob (Web Security Checker)
• searchJobs (Web Security Checker)