분석기 설정 사용자 정의
인증
인증은 헤더 또는 쿠키로 인증 토큰을 제공하여 처리됩니다. 인증 흐름을 수행하거나 토큰을 계산하는 스크립트를 제공할 수 있습니다.
HTTP 기본 인증
HTTP 기본 인증은 HTTP 프로토콜에 내장된 인증 방법으로, 전송 계층 보안(TLS)과 함께 사용됩니다.
비밀번호(예: TEST_API_PASSWORD
)를 CI/CD 변수를 생성하고, 이를 마스킹된 상태로 설정하는 것을 권장합니다. GitLab 프로젝트 페이지의 설정 > CI/CD 메뉴에서 변수 섹션에서 CI/CD 변수를 생성할 수 있습니다. 마스킹된 변수에 대한 제한 사항으로 인해 변수를 추가하기 전에 비밀번호를 Base64로 인코딩해야 합니다.
마지막으로, .gitlab-ci.yml
파일에 두 개의 CI/CD 변수를 추가합니다.
-
DAST_API_HTTP_USERNAME
: 인증을 위한 사용자 이름 -
DAST_API_HTTP_PASSWORD_BASE64
: 인증을 위해 Base64로 인코딩된 비밀번호
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_HAR: test-api-recording.har
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_HTTP_USERNAME: testuser
DAST_API_HTTP_PASSWORD_BASE64: $TEST_API_PASSWORD
원시 암호
암호를 Base64로 인코딩하고 싶지 않거나 GitLab 15.3 이전 버전을 사용하고 있다면, DAST_API_HTTP_PASSWORD_BASE64
대신 원시 암호 DAST_API_HTTP_PASSWORD
를 제공할 수 있습니다.
Bearer 토큰
Bearer 토큰은 OAuth2 및 JSON Web Tokens (JWT)을 포함한 여러 인증 메커니즘에서 사용됩니다. Bearer 토큰은 Authorization
HTTP 헤더를 사용하여 전송됩니다. API 보안 테스트에 Bearer 토큰을 사용하려면 다음 중 하나가 필요합니다.
- 만료되지 않는 토큰
- 테스트 기간 동안 유효한 토큰 생성 방법
- API 보안 테스트가 토큰을 생성하기 위해 호출할 Python 스크립트
토큰 만료되지 않음
Bearer 토큰이 만료되지 않으면 DAST_API_OVERRIDES_ENV
변수를 사용하여 제공합니다. 이 변수의 내용은 API 보안 테스트를 위한 대상 URL에 추가할 헤더 및 쿠키를 제공하는 JSON 스니펫입니다.
DAST_API_OVERRIDES_ENV
에 Bearer 토큰을 제공하려면 다음 단계를 따릅니다.
-
예를 들어
TEST_API_BEARERAUTH
와 같이 값을{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}
(해당 토큰으로 대체)으로 설정하는 CI/CD 변수를 생성합니다. GitLab 프로젝트 페이지의 설정 > CI/CD 메뉴에서 변수 섹션에서 CI/CD 변수를 생성할 수 있습니다.TEST_API_BEARERAUTH
의 형식 때문에 변수를 마스킹할 수 없습니다. 토큰 값을 마스킹하려면 두 번째 변수를 생성하고 해당 값을$MASKED_VARIABLE
로 설정한 다음TEST_API_BEARERAUTH
를 정의합니다. -
.gitlab-ci.yml
파일에서DAST_API_OVERRIDES_ENV
를 방금 생성한 변수로 설정합니다.stages: - dast include: - template: DAST-API.gitlab-ci.yml variables: DAST_API_PROFILE: Quick DAST_API_OPENAPI: test-api-specification.json DAST_API_TARGET_URL: http://test-deployment/ DAST_API_OVERRIDES_ENV: $TEST_API_BEARERAUTH
-
인증이 작동하는지 확인하려면 API 보안 테스트를 실행하고 작업 로그 및 테스트 API의 애플리케이션 로그를 검토합니다.
테스트 실행 시 생성된 토큰
Bearer 토큰이 생성되어 테스트 중에 만료되지 않으면 해당 토큰이 포함된 파일을 API 보안 테스트에 제공할 수 있습니다. 이 파일은 이전 단계 및 작업 또는 API 보안 테스트 작업의 일부에서 생성될 수 있습니다.
API 보안 테스트가 다음과 같은 구조의 JSON 파일을 받도록 기대합니다.
{
"headers" : {
"Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
}
}
.gitlab-ci.yml
파일에서 DAST_API_OVERRIDES_FILE
을 설정합니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_FILE: dast-api-overrides.json
인증이 작동하는지 확인하려면 API 보안 테스트를 실행하고 작업 로그 및 테스트 API의 애플리케이션 로그를 검토하세요.
토큰의 만료 기간이 짧음
Bearer 토큰이 생성되어 테스트가 완료되기 전에 만료되는 경우, API 보안 테스트 스캐너가 제공된 간격에 따라 실행되는 프로그램이나 스크립트를 제공할 수 있습니다. 제공된 스크립트는 Python 3 및 Bash가 설치된 Alpine Linux 컨테이너에서 실행됩니다. Python 스크립트가 추가 패키지가 필요한 경우 이를 실행 시간에 감지하고 해당 패키지를 설치해야 합니다.
스크립트는 다음과 같은 형식의 Bearer 토큰을 포함하는 JSON 파일을 생성하여야 합니다:
{
"headers" : {
"Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
}
}
올바른 작동을 위해 해당 작동에 대해 설정된 세 가지 CI/CD 변수를 제공해야 합니다:
-
DAST_API_OVERRIDES_FILE
: 제공된 명령으로 생성되는 JSON 파일 -
DAST_API_OVERRIDES_CMD
: JSON 파일을 생성하는 명령 -
DAST_API_OVERRIDES_INTERVAL
: 명령을 실행하는 간격(초) 설정
예시:
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_FILE: dast-api-overrides.json
DAST_API_OVERRIDES_CMD: renew_token.py
DAST_API_OVERRIDES_INTERVAL: 300
인증이 작동하는지 확인하려면 API 보안 테스트를 실행하고 작업 로그 및 테스트 API의 애플리케이션 로그를 검토하세요. 더 자세한 정보는 overrides section(overrides 섹션)을 참조하세요.
Overrides
API 보안 테스트는 요청의 특정 항목을 추가하거나 재정의할 수 있는 방법을 제공합니다. 예를 들어 다음과 같습니다:
- 헤더
- 쿠키
- 쿼리 문자열
- 폼 데이터
- JSON 노드
- XML 노드
이를 사용하여 의미론적 버전 헤더, 인증 등을 삽입할 수 있습니다. 인증 섹션에는 해당 목적을 위해 overrides를 사용하는 예시가 포함되어 있습니다.
Overrides는 각 재정의 유형이 JSON 객체로 표시된 JSON 문서를 사용합니다:
{
"headers": {
"header1": "value",
"header2": "value"
},
"cookies": {
"cookie1": "value",
"cookie2": "value"
},
"query": {
"query-string1": "value",
"query-string2": "value"
},
"body-form": {
"form-param1": "value",
"form-param2": "value"
},
"body-json": {
"json-path1": "value",
"json-path2": "value"
},
"body-xml" : {
"xpath1": "value",
"xpath2": "value"
}
}
단일 헤더 설정 예시:
{
"headers": {
"Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
}
}
헤더와 쿠키를 함께 설정하는 예시:
{
"headers": {
"Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
},
"cookies": {
"flags": "677"
}
}
body-form
재정의를 설정하는 예시:
{
"body-form": {
"username": "john.doe"
}
}
요청 본문이 form-data 콘텐츠만 포함하는 경우, 재정의 엔진은 body-form
을 사용합니다.
body-json
을 설정하는 예시:
{
"body-json": {
"$.credentials.access-token": "iddqd!42.$"
}
}
객체 body-json
의 각 JSON 속성 이름은 JSON Path식으로 설정됩니다. JSON Path 식 $ .credentials.access-token
은 iddqd!42.$
값으로 재정의될 노드를 식별합니다. 재정의 엔진은 요청 본문이 JSON 콘텐츠만 포함하는 경우 body-json
을 사용합니다.
예를 들어, 본문이 다음과 같은 JSON으로 설정된 경우:
{
"credentials" : {
"username" :"john.doe",
"access-token" : "non-valid-password"
}
}
다음과 같이 변경됩니다:
{
"credentials" : {
"username" :"john.doe",
"access-token" : "iddqd!42.$"
}
}
body-xml
재정의를 설정하는 예시입니다. 첫 번째 항목은 XML 속성을, 두 번째 항목은 XML 요소를 재정의합니다:
{
"body-xml" : {
"/credentials/@isEnabled": "true",
"/credentials/access-token/text()" : "iddqd!42.$"
}
}
객체 body-xml
의 각 JSON 속성 이름은 XPath v2식으로 설정됩니다. XPath 식 /credentials/@isEnabled
은 값 true
로 재정의할 속성 노드를 식별합니다. XPath 식 /credentials/access-token/text()
은 값 iddqd!42.$
로 재정의할 요소 노드를 식별합니다. 재정의 엔진은 요청 본문이 XML 콘텐츠만 포함하는 경우 body-xml
을 사용합니다.
예를 들어, 본문이 다음과 같은 XML로 설정된 경우:
<credentials isEnabled="false">
<username>john.doe</username>
<access-token>non-valid-password</access-token>
</credentials>
다음과 같이 변경됩니다:
<credentials isEnabled="true">
<username>john.doe</username>
<access-token>iddqd!42.$</access-token>
</credentials>
이 JSON 문서를 파일 또는 환경 변수로 제공할 수 있습니다. 또한 JSON 문서를 생성하는 명령을 제공할 수 있습니다. 해당 명령은 만료되는 값을 지원하기 위해 일정 간격으로 실행할 수 있습니다.
파일 사용
오버라이드 JSON을 파일로 제공하려면 DAST_API_OVERRIDES_FILE
CI/CD 변수를 설정합니다. 경로는 작업의 현재 작업 디렉터리를 기준으로 상대적입니다.
다음은 예제 .gitlab-ci.yml
입니다:
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_FILE: dast-api-overrides.json
CI/CD 변수 사용
오버라이드 JSON을 CI/CD 변수로 제공하려면 DAST_API_OVERRIDES_ENV
변수를 사용합니다.
이를 통해 마스킹 및 보호할 변수로 JSON을 배치할 수 있습니다.
다음은 예제 .gitlab-ci.yml
입니다. DAST_API_OVERRIDES_ENV
변수는 JSON으로 직접 설정됩니다:
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}'
다음은 예제 .gitlab-ci.yml
입니다. SECRET_OVERRIDES
변수가 JSON을 제공합니다. 이는
UI에서 정의된 그룹 또는 인스턴스 레벨 CI/CD 변수입니다:
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_ENV: $SECRET_OVERRIDES
명령어 사용
값이 생성되거나 만료되면 프로그램이나 스크립트를 제공하여 API 보안 테스트 스캐너에서 지정된 간격으로 실행하도록 할 수 있습니다. 제공된 명령어는 이전에 정의된대로 오버라이드 JSON 파일을 생성합니다.
DAST_API_OVERRIDES_CMD
환경 변수를 실행하려는 프로그램 또는 스크립트로 설정해야 합니다. 제공된 명령어는 분석기가 시작하기 전에 한 번 실행됩니다.
NodeJS나 Ruby와 같은 기타 스크립팅 런타임을 설치하거나 오버라이드 명령어에 대한 의존성을 설치해야 하는 경우 DAST_API_PRE_SCRIPT
를 관련 스크립트 파일의 파일 경로로 설정하는 것을 권장합니다. DAST_API_PRE_SCRIPT
에서 제공된 스크립트는 분석기가 시작되기 전에 한 번 실행됩니다.
Alpine Linux 패키지 관리 페이지에서 Alpine Linux 패키지를 설치하는 방법에 대한 정보를 참조하세요.
올바른 작동을 위해 세 개의 CI/CD 변수를 제공해야 합니다.
- DAST_API_OVERRIDES_FILE
: 제공된 명령어에 의해 생성된 파일입니다.
- DAST_API_OVERRIDES_CMD
: 오버라이드 JSON 파일을 주기적으로 생성하는 명령어입니다.
- DAST_API_OVERRIDES_INTERVAL
: 명령어를 실행할 간격(초)입니다.
선택적으로:
-
DAST_API_PRE_SCRIPT
: 스캔이 시작되기 전에 런타임이나 의존성을 설치하는 스크립트입니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_OVERRIDES_FILE: dast-api-overrides.json
DAST_API_OVERRIDES_CMD: renew_token.py
DAST_API_OVERRIDES_INTERVAL: 300
오버라이드 디버깅
기본적으로 오버라이드 명령어의 출력은 숨겨집니다. 오버라이드 명령어가 0이 아닌 종료 코드를 반환하면 해당 명령어가 작업 출력의 일부로 표시됩니다. 선택적으로 DAST_API_OVERRIDES_CMD_VERBOSE
변수를 임의의 값으로 설정하여 오버라이드 명령어 출력을 생성될 때 표시할 수 있습니다. 이 기능은 오버라이드 스크립트를 테스트할 때 유용하지만 테스트 속도를 늦추므로 테스트가 끝난 후 비활성화해야 합니다.
또한 스크립트에서 작업 수행이 완료되거나 실패할 때 수집된 로그 파일에 메시지를 쓸 수 있습니다. 로그 파일은 특정 위치에 생성되고 특정한 명명 규칙을 따라야 합니다.
오버라이드 스크립트에 기본적인 로깅을 추가하면, 작업의 표준 실행 중 스크립트가 예상치 못하게 실패하는 경우에 유용합니다. 로그 파일은 작업의 일환으로 자동으로 포함되므로 작업이 완료된 후 다운로드할 수 있습니다.
예를 들어, 환경 변수 DAST_API_OVERRIDES_CMD
에 renew_token.py
를 제공했습니다. 스크립트의 두 가지 사항을 주목하세요:
- 로그 파일은 환경 변수
CI_PROJECT_DIR
에 저장됩니다. - 로그 파일 이름은
gl-*.log
와 일치해야 합니다.
#!/usr/bin/env python
# 오버라이드 명령어의 예제
# 오버라이드 명령어는 사용할 새 값으로 overrides json 파일을 업데이트할 수 있습니다.
# 이는 테스트 중에 만료될 수 있는 인증 토큰을 업데이트하는 훌륭한 방법입니다.
import logging
import json
import os
import requests
import backoff
# [1] Log 파일을 env 변수 CI_PROJECT_DIR에 저장
working_directory = os.environ.get( 'CI_PROJECT_DIR')
overrides_file_name = os.environ.get('DAST_API_OVERRIDES_FILE', 'dast-api-overrides.json')
overrides_file_path = os.path.join(working_directory, overrides_file_name)
# [2] 파일 이름은 gl-*.log와 일치해야 합니다.
log_file_path = os.path.join(working_directory, 'gl-user-overrides.log')
# 로거 설정
logging.basicConfig(filename=log_file_path, level=logging.DEBUG)
# `backoff` 데코레이터를 사용하여 일시적 오류 발생 시 재시도합니다.
@backoff.on_exception(backoff.expo,
(requests.exceptions.Timeout,
requests.exceptions.ConnectionError),
max_time=30)
def get_auth_response():
authorization_url = 'https://authorization.service/api/get_api_token'
return requests.get(
f'{authorization_url}',
auth=(os.environ.get('AUTH_USER'), os.environ.get('AUTH_PWD'))
)
# 예제에서는 액세스 토큰을 지정된 엔드포인트에서 검색합니다
try:
response = get_auth_response()
response.raise_for_status()
response_body = response.json()
except json.JSONDecodeError as json_decode_error:
logging.error(f'Error, failed while decoding JSON response. Error message: {json_decode_error}')
raise
except requests.exceptions.RequestException as requests_error:
logging.error(f'Error, failed while performing HTTP request. Error message: {requests_error}')
raise
except Exception as e:
logging.error(f'Error, unknown error while retrieving access token. Error message: {e}')
raise
overrides_data = {
"headers": {
"Authorization": f"Token {response_body['Token']}"
}
}
logging.info("Creating overrides file: %s" % overrides_file_path)
try:
if os.path.exists(overrides_file_path):
os.unlink(overrides_file_path)
with open(overrides_file_path, "wb+") as fd:
fd.write(json.dumps(overrides_data).encode('utf-8'))
except Exception as e:
logging.error(f'Error, unknown error when overwriting file {overrides_file_path}. Error message: {e}')
raise
logging.info("Override file has been updated")
# 끝
오버라이드 명령어 예제에서 Python 스크립트는 backoff
라이브러리에 의존합니다. Python 스크립트를 실행하기 전에 라이브러리가 설치되어 있는지 확인하려면 DAST_API_PRE_SCRIPT
를 오버라이드 명령어의 의존성을 설치하는 스크립트로 설정해야 합니다.
예를 들어, 다음 스크립트 user-pre-scan-set-up.sh
:
#!/bin/bash
# user-pre-scan-set-up.sh
# Python 의존성이 설치되었는지 확인
echo "**** install python dependencies ****"
python3 -m ensurepip
pip3 install --no-cache --upgrade \
pip \
backoff
echo "**** python dependencies installed ****"
# 끝
환경을 업데이트하여 DAST_API_PRE_SCRIPT
를 새 user-pre-scan-set-up.sh
스크립트로 설정해야 합니다. 예:
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_PRE_SCRIPT: user-pre-scan-set-up.sh
DAST_API_OVERRIDES_FILE: dast-api-overrides.json
DAST_API_OVERRIDES_CMD: renew_token.py
DAST_API_OVERRIDES_INTERVAL: 300
앞의 예제에서 user-pre-scan-set-up.sh
스크립트를 사용하여 나중에 오버라이드 명령어에서 사용할 새 런타임 또는 응용 프로그램을 설치할 수 있습니다.
요청 헤더
요청 헤더 기능을 사용하면 스캔 세션 중에 헤더에 대한 고정 값을 지정할 수 있습니다. 예를 들어, 구성 변수 DAST_API_REQUEST_HEADERS
를 사용하여 Cache-Control
헤더에 고정 값을 설정할 수 있습니다. 설정해야 하는 헤더에 Authorization
헤더와 같은 민감한 값이 포함되어 있는 경우, 가리기 변수 기능을 사용하여 변수 DAST_API_REQUEST_HEADERS_BASE64
와 함께 사용하십시오.
스캔 중에 Authorization
헤더나 다른 헤더를 업데이트해야 하는 경우 중첩 기능을 사용해보십시오.
변수 DAST_API_REQUEST_HEADERS
를 사용하면 쉼표로 구분된 헤더(,
) 디렉터리을 지정할 수 있습니다. 이러한 헤더는 스캐너가 수행하는 각 요청에 포함됩니다. 디렉터리에서 각 헤더 항목은 이름 다음에 콜론(:
)을 붙인 다음 값으로 이어집니다. 키나 값 앞의 공백은 무시됩니다. 예를 들어, 값이 max-age=604800
인 Cache-Control
헤더 이름을 선언하려면 헤더 항목은 Cache-Control: max-age=604800
입니다. 두 개의 헤더 Cache-Control: max-age=604800
와 Age: 100
을 사용하려면 DAST_API_REQUEST_HEADERS
변수를 Cache-Control: max-age=604800, Age: 100
으로 설정하십시오.
변수 DAST_API_REQUEST_HEADERS
에 제공된 서로 다른 헤더의 순서는 결과에 영향을 주지 않습니다. DAST_API_REQUEST_HEADERS
를 Cache-Control: max-age=604800, Age: 100
로 설정하든, Age: 100, Cache-Control: max-age=604800
로 설정하든 동일한 결과를 얻을 수 있습니다.
Base64
DAST_API_REQUEST_HEADERS_BASE64
변수는 DAST_API_REQUEST_HEADERS
와 동일한 헤더 디렉터리을 사용하지만, 차이점은 변수의 전체 값이 Base64로 인코딩되어야 한다는 것입니다. 예를 들어, DAST_API_REQUEST_HEADERS_BASE64
변수를 Authorization: QmVhcmVyIFRPS0VO, Cache-control: bm8tY2FjaGU=
로 설정하려면 디렉터리을 해당 Base64 값으로 변환해야 합니다. 이 Base64로 인코딩된 값은 가리기 변수에 비밀 헤더 값을 저장할 때 유용합니다.
예시: 일반 텍스트를 사용하여 각 요청에 헤더 디렉터리 추가
다음 .gitlab-ci.yml
예시에서 DAST_API_REQUEST_HEADERS
구성 변수는 요청 헤더에서 설명한 대로 두 개의 헤더 값을 지정합니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_REQUEST_HEADERS: 'Cache-control: no-cache, Save-Data: on'
예시: 가리기 CI/CD 변수 사용
다음 .gitlab-ci.yml
샘플은 가리기 변수 SECRET_REQUEST_HEADERS_BASE64
가 UI에서 정의된 그룹 또는 인스턴스 레벨 CI/CD 변수로 정의되었다고 가정합니다. SECRET_REQUEST_HEADERS_BASE64
의 값은 WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=
로 설정되는데, 이것은 X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb
의 Base64 인코딩된 텍스트 버전입니다. 그런 다음 다음과 같이 사용할 수 있습니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_PROFILE: Quick
DAST_API_OPENAPI: test-api-specification.json
DAST_API_TARGET_URL: http://test-deployment/
DAST_API_REQUEST_HEADERS_BASE64: $SECRET_REQUEST_HEADERS_BASE64
가리기 변수에 비밀 헤더 값을 저장할 때 DAST_API_REQUEST_HEADERS_BASE64
를 사용하는 것을 고려해보십시오.
제외 경로
API를 테스트할 때 특정 경로를 제외하는 것이 유용할 수 있습니다. 예를 들어, 인증 서비스나 API의 이전 버전을 제외할 수 있습니다. 경로를 제외하려면 .gitlab-ci.yml
파일에서 DAST_API_EXCLUDE_PATHS
CI/CD 변수를 사용하십시오. 여러 경로를 제외하려면 ;
문자를 사용하여 항목을 구분하십시오. 제공된 경로에서는 단일 문자 와일드카드 ?
와 다중 문자 와일드카드 *
를 사용할 수 있습니다.
경로가 제외되었는지 확인하려면 작업 출력의 테스트된 작업(Tested Operations)
및 제외된 작업(Excluded Operations)
부분을 검토하십시오. 테스트된 작업
에 나열된 제외된 경로가 없어야 합니다.
2021-05-27 21:51:08 [INF] DAST API: --[ 테스트된 작업 ]-------------------------
2021-05-27 21:51:08 [INF] DAST API: 201 POST http://target:7777/api/users CREATED
2021-05-27 21:51:08 [INF] DAST API: ------------------------------------------------
2021-05-27 21:51:08 [INF] DAST API: --[ 제외된 작업 ]-----------------------
2021-05-27 21:51:08 [INF] DAST API: GET http://target:7777/api/messages
2021-05-27 21:51:08 [INF] DAST API: POST http://target:7777/api/messages
2021-05-27 21:51:08 [INF] DAST API: ------------------------------------------------
예시
이 예시에서 /auth
리소스를 제외합니다. 이로 인해 /auth/child
하위 리소스는 제외되지 않습니다.
variables:
DAST_API_EXCLUDE_PATHS: /auth
/auth
와 /auth/child
하위 리소스를 제외하려면 와일드카드를 사용합니다.
variables:
DAST_API_EXCLUDE_PATHS: /auth*
여러 경로를 제외하려면 ;
문자를 사용합니다. 이 예시에서는 /auth*
와 /v1/*
를 제외합니다.
variables:
DAST_API_EXCLUDE_PATHS: /auth*;/v1/*
경로의 하나 이상의 중첩 레벨을 제외하려면 **
를 사용합니다. 이 예시에서는 API 엔드포인트를 테스트합니다. planet
, moon
, star
, satellite
객체에 대한 mass
, brightness
, coordinates
데이터를 요청하는 데이터 쿼리의 /api/v1/
와 /api/v2/
를 테스트하고 있습니다. 검사할 수 있는 예시 경로는 다음과 같습니다:
/api/v2/planet/coordinates
/api/v1/star/mass
/api/v2/satellite/brightness
이 예시에서는 brightness
엔드포인트만 테스트합니다.
variables:
DAST_API_EXCLUDE_PATHS: /api/**/mass;/api/**/coordinates
매개변수 제외
API를 테스트하는 동안 특정 매개변수(쿼리 문자열, 헤더 또는 본문 요소)를 테스트에서 제외하고 싶을 수 있습니다. 이는 매개변수가 항상 실패를 유발하거나 테스트를 늦추는 경우 등 여러 이유로 필요할 수 있습니다. 매개변수를 제외하려면 다음 변수 중 하나를 설정할 수 있습니다: DAST_API_EXCLUDE_PARAMETER_ENV
또는 DAST_API_EXCLUDE_PARAMETER_FILE
.
DAST_API_EXCLUDE_PARAMETER_ENV
를 사용하면 제외된 매개변수를 포함하는 JSON 문자열을 제공할 수 있습니다. 이 옵션은 JSON이 짧고 자주 변경되지 않는 경우 좋은 선택입니다. 또 다른 옵션은 DAST_API_EXCLUDE_PARAMETER_FILE
변수입니다. 이 변수는 리포지터리에 체크인할 수 있는 파일 경로로 설정되며, 다른 작업에 의해 아티팩트로 생성되거나 DAST_API_PRE_SCRIPT
를 사용하여 런타임에 생성될 수 있습니다.
JSON 문서를 사용하여 매개변수 제외
JSON 문서는 JSON 객체를 포함하며, 이 객체는 제외해야 하는 매개변수를 식별하기 위해 특정 속성을 사용합니다. 스캔 프로세스 중에 특정 매개변수를 제외하기 위해 다음 속성을 제공할 수 있습니다.
-
headers
: 특정 헤더를 제외하려면 이 속성을 사용합니다. 속성 값은 제외할 헤더 이름의 배열입니다. 이름은 대소문자를 구분하지 않습니다. -
cookies
: 특정 쿠키를 제외하려면 이 속성을 사용합니다. 속성 값은 제외할 쿠키 이름의 배열입니다. 이름은 대소문자를 구분합니다. -
query
: 쿼리 문자열에서 특정 필드를 제외하려면 이 속성을 사용합니다. 속성 값은 제외할 쿼리 문자열의 필드 이름의 배열입니다. 이름은 대소문자를 구분합니다. -
body-form
:application/x-www-form-urlencoded
미디어 유형을 사용하는 요청에서 본문의 특정 필드를 제외하려면 이 속성을 사용합니다. 속성 값은 본문에서 제외할 필드 이름의 배열입니다. 이름은 대소문자를 구분합니다. -
body-json
:application/json
미디어 유형을 사용하는 요청에서 특정 JSON 노드를 제외하려면 이 속성을 사용합니다. 속성 값은 JSON Path 표현식의 배열입니다. -
body-xml
:application/xml
미디어 유형을 사용하는 요청에서 특정 XML 노드를 제외하려면 이 속성을 사용합니다. 속성 값은 XPath v2 표현식의 배열입니다.
따라서 다음 JSON 문서는 매개변수를 제외하기 위한 예상 구조의 예입니다.
{
"headers": [
"header1",
"header2"
],
"cookies": [
"cookie1",
"cookie2"
],
"query": [
"query-string1",
"query-string2"
],
"body-form": [
"form-param1",
"form-param2"
],
"body-json": [
"json-path-expression-1",
"json-path-expression-2"
],
"body-xml" : [
"xpath-expression-1",
"xpath-expression-2"
]
}
예시
단일 헤더 제외
Upgrade-Insecure-Requests
헤더를 제외하려면 header
속성의 값을 헤더 이름이 포함된 배열로 설정합니다: [ "Upgrade-Insecure-Requests" ]
. 예를 들어, JSON 문서는 다음과 같습니다.
{
"headers": [ "Upgrade-Insecure-Requests" ]
}
헤더 이름은 대소문자를 구분하지 않으므로 UPGRADE-INSECURE-REQUESTS
헤더 이름은 Upgrade-Insecure-Requests
와 동등합니다.
헤더 및 쿠키 둘 다 제외
Authorization
헤더 및 PHPSESSID
및 csrftoken
쿠키를 제외하려면 headers
속성의 값에 헤더 이름을 포함하는 배열 [ "Authorization" ]
및 cookies
속성의 값에 쿠키 이름을 포함하는 배열 [ "PHPSESSID", "csrftoken" ]
를 설정합니다. 예를 들어, JSON 문서는 다음과 같습니다.
{
"headers": [ "Authorization" ],
"cookies": [ "PHPSESSID", "csrftoken" ]
}
body-form
매개변수 제외
application/x-www-form-urlencoded
를 사용하는 요청에서 password
필드를 제외하려면 body-form
속성의 값을 필드 이름이 포함된 배열으로 설정합니다: [ "password" ]
. 예를 들어, JSON 문서는 다음과 같습니다.
{
"body-form": [ "password" ]
}
제외 매개변수는 요청이 application/x-www-form-urlencoded
콘텐츠 유형을 사용할 때 body-form
을 사용합니다.
JSON Path를 사용하여 특정 JSON 노드 제외
루트 오브젝트에서 schema
속성을 제외하려면 body-json
속성의 값을 JSON Path 표현식이 포함된 배열로 설정합니다: [ "$.schema" ]
.
JSON Path 표현식은 JSON 노드를 식별하기 위해 특수한 구문을 사용합니다: $
는 JSON 문서의 루트를 의미하며, .
는 현재 오브젝트를 의미합니다 (이 경우에는 루트 오브젝트), 그리고 schema
는 속성 이름을 의미합니다. 따라서 JSON 경로 표현식 $.schema
는 루트 오브젝트의 schema
속성을 의미합니다.
예를 들어, JSON 문서는 다음과 같습니다.
{
"body-json": [ "$.schema" ]
}
제외 매개변수는 요청이 application/json
콘텐츠 유형을 사용할 때 body-json
을 사용합니다. body-json
의 각 항목은 JSON Path 표현식이어야 합니다. JSON Path에는 $
, *
, .
등의 문자가 특별한 의미를 가집니다.
JSON Path를 사용하여 여러 JSON 노드 제외
루트 레벨에서 users
배열의 각 항목에서 password
속성을 제외하려면 body-json
속성의 값을 JSON Path 표현식이 포함된 배열로 설정합니다: [ "$.users[*].paswword" ]
.
JSON Path 표현식은 $
로 시작하여 루트 노드를 참조하고, .
를 사용하여 현재 노드를 참조합니다. 그런 다음 users
를 사용하여 속성을 참조하고, [
와 ]
문자를 사용하여 index를 제공하는 대신 *
를 사용하여 모든 index를 지정합니다. 그 다음 인덱스 참조 이후, 이제 속성 이름 password
앞에 선택된 배열의 모든 index를 나타내는 .
를 사용합니다.
예를 들어, JSON 문서는 다음과 같습니다.
{
"body-json": [ "$.users[*].paswword" ]
}
제외 매개변수는 요청이 application/json
콘텐츠 유형을 사용할 때 body-json
을 사용합니다. body-json
의 각 항목은 JSON Path 표현식이어야 합니다. JSON Path에는 $
, *
, .
등의 문자가 특별한 의미를 가집니다.
XML 속성 제외
루트 엘리먼트 credentials
에서 isEnabled
라는 속성을 제외하려면 body-xml
속성의 값을 XPath 표현식이 포함된 배열로 설정합니다: [ "/credentials/@isEnabled" ]
.
XPath 표현식 /credentials/@isEnabled
은 XML 문서의 루트를 나타내는 /
로 시작하여, 일치해야 하는 엘리먼트 이름인 credentials
로 이어집니다. 이전 XML 엘리먼트의 노드를 참조하기 위해 /
을 사용하고, 속성 이름 isEnable
은 @
문자로 시작함을 나타냅니다.
예를 들어, JSON 문서는 다음과 같습니다.
{
"body-xml": [
"/credentials/@isEnabled"
]
}
제외 매개변수는 요청이 application/xml
콘텐츠 유형을 사용할 때 body-xml
을 사용합니다. body-xml
의 각 항목은 XPath v2 표현식이어야 합니다. XPath 표현식에는 @
, /
, :
, [
, ]
등의 문자가 특별한 의미를 가집니다.
XML 텍스트의 요소 제외
credentials
루트 노드에 포함된 username
요소의 텍스트를 제외하려면 body-xml
속성 값을 XPath 표현식 [/credentials/username/text()" ]
을 포함한 배열으로 설정합니다.
XPath 표현식 /credentials/username/text()
에서 첫 번째 문자 /
는 루트 XML 노드를 가리키며, 그 후에는 XML 요소의 이름 credentials
을 나타냅니다. 비슷하게 문자 /
는 현재 요소를 가리키고, 새로운 XML 요소의 이름 username
을 나타내고 있습니다. 마지막 부분에는 /
가 있으며, 현재 요소의 텍스트를 식별하는 text()
라는 XPath 함수를 사용합니다.
예를 들어, 다음과 같이 JSON 문서가 구성됩니다:
{
"body-xml": [
"/credentials/username/text()"
]
}
요청에서 콘텐츠 유형이 application/xml
일 때, 제외 매개변수는 body-xml
을 사용합니다. body-xml
의 각 항목은 XPath v2 표현식이어야 합니다. XPath 표현식에는 @
, /
, :
, [
, ]
등의 문자가 특별한 의미를 가지고 있습니다.
XML 요소 제외
credentials
루트 노드에 포함된 username
요소를 제외하려면 body-xml
속성 값을 XPath 표현식 [/credentials/username" ]
을 포함한 배열으로 설정합니다.
XPath 표현식 /credentials/username
에서 첫 번째 문자 /
는 루트 XML 노드를 가리키며, 그 후에는 XML 요소의 이름 credentials
을 나타냅니다. 비슷하게 문자 /
는 현재 요소를 가리키고, 새로운 XML 요소의 이름 username
을 나타내고 있습니다.
예를 들어, 다음과 같이 JSON 문서가 구성됩니다:
{
"body-xml": [
"/credentials/username"
]
}
요청에서 콘텐츠 유형이 application/xml
일 때, 제외 매개변수는 body-xml
를 사용합니다. body-xml
의 각 항목은 XPath v2 표현식이어야 합니다. XPath 표현식에는 @
, /
, :
, [
, ]
등의 문자가 특별한 의미를 가지고 있습니다.
네임스페이스를 사용하는 XML 노드 제외
네임스페이스 s
에서 정의된 credentials
루트 노드에 포함된 login
XML 요소를 제외하려면 body-xml
속성 값을 XPath 표현식 [ "/credentials/s:login" ]
을 포함한 배열으로 설정합니다.
XPath 표현식 /credentials/s:login
에서 첫 번째 문자 /
는 루트 XML 노드를 가리키며, 그 후에는 XML 요소의 이름 credentials
을 나타냅니다. 비슷하게 문자 /
는 현재 요소를 가리키고, 새로운 XML 요소의 이름 s:login
을 나타내고 있습니다. 이름에 :
문자가 포함되어 있는 것을 주목해야 하는데, 이 문자는 네임스페이스와 노드 이름을 구분합니다.
네임스페이스 이름은 요청 본문의 일부인 XML 문서에서 정의되어야 합니다. 네임스페이스는 사양 문서인 HAR, OpenAPI 또는 Postman Collection 파일에서 확인할 수 있습니다.
{
"body-xml": [
"/credentials/s:login"
]
}
요청에서 콘텐츠 유형이 application/xml
일 때, 제외 매개변수는 body-xml
를 사용합니다. body-xml
의 각 항목은 XPath v2 표현식이어야 합니다. XPath 표현식에는 @
, /
, :
, [
, ]
등의 문자가 특별한 의미를 가지고 있습니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_TARGET_URL: http://target/
DAST_API_OPENAPI: test-api-specification.json
DAST_API_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell
정규 표현식을 사용하여 URL 제외
https://target/api/v1/user/create
및 https://target/api/v2/user/create
또는 다른 버전(v3
,v4
등)을 정확히 제외하려면 https://target/api/v.*/user/create$
와 같은 정규 표현식을 사용할 수 있습니다. 여기서 앞의 정규 표현식에서 .
는 어떤 문자든, *
는 0회 이상을 나타내며, 추가로 $
는 URL이 그 위치에서 끝나야 함을 나타냅니다.
stages:
- dast
include:
- template: DAST-API.gitlab-ci.yml
variables:
DAST_API_TARGET_URL: http://target/
DAST_API_OPENAPI: test-api-specification.json
DAST_API_EXCLUDE_URLS: https://target/api/v.*/user/create$