createJob
- 인쇄
- PDF
createJob
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
주의
고객 소유의 웹 서버가 아닌 대상을 진단할 경우 발생할 수 있는 각종 법적 책임(업무방해, 정보통신망법 위반 등 관련 민형사상 책임)은 본인에게 있음을 알려드립니다. API를 사용하는 것은 고객이 이를 동의한 것으로 간주합니다.
개요
- 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를 호출해 주세요.
요청
Method | Request URI |
---|---|
PUT | https://wsc.apigw.gov-ntruss.com/api/v1/job |
Path Variables
파라미터 | 필수 여부 | 타입 | 설명 |
---|---|---|---|
StartUrl | Yes | string | 진단 대상 URL (ex. "https://www.ncloud.com" ) |
ExcludeUrl | No | list | 진단 제외 URL 목록 (ex. [ "https://www.ncloud.com/events", "https://www.ncloud.com/product/security/webSecurityChecker"] ) |
Headers | No | object | 인증을 위한 HTTP Header 정보 (ex. { "Cookie": "JSESSIONID=AB123123123123ASAS", "Accept": "text/html.....", "Authorization": "Bearer ejs..." ) |
VulnItems | Yes | list | 진단 항목 목록 (ex. [ "ALL" ] , ["XSS", "SSI Injection", ...] ) |
UserAgent | Yes | string | 진단 작업에 이용할 브라우저(User-Agent) 정보를 선택 ( "Android" , "iPhone" , "PC Chrome" , "PC IE" 예약어 중 택일) |
Speed | Yes | string | 진단 작업의 속도를 조절 ( "1" -보통, "2" -조금빠르게, "3" -빠르게 중 택일) |
Memo | No | string | 메모 (ex. "상반기 보안진단" ) |
MasterInstanceNo | No | string | 재진단 작업을 생성할 완료된 진단의 인스턴스 번호(InstanceNo) 재진단을 위한 인스턴스 번호는 getJobs (Web Security Checker) API를 통해 확인 가능 (ex. "1234111231" ) |
요청 헤더
IAM 인증을 위한 요청 헤더입니다.
헤더명 | 설명 |
---|---|
x-ncp-apigw-timestamp | 1970년 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 Chrome | PC 환경의 Chrome 브라우저 |
PC IE | PC 환경의 Internet Explorer 브라우저 |
iPhone | 모바일 환경의 iPhone 브라우저 |
Android | 모바일 환경의 Android 브라우저 |
진단 항목 예약어 목록
진단 생성 API는 진단 항목을 명시하여 원하는 진단을 선택적으로 할 수 있도록 기능을 제공합니다.
진단 항목에 대한 자세한 내용은 Web Security Checker 소개 페이지 > 진단 항목 에서도 확인 가능합니다.
- 모든 점검 항목으로 진단할 경우
ALL
키워드를 사용해 주세요. - 일부 점검 항목만으로 진단할 경우 아래의 테이블에서 원하는 키워드를 선택해 주세요.
예약어 | 설명 |
---|---|
ALL | Web Security Checker 가 지원하는 모든 진단 항목으로 진단 수행 (권장 옵션) |
LFI | 웹 서버 내부에 위치한 악의적인 파일을 Include 하여 해당 파일을 실행하는 취약점 |
SQL Injection | 웹 애플리케이션에서 사용되는 SQL 구문에 공격자가 임의의 구문을 주입(Injection) 하여 내부 데이터베이스의 데이터를 유출, 변조할 수 있는 취약점 |
XSS | 공격자가 웹 페이지에 악성 스크립트를 삽입할 수 있는 취약점 |
RFI | 원격지의 공격자 서버에 위치한 악의적인 파일을 Include 하여 해당 파일을 실행하는 취약점 |
SSRF | 외부에서는 접근되지 않는 내부의 다른 서버로 요청하도록 개입하여 내부 서버가 의도하지 않은 행위를 하도록 하는 취약점 |
File Upload | 악의적인 스크립트 파일을 웹 서버에 업로드하여 접근할 경우 웹 서버 사용자 권한으로 실행이 되는 취약점 |
File Download | 서버에 존재하는 파일이 의도하지 않게 클라이언트로 다운로드 되는 취약점 |
XXE | XML 문서에서 동적으로 외부 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 Injection | SSI(Server-Side Includes) 설정에 의해 악의적인 동적 HTML 코드가 실행될수 있는 취약점 |
예시
- 예시를 참고하여 API를 사용해 주세요.
요청 예시 1 (진단 작업 생성)
curl -X PUT "https://wsc.apigw.gov-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. 재진단 가능한 진단 검색 (수동)
- getJobs (Web Security Checker) API를 이용해 진단 목록을 호출합니다.
- 응답에서
resources > record_data
속성의 항목 중"rescan_button": "possible"
로 표기된 항목을 찾습니다. - 2번 단계에서 찾은 항목의
instanceNo
를 복사합니다.
- 비고:
rescan_button
의 값이null
혹은expired
인 경우는 재진단이 불가한 케이스입니다.
curl -X GET "https://wsc.apigw.gov-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.gov-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.gov-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.gov-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.gov-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"
}
}
이 문서가 도움이 되었습니까?