createJob
    • PDF

    createJob

    • PDF

    기사 요약

    주의

    고객 소유의 웹 서버가 아닌 대상을 진단할 경우 발생할 수 있는 각종 법적 책임(업무방해, 정보통신망법 위반 등 관련 민형사상 책임)은 본인에게 있음을 알려드립니다. API를 사용하는 것은 고객이 이를 동의한 것으로 간주합니다.

    개요

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

    지원 범위 및 주의 사항

    요청

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

    Path Variables

    파라미터필수 여부타입설명
    StartUrlYesstring진단 대상 URL
    (ex. "https://www.fin-ncloud.com")
    ExcludeUrlYeslist진단 제외 URL 목록
    (ex. [ "https://www.fin-ncloud.com/events", "https://www.fin-ncloud.com/product/security/webSecurityChecker"])
    HeadersNoobject인증을 위한 HTTP Header 정보
    (ex. { "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs...")
    VulnItemsYeslist진단 항목 목록
    (ex. [ "ALL" ], ["XSS", "SSI Injection", ...])
    UserAgentYesstring진단 작업에 이용할 브라우저(User-Agent) 정보를 선택
    ("Android", "iPhone", "PC Chrome", "PC IE" 예약어 중 택일)
    SpeedYesstring진단 작업의 속도를 조절
    ("1"-보통, "2"-조금빠르게, "3"-빠르게 중 택일)
    MemoNostring메모
    (ex. "상반기 보안진단" )
    MasterInstanceNoNostring재진단 작업을 생성할 완료된 진단의 인스턴스 번호(InstanceNo)
    재진단을 위한 인스턴스 번호는 getJobs (Web Security Checker) API를 통해 확인 가능
    (ex. "1234111231")

    요청 헤더

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

    헤더명설명
    x-ncp-apigw-timestamp1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것
    API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
    x-ncp-iam-access-key네이버 클라우드 플랫폼에서 IAM 에서 발급받은 AccessKey
    x-ncp-apigw-signature-v2요청 경로 및 헤더를 AccessKey와 맵핑되는 SecretKey로 암호화한 서명으로
    HMAC 암호화 알고리즘은 HmacSHA256 을 사용함

    예약어 설명

    UserAgent 예약어 목록

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

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

    예약어설명
    PC ChromePC 환경의 Chrome 브라우저
    PC IEPC 환경의 Internet Explorer 브라우저
    iPhone모바일 환경의 iPhone 브라우저
    Android모바일 환경의 Android 브라우저

    진단 항목 예약어 목록

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

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

    • 모든 점검 항목으로 진단할 경우 ALL 키워드를 사용해 주세요.
    • 일부 점검 항목만으로 진단할 경우 아래의 테이블에서 원하는 키워드를 선택해 주세요.
    예약어설명
    ALLWeb Security Checker가 지원하는 모든 진단 항목으로 진단 수행 (권장 옵션)
    LFI웹 서버 내부에 위치한 악의적인 파일을 Include 하여 해당 파일을 실행하는 취약점
    SQL Injection웹 애플리케이션에서 사용되는 SQL 구문에 공격자가 임의의 구문을 주입(Injection) 하여 내부 데이터베이스의 데이터를 유출, 변조할 수 있는 취약점
    XSS공격자가 웹 페이지에 악성 스크립트를 삽입할 수 있는 취약점
    RFI원격지의 공격자 서버에 위치한 악의적인 파일을 Include 하여 해당 파일을 실행하는 취약점
    SSRF외부에서는 접근되지 않는 내부의 다른 서버로 요청하도록 개입하여 내부 서버가 의도하지 않은 행위를 하도록 하는 취약점
    File Upload악의적인 스크립트 파일을 웹 서버에 업로드하여 접근할 경우 웹 서버 사용자 권한으로 실행되는 취약점
    File Download서버에 존재하는 파일이 의도하지 않게 클라이언트로 다운로드 되는 취약점
    XXEXML 문서에서 동적으로 외부 URI의 리소스를 포함시킬 수 있는 External Entity 기능을 악용하여 의도하지 않은 동작을 하도록 하는 취약점
    Command Injection공격자가 서버에 직접적으로 명령을 전달하고, 실행할 수 있는 취약점
    Insufficient Authorization일반적으로 사용자에게 노출되지 않아야 하는 특정 웹 애플리케이션에 대한 접근 가능 여부를 점검하는 항목
    Specific Vulnerability특정 애플리케이션과 관련된 파급력이 큰 취약점들에 대해 점검하는 항목
    File Management웹 서버를 운영하는데 불필요한 파일은 모두 삭제하거나 다른 시스템에서 관리 필요
    Directory Listing디렉터리 내 파일 리스트가 노출될 수 있는 취약점
    Source Code Disclosure웹 서버가 스크립트 파일을 정상적으로 처리하지 못해 소스 코드가 그대로 노출되는 취약점
    Information Disclosure웹 서비스에서 서버 정보, 오류 정보 등 공격에 활용될 수 있는 정보가 노출되는 취약점
    URL Redirection사용자가 의도하지 않은 페이지로 이동시킬 수 있는 취약점
    Insecure SSL/TLS안전하지 않은 SSL/TLS 버전 사용으로 인해 발생 가능한 취약점을 점검하는 항목
    Mixed Content보호되어야 하는 중요한 콘텐츠가 HTTP를 사용해 전송되는 취약점
    HTTP Request Smuggling공격자가 조작된 HTTP 패킷을 웹 서버로 전송하여 원격에 있는 임의의 사용자가 웹 서버로 전송하는 HTTP 패킷을 조작할 수 있는 취약점
    Personal Information Exposure웹 서비스에서 주민등록번호, 신용카드번호 등 개인정보가 평문으로 노출되는 취약점
    SSI InjectionSSI(Server-Side Includes) 설정에 의해 악의적인 동적 HTML 코드가 실행될수 있는 취약점

    예시

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

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

    curl -X PUT "https://wsc.apigw.fin-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.fin-ncloud.com",
        "ExcludeUrl": [
            "https://www.fin-ncloud.com/event",
            "https://www.fin-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.fin-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://fin-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.fin-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.fin-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.fin-ncloud.com",
        "ExcludeUrl": [
            "https://www.fin-ncloud.com/event",
            "https://www.fin-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.fin-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.fin-ncloud.com",
        "ExcludeUrl": [
            "https://www.fin-ncloud.com/event",
            "https://www.fin-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.fin-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.fin-ncloud.com",
        "ExcludeUrl": [
            "https://www.fin-ncloud.com/event",
            "https://www.fin-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"
        }
    }
    

    이 문서가 도움이 되었습니까?

    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.