문제 해결

API 보안 테스트 작업이 N 시간 이후에 타임 아웃됨

대형 리포지터리의 경우, API 보안 테스트 작업은 기본적으로 설정된 작은 호스팅 러너인 리눅스에서 시간 초과될 수 있습니다. 작업 중에 이러한 문제가 발생하면 더 큰 러너로 스케일을 확장해야 합니다.

지원을 받기 위해 다음 설명서 섹션을 참조하세요:

API 보안 테스트 작업이 완료하는 데 너무 오래 걸림

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

오류: DAST API 'http://127.0.0.1:5000' 대기 중 오류 발생

1.6.196 이전 버전의 API 보안 테스트 분석기에는 특정 조건 하에 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다. 문제를 해결하려면 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' 대기 중 오류 발생.

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

API 보안 테스트 엔진에서는 스캐너 응용프로그램 컴포넌트와 연결을 설정할 수 없는 경우에 오류 메시지가 발생합니다. 이 오류 메시지는 DAST_API_API 변수를 기본 설정에서 변경했을 때 출력 창에 표시됩니다.

오류 메시지

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

해결 방법

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

스캐너와 세션 시작하지 못했습니다. 계속해서 문제가 발생하면 지원팀에 연락하세요.

API 보안 테스트 엔진에서는 스캐너 응용프로그램 컴포넌트와 연결을 설정할 수 없는 경우에 오류 메시지가 발생합니다. 이 오류 메시지는 배경 컴포넌트가 선택된 포트를 사용할 수 없기 때문에 발생할 수 있습니다. 이 문제는 타이밍에 따라 가끔 발생하며 (경합 조건이 있는 경우) 주로 다른 서비스가 컨테이너로 매핑되어 포트 충돌이 발생하는 Kubernetes 환경에서 가장 자주 발생합니다.

해결 방법을 진행하기 전에, 발생한 오류 메시지가 포트가 이미 사용 중이기 때문인지 확인하는 것이 중요합니다. 이것이 원인임을 확인하려면:

  1. 작업 콘솔로 이동하세요.

  2. gl-api-security-scanner.log 작업 품에가서 확인합니다. 다운로드 선택한 다음 파일을 찾거나 직접 검색하거나 찾아보기를 선택하여 시작합니다.

  3. gl-api-security-scanner.log 파일을 텍스트 편집기에서 엽니다.

  4. 포트가 이미 사용 중이기 때문에 오류 메시지가 발생했다는 것을 확인하려면, 다음과 유사한 메시지를 파일에서 확인해야 합니다:

  • GitLab 15.5 및 이후: 

    http://127.0.0.1:5500 주소를 바인드하지 못했습니다: 주소가 이미 사용 중입니다.

  • GitLab 15.4 및 이전: 

    http://[::]:5000 주소를 바인드하지 못했습니다: 주소가 이미 사용 중입니다.

이전 메시지에서 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에서 사용하는 포트의 전체 디렉터리은 패키지 기본값에서 확인하는 것이 좋습니다.

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

API 보안 테스트 엔진은 OpenAPI 문서를 검사한 후 대상 API를 결정할 수 없는 경우 오류 메시지가 출력됩니다. 이 오류 메시지는 .gitlab-ci.yml 파일에서 대상 API가 설정되지 않았고 environment_url.txt 파일에 사용 가능하지 않으며 OpenAPI 문서에서 대상 API를 계산할 수 없는 경우 표시됩니다.

대상 API를 확인하는 다양한 소스를 확인할 때 API 보안 테스트 엔진은 우선적으로 DAST_API_TARGET_URL을 사용하려고 시도합니다. 환경 변수가 설정되지 않은 경우 API 보안 테스트 엔진은 environment_url.txt 파일을 시도합니다. environment_url.txt 파일이 없는 경우 API 보안 테스트 엔진은 OpenAPI 문서의 내용과 DAST_API_OPENAPI에서 제공된 URL을 사용하여 대상 API를 계산하려고 시도합니다.

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

API 보안 테스트 작업은 일부 경로를 작업에서 제외합니다

일부 경로가 작업에서 제외되는 경우, 대상 정의 JSON 파일에서 consumes 배열이 정의되어 있고 유효한 유형을 갖는지 확인하십시오. 이것은 필수 사항입니다.

예제 프로젝트 대상 정의 파일에서 consumes 배열이 정의된 위치를 확인하세요.

정적 환경 솔루션

대상 API URL이 변경되지 않는 파이프라인의 경우에만 해당되는 솔루션입니다.

환경 변수 추가

대상 API가 동일한 상태의 환경에서, 대상 URL을 DAST_API_TARGET_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이 변경되는 동적 환경을 지원하기 위해, API 보안 테스트 엔진은 사용할 URL이 포함된 environment_url.txt 파일의 사용을 지원합니다. 이 파일은 리포지터리에 체크인되지 않으며, 대신 테스트 대상을 배포하는 작업에 의해 파이프라인 중에 생성되고 이후 작업에서 사용할 수 있는 artifact로 수집됩니다. environment_url.txt 파일을 만드는 작업은 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 사용

스키마가 올바르지 않거나 적시에 매뉴얼으로 편집할 수 없는 경우가 있습니다. 이러한 시나리오에서 API 보안 테스트는 DAST_API_OPENAPI_RELAXED_VALIDATION 변수 설정을 통해 완화된 유효성 검사를 수행할 수 있습니다. 예상치 못한 동작을 방지하려면 완전히 호환되는 OpenAPI 문서를 제공하는 것이 좋습니다.

호환되지 않는 OpenAPI 파일 편집

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

편집기 OpenAPI 2.0 OpenAPI 3.0.x OpenAPI 3.1.x
Stoplight Studio YAML, JSON YAML, JSON YAML, JSON
Swagger Editor YAML, JSON YAML, JSON YAML, JSON

매뉴얼으로 생성된 OpenAPI 문서를 사용 중이라면 편집기에서 문서를 불러와 준수하지 않는 사항을 수정하세요. 자동으로 생성된 문서의 경우, 편집기에서 불러와 스키마의 문제를 식별한 후 사용 중인 프레임워크에 따라 보정 작업을 수행하세요.

OpenAPI 완화된 유효성 검사 활성화

OpenAPI 문서가 OpenAPI 사양을 준수하지 못해도 다양한 도구에서 사용할 내용이 충분하다면 완화된 검사가 수행됩니다.

API 보안 테스트는 여전히 OpenAPI 사양을 완전히 준수하지 않는 OpenAPI 문서를 사용할 수 있습니다. 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 문서에서 지원하는 미디어 유형을 사용하는 작업이 없습니다

API 보안 테스트는 OpenAPI 문서에서 지정된 미디어 유형을 사용하여 요청을 생성합니다. 지원되는 미디어 유형이 없어서 요청을 생성할 수 없는 경우 오류가 발생합니다.

오류 메시지

  • 오류, OpenAPI 문서에 있는 작업 중에서 지원하는 미디어 유형을 사용하는 작업이 없습니다. 'OpenAPI 사양'에서 지원하는 미디어 유형을 확인하세요.

해결 방법

  1. OpenAPI 사양 섹션에서 지원되는 미디어 유형을 검토하세요.
  2. OpenAPI 문서를 편집하여 특정 작업이 지원하는 미디어 유형을 허용하도록 수정하세요. 또는 OpenAPI 문서 수준에서 지원되는 미디어 유형을 설정하고 모든 작업에 적용할 수 있습니다. 이 단계는 지원되는 미디어 유형이 애플리케이션에 의해 수용되도록 변경해야 할 수도 있습니다.

오류, `<URL>` 다운로드 중 오류 발생: ' <URL>'에서 내용을 검색하는 동안 오류가 발생했습니다. 오류:SSL 연결을 설정할 수 없음, 내부 예외 확인.

API 보안 테스트는 오래된 프로토콜 및 암호화를 포함한 다양한 TLS 구성과 호환됩니다. 넓은 지원을 제공하지만 연결 오류가 발생할 수 있습니다. 지정한 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: 작업 실패: 이미지를 가져오는 데 실패함

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

작업 콘솔 출력에서 오류는 다음과 같이 표시됩니다: 

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: 작업 실패: 이미지를 가져오는 데 실패함 "registry.example.com/my-target-app:latest"가 지정된 정책 [always]로: 에러 응답 from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s)

오류 메시지

  • GitLab 15.9 이전 버전에서 ERROR: 작업 실패: 이미지를 가져오는 데 실패함 이후에 에러 응답 from daemon: Get IMAGE: unauthorized가 표시됩니다.

해결 방법

인증 자격 증명은 컨테이너 레지스트리 제공업체 및 해당 구성에 따라 제공 방법이 결정됩니다. 3rd party(예: 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에 접근할 때, 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를 가져오는 데 사용되어 지정된 정책 [always]로 작업이 성공하면 다음과 같이 표시됩니다: 

    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)...