Troubleshooting

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

더 큰 저장소의 경우 기본으로 설정된 작은 SaaS 러너에서 DAST API 작업이 시간 초과될 수 있습니다. 작업 중에 이러한 문제가 발생하면 더 큰 러너로 확장해야 합니다.

도움을 얻으려면 다음 설명서 섹션을 참조하세요:

DAST API 작업이 완료하는 데 너무 오래 걸림

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

오류: ‘DAST API ‘http://127.0.0.1:5000’를 사용 가능하게 기다리는 중에 오류 발생’

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

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

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

  1. 이 문제를 트러블슈팅 섹션으로 언급하고, 동적 분석 팀에 문제를 Eskalate해야 한다고 요청하세요.
  2. 작업의 전체 콘솔 출력.
  3. 작업 세부 정보 페이지의 오른쪽 패널에서 사용 가능한 gl-api-security-scanner.log 파일. 찾아보기 버튼을 선택하여 모든 아티팩트를 다운로드하거나 파일을 직접 검색할 수 있습니다.
  4. .gitlab-ci.yml 파일에서 dast_api 작업 정의.

오류 메시지

  • GitLab 15.6 및 이후에서 'DAST API 'http://127.0.0.1:5000'를 사용 가능하게 기다리는 중에 오류 발생
  • GitLab 15.5 및 이전 버전에서 'API Security 'http://127.0.0.1:5000'를 사용 가능하게 기다리는 중에 오류 발생

스캐너 세션 시작 실패 (버전 헤더를 찾을 수 없음)

DAST API 엔진은 스캐너 응용 프로그램 구성 요소와 연결을 설정할 수 없을 때 오류 메시지를 출력합니다. 이 오류 메시지는 dast_api 작업의 작업 출력 창에 표시됩니다. 이 문제의 일반적인 원인은 DAST_API_API 변수를 기본값에서 변경한 것입니다.

오류 메시지

  • GitLab 13.11 및 이후에서 스캐너 세션 시작 실패 (버전 헤더를 찾을 수 없음)
  • GitLab 13.10 및 이전 버전에서 API 보안 버전 헤더를 찾을 수 없음. DAST API 서버에 연결 중이 확실한가요?

해결책

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

스캐너와의 세션 시작 실패. 계속해서 시도하고 문제가 지속되면 지원팀에 문의하세요.

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에서 사용하는 포트의 전체 목록은 패키지 기본값에서 확인할 수 있습니다.

어플리케이션은 대상 API의 기본 URL을 결정할 수 없습니다

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

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

가장 적합한 해결책은 대상 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 Editor YAML, JSON YAML, JSON YAML, JSON
Stoplight Studio YAML, JSON YAML, JSON YAML, JSON

수동으로 생성된 OpenAPI 문서가 있다면, 해당 문서를 편집기에 로드하고 준수하지 않는 부분을 수정하세요. 자동으로 생성된 문서라면, 해당 문서를 편집기에 로드하여 스키마의 문제를 식별한 다음, 사용 중인 프레임워크에 기반하여 수정을 수행하세요.

OpenAPI 유연한 유효성 검사 활성화

유연한 유효성 검사는 OpenAPI 문서가 OpenAPI 명세를 준수하지 못할 때 사용합니다. 여전히 다양한 도구에서 사용할 수 있는 내용이 포함되어 있지만 문서 스키마에 대해 덜 엄격하게 유효성 검사가 수행됩니다.

DAST API는 여전히 OpenAPI 명세를 완전히 준수하지 않는 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 Specification'에서 지원되는 미디어 유형을 확인하세요.

해결 방법

  1. OpenAPI Specification 섹션에서 지원되는 미디어 유형을 검토합니다.
  2. OpenAPI 문서를 편집하여 적어도 하나의 작업이 지원되는 미디어 유형을 수락하도록 허용합니다. 또는 OpenAPI 문서 수준에서 지원되는 미디어 유형을 설정하고 모든 작업에 적용할 수 있습니다. 이 단계는 지원되는 미디어 유형이 응용 프로그램에서 수락되도록 변경해야 할 수 있습니다.

Error, error occurred trying to download `<URL>`: There was an error when retrieving content from Uri:' <URL>'. Error:The SSL connection could not be established, see inner exception.

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가 표시됩니다.

해결 방법

접근 방법에 따라 비공개 컨테이너 레지스트리에서 이미지에 액세스하는 방법에 설명된 방법을 사용하여 인증 자격 증명을 제공합니다. 컨테이너 레지스트리 제공업체와 해당 구성에 따라 사용하는 방법이 결정됩니다. Azure, Google Could (GCP), AWS 등 클라우드 제공자가 제공하는 컨테이너 레지스트리를 사용하는 경우 해당 제공업체의 문서를 확인하여 컨테이너 레지스트리에 대한 인증 방법을 찾을 수 있습니다.

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

  1. DOCKER_AUTH_CONFIG 데이터를 결정하는 방법과 DOCKER_AUTH_CONFIG 변수의 값을 계산하는 방법을 이해하기 위해 읽어봅니다. 구성 변수 DOCKER_AUTH_CONFIG에는 적절한 인증 정보를 제공하기 위한 Docker JSON 구성이 포함됩니다. 예를 들어, 자격 증명 abcdefghijklmn을 사용하여 비공개 컨테이너 레지스트리 registry.example.com에 액세스하는 경우 Docker 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)...