- API Fuzzing 작업이 N시간 후에 타임 아웃됨
- API Fuzzing 작업 완료에 너무 오래 걸림
-
오류:
Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available
오류, OpenAPI 문서가 유효하지 않습니다. 발행된 OpenAPI 스키마를 사용하여 문서를 유효성 검사하는 중에 오류가 발견되었습니다
스캐너 세션 시작 실패 (버전 헤더를 찾을 수 없음)
-
애플리케이션이 대상 API의 기본 URL을 결정할 수 없음
- 유효하지 않은 스키마로 OpenAPI 사용
OpenAPI 문서에 있는 어떠한 작업도 지원되는 미디어 타입을 사용하지 않습니다
에러, `<URL>` 다운로드 중 오류가 발생했습니다: Uri에서 콘텐츠 검색 중 오류가 발생했습니다.' <URL>'. 오류: SSL 연결을 설정할 수 없습니다. 내부 예외를 확인하세요.
ERROR: 작업 실패: 이미지를 가져오지 못했습니다
문제 해결
API Fuzzing 작업이 N시간 후에 타임 아웃됨
대형 리포지터리의 경우 기본값으로 설정된 작은 SaaS 러너에서 API Fuzzing 작업이 타임 아웃 될 수 있습니다. 작업 시 이 문제가 발생하면 더 큰 러너로 스케일 업해야 합니다.
도움이 필요할 때 다음 문서 섹션을 참조하세요:
API Fuzzing 작업 완료에 너무 오래 걸림
오류: Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available
v1.6.196 이전 버전의 API Fuzzing 분석기에는 특정 조건에서 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다. 해결책은 더 최신 버전의 API Fuzzing 분석기로 업데이트하는 것입니다.
버전 정보는 apifuzzer_fuzz
작업의 작업 세부 정보에서 찾을 수 있습니다.
v1.6.196 이상 버전에서 문제가 발생하는 경우, 지원팀에 문의하고 다음 정보를 제공하세요:
- 이 문제가 동적 분석 팀에 eskalte되도록 이 문제 해결 섹션을 참조하세요.
- 작업의 전체 콘솔 출력.
- 작업 아티팩트로서 제공되는
gl-api-security-scanner.log
파일. 작업 세부 정보 페이지의 오른쪽 패널에서 찾아보기 버튼을 선택합니다. -
.gitlab-ci.yml
파일에서apifuzzer_fuzz
작업 정의.
오류 메시지
-
GitLab 15.6 및 이후,
Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available
- GitLab 15.5 및 이전,
Error waiting for API Security 'http://127.0.0.1:5000' to become available
.
Failed to start session with scanner. Please retry, and if the problem persists reach out to support.
API Fuzzing 엔진이 스캐너 응용 프로그램 구성요소와 연결을 설정할 수 없는 경우 오류 메시지가 출력됩니다. 이 오류 메시지는 apifuzzer_fuzz
작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 백그라운드 구성요소가 이미 사용 중인 포트를 사용할 수 없는 것입니다. 타이밍이 부분적으로 영향을 미칠 수 있기 때문에 이 오류는 때로는 간헐적으로 발생할 수 있습니다. 이 문제는 주로 쿠버네티스 환경에서 발생하며 다른 서비스가 컨테이너에 매핑되어 포트 충돌이 발생할 수 있습니다.
해결책으로 넘어가기 전에 포트가 이미 사용 중이었기 때문에 이 문제가 발생했다는 것을 확인하는 것이 중요합니다. 이것이 원인이었음을 확인하려면:
- 작업 콘솔로 이동합니다.
-
gl-api-security-scanner.log
아티팩트를 찾습니다. 다운로드를 선택하고 파일을 검색하거나 찾아보기를 직접 선택하여 검색을 시작할 수 있습니다. -
gl-api-security-scanner.log
파일을 텍스트 편집기에서 엽니다. - 포트가 이미 사용 중이기 때문에 오류 메시지가 생성된 경우, 파일에 다음과 유사한 메시지를 볼 수 있어야 합니다:
-
Failed to bind to address http://127.0.0.1:5500: address already in use.
-
GitLab 15.4 및 이전:
Failed to bind to address http://[::]:5000: address already in use.
이전 메시지의 http://[::]:5000
부분은 당신의 경우에는 다를 수 있으며, 예를 들어 http://[::]:5500
또는 http://127.0.0.1:5500
일 수 있습니다. 그러나 에러 메시지의 나머지 부분이 동일하다면 안전하게 포트가 이미 사용 중이라고 가정할 수 있습니다.
포트가 이미 사용 중이지 않았다면 작업 콘솔 출력에 표시된 오류 메시지와 동일한 메시지를 해결하는 다른 문제 해결 섹션을 확인합니다. 더 이상의 옵션이 없다면 적절한 채널을 통해 지원을 받거나 개선 사항을 요청해 주세요.
이 문제가 포트가 이미 사용 중이었기 때문에 발생했음을 확인한 후, GitLab 15.5 및 이후에서 이 문제를 해결하기 위해 구성 변수 FUZZAPI_API_PORT
가 소개되었습니다. 이 구성 변수는 스캐너 백그라운드 구성요소에 대한 고정 포트 번호를 설정할 수 있습니다.
해결책
-
.gitlab-ci.yml
파일이 구성 변수FUZZAPI_API_PORT
를 정의했는지 확인합니다. -
FUZZAPI_API_PORT
의 값을 1024보다 큰 사용 가능한 포트 번호로 업데이트합니다. 새 값이 GitLab에서 사용되고 있지 않은지 확인하는 것이 좋습니다. GitLab에서 사용하는 모든 포트의 전체 디렉터리은 패키지 기본값에서 확인할 수 있습니다.
오류, OpenAPI 문서가 유효하지 않습니다. 발행된 OpenAPI 스키마를 사용하여 문서를 유효성 검사하는 중에 오류가 발견되었습니다
API Fuzzing 작업 시작 시 제공된 OpenAPI 명세가 유효성 오류를 가지면 발행된 스키마에 대해 유효성을 검사합니다. 이 오류는 제공된 OpenAPI 명세에 유효성 오류가 있는 경우에 표시됩니다. 오류는 OpenAPI 명세를 매뉴얼으로 만드는 경우나 스키마가 생성된 경우에도 발생할 수 있습니다.
자동으로 생성된 OpenAPI 명세의 경우, 유효성 오류는 종종 코드 주석이 누락되어 발생합니다.
오류 메시지
-
GitLab 13.11 및 이후,
오류, 발행된 OpenAPI 스키마를 사용하여 문서를 유효성 검사하는 중에 오류가 발견되었습니다
OpenAPI 2.0 스키마 유효성 오류 ...
OpenAPI 3.0.x 스키마 유효성 오류 ...
해결책
자동으로 생성된 OpenAPI 명세의 경우
- 유효성 오류를 식별합니다.
- 명세에서 유효성 문제를 식별하기 위해 Swagger Editor를 사용합니다. Swagger Editor의 시각적 성격 덕분에 변경해야 할 내용을 이해하는 데 더 도움이 됩니다.
- 다른 방법으로 로그 출력을 확인하고
OpenAPI 2.0 스키마 유효성 오류
또는OpenAPI 3.0.x 스키마 유효성 오류
와 같은 접두어가 붙은 스키마 유효성 경고를 찾습니다. 각 실패한 유효성은위치
와설명
에 대한 추가 정보를 제공합니다. JSON 스키마 유효성 메시지는 복잡할 수 있으며, 편집기는 스키마 문서를 유효성 검사하는 데 도움이 될 수 있습니다.
- 사용 중인 프레임워크/기술 스택의 OpenAPI 생성에 필요한 변경 사항을 식별해 문서를 올바르게 만들기 위한 변경을 확인합니다.
- 유효성 오류가 해결된 후 파이프라인을 다시 실행합니다.
매뉴얼으로 생성된 OpenAPI 명세의 경우
- 유효성 오류를 식별합니다.
- 시각적 도구를 사용하여 OpenAPI 문서를 편집하고 유효성을 검사합니다. 예를 들어 Swagger Editor는 스키마 오류를 강조하고 가능한 해결책을 제시합니다.
- 또는 로그 출력을 확인하고
OpenAPI 2.0 스키마 유효성 오류
또는OpenAPI 3.0.x 스키마 유효성 오류
와 같은 접두어가 붙은 스키마 유효성 경고를 찾습니다. 각 실패한 유효성은위치
와설명
에 대한 추가 정보를 제공합니다. 각 유효성 실패를 수정한 후 OpenAPI 문서를 다시 제출합니다. JSON 스키마 유효성 메시지는 복잡할 수 있으며, 편집기는 스키마 문서를 유효성 검사하는 데 도움이 될 수 있습니다.
- 유효성 오류가 해결된 후 파이프라인을 다시 실행합니다.
스캐너 세션 시작 실패 (버전 헤더를 찾을 수 없음)
API Fuzzing 엔진은 스캐너 응용 프로그램 컴포넌트와의 연결을 설정할 수 없을 때 오류 메시지를 출력합니다. 이 오류 메시지는 apifuzzer_fuzz
작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 FUZZAPI_API
변수를 기본 설정에서 변경하는 것입니다.
오류 메시지
-
GitLab 13.11 및 이후에서는
Failed to start scanner session (version header not found).
- GitLab 13.10 및 이전 버전에서는
API Security version header not found. Are you sure that you are connecting to the API Security server?
.
해결 방법
-
.gitlab-ci.yml
파일에서FUZZAPI_API
변수를 삭제합니다. 이 값은 API Fuzzing CI/CD 템플릿에서 상속됩니다. 이 값을 매뉴얼으로 설정하는 대신에 이 방법을 권장합니다. - 변수를 제거할 수 없는 경우, API Fuzzing CI/CD 템플릿에서 이 값이 변경되었는지 확인한 후,
.gitlab-ci.yml
파일에서 값을 업데이트하십시오.
애플리케이션이 대상 API의 기본 URL을 결정할 수 없음
API Fuzzing 분석기는 OpenAPI 문서를 검사한 후 대상 API를 결정할 수 없는 경우 오류 메시지를 출력합니다. 이 오류 메시지는 대상 API가 .gitlab-ci.yml
파일에 설정되지 않았거나 environment_url.txt
파일에 없으며 OpenAPI 문서를 사용하여 계산할 수 없는 경우에 표시됩니다.
다른 소스를 확인할 때 API Fuzzing 분석기가 대상 API를 가져오기 위한 우선 순위가 있습니다. 먼저 FUZZAPI_TARGET_URL
을 사용하려고 시도합니다. 환경 변수가 설정되지 않은 경우 API Fuzzing 분석기는 environment_url.txt
파일을 사용하려고 합니다. environment_url.txt
파일이 없는 경우, API Fuzzing 분석기는 이제 OpenAPI 문서 내용과 FUZZAPI_OPENAPI
(제공된 경우)에 제공된 URL을 사용하여 대상 API를 계산하려고 시도합니다.
가장 적합한 해결책은 대상 API가 배포마다 변경되는지 여부에 따라 다릅니다:
정적 환경 해결책
이 해결책은 대상 API URL이 변경되지 않는(정적인) 파이프라인에 사용됩니다.
환경 변수 추가
대상 API가 동일한지 확인해야 하는 환경에 대해, FUZZAPI_TARGET_URL
환경 변수를 사용하여 대상 URL을 지정하는 것을 권장합니다. .gitlab-ci.yml
파일에 FUZZAPI_TARGET_URL
변수를 추가합니다. 이 변수는 API 테스트 대상의 기본 URL로 설정되어야 합니다. 예시:
stages:
- fuzz
include:
- template: API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_TARGET_URL: http://test-deployment/
FUZZAPI_OPENAPI: test-api-specification.json
동적 환경 해결책
동적 환경에서는 각각의 배포마다 대상 API가 변경됩니다. 이 경우, environment_url.txt
파일을 사용하는 것을 권장합니다.
environment_url.txt 파일 사용
각 파이프라인에서 대상 API URL이 변경되는 동적 환경을 지원하기 위해 API Fuzzing은 사용할 URL이 포함된 environment_url.txt
파일을 지원합니다. 이 파일은 리포지터리에 체크되지 않으며, 대신 테스트 대상을 배포하는 작업에 의해 생성되고 이후 작업에서 사용할 수 있는 artifact로 수집됩니다. environment_url.txt
파일을 생성하는 작업은 API Fuzzing 작업 이전에 실행되어야 합니다.
- 테스트 대상 배치 작업을 수정하여 프로젝트 루트에
environment_url.txt
파일에 기본 URL을 추가합니다. - 테스트 대상 배치 작업을 수정하여
environment_url.txt
을 artifact로 수집합니다.
예시:
deploy-test-target:
script:
# 배포 단계 수행
# environment_url.txt 생성 (예시)
- echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt
artifacts:
paths:
- environment_url.txt
유효하지 않은 스키마로 OpenAPI 사용
문서가 유효하지 않은 스키마로 자동 생성되거나 즉시 수정할 수 없는 경우가 있습니다. 이러한 시나리오에서 API Fuzzing은 FUZZAPI_OPENAPI_RELAXED_VALIDATION
변수를 설정하여 느슨한 유효성 검사를 수행할 수 있습니다. 예상치 못한 동작을 방지하기 위해 완전히 준수하는 OpenAPI 문서를 제공하는 것이 좋습니다.
준수하지 않는 OpenAPI 파일 편집
OpenAPI 사양을 준수하지 않는 요소를 감지하고 수정하는 것을 위해 에디터를 사용하는 것을 권장합니다. 일반적으로 에디터는 문서 유효성 검사와 스키마 준수 OpenAPI 문서를 만들기 위한 제안을 제공합니다.
에디터 | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
---|---|---|---|
Swagger Editor | YAML, JSON | YAML, JSON | YAML, JSON |
Stoplight Studio | YAML, JSON | YAML, JSON | YAML, JSON |
매뉴얼으로 생성된 OpenAPI 문서인 경우 에디터에서 문서를 로드하고 준수하지 않는 사항을 수정하세요. 자동으로 생성된 문서인 경우, 에디터에서 문서를 로드하여 스키마의 문제를 확인한 후 응용 프로그램으로 이동하여 사용하는 프레임워크에 따라 수정을 수행하세요.
OpenAPI 느슨한 유효성 검사 활성화
느슨한 유효성 검사는 OpenAPI 문서가 OpenAPI 사양을 충족하지 못하는 경우에 사용되며 여전히 다른 도구에 의해 소비될 수 있는 내용이 충분히 포함되어 있는 경우에 사용됩니다. 검증은 문서 스키마에 대해 덜 엄격하게 수행됩니다.
API Fuzzing은 여전히 OpenAPI 사양을 완전히 준수하지 않는 OpenAPI 문서를 사용할 수 있습니다. API Fuzzing 분석기에 느슨한 유효성 검사를 수행하도록 지시하기 위해 FUZZAPI_OPENAPI_RELAXED_VALIDATION
변수를 모든 값으로 설정할 수 있습니다. 예시:
stages:
- fuzz
include:
- template: API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_PROFILE: Quick-10
FUZZAPI_TARGET_URL: http://test-deployment/
FUZZAPI_OPENAPI: test-api-specification.json
FUZZAPI_OPENAPI_RELAXED_VALIDATION: 'On'
OpenAPI 문서에 있는 어떠한 작업도 지원되는 미디어 타입을 사용하지 않습니다
API 퍼징은 OpenAPI 문서 내의 지정된 미디어 타입을 사용하여 요청을 생성합니다. 지원되는 미디어 타입이 없어서 요청을 생성할 수 없는 경우 오류가 발생합니다.
에러 메시지
-
GitLab 14.10 이상에서
에러, OpenApi 문서에 있는 어떠한 작업도 지원되는 미디어 타입을 사용하지 않습니다. 'OpenAPI Specification'을 확인하여 지원되는 미디어 타입을 확인하세요.
해결책
- OpenAPI Specification 섹션에서 지원되는 미디어 타입을 검토하세요.
- 적어도 특정 작업이 지원되는 미디어 타입 중 하나를 허용하도록 OpenAPI 문서를 편집하세요. 또는 지원되는 미디어 타입을 OpenAPI 문서 수준에 설정하고 모든 작업에 적용할 수 있습니다. 이 단계에서는 애플리케이션이 해당 지원되는 미디어 타입을 수락하도록 변경해야 할 수 있습니다.
에러, `<URL>` 다운로드 중 오류가 발생했습니다: Uri에서 콘텐츠 검색 중 오류가 발생했습니다.' <URL>'. 오류: SSL 연결을 설정할 수 없습니다. 내부 예외를 확인하세요.
API 퍼징은 구식 프로토콜 및 암호를 포함한 다양한 TLS 구성과 호환됩니다. 널리 지원되지만 연결 오류가 발생할 수 있습니다. 이 오류는 API 퍼징이 지정된 URL의 서버와 안전한 연결을 설정하지 못했기 때문에 발생합니다.
이 문제를 해결하려면:
에러 메시지의 호스트가 TLS 연결을 지원하는 경우 구성에서 https://
를 http://
로 변경하세요.
예를 들어, 다음 구성에서 오류가 발생하는 경우:
stages:
- fuzz
include:
- template: API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_TARGET_URL: https://test-deployment/
FUZZAPI_OPENAPI: https://specs/openapi.json
FUZZAPI_OPENAPI
의 접두어를 https://
에서 http://
로 변경하세요.
stages:
- fuzz
include:
- template: API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_TARGET_URL: https://test-deployment/
FUZZAPI_OPENAPI: http://specs/openapi.json
URL에 비-TLS 연결을 사용할 수 없는 경우 지원팀에 문의하세요.
testssl.sh 도구를 사용하여 조사를 가속화할 수 있습니다. 영향을 받는 서버와 연결할 수 있는 bash 셸이 있는 컴퓨터에서 다음을 수행하세요:
- 최신 버전의
zip
또는tar.gz
파일을 다운로드하고 https://github.com/drwetter/testssl.sh/releases에서 압축을 푸세요. -
./testssl.sh --log https://specs
를 실행하세요. - 로그 파일을 지원 티켓에 첨부하세요.
ERROR: 작업 실패: 이미지를 가져오지 못했습니다
이 에러 메시지는 인증이 필요한 컨테이너 레지스트리에서 이미지를 가져오려고 시도할 때 발생합니다(공개되지 않은 경우).
작업 콘솔 출력에서 오류 메시지는 다음과 같습니다:
Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a)
on blue-2.shared.runners-manager.gitlab.com/default XxUrkriX
Resolving secrets
00:00
Preparing the "docker+machine" executor
00:06
Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ...
Starting service registry.example.com/my-target-app:latest ...
Pulling docker image registry.example.com/my-target-app:latest ...
WARNING: Failed to pull image with policy "always": Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s)
ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:latest" with specified policies [always]: Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s)
에러 메시지
- GitLab 15.9 이하에서,
ERROR: 작업 실패: 이미지를 가져오지 못했습니다
다음에Error response from daemon: Get IMAGE: unauthorized
가 표시됩니다.
해결책
개인 컨테이너 레지스트리에서 이미지에 액세스하는 방법에 따라 인증 자격 증명을 제공합니다. 사용되는 방법은 컨테이너 레지스트리 제공 업체와 해당 구성에 따라 결정됩니다. Azure, Google Could (GCP), AWS 등 클라우드 제공자가 제공하는 컨테이너 레지스트리를 사용하는 경우 해당 제공 업체의 문서를 확인하여 컨테이너 레지스트리에 인증하는 방법에 대한 정보를 확인하세요.
다음 예제는 정적으로 정의된 자격 증명 인증 방법을 사용합니다. 이 예에서 컨테이너 레지스트리는 registry.example.com
이고 이미지는 my-target-app:latest
입니다.
-
DOCKER_AUTH_CONFIG
데이터를 어떻게 결정할 것인가를 읽어서DOCKER_AUTH_CONFIG
의 변수 값을 계산하는 방법에 대해 이해하세요. 구성 변수DOCKER_AUTH_CONFIG
은 적절한 인증 정보를 제공하기 위한 Docker JSON 구성을 포함합니다. 예를 들어, 자격 증명abcdefghijklmn
로registry.example.com
에 액세스하는 경우 Docker JSON은 다음과 같습니다:{ "auths": { "registry.example.com": { "auth": "abcdefghijklmn" } } }
-
DOCKER_AUTH_CONFIG
를 CI/CD 변수로 추가하세요..gitlab-ci.yml
파일에 구성 변수를 직접 추가하는 대신 프로젝트 CI/CD 변수를 만드세요. -
작업을 다시 실행하면 정적으로 정의된 자격 증명이 사용되어
registry.example.com
의 비공개 컨테이너 레지스트리에 로그인하여 이미지my-target-app:latest
를 가져올 수 있습니다. 성공하면 작업 콘솔에 다음과 같은 출력이 표시됩니다:Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a) on blue-4.shared.runners-manager.gitlab.com/default J2nyww-s Resolving secrets 00:00 Preparing the "docker+machine" executor 00:56 Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ... Starting service registry.example.com/my-target-app:latest ... Authenticating with credentials from $DOCKER_AUTH_CONFIG Pulling docker image registry.example.com/my-target-app:latest ... Using docker image sha256:139c39668e5e4417f7d0eb0eeb74145ba862f4f3c24f7c6594ecb2f82dc4ad06 for registry.example.com/my-target-app:latest with digest registry.example.com/my-target- app@sha256:2b69fc7c3627dbd0ebaa17674c264fcd2f2ba21ed9552a472acf8b065d39039c ... Waiting for services to be up and running (timeout 30 seconds)...