- API Fuzzing 작업이 N 시간 후에 타임아웃됨
- API Fuzzing 작업 완료에 너무 많은 시간이 걸림
-
에러:
API Fuzzing 'http://127.0.0.1:5000' 대기 중 오류 발생
OpenAPI 문서가 유효하지 않습니다. 게시된 OpenAPI 스키마를 사용하여 문서를 확인하는 중 오류가 발견되었습니다
스캐너 세션 시작에 실패했습니다(버전 헤더를 찾을 수 없음)
-
애플리케이션이 대상 API의 기본 URL을 결정할 수 없음
- 잘못된 스키마를 사용한 OpenAPI 사용
OpenAPI 문서에 포함된 작업이 지원되는 미디어 타입을 사용하지 않음
오류, 'URL'에서 내용을 검색하는 동안 오류가 발생했습니다: URI에서 내용 검색 중 오류 발생. 오류: SSL 연결을 설정할 수 없음. 내부 예외 참조하세요.
ERROR: Job failed: failed to pull image
문제 해결
API Fuzzing 작업이 N 시간 후에 타임아웃됨
더 큰 리포지터리의 경우, 기본으로 설정된 작은 호스팅 러너인 리눅스에서 API Fuzzing 작업이 시간 초과될 수 있습니다. 작업에서 이러한 일이 발생하는 경우 더 큰 러너로 확장해야 합니다.
지원을 위한 다음 문서 섹션을 참조하세요:
API Fuzzing 작업 완료에 너무 많은 시간이 걸림
성능 튜닝 및 테스트 속도 를 참조하세요.
에러: API Fuzzing 'http://127.0.0.1:5000' 대기 중 오류 발생
v1.6.196 이전 버전의 API Fuzzing 분석기에 버그가 있어 특정 조건 하에서 백그라운드 프로세스가 실패할 수 있습니다. 해결책은 더 새로운 버전의 API Fuzzing 분석기로 업데이트하는 것입니다.
버전 정보는 apifuzzer_fuzz
작업의 작업 세부 정보에서 찾을 수 있습니다.
v1.6.196 이상 버전에서 문제가 발생하는 경우, 지원팀에 문의하고 다음 정보를 제공하세요:
- 이 문제가 Dynamic Analysis Team으로 eskalasi될 것을 요청하는 문제 해결 섹션을 참조하세요.
- 작업의 전체 콘솔 출력.
- 작업 세부 정보 페이지의 오른쪽 패널에서 사용 가능한
gl-api-security-scanner.log
파일. 찾아보기 버튼을 선택하거나 직접 파일을 검색하여 모든 artifact를 다운로드할 수 있습니다. -
.gitlab-ci.yml
파일에서apifuzzer_fuzz
작업 정의.
에러 메시지
-
GitLab 15.6 및 이후에서
API Fuzzing 'http://127.0.0.1:5000' 대기 중 오류 발생
- GitLab 15.5 및 이전 버전에서
API Security 'http://127.0.0.1:5000' 대기 중 오류 발생
.
스캐너와 세션을 시작할 수 없습니다. 다시 시도하고 문제가 지속되면 지원팀에 문의하세요.
API Fuzzing 엔진은 스캐너 응용프로그램 컴포넌트와 연결을 설정하지 못할 때 오류 메시지를 출력합니다. 오류 메시지는 apifuzzer_fuzz
작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 선택한 포트를 백그라운드 컴포넌트가 이미 사용 중이기 때문에 사용할 수 없는 것입니다. 이 에러는 타이밍이 중요한 경우 (레이스 조건), 가끔 발생할 수 있습니다. 이 문제는 주로 다른 서비스가 컨테이너에 매핑되어 포트 충돌이 발생하는 쿠버네티스 환경에서 가장 자주 발생합니다.
해결책에 대해 진행하기 전에, 문제가 발생한 이유가 포트가 이미 사용 중인지 확인하는 것이 중요합니다. 확인해야 할 사항:
-
작업 콘솔로 이동합니다.
-
gl-api-security-scanner.log
artifact를 찾습니다. 다운로드를 선택하여 모든 artifact를 다운로드하고 파일을 검색하거나, 찾아보기를 선택하여 필요한 artifact를 직접 찾을 수 있습니다. -
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 Specification이 게시된 스키마에 대해 유효성을 검사합니다. 제공된 OpenAPI Specification에 유효성 오류가 있으면 이 오류가 표시됩니다. OpenAPI Specification을 매뉴얼으로 작성할 때 오류가 발생할 수 있으며 스키마를 생성할 때도 오류가 발생할 수 있습니다.
자동으로 생성된 OpenAPI Specification의 경우, 유효성 오류는 일반적으로 코드 어노테이션의 누락으로 인해 발생합니다.
에러 메시지
-
OpenAPI 문서가 유효하지 않습니다. 게시된 OpenAPI 스키마를 사용하여 문서를 확인하는 중 오류가 발견되었습니다
OpenAPI 2.0 스키마 유효성 검사 오류 ...
OpenAPI 3.0.x 스키마 유효성 검사 오류 ...
해결책
자동으로 생성된 OpenAPI Specification의 경우
- 유효성 오류를 식별합니다.
- Swagger Editor를 사용하여 명세의 유효성 문제를 식별합니다. Swagger Editor의 비주얼한 특성 때문에 어떤 부분을 변경해야 하는지 이해하기가 쉽습니다.
- 또는 로그 출력을 확인하고 스키마 유효성 경고를 찾습니다. 이러한 경고는
OpenAPI 2.0 스키마 유효성 검사 오류
또는OpenAPI 3.0.x 스키마 유효성 검사 오류
와 같은 메시지로 시작합니다. 각 실패한 유효성은location
및description
에 대한 추가 정보를 제공합니다. JSON 스키마 유효성 메시지는 복잡할 수 있으며, 에디터는 스키마 문서의 유효성을 검사하는 데 도움이 될 수 있습니다.
- 사용 중인 프레임워크/기술 스택의 OpenAPI 생성 문서에 대한 문서를 검토하세요. 올바른 OpenAPI 문서를 생성하도록 하기 위해 필요한 변경 사항을 식별합니다.
- 유효성 오류가 해결된 후에 파이프라인을 다시 실행합니다.
매뉴얼으로 작성된 OpenAPI Specification의 경우
- 유효성 오류를 식별합니다.
- 가장 간단한 해결책은 시각적 도구를 사용하여 OpenAPI 문서를 편집하고 유효성을 검사하는 것입니다. 예를 들어 Swagger Editor는 스키마 오류와 가능한 해결책을 강조 표시합니다.
- 또는 로그 출력을 확인하고 스키마 유효성 경고를 찾습니다. 이러한 경고는
OpenAPI 2.0 스키마 유효성 검사 오류
또는OpenAPI 3.0.x 스키마 유효성 검사 오류
와 같은 메시지로 시작합니다. 각 실패한 유효성은location
및description
에 대한 추가 정보를 제공합니다. 각각의 유효성 실패를 수정한 후 OpenAPI 문서를 다시 제출합니다.
- 유효성 오류가 해결된 후에 파이프라인을 다시 실행합니다.
스캐너 세션 시작에 실패했습니다(버전 헤더를 찾을 수 없음)
API Fuzzing 엔진은 스캐너 애플리케이션 컴포넌트와 연결을 설정할 수 없는 경우 오류 메시지를 출력합니다. 이 오류 메시지는 apifuzzer_fuzz
작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 FUZZAPI_API
변수를 기본값에서 변경하는 것입니다.
오류 메시지
스캐너 세션 시작에 실패했습니다(버전 헤더를 찾을 수 없음).
해결 방법
-
.gitlab-ci.yml
파일에서FUZZAPI_API
변수를 제거합니다. 이 값은 API Fuzzing CI/CD 템플릿에서 상속됩니다. 값을 매뉴얼으로 설정하는 대신 이 방법을 권장합니다. - 변수를 제거할 수 없는 경우, 최신 API Fuzzing CI/CD 템플릿에서 이 값이 변경되었는지 확인한 후, 필요에 따라
.gitlab-ci.yml
파일에서 값을 업데이트합니다.
애플리케이션이 대상 API의 기본 URL을 결정할 수 없음
API Fuzzing 분석기는 OpenAPI 문서를 검사한 후 대상 API를 결정할 수 없는 경우 오류 메시지를 출력합니다. 이 오류 메시지는 .gitlab-ci.yml
파일에서 대상 API가 설정되지 않았거나 environment_url.txt
파일에서 사용할 수 없으며 OpenAPI 문서를 사용하여 대상 API를 계산할 수 없는 경우에 표시됩니다.
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 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 사양을 완전히 준수하지 않는 문서를 사용할 수 있습니다. 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 Fuzzing은 OpenAPI 문서에 지정된 미디어 타입을 사용하여 요청을 생성합니다. 지원되는 미디어 타입이 없어서 요청을 생성할 수 없는 경우 오류가 발생합니다.
오류 메시지
오류, OpenAPI 문서에 포함된 작업이 지원되는 미디어 타입을 사용하지 않음. 지원되는 미디어 타입을 확인하려면 'OpenAPI 사양'을 확인하세요.
해결 방법
- OpenAPI 사양 섹션에서 지원되는 미디어 타입을 검토하세요.
- OpenAPI 문서를 편집하여 적어도 특정 작업이 지원하는 미디어 타입 중 하나를 수락하도록 수정하세요. 또는 지원되는 미디어 타입을 OpenAPI 문서 수준에 설정하고 모든 작업에 적용할 수 있습니다. 이 단계는 지원되는 미디어 타입이 애플리케이션에서 수락되도록 변경 사항을 적용하기 위해 애플리케이션에서 변경이 필요할 수 있습니다.
오류, 'URL'에서 내용을 검색하는 동안 오류가 발생했습니다: URI에서 내용 검색 중 오류 발생. 오류: SSL 연결을 설정할 수 없음. 내부 예외 참조하세요.
API fuzzing은 낡은 프로토콜 및 암호를 포함한 다양한 TLS 구성과 호환됩니다. 넓은 지원을 받지만 연결 오류가 발생할 수도 있습니다. 이 오류는 API fuzzing이 주어진 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 연결을 사용할 수 없는 경우 지원팀에 문의하세요.
테스트ssl.sh 도구를 사용하여 조사를 가속화할 수 있습니다. bash 셸을 사용하는 컴퓨터에서 다음 단계를 실행하세요:
- 최신 릴리스
zip
또는tar.gz
파일을 다운로드하고 https://github.com/drwetter/testssl.sh/releases에서 압축 해제합니다. -
./testssl.sh --log https://specs
을 실행합니다. - 로그 파일을 지원 티켓에 첨부합니다.
ERROR: Job failed: failed to pull image
이 오류 메시지는 컨테이너 레지스트리에서 이미지를 가져오기 위해 인증이 필요한 경우 (공개되지 않은 경우) 발생합니다.
작업 콘솔 출력에서 오류는 다음과 같습니다.
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: Job failed: failed to pull image
다음에Error response from daemon: Get IMAGE: unauthorized
가 따릅니다.
해결책
인증 자격 증명은 private container registry에서 이미지에 액세스하는 방법에 설명된 방법을 사용하여 제공됩니다. 사용하는 방법은 컨테이너 레지스트리 제공업체와 해당 구성에 따라 결정됩니다. Azure, Google Cloud (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
의 private 컨테이너 레지스트리에 로그인하여 이미지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)...