문제 해결

API Fuzzing 작업이 N시간 후에 타임 아웃됨

대형 저장소의 경우 small SaaS runner on Linux에서 기본으로 설정된 대로 시간이 초과될 수 있습니다. 이 경우에는 더 큰 runner로 스케일을 조정해야 합니다.

지원을 위한 아래 문서 섹션을 확인해 보세요:

API Fuzzing 작업이 완료되기까지 시간이 너무 오래 걸림

성능 튜닝 및 테스트 속도를 확인하세요.

오류: Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available

버전 v1.6.196 이전의 API Fuzzing analyzer에는 특정 조건에서 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다. 해결책은 더 최신 버전의 API Fuzzing analyzer로 업데이트하는 것입니다.

버전 정보는 apifuzzer_fuzz 작업의 세부 정보에서 찾을 수 있습니다.

v1.6.196 이상의 버전에서 문제가 발생하는 경우, 다음 정보를 제공하면 지원팀에 문의하세요:

  1. 이 문제 해결 섹션을 참조하고 문제를 Dynamic Analysis 팀에 Eskalation해 달라고 요청합니다.
  2. 작업의 전체 콘솔 출력.
  3. 작업 아티팩트로서 사용 가능한 gl-api-security-scanner.log 파일입니다. 작업 상세 페이지의 오른쪽 패널에서 Browse 버튼을 선택하세요.
  4. .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 작업의 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 선택된 포트를 백그라운드 구성 요소가 이미 사용 중인 경우입니다. 시간이 관련된 경우, 이 문제는 때때로 발생할 수 있습니다. 이 문제는 기타 서비스가 컨테이너로 매핑될 때 가장 많이 발생합니다.

솔루션을 진행하기 전에 포트가 이미 사용 중이라는 것을 확인하는 것이 중요합니다. 이를 확인하려면 다음을 수행하세요:

  1. 작업 콘솔로 이동합니다.
  2. gl-api-security-scanner.log 아티팩트를 찾습니다. 모든 아티팩트를 다운로드하거나 직접 찾는 방법 중 선택하세요.
  3. 텍스트 편집기에서 gl-api-security-scanner.log 파일을 엽니다.
  4. 포트가 이미 사용 중이라는 오류 메시지를 확인합니다.

오류 메시지를 찾지 못했다면 작업 콘솔 출력에 표시된 동일한 오류 메시지를 해결하기 위한 다른 문제 해결 섹션을 확인하세요. 더 이상 옵션이 없다면 적절한 채널을 통해 지원을 받거나 개선을 요청하세요.

이슈가 포트가 이미 사용 중이라는 사실로 인해 발생했다는 것을 확인한 후, GitLab 15.5 및 이후 버전에서 구성 변수 FUZZAPI_API_PORT가 도입되었습니다. 이 구성 변수를 사용하여 스캐너 백그라운드 구성 요소의 고정 포트 번호를 설정할 수 있습니다.

해결책

  1. .gitlab-ci.yml 파일이 구성 변수 FUZZAPI_API_PORT를 정의했는지 확인합니다.
  2. FUZZAPI_API_PORT 값을 1024보다 큰 사용 가능한 포트 번호로 업데이트합니다. 새 값이 GitLab에서 사용되지 않음을 확인하는 것을 권장합니다. GitLab에서 사용하는 포트의 전체 목록은 패키지 기본값을 참조하세요.

오류, OpenAPI 문서가 유효하지 않습니다. 문서를 게시된 OpenAPI 스키마를 사용하여 유효성을 검사하는 동안 오류가 발견되었습니다.

API Fuzzing 작업을 시작할 때 OpenAPI 명세는 게시된 스키마에 대해 유효성을 검사합니다. 제공된 OpenAPI 명세에 유효성 오류가 있을 때 이 오류가 표시됩니다. OpenAPI 명세를 수동으로 작성하는 경우나 스키마가 생성된 경우에도 오류가 발생할 수 있습니다.

자동으로 생성된 OpenAPI 명세의 경우 유효성 오류는 종종 코드 어노테이션의 누락으로 인해 발생합니다.

오류 메시지

  • GitLab 13.11 이상, 오류, OpenAPI 문서가 유효하지 않습니다. 게시된 OpenAPI 스키마를 사용하여 문서의 유효성을 검사하는 중 오류가 발견되었습니다.
    • OpenAPI 2.0 스키마 유효성 오류...
    • OpenAPI 3.0.x 스키마 유효성 오류...

해결 방법

자동으로 생성된 OpenAPI 명세의 경우

  1. 유효성 오류를 식별합니다.
    1. Swagger Editor를 사용하여 명세서의 유효성 문제를 식별하세요. Swagger Editor의 시각적 특성 덕분에 어떤 부분을 변경해야 하는지 이해하기 쉬워집니다.
    2. 또는 로그 출력을 확인하고 스키마 유효성 경고를 찾으세요. OpenAPI 2.0 스키마 유효성 오류나 OpenAPI 3.0.x 스키마 유효성 오류와 같은 메시지로 시작합니다. 각 유효성 실패는 위치와 설명에 대한 추가 정보를 제공합니다. JSON 스키마 유효성 검사 메시지는 복잡할 수 있으며 편집기를 사용하여 스키마 문서를 검증하는 데 도움을 받을 수 있습니다.
  2. 사용 중인 프레임워크/기술 스택의 OpenAPI 생성에 대한 문서를 검토하세요. 올바른 OpenAPI 문서를 생성하기 위해 필요한 변경 사항을 식별합니다.
  3. 유효성 문제가 해결된 후에는 파이프라인을 다시 실행하세요.

수동으로 작성된 OpenAPI 명세의 경우

  1. 유효성 오류를 식별합니다.
    1. 가장 간단한 해결책은 시각적 툴을 사용하여 OpenAPI 문서를 편집하고 검증하는 것입니다. 예를 들어 Swagger Editor는 스키마 오류와 가능한 해결책을 강조합니다.
    2. 또는 로그 출력을 확인하고 스키마 유효성 경고를 찾으세요. OpenAPI 2.0 스키마 유효성 오류나 OpenAPI 3.0.x 스키마 유효성 오류와 같은 메시지로 시작합니다. 각 유효성 실패는 위치와 설명에 대한 추가 정보를 제공합니다. 각 유효성 실패를 수정한 다음 OpenAPI 문서를 다시 제출하세요. JSON 스키마 유효성 메시지는 복잡할 수 있으며 편집기를 사용하여 스키마 문서를 검증하는 데 도움을 받을 수 있습니다.
  2. 유효성 문제가 해결된 후에는 파이프라인을 다시 실행하세요.

스캐너 세션을 시작하지 못했습니다 (버전 헤더를 찾을 수 없음)

API Fuzzing 엔진은 스캐너 애플리케이션 구성요소와 연결을 확립하지 못할 때 오류 메시지를 출력합니다. 이 오류 메시지는 apifuzzer_fuzz 작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 FUZZAPI_API 변수를 기본값에서 변경한 경우입니다.

오류 메시지

  • GitLab 13.11 이상, 스캐너 세션을 시작하지 못했습니다 (버전 헤더를 찾을 수 없음).
  • GitLab 13.10 이하, API Security 버전 헤더를 찾을 수 없습니다. API Security 서버에 연결 중임을 확실합니까?.

해결 방법

  • .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을 사용하려고 하고, 환경 변수가 설정되지 않았다면 environment_url.txt 파일을 사용하려고 합니다. environment_url.txt 파일이 없으면 API Fuzzing 분석기는 FUZZAPI_OPENAPI에서 제공된 URL(제공되었다면) 및 OpenAPI 문서 내용을 사용하여 대상 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 작업 이전에 실행되어야 합니다.

  1. 테스트 대상 배포 작업을 수정하여 프로젝트 루트에 environment_url.txt 파일에 기본 URL을 추가합니다.
  2. 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 Fuzzing은 OpenAPI 문서에서 지정된 미디어 유형을 사용하여 요청을 생성합니다. 지원되는 미디어 유형이 없어서 요청을 생성할 수 없는 경우 오류가 발생합니다.

오류 메시지

  • GitLab 14.10 이후에는 Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.

해결 방법

  1. OpenAPI 사양 섹션에서 지원되는 미디어 유형을 검토하세요.
  2. OpenAPI 문서를 수정하여 특정 작업이 지원되는 미디어 유형을 허용하도록 합니다. 또는 OpenAPI 문서 수준에서 지원되는 미디어 유형을 설정하고 모든 작업에 적용하도록 합니다. 해당 단계에서 응용 프로그램을 수정하여 지원되는 미디어 유형이 응용 프로그램에서 수락되도록 합니다.

<URL> 다운로드 중 오류가 발생하였습니다: Uri에서 콘텐츠를 검색하는 중 오류가 발생했습니다: 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에 비안전한 연결을 사용할 수 없는 경우 지원팀에 문의하십시오.

testssl.sh 도구를 사용하여 조사를 가속화할 수 있습니다. 영향을 받는 서버에 대한 bash 쉘과 연결이있는 기계에서:

  1. 최신 릴리스 zip 또는 tar.gz 파일을 https://github.com/drwetter/testssl.sh/releases에서 다운로드하고 추출합니다.
  2. ./testssl.sh --log https://specs를 실행합니다.
  3. 로그 파일을 지원 티켓에 첨부합니다.

오류: 작업 실패: 이미지를 가져오는 데 실패함

이 오류 메시지는 인증이 필요한 컨테이너 레지스트리에서 이미지를 가져올 때 발생합니다(공개되지 않음).

작업 콘솔 출력에서 오류는 다음과 같습니다: 

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가 옵니다.

해결 방법

컨테이너 레지스트리 공급자와 해당 구성에 따라 인증 자격 증명을 제공합니다. 타사(예: Azure, Google Could(GCP), AWS 등)의 컨테이너 레지스트리를 사용하는 경우 해당 레지스트리 공급자의 문서를 확인하여 인증하는 방법에 대한 정보를 확인하십시오.

다음 예에서는 정적으로 정의된 자격 증명 인증 방법을 사용합니다. 이 예에서 컨테이너 레지스트리는 registry.example.com 이고 이미지는 my-target-app:latest입니다.

  1. DOCKER_AUTH_CONFIG 데이터를 결정하는 방법에 대해 자세히 알아봅니다. 설정 변수 DOCKER_AUTH_CONFIG에는 적절한 인증 정보를 제공하는 도커 JSON 구성이 포함되어 있습니다. 예를 들어, 자격 증명 abcdefghijklmn으로 비공개 컨테이너 레지스트리 registry.example.com에 액세스하려면 도커 JSON은 다음과 같습니다: 

     {
     "auths": {
         "registry.example.com": {
             "auth": "abcdefghijklmn"
         }
     }
 }
  2. DOCKER_AUTH_CONFIG를 CI/CD 변수로 추가합니다. 설정 변수를 .gitlab-ci.yml 파일에 직접 추가하는 대신 프로젝트 CI/CD 변수를 만들어야 합니다.

  3. 작업을 다시 실행하면 정적으로 정의된 자격 증명이 사용되어 비공개 컨테이너 레지스트리 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)...