문제 해결

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

대형 리포지터리의 경우, DAST API 작업은 기본으로 설정된 small SaaS runner on Linux에서 시간이 초과될 수 있습니다. 이 문제가 발생하는 경우, 더 큰 runner로 확장해야 합니다.

지원을 받으려면 다음 문서 섹션을 확인하세요:

DAST API 작업 완료에 너무 많은 시간이 소요됨

성능 튜닝 및 테스트 속도를 참고하세요.

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

이 문제는 DAST API 분석기의 이전 버전(v1.6.196 이전)에서 특정 조건 하에서 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다. 해결책은 새로운 버전의 DAST API 분석기로 업데이트하는 것입니다.

버전 정보는 dast_api 작업의 작업 세부 정보에서 확인할 수 있습니다.

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

  1. 이 문제가 승격되어야 한다는 증거를 가리키는 이 문제 해결 섹션을 참조하고 Dynamic Analysis Team으로 문제가 승격되도록 요청합니다.
  2. 작업의 전체 콘솔 출력.
  3. 작업 아티팩트로 제공되는 gl-api-security-scanner.log 파일. 작업 세부 정보 페이지의 오른쪽 패널에서 찾아보기 버튼을 선택합니다.
  4. .gitlab-ci.yml 파일에서 dast_api 작업 정의.

오류 메시지

  • GitLab 15.6 및 이후 버전, Error waiting for DAST API '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 scanner session (version header not found)

DAST API 엔진에서는 스캐너 응용 프로그램 컴포넌트와 연결을 수립할 수 없을 때 오류 메시지가 출력됩니다. 이 오류 메시지는 dast_api 작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 DAST_API_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 DAST API server?.

해결책

  • .gitlab-ci.yml 파일에서 DAST_API_API 변수를 제거합니다. 이 값은 DAST API CI/CD 템플릿에서 상속되는 것을 권장합니다. 매뉴얼으로 값을 설정하는 대신 이 방법을 권장합니다.
  • 변수를 제거할 수 없는 경우, 최신 버전의 DAST API CI/CD 템플릿에서 이 값이 변경되었는지 확인합니다. 변경된 경우, .gitlab-ci.yml 파일에서 값을 업데이트하세요.

Failed to start session with scanner. Please retry, and if the problem persists reach out to support.

DAST API 엔진은 스캐너 응용 프로그램 컴포넌트와 연결을 수립할 수 없을 때 오류 메시지가 출력됩니다. 이 오류 메시지는 dast_api 작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 선택한 포트를 백그라운드 컴포넌트가 이미 사용 중인 경우입니다. 시간이 교차하는 요소가 들어갈 수 있으므로 이 문제는 때때로 간헐적으로 발생할 수 있습니다. 이 문제는 Kubernetes 환경에서 가장 자주 발생하는데, 이는 다른 서비스가 도커에 매핑되어 포트 충돌을 일으키기 때문입니다.

해결책을 진행하기 전에, 반드시 문제가 발생한 이유가 포트가 이미 차지되었기 때문인지 확인하는 것이 중요합니다. 이것이 원인임을 확인하려면:

  1. 작업 콘솔로 이동합니다.
  2. gl-api-security-scanner.log 아티팩트를 찾습니다. 다운로드를 선택하여 모든 아티팩트를 다운로드하고 파일을 찾거나, 찾아보기를 선택하여 직접 검색합니다.
  3. 텍스트 편집기에서 gl-api-security-scanner.log 파일을 엽니다.
  4. 포트가 이미 차지되었기 때문에 오류 메시지가 생성된 경우, 파일에 다음과 유사한 메시지가 표시됩니다:

  • GitLab 15.5 및 이후 버전: 

    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 및 이후 버전에서 구성 변수 DAST_API_API_PORT가 소개되었습니다. 이 구성 변수를 사용하여 스캐너 백그라운드 컴포넌트에 대해 고정된 포트 번호를 설정할 수 있습니다.

해결책

  1. .gitlab-ci.yml 파일에서 구성 변수 DAST_API_API_PORT를 정의합니다.
  2. DAST_API_API_PORT 값을 1024보다 큰 사용 가능한 포트 번호로 업데이트합니다. GitLab에서 사용 중이 아닌지 확인하는 것을 권장합니다. 패키지 기본값에서 GitLab이 사용하는 포트의 전체 디렉터리을 확인하세요.

Application cannot determine the base URL for the target API

DAST API 엔진은 OpenAPI 문서를 검사한 후 대상 API를 결정할 수 없을 때 오류 메시지를 출력합니다. 이 오류 메시지는 대상 API가 .gitlab-ci.yml 파일에 설정되지 않았거나 environment_url.txt 파일에 없으며 OpenAPI 문서를 사용하여 대상 API를 계산할 수 없는 경우에 표시됩니다.

DAST API 엔진은 서로 다른 소스를 확인할 때 대상 API를 가져오기 위해 우선순위가 있습니다. 먼저 DAST_API_TARGET_URL을 사용하려고 시도합니다. 환경 변수가 설정되지 않았다면 DAST API 엔진은 environment_url.txt 파일을 사용하려고 시도합니다. environment_url.txt 파일이 없는 경우 DAST API 엔진은 대상 API를 계산하기 위해 OpenAPI 문서 내용과 DAST_API_OPENAPI(URL이 제공된 경우)를 사용합니다.

가장 적합한 해결책은 대상 API가 각 배포마다 변경되는지 여부에 따라 다릅니다. 정적 환경에서는 대상 API가 각 배포마다 동일하므로 정적 환경 솔루션을 참조하십시오. 대상 API가 각 배포마다 변경되는 경우 동적 환경 솔루션을 적용해야 합니다.

정적 환경 솔루션

이 솔루션은 대상 API URL이 변경되지 않는 파이프라인을 위한 것입니다(정적).

환경 변수 추가

대상 API가 동일한 상태에 있는 환경에 대해서는 DAST_API_TARGET_URL 환경 변수를 사용하여 대상 URL을 지정하는 것이 좋습니다. .gitlab-ci.yml에서 DAST_API_TARGET_URL 변수를 추가하세요. 변수는 API 테스트 대상의 기본 URL로 설정되어야 합니다. 예시는 다음과 같습니다: 

stages:
  - dast

include:
  - template: DAST-API.gitlab-ci.yml

variables:
  DAST_API_TARGET_URL: http://test-deployment/
  DAST_API_OPENAPI: test-api-specification.json

동적 환경 솔루션

동적 환경에서는 각각의 배포에 따라 대상 API가 변경됩니다. 이 경우 environment_url.txt 파일을 사용하는 것이 좋습니다.

environment_url.txt 사용

파이프라인 중에 대상 API URL이 각 배포마다 변경되는 동적 환경을 지원하기 위해 DAST API 엔진은 environment_url.txt 파일을 지원합니다. 이 파일은 리포지터리에 체크인되지 않으며 대신 테스트 대상을 배포하는 작업에서 생성되어 이후 파이프라인의 다른 작업에서 사용할 수 있는 artifact로 수집됩니다. environment_url.txt 파일을 생성하는 작업은 DAST API 엔진 작업 전에 실행되어야 합니다.

  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 사용

문서가 잘못된 스키마로 자동 생성되거나 즉시 수정할 수 없는 경우가 있습니다. 이러한 시나리오에서는 DAST API가 DAST_API_OPENAPI_RELAXED_VALIDATION 변수를 설정하여 완전히 호환되는 OpenAPI 문서를 제공하는 것을 권장합니다.

호환되지 않는 OpenAPI 파일 편집

OpenAPI 사양을 준수하지 않는 요소를 감지하고 수정하기 위해 편집기 사용을 권장합니다. 편집기는 일반적으로 문서 유효성 검사를 제공하며 스키마에 맞는 OpenAPI 문서를 작성하기 위한 제안을 제공합니다. 추천되는 편집기는 다음과 같습니다:

편집기 OpenAPI 2.0 OpenAPI 3.0.x OpenAPI 3.1.x
Swagger 에디터 YAML, JSON YAML, JSON YAML, JSON
Stoplight Studio YAML, JSON YAML, JSON YAML, JSON

매뉴얼으로 생성된 OpenAPI 문서는 편집기에 로드하고 호환되지 않는 항목을 수정하세요. 자동으로 생성된 문서라면 편집기에서 로드하여 스키마의 문제를 식별한 후 애플리케이션으로 이동하여 사용 중인 프레임워크에 따라 수정을 수행하세요.

OpenAPI 완화 유효성 활성화

완화된 검증은 OpenAPI 문서가 OpenAPI 사양을 충족하지 못하는 경우에 사용되며 여전히 다른 도구에서 사용할 수 있는 내용이 충분히 있을 때 수행됩니다. 문서 스키마에 대해 덜 엄밀하게 검증됩니다.

DAST API는 여전히 OpenAPI 사양을 완전히 준수하지 않는 문서를 사용할 수 있습니다. DAST API에 완화된 검증을 수행하도록 지시하려면 DAST_API_OPENAPI_RELAXED_VALIDATION 변수를 설정하세요. 예를 들면: 

stages:
  - dast

include:
  - template: DAST-API.gitlab-ci.yml

variables:
  DAST_API_PROFILE: Quick
  DAST_API_TARGET_URL: http://test-deployment/
  DAST_API_OPENAPI: test-api-specification.json
  DAST_API_OPENAPI_RELAXED_VALIDATION: 'On'

OpenAPI 문서의 작업이 지원되는 미디어 타입을 사용하지 않음

DAST API는 OpenAPI 문서에서 지정된 미디어 타입을 사용하여 요청을 생성합니다. 지원되는 미디어 타입이 없어서 요청을 만들 수 없는 경우 오류가 발생합니다.

오류 메시지

  • GitLab 14.10 및 이후 버전에서 오류, OpenApi 문서의 작업이 지원되는 미디어 타입을 소비하지 않습니다. 사용 가능한 미디어 타입을 확인하려면 'OpenAPI 사양'을 확인하세요.

해결책

  1. OpenAPI 사양 섹션에서 지원되는 미디어 타입을 검토합니다.
  2. OpenAPI 문서를 수정하여 지정된 작업 중 하나가 지원되는 미디어 타입을 수용하도록 합니다. 대안으로 OpenAPI 문서 수준에 지원되는 미디어 타입을 설정하고 모든 작업에 적용될 수 있습니다. 이 단계는 지원되는 미디어 타입이 애플리케이션에 의해 수용되도록 하기 위해 애플리케이션에서 변경이 필요할 수 있습니다.

Error, error occurred trying to download `<URL>`: 해당 Uri에서 콘텐츠를 검색하려고 시도하는 동안 오류가 발생했습니다: SSL 연결을 설정할 수 없어 내부 예외를 확인하십시오.

DAST API는 낡은 프로토콜 및 암호를 포함한 다양한 TLS 구성과 호환됩니다. 널리 지원되지만 연결 오류가 발생할 수 있습니다. 이 오류는 DAST API가 지정된 URL의 서버와 안전한 연결을 설정하지 못했기 때문에 발생합니다.

이 문제를 해결하려면:

오류 메시지의 호스트가 TLS 연결을 지원하는 경우 구성에서 https://를 http://으로 변경하십시오. 예를 들어, 다음 구성에서 오류가 발생하는 경우: 

stages:
  - dast

include:
  - template: DAST-API.gitlab-ci.yml

variables:
  DAST_API_TARGET_URL: https://test-deployment/
  DAST_API_OPENAPI: https://specs/openapi.json

DAST_API_OPENAPI의 접두어를 https://에서 http://로 변경하십시오. 

stages:
  - dast

include:
  - template: DAST-API.gitlab-ci.yml

variables:
  DAST_API_TARGET_URL: https://test-deployment/
  DAST_API_OPENAPI: http://specs/openapi.json

URL에 비안전한 TLS 연결을 사용할 수 없는 경우 지원팀에 문의하십시오.

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

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

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 Could (GCP), AWS 등과 같은 클라우드 제공 업체가 제공하는 컨테이너 레지스트리를 사용하는 경우 해당 제공 업체의 문서에서 해당 컨테이너 레지스트리에 인증하는 방법에 대한 정보를 확인하십시오.

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

  1. DOCKER_AUTH_CONFIG 변수 값 계산 방법을 이해하려면 당신의 DOCKER_AUTH_CONFIG 데이터 결정하기를 참조하십시오. 구성 변수 DOCKER_AUTH_CONFIG에는 적절한 인증 정보를 제공하기 위한 Docker JSON 구성이 포함되어 있습니다. 예를 들어, registry.example.com에 대한 비공개 컨테이너 레지스트리에 액세스하기 위해 자격 증명 abcdefghijklmn을 사용하는 경우 Docker JSON은 다음과 같습니다: 

     {
     "auths": {
         "registry.example.com": {
             "auth": "abcdefghijklmn"
         }
     }
 }
  2. DOCKER_AUTH_CONFIG를 CI/CD 변수로 추가하십시오. 구성 변수를 .gitlab-ci.yml 파일에 직접 추가하는 대신, 프로젝트 CI/CD 변수를 생성해야 합니다.

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