IBM Cloud Docs
ZAP 스캔 구성

ZAP 스캔 구성

ZAP (Zed Attack Proxy) 는 OWASP의 우산 아래에서 유지되는 자유롭고 오픈 소스인 PEN (penetration test) 도구입니다. ZAP는 테스터의 웹 브라우저와 웹 서버 사이에 있는 "중간자" 프록시입니다. ZAP는 패킷을 가로채고 필요한 경우 컨텐츠를 수정하며 해당 패킷을 웹 서버로 전달합니다.

ZAP 스캔에 사용 가능한 매개변수

애플리케이션 저장소 내에서 trigger_zap_scans 파일을 작성하십시오 (예: scripts 디렉토리 내에서 선택한 위치에).

다음과 같이 trigger_zap_scans 에 이러한 행을 추가하여 해당 매개변수의 값을 설정하십시오. - set_env <parameter name> <value>. 참조 구현에 대한 자세한 정보는 hello-compliance-app를 참조하십시오.

다음 매개변수를 설정하고 사용자 정의하여 실행 중인 앱에서 침투 테스트를 실행하도록 ZAP 스캔을 구성할 수 있습니다.

표 1. ZAP 스캔 구성 매개변수
이름 유형 설명 필수 또는 선택사항
cluster-name 문자열 DinD에서 실행 중이 아닌 경우, zap 스캐너를 배치하고 실행할 클러스터의 이름입니다. DinD에서 실행되지 않는 경우 필수입니다. 즉, zap-dindfalse 로 설정됩니다.
ibmcloud-api 문자열 ZAP 클러스터의 클라우드 환경을 지정합니다. 기본값은 https://cloud.ibm.com DinD에서 실행되지 않는 경우 필수입니다. 즉, zap-dindfalse 로 설정됩니다.
ibmcloud-api-key 문자열 클러스터에 ZAP를 배치하기 위한 API키입니다. DinD에서 실행되지 않는 경우 필수입니다. 즉, zap-dindfalse 로 설정됩니다.
iam-token-endpoint 문자열 IAM 인증을 위한 토큰을 검색하기 위한 엔드포인트입니다. 기본값은 https://iam.cloud.ibm.com/identity/token 선택사항이지만 제공된 경우 target-api-key 도 제공해야 합니다.
target-api-key 문자열 IAM 인증을 위한 API키입니다. 선택사항이지만 제공된 경우 iam-token-endpoint 도 제공해야 합니다.
target-application-server-url 문자열 zap이 스캔할 애플리케이션 서버의 기본 URL 입니다. 배치된 애플리케이션의 URL 과 동일할 수 있습니다. 필수
filter-options 문자열 심각도에 따라 경보를 필터링하려면 이를 설정하십시오. 가능한 값: Critical, High, Medium, Low, Informational. 기본값은 Informational 이며, 쉼표로 구분된 목록일 수 있습니다. 선택사항
zap-custom-api-policy-file-path 문자열 ZAP API 스캔을 위한 사용자 정의 정책 파일 (XML 형식) 에 대한 저장소의 상대 경로입니다. 이를 설정하지 않으면 기본 정책 API-Minimal.policy 가 사용됩니다. 선택사항
zap-custom-ui-policy-file-path 문자열 ZAP UI 스캔에서 사용되는 사용자 정의 정책 파일 (XML 형식) 에 대한 저장소의 상대 경로입니다. 이 경로가 설정되지 않으면 기본 정책 default.policy 가 사용됩니다. 선택사항
zap-ui-scan 문자열 스캔이 UI 스캔인지 또는 API 스캔인지 여부를 판별하는 플래그입니다. 가능한 값: true, false. 이 플래그를 true 로 설정하면 UI 스캔이 실행되고, false로 설정하면 API 스캔이 실행됩니다. 이 매개변수는 opt-in-dynamic-api-scanopt-in-dynamic-ui-scan 매개변수와 함께 작동합니다. 필수
zap_dind 문자열 클러스터에 ZAP 배치 또는 DinD실행 사이에서 전환하는 플래그입니다. 기본값: true. 가능한 값: true, false. true 로 설정하면 ZAP가 DinD으로 실행되고, false 로 설정하면 cluster-name, ibmcloud-apiibmcloud-api-key 가 설정되어야 하는 클러스터에 ZAP가 배치됩니다. 선택사항
zap-dind-localhost 문자열 DinD에서 실행 중인 경우 ZAP 스캐너의 호스트 이름입니다. 기본값은 localhost 입니다. 선택사항
zap-namespace 문자열 클러스터에서 ZAP API및 UI 스캐너를 배치하기 위한 네임스페이스 (기본값: zap). 클러스터에서 ZAP를 실행하는 경우 선택사항이며, DinD에서 실행 중인 ZAP의 경우 Not required 입니다.
zap-polling-interval 문자열 스캐너가 스캔 완료를 위해 ZAP를 폴링하는 간격입니다. 기본값: 120s. 선택사항
zap-artifact 문자열 스캔되는 zap이며 수집 증거가 호출되는 아티팩트의 자산 키입니다. 기본값은 app-image 입니다. 선택사항
zap_evidence_type 문자열 ZAP에서 수행된 스캔에 대한 증거 수집의 증거 유형입니다. 기본값: com.ibm.dynamic_scan. 선택사항
show-container-log 문자열 DinD에서 실행 중인 경우 ZAP 스캐너에 대한 컨테이너 로깅 기능을 사용 또는 사용 안함으로 설정하는 플래그입니다. 기본값: false. 선택사항
show-zap-log 문자열 ZAP 서버 로깅 기능을 사용 또는 사용 안함으로 설정하는 플래그입니다. 기본값: false. 선택사항

ZAP API 스캔 구성

애플리케이션 저장소 내에 json 형식의 API 정의 파일이 하나 이상 있어야 합니다. 이 API 정의 파일은 올바른 swagger 또는 openapi 정의여야 합니다. 이러한 파일은 애플리케이션 저장소 내의 임의의 위치 (예: definitions 디렉토리 내) 에 있을 수 있습니다. 명확성을 위해 이러한 파일을 definitions1.json, definitions2.json 등과 같이 참조합니다.

ZAP API 스캔을 구성하려면 추가 매개변수가 필요합니다. 이러한 매개변수는 다음과 같이 trigger_zap_scans 에 다음 행을 추가하여 설정할 수 있습니다. - set_env <parameter name> <value>.

표 2. ZAP API 구성 매개변수
이름 유형 설명 필수 또는 선택사항
zap-api-custom-script 문자열 ZAP API 스캔을 시작하기 전에 요청 변환 로직을 포함하는 파일의 경로입니다. 필수
swagger-definition-files 문자열 Swagger 정의를 포함하는 파일의 경로입니다. 쉼표로 구분된 목록일 수 있습니다. 필수
zap-api-port 문자열 클러스터에 배치될 때 ZAP API 스캐너를 실행하기 위한 포트입니다. 기본값: 9086. 선택사항
zap_api_deployment_name 문자열 ZAP API 스캐너 배치의 이름입니다. 기본값: zap-api-deployment. 선택사항
zap-api-image 문자열 사용자 정의 ZAP API 스캐너 이미지를 사용하려면 이 매개변수를 설정하십시오. 그렇지 않으면 IBM 기본값이 사용됩니다. 선택사항
flatten-zap-api-scan-report 문자열 ZAP API 스캔 결과를 하나의 단일 html및 json 파일로 변환하려면 이 매개변수를 true 로 설정하십시오. 기본값은 false 입니다. 선택사항

애플리케이션 저장소 내에서 선택한 위치 (예: scripts/zap-custom-scripts 디렉토리 내) 에 custom-api-script 파일을 작성하십시오. 이 파일의 이름도 다르게 지정할 수 있으며 zap-api-custom-script 매개변수에 대해 이 파일의 경로를 설정할 수 있습니다.

custom-api-script 파일을 사용하여 ZAP 스캐너로 이동하는 요청을 수정하십시오. 요청 페이로드에서 사용할 수 있는 매개변수는 다음과 같습니다.

표 3. 요청 페이로드의 매개변수
이름 유형 설명 필수 또는 선택사항
excludeScanTypes 배열 사용자가 제외하려는 스캔 목록입니다. CRLF_Injection,Buffer_Overflow, Directory_Browsing, External_Redirect, Format_String_Error, Parameter_Tampering, Remote_File_Inclusion, Script_Active_Scan, Server_Side_Code_Injection, Server_Side_Include, SQL_Injection, Xpath_Injection, XXE_External_Entity, SOAP_Action_Spoofing, SOAP_XML_Injection, Relative_Path_Confusion, Remote_OS_Command_Injection, ElmahScanRuleHtAccessScanRule 중에서 선택할 스캔의 전체 목록입니다. 선택사항
apisToScan 배열 필수 매개변수와 함께 스캔할 API 목록입니다. "apisToScan": ["all"] 가 언급되면 Swagger 정의에서 언급된 모든 API가 필수 매개변수/본문에 대한 모의 데이터를 사용하여 스캔됩니다. 선택적 API를 스캔하도록 이 배열을 사용자 정의하려면 이 하위 구조 apisToScan: [ { "path": "/path/to/endpoint", method: "get" } ] 를 사용하십시오. 필수
globalExcludeUrls 배열 ZAP에 해당 라우트를 스캔하지 않도록 지시하는 URL 정규식의 배열입니다. 예를 들어, "globalExcludeUrls": [ "^http://foo.bar$", "^http://john.doe$" ]입니다. 선택사항
authenticationType 문자열 요청 헤더의 인증 메커니즘입니다. 지원되는 인증 메커니즘은 Bearer, Basic 또는 ApiKey 입니다. 선택사항
apiKey 문자열 authenticationType 가 전송되지 않으면 이 API키는 모든 요청에 대해 권한 헤더에서 전송되는 IAM 인증에 사용됩니다. authenticationTypeBearer 로 설정되면, 구성되는 헤더는 Authorization: Bearer <apiKey> 입니다. authenticationTypeApiKey 로 설정되면, 구성되는 헤더는 Authorization: <apiKey> 입니다. authenticationType 에 대한 필드가 Basic(으) 로 무시됩니다. 선택사항
username 문자열 authenticationType Basic 에 사용할 사용자 이름입니다. authenticationTypeBasic 인 경우 필수입니다.
password 문자열 authenticationType Basic 에 사용할 비밀번호입니다. authenticationTypeBasic 인 경우 필수입니다.

신임 정보와 같은 민감한 정보의 경우 저장소 또는 시크릿 저장소에서 이러한 값을 읽어야 합니다.

ZAP UI 스캔 구성

ZAP API 스캔 구성과 유사하게, 선택한 위치 (예: scripts 디렉토리) 에서 애플리케이션 저장소 내에 trigger_zap_scans 파일을 작성하거나 업데이트하십시오.

다음과 같이 trigger_zap_scans 에 이러한 행을 추가하여 해당 매개변수의 값을 설정하십시오. - set_env <parameter name> <value>. 참조 구현에 대한 자세한 정보는 hello-compliance-app를 참조하십시오.

ZAP UI 스캔을 실행하려면 zap-ui-scan 매개변수를 true 로 설정하십시오.

ZAP UI 스캔을 구성하는 데 필요한 매개변수는 다음과 같습니다.

표 4. ZAP UI 구성 매개변수
이름 유형 설명 필수 또는 선택사항
zap-ui-custom-script 문자열 ZAP UI 스캔이 시작되기 전에 필요한 경우 UI 스캔 페이로드에 대한 수정 로직을 포함하는 파일의 경로입니다. 선택사항
zap-ui-script-directory 문자열 UI 스캔을 실행하기 위한 UI 테스트 및 필수 파일이 포함된 디렉토리의 경로입니다. 필수
context-file 문자열 ZAP에 제공된 UI 스캔에 대한 사용자 정의 컨텍스트 파일의 경로입니다. 선택사항
zap-ui-port 문자열 클러스터에 배치될 때 ZAP UI 스캐너를 실행하기 위한 포트입니다. 기본값: 9085. 선택사항
zap_ui_deployment_name 문자열 ZAP UI 스캐너 배치의 이름입니다. 기본값: zap-ui-deployment. 선택사항
zap-proxy-service 문자열 UI 스캐너에 필요한 ZAP 프록시 서비스의 이름입니다 (기본값: zap-proxy-service). 선택사항
zap-ui-image 문자열 사용자 정의 ZAP UI 스캐너 이미지를 사용하려면 이 매개변수를 설정하십시오. 그렇지 않으면 IBM 기본값이 사용됩니다. 선택사항
zap-proxy-image 문자열 사용자 정의 ZAP 프록시 이미지를 사용하려면 이를 설정하십시오. 그렇지 않으면 IBM 기본값이 사용됩니다. 선택사항

애플리케이션 저장소 내의 scripts/zap 디렉토리 내에 uiscripts 폴더를 작성하십시오. 또한 trigger_zap_scans 파일에서 zap-ui-script-directory 에 대해 이 폴더 경로를 설정하십시오. 이 폴더는 다른 위치에서도 작성할 수 있습니다. zap-ui-script-directory 에 대해 경로를 조정해야 합니다.

uiscripts 디렉토리 내에 run.sh 파일을 작성하십시오. run.sh 는 UI 테스트를 구동합니다. 우리는 견인기 기반 테스트 또는 기타 적합한 프레임워크를 구성할 수 있습니다.

uiscripts 디렉토리 내에 export.sh 파일을 작성하십시오. 이 파일은 테스트 프레임워크가 사용하는 데 필요한 모든 다른 환경 변수를 보유합니다. export <VARIABLE_NAME>=<VALUE> 를 추가하여 해당 환경 값을 설정하십시오.

테스트 프레임워크에 대한 구성 정보를 보유하려면 uiscripts 디렉토리 내에 conf 폴더를 작성하여 테스트 프레임워크에 대한 구성 정보를 보관하십시오.

테스트 프레임워크로 Protractor를 사용하는 참조 구현은 hello-compliance-app를 참조하십시오.

ZAP 스캔 결과 관리

opt-in-dynamic-api-scanopt-in-dynamic-ui-scan 매개변수의 값을 기반으로 API 스캔 또는 UI 스캔 또는 둘 다 선택적으로 실행하도록 선택할 수 있습니다.

trigger_zap_scans 파일 내에서 다음과 같이 옵트 인 매개변수를 기반으로 개별 스캔을 트리거할 수 있습니다.

if [ -n "$(get_env opt-in-dynamic-api-scan "")" ]; then
    # start the api scan
    set_env "zap-ui-scan" "false"
    source "${COMMONS_PATH}"/owasp-zap/run_scan.sh
fi

if [ -n "$(get_env opt-in-dynamic-ui-scan "")" ]; then
    # set for zap-ui-scans and start zap-ui-scan
    set_env "zap-ui-scan" "true"
    source "${COMMONS_PATH}"/owasp-zap/run_scan.sh
fi

COMMONS_PATH 은 DevSecOps 파이프라인의 일부인 다양한 도구에 대한 빌드 스크립트 및 실행 스크립트를 보유하는 위치를 참조합니다. 자세한 정보는 공통 스크립트 를 참조하십시오.

API 스캔 또는 UI 스캔이 실행되었는지 여부에 따라 종료 코드를 설정하여 ZAP 스캔의 성공 여부를 계산할 수 있습니다. 발견된 모든 취약성도 보고됩니다. api-scan-resultui-scan-result 변수를 눌러 이를 확인할 수 있습니다.

이러한 매개변수가 사용할 수 있는 가능한 값은 success 또는 failure 이며 기본값은 notRun 입니다.

ZAP_API_RESULT=$(get_env api-scan-result "notRun")
ZAP_UI_RESULT=$(get_env ui-scan-result "notRun")

if [[ "${ZAP_API_RESULT}" =~ ^(success|notRun)$ && "${ZAP_UI_RESULT}" =~ ^(success|notRun)$ ]]; then
   exit 0
else
   exit 1
fi

샘플 구현은 이 저장소내의 scripts/zap 디렉토리 내의 trigger_zap_scans 파일에서 찾을 수 있습니다.

CC 파이프라인에 대한 ZAP 스캔 구성

다음 표에는 CC 파이프라인 내에서 ZAP 스캔을 실행하는 데 필요한 추가 매개변수가 나열되어 있습니다.

표 5. CC 파이프라인의 ZAP 매개변수
이름 유형 설명 필수 또는 선택사항
app-url 문자열 ZAP 스캔이 실행되는 배치된 애플리케이션의 URL 입니다. 애플리케이션의 staging URL을 사용하십시오. 필수
repo-url 문자열 배치된 애플리케이션 저장소의 URL. 선택사항이며, inventory repo 에 하나의 애플리케이션 저장소의 모든 아티팩트가 있는 경우입니다.

UI 테스트를 압축하지 않고 사용자 정의 UI 테스트 이미지를 사용하도록 Zap UI 스캔 구성

다음 표에는 사용자 정의 UI 테스트 이미지를 사용하도록 ZAP UI 스캔을 구성하는 데 필요한 추가 매개변수가 나열되어 있습니다.

표 6. CC 파이프라인의 ZAP 매개변수
이름 유형 설명 필수 또는 선택사항
zap-custom-ui-deployment-name 문자열 사용자 정의 UI Docker 컨테이너 이름입니다. 선택사항
zap-custom-ui-docker-run-param 문자열 Docker 는 매개변수를 실행하여 사용자 정의 UI 이미지를 실행합니다. 선택사항
zap-custom-ui-exit-code-ignored 문자열 Zap UI는 사용자 정의 UI 종료 코드와 함께 종료되지만 이 변수가 true 로 설정되면 종료 코드가 무시됩니다. 선택사항
zap-custom-ui-image 문자열 테스트를 실행하는 사용자 정의 UI Docker 이미지입니다. 필수
zap-custom-ui-post-script 문자열 사용자 정의 UI 이미지를 실행한 후 실행할 스크립트입니다. 선택사항
zap-custom-ui-pre-script 문자열 사용자 정의 UI 이미지를 실행하기 전에 실행할 스크립트입니다. 선택사항
zap-custom-ui-progress-script 문자열 사용자 정의 UI 이미지를 실행하는 동안 실행할 스크립트입니다. 선택사항
zap-custom-ui-timeout-in-sec 문자열 이 시간 이후에 Zap UI 스캔이 종료됩니다. 선택사항

이 사용자 정의 UI 스캔 단계에서는 기본 케이스인 zip 파일에 Docker 이미지 정보를 넣는 대신 사용자의 사용자 정의 UI Docker 이미지를 사용하여 zap UI 스캔을 수행합니다. zap-custom-ui-image 는 사용자 정의 UI 테스트 이미지를 사용하도록 ZAP UI 스캔을 구성하기 위해 설정되는 필수 환경 변수입니다.