API 보안 테스트 job 문제 해결

요약

리포지터리 규모가 큰 경우 기본값으로 지정된 Linux 용 small 호스티드 러너에서 API 보안 테스트 job 이 타임아웃될 수 있습니다. 성능 튜닝 및 테스트 속도를 참고합니다. v1.6.196 이전 버전의 API 보안 테스트 분석기에는 특정 조건에서 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다.

API 보안 테스트 job 이 N시간 후 타임아웃됨#

리포지터리 규모가 큰 경우 기본값으로 지정된 Linux 용 small 호스티드 러너에서 API 보안 테스트 job 이 타임아웃될 수 있습니다. job에서 이런 현상이 발생하면 더 큰 러너로 확장합니다.

다음 문서 절을 참고합니다.

API 보안 테스트 job 완료에 너무 오랜 시간이 걸림#

성능 튜닝 및 테스트 속도를 참고합니다.

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

v1.6.196 이전 버전의 API 보안 테스트 분석기에는 특정 조건에서 백그라운드 프로세스가 실패할 수 있는 버그가 있습니다. 해결 방법은 API 보안 테스트 분석기를 최신 버전으로 업데이트하는 것입니다.

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

v1.6.196 이상에서 이 문제가 발생하면 Support에 문의해 다음 정보를 제공합니다.

이 문제 해결 절을 언급하고 Dynamic Analysis 팀으로 이슈를 에스컬레이션해 달라고 요청합니다.
job의 전체 콘솔 출력입니다.
job 아티팩트로 제공되는 gl-api-security-scanner.log 파일입니다. job 세부 정보 페이지의 오른쪽 패널에서 Browse를 선택합니다.
.gitlab-ci.yml 파일의 dast_api job 정의입니다.

`Failed to start scanner session (version header not found)`#

API 보안 테스트 엔진은 스캐너 애플리케이션 컴포넌트와 연결을 맺지 못하면 오류 메시지를 출력합니다. 이 오류 메시지는 dast_api job의 job 출력 창에 표시됩니다. 이 문제의 흔한 원인은 APISEC_API 변수를 기본값에서 변경한 것입니다.

오류 메시지

Failed to start scanner session (version header not found).

해결 방법

.gitlab-ci.yml 파일에서 APISEC_API 변수를 제거합니다. 값은 API 보안 테스트 CI/CD 템플릿에서 상속됩니다. 값을 직접 지정하는 대신 이 방법을 사용합니다.
변수를 제거할 수 없다면 API 보안 테스트 CI/CD 템플릿의 최신 버전에서 이 값이 변경되었는지 확인합니다. 변경되었다면 .gitlab-ci.yml 파일의 값을 업데이트합니다.

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

API 보안 테스트 엔진은 스캐너 애플리케이션 컴포넌트와 연결을 맺지 못하면 오류 메시지를 출력합니다. 이 오류 메시지는 dast_api job의 job 출력 창에 표시됩니다. 이 문제의 흔한 원인은 백그라운드 컴포넌트가 선택한 포트를 이미 다른 프로세스가 사용하고 있어 쓸 수 없는 경우입니다. 타이밍이 관여하는 경쟁 조건이라면 이 오류가 간헐적으로 발생할 수 있습니다. 이 문제는 다른 서비스가 컨테이너에 매핑되어 포트 충돌이 생기는 쿠버네티스 환경에서 가장 자주 발생합니다.

해결 방법을 진행하기 전에 포트가 이미 사용 중이어서 오류 메시지가 발생했는지 확인해야 합니다. 원인을 확인하는 방법은 다음과 같습니다.

job 콘솔로 이동합니다.
gl-api-security-scanner.log 아티팩트를 찾습니다. Download를 선택해 모든 아티팩트를 내려받은 뒤 파일을 검색하거나, Browse를 선택해 바로 검색할 수 있습니다.
텍스트 편집기에서 gl-api-security-scanner.log 파일을 엽니다.
포트가 이미 사용 중이어서 오류 메시지가 발생했다면 파일에서 다음과 같은 메시지를 확인할 수 있습니다.
```
Failed to bind to address http://127.0.0.1:5500: address already in use.
```

앞의 메시지에 있는 http://[::]:5000 텍스트는 환경에 따라 다를 수 있습니다. 예를 들어 http://[::]:5500 이나 http://127.0.0.1:5500 일 수 있습니다. 오류 메시지의 나머지 부분이 같다면 포트가 이미 사용 중이었다고 보아도 됩니다.

포트가 이미 사용 중이었다는 근거를 찾지 못했다면, job 콘솔 출력에 같은 오류 메시지가 나오는 다른 문제 해결 절도 확인합니다. 더 이상 방법이 없다면 적절한 채널로 지원을 받거나 개선을 요청합니다.

포트가 이미 사용 중이어서 문제가 발생했다고 확인되면 CI/CD 변수 APISEC_API_PORT로 스캐너 백그라운드 컴포넌트에 다른 포트를 지정합니다.

해결 방법

.gitlab-ci.yml 파일에 설정 변수 APISEC_API_PORT가 정의되어 있는지 확인합니다.
APISEC_API_PORT 값을 1024보다 큰 사용 가능한 포트 번호로 업데이트합니다. 지정한 포트 번호를 GitLab 이 사용하고 있지는 않은지 확인합니다. GitLab 이 사용하는 전체 포트 목록은 패키지 기본값에서 확인할 수 있습니다.

`Application cannot determine the base URL for the target API`#

API 보안 테스트 엔진은 OpenAPI 문서를 검사한 뒤에도 대상 API를 판별하지 못하면 오류 메시지를 출력합니다. 이 오류 메시지는 .gitlab-ci.yml 파일에 대상 API가 설정되어 있지 않고, environment_url.txt 파일에도 없으며, OpenAPI 문서로도 계산할 수 없을 때 표시됩니다.

API 보안 테스트 엔진은 여러 소스를 확인하면서 정해진 우선순위로 대상 API를 가져옵니다. 먼저 APISEC_TARGET_URL을 사용합니다. 이 환경 변수가 설정되어 있지 않으면 API 보안 테스트 엔진은 environment_url.txt 파일을 사용합니다. environment_url.txt 파일도 없으면 API 보안 테스트 엔진은 OpenAPI 문서 내용과 APISEC_OPENAPI에 지정된 URL(URL 이 지정된 경우)로 대상 API를 계산합니다.

가장 적합한 해결 방법은 배포마다 대상 API가 바뀌는지에 따라 달라집니다. 정적 환경에서는 배포마다 대상 API가 같습니다. 이 경우 정적 환경 해결 방법을 참고합니다. 배포마다 대상 API가 바뀐다면 동적 환경 해결 방법을 적용합니다.

API 보안 테스트 job 이 일부 경로를 operation에서 제외함#

일부 경로가 operation에서 제외된다면 다음을 확인합니다.

테스트하려는 operation 이 제외되도록 APISEC_EXCLUDE_URLS 변수가 설정되어 있지는 않은지 확인합니다.
대상 정의 JSON 파일에 consumes 배열이 정의되어 있고 유효한 타입을 가지고 있는지 확인합니다.

정의 예시는 예제 프로젝트의 대상 정의 파일을 참고합니다.

정적 환경 해결 방법#

이 해결 방법은 대상 API URL 이 바뀌지 않는(정적인) 파이프라인에 적용합니다.

환경 변수 추가

대상 API가 항상 같은 환경에서는 APISEC_TARGET_URL 환경 변수로 대상 URL을 지정합니다. .gitlab-ci.yml에 APISEC_TARGET_URL 변수를 추가합니다. 이 변수에는 API 테스트 대상의 기본 URL을 설정해야 합니다. 예를 들면 다음과 같습니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: http://test-deployment/
  APISEC_OPENAPI: test-api-specification.json

동적 환경 해결 방법#

동적 환경에서는 배포마다 대상 API가 달라집니다. 이 경우 해결 방법이 여럿 있으며, 동적 환경에서는 environment_url.txt 파일을 사용합니다.

environment_url.txt 사용

파이프라인마다 대상 API URL 이 바뀌는 동적 환경을 지원하기 위해 API 보안 테스트 엔진은 사용할 URL 이 담긴 environment_url.txt 파일을 지원합니다. 이 파일은 리포지터리에 체크인하지 않고, 테스트 대상을 배포하는 job 이 파이프라인 도중에 생성한 뒤 아티팩트로 수집해 파이프라인의 이후 job에서 사용합니다. environment_url.txt 파일을 생성하는 job은 API 보안 테스트 엔진 job보다 먼저 실행되어야 합니다.

테스트 대상 배포 job을 수정해 프로젝트 루트의 environment_url.txt 파일에 기본 URL을 기록하도록 합니다.
테스트 대상 배포 job을 수정해 environment_url.txt를 아티팩트로 수집하도록 합니다.

예시는 다음과 같습니다.

deploy-test-target:
  script:
    # Perform deployment steps
    # Create environment_url.txt (example)
    - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt

  artifacts:
    paths:
      - environment_url.txt

유효하지 않은 스키마의 OpenAPI 사용#

OpenAPI 문서가 유효하지 않은 스키마로 자동 생성되거나, 제때 직접 수정할 수 없는 경우가 있습니다. 이런 상황에서는 APISEC_OPENAPI_RELAXED_VALIDATION 변수를 설정해 API 보안 테스트가 완화된 유효성 검사를 수행하도록 할 수 있습니다. 예기치 않은 동작을 막으려면 규격을 완전히 준수하는 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 보안 테스트가 완화된 유효성 검사를 수행하도록 하려면 APISEC_OPENAPI_RELAXED_VALIDATION 변수에 아무 값이나 설정합니다. 예를 들면 다음과 같습니다.

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_TARGET_URL: http://test-deployment/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_OPENAPI_RELAXED_VALIDATION: 'On'

`No operation in the OpenAPI document is consuming any supported media type`#

API 보안 테스트는 OpenAPI 문서에 지정된 미디어 타입으로 요청을 생성합니다. 지원되는 미디어 타입이 없어 요청을 만들 수 없으면 오류가 발생합니다.

오류 메시지

Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.

해결 방법

OpenAPI 규격 절에서 지원되는 미디어 타입을 확인합니다.
OpenAPI 문서를 편집해 최소한 하나의 operation 이 지원되는 미디어 타입 중 하나를 받도록 합니다. 또는 OpenAPI 문서 수준에 지원되는 미디어 타입을 설정해 모든 operation에 적용할 수도 있습니다. 이 단계에서는 애플리케이션이 해당 미디어 타입을 받아들이도록 애플리케이션을 수정해야 할 수 있습니다.

오류: `The SSL connection could not be established, see inner exception.`#

API 보안 테스트는 오래된 프로토콜과 암호 방식을 포함해 다양한 TLS 설정과 호환됩니다. 다만 지원 범위가 넓은데도 다음과 같은 연결 오류가 발생할 수 있습니다.

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

이 오류는 API 보안 테스트가 해당 URL의 서버와 보안 연결을 맺지 못했을 때 발생합니다.

문제를 해결하는 방법은 다음과 같습니다.

오류 메시지의 호스트가 비 TLS 연결을 지원한다면 설정에서 https://를 http://로 변경합니다. 예를 들어 다음 설정에서 오류가 발생했다고 가정합니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: https://specs/openapi.json

APISEC_OPENAPI의 접두사를 https://에서 http://로 변경합니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: http://specs/openapi.json

해당 URL에 비 TLS 연결로 접근할 수 없다면 Support 팀에 문의합니다.

testssl.sh 도구를 사용하면 조사를 앞당길 수 있습니다. bash 셸을 쓸 수 있고 해당 서버에 연결 가능한 머신에서 다음을 수행합니다.

https://github.com/testssl/testssl.sh/releases에서 최신 릴리스의 zip 또는 tar.gz 파일을 내려받아 압축을 풉니다.
./testssl.sh --log https://specs를 실행합니다.
로그 파일을 지원 티켓에 첨부합니다.

`ERROR: Job failed: failed to pull image`#

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

job 콘솔 출력에서는 다음과 같이 나타납니다.

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)

해결 방법

인증 자격 증명은 비공개 컨테이너 레지스트리의 이미지 접근 문서 절에 설명된 방법으로 제공합니다. 어떤 방법을 쓸지는 컨테이너 레지스트리 제공자와 그 설정에 따라 달라집니다. 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 변수로 생성합니다.

job을 다시 실행하면 정적으로 정의한 자격 증명으로 비공개 컨테이너 레지스트리 registry.example.com에 로그인해 my-target-app:latest 이미지를 가져옵니다. 성공하면 job 콘솔에 다음과 같은 출력이 표시됩니다.

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

연속된 스캔 간 취약점 결과 차이#

코드나 설정을 바꾸지 않았는데도 연속된 스캔에서 취약점 결과가 다르게 나올 수 있습니다. 주된 이유는 대상 환경과 그 상태를 예측하기 어렵다는 점, 그리고 스캐너가 요청을 병렬로 보낸다는 점입니다. 스캐너는 스캔 시간을 줄이려고 여러 요청을 병렬로 보내므로, 대상 서버가 요청에 응답하는 정확한 순서는 미리 정해지지 않습니다.

OS Command 나 SQL Injection처럼 요청과 응답 사이의 시간으로 탐지하는 타이밍 공격 취약점은, 서버에 부하가 걸려 정해진 임계값 안에 테스트에 응답하지 못할 때 탐지될 수 있습니다. 서버에 부하가 없는 상태에서 같은 스캔을 실행하면 이러한 취약점이 탐지되지 않아 결과가 달라질 수 있습니다. 대상 서버를 프로파일링하고, 성능 튜닝 및 테스트 속도를 참고해 테스트 중 최적의 서버 성능 기준선을 세우면, 앞서 말한 요인 때문에 오탐이 생길 수 있는 지점을 찾는 데 도움이 됩니다.

오류: `sudo: The "no new privileges" flag is set, which prevents sudo from running as root.`#

분석기 v5부터는 기본적으로 root가 아닌 사용자를 사용합니다. 따라서 권한이 필요한 동작을 수행할 때 sudo를 사용해야 합니다.

이 오류는 실행 중인 컨테이너가 새 권한을 얻지 못하도록 막는 특정 컨테이너 데몬 구성에서 발생합니다. 대부분의 환경에서 이는 기본 구성이 아니며, 주로 보안 강화 가이드에 따라 별도로 설정한 항목입니다.

오류 메시지

이 문제는 before_script 또는 APISEC_PRE_SCRIPT를 실행할 때 나오는 다음 오류 메시지로 확인할 수 있습니다.

$ sudo apk add nodejs

sudo: The "no new privileges" flag is set, which prevents sudo from running as root.

sudo: If sudo is running in a container, you may need to adjust the container configuration to disable the flag.

해결 방법

이 문제는 다음 방법으로 우회할 수 있습니다.

컨테이너를 root 사용자로 실행합니다. 모든 환경에서 동작하지는 않으므로 이 구성을 반드시 테스트해야 합니다. CI/CD 설정을 수정한 뒤 job 출력에서 whoami 결과가 gitlab 이 아니라 root로 나오는지 확인합니다. gitlab 이 표시되면 다른 우회 방법을 사용합니다. 테스트로 변경이 적용된 것을 확인한 뒤에는 before_script를 제거할 수 있습니다.

api_security:
  image:
    name: $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
    docker:
      user: root
 before_script:
   - whoami

job 콘솔 출력 예시:

Executing "step_script" stage of the job script
Using docker image sha256:8b95f188b37d6b342dc740f68557771bb214fe520a5dc78a88c7a9cc6a0f9901 for registry.gitlab.com/security-products/api-security:5 with digest registry.gitlab.com/security-products/api-security@sha256:092909baa2b41db8a7e3584f91b982174772abdfe8ceafc97cf567c3de3179d1 ...
$ whoami
root
$ /peach/analyzer-api-security
17:17:14 [INF] API Security: Gitlab API Security
17:17:14 [INF] API Security: -------------------
17:17:14 [INF] API Security:
17:17:14 [INF] API Security: version: 5.7.0

컨테이너를 감싸서 빌드 시점에 필요한 의존성을 추가합니다. 이 방법은 root보다 낮은 권한으로 실행할 수 있어, 그것이 요구 사항인 고객에게 유리합니다.
1. 기존 이미지를 감싸는 새 Dockerfile을 만듭니다.
```
ARG SECURE_ANALYZERS_PREFIX
ARG APISEC_IMAGE
ARG APISEC_VERSION
ARG APISEC_IMAGE_SUFFIX
FROM $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
USER root

RUN pip install ...
RUN apk add ...

USER gitlab
```
2. API 보안 테스트 job 이 시작되기 전에 새 이미지를 빌드해 로컬 컨테이너 레지스트리에 푸시합니다. api_security job 이 끝난 뒤에는 이미지를 제거해야 합니다.
```
TARGET_NAME=apisec-$CI_COMMIT_SHA
docker build -t $TARGET_IMAGE \
  --build-arg "SECURE_ANALYZERS_PREFIX=$SECURE_ANALYZERS_PREFIX" \
  --build-arg "APISEC_IMAGE=$APISEC_IMAGE" \
  --build-arg "APISEC_VERSION=$APISEC_VERSION" \
  --build-arg "APISEC_IMAGE_SUFFIX=$APISEC_IMAGE_SUFFIX" \
  .
docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
docker push $TARGET_IMAGE
```
3. api_security job을 확장해 새 이미지 이름을 사용합니다.
```
api_security:
  image: apisec-$CI_COMMIT_SHA
```
4. 임시 컨테이너를 레지스트리에서 제거합니다. 컨테이너 이미지 제거 방법은 이 문서 페이지에서 확인합니다.
GitLab Runner 설정을 변경해 no-new-privileges 플래그를 비활성화합니다. 이 방법은 보안에 영향을 줄 수 있으므로 운영팀·보안팀과 논의해야 합니다.

`Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()`#

이 오류 메시지는 API 보안 테스트 분석기가 APISEC_REQUEST_HEADERS 또는 APISEC_REQUEST_HEADERS_BASE64 설정 변수의 값을 파싱하지 못했음을 뜻합니다.

오류 메시지

이 문제는 두 가지 오류 메시지로 확인할 수 있습니다. 첫 번째 오류 메시지는 job 콘솔 출력에, 두 번째는 gl-api-security-scanner.log 파일에 나타납니다.

job 콘솔의 오류 메시지:

05:48:38 [ERR] API Security: Testing failed: An unexpected exception occurred: Index was outside the bounds of the array.

gl_api_security-scanner.log의 오류 메시지:

08:45:43.616 [ERR]  Unexpected exception in WebRunnerMachine::Run()
System.IndexOutOfRangeException: Index was outside the bounds of the array.
   at Peach.Web.Runner.Services.RunnerOptions.GetHeaders() in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/[RunnerOptions.cs:line 362
   at Peach.Web.Runner.Services.RunnerService.Start(Job job, IRunnerOptions options) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/RunnerService.cs:line 67
   at Peach.Web.Core.Services.WebRunnerMachine.Run(IRunnerOptions runnerOptions, CancellationToken token) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Core/Services/WebRunnerMachine.cs:line 321
08:45:43.634 [WRN]  * Session failed: An unexpected exception occurred: Index was outside the bounds of the array.
08:45:43.677 [INF]  Finished testing. Performed a total of 0 requests.

해결 방법

이 문제는 APISEC_REQUEST_HEADERS 또는 APISEC_REQUEST_HEADERS_BASE64 변수의 형식이 잘못되어 발생합니다. 올바른 형식은 Header: value 형태의 헤더를 하나 이상 쉼표로 구분한 것입니다. 해결 방법은 이 형식에 맞게 구문을 수정하는 것입니다.

올바른 예시:

Authorization: Bearer XYZ
X-Custom: Value,Authorization: Bearer XYZ

잘못된 예시:

Header:,value
HeaderA: value,HeaderB:,HeaderC: value
Header

API 보안 테스트 job 문제 해결

GitLab v19.4

원문 보기

번역일: 2026-09-18

요약

API 보안 테스트 job 이 N시간 후 타임아웃됨#

다음 문서 절을 참고합니다.

API 보안 테스트 job 완료에 너무 오랜 시간이 걸림#

성능 튜닝 및 테스트 속도를 참고합니다.

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

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

v1.6.196 이상에서 이 문제가 발생하면 Support에 문의해 다음 정보를 제공합니다.

이 문제 해결 절을 언급하고 Dynamic Analysis 팀으로 이슈를 에스컬레이션해 달라고 요청합니다.
job의 전체 콘솔 출력입니다.
job 아티팩트로 제공되는 gl-api-security-scanner.log 파일입니다. job 세부 정보 페이지의 오른쪽 패널에서 Browse를 선택합니다.
.gitlab-ci.yml 파일의 dast_api job 정의입니다.

`Failed to start scanner session (version header not found)`#

오류 메시지

Failed to start scanner session (version header not found).

해결 방법

.gitlab-ci.yml 파일에서 APISEC_API 변수를 제거합니다. 값은 API 보안 테스트 CI/CD 템플릿에서 상속됩니다. 값을 직접 지정하는 대신 이 방법을 사용합니다.
변수를 제거할 수 없다면 API 보안 테스트 CI/CD 템플릿의 최신 버전에서 이 값이 변경되었는지 확인합니다. 변경되었다면 .gitlab-ci.yml 파일의 값을 업데이트합니다.

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

해결 방법을 진행하기 전에 포트가 이미 사용 중이어서 오류 메시지가 발생했는지 확인해야 합니다. 원인을 확인하는 방법은 다음과 같습니다.

job 콘솔로 이동합니다.
gl-api-security-scanner.log 아티팩트를 찾습니다. Download를 선택해 모든 아티팩트를 내려받은 뒤 파일을 검색하거나, Browse를 선택해 바로 검색할 수 있습니다.
텍스트 편집기에서 gl-api-security-scanner.log 파일을 엽니다.
포트가 이미 사용 중이어서 오류 메시지가 발생했다면 파일에서 다음과 같은 메시지를 확인할 수 있습니다.
```
Failed to bind to address http://127.0.0.1:5500: address already in use.
```

포트가 이미 사용 중이어서 문제가 발생했다고 확인되면 CI/CD 변수 APISEC_API_PORT로 스캐너 백그라운드 컴포넌트에 다른 포트를 지정합니다.

해결 방법

.gitlab-ci.yml 파일에 설정 변수 APISEC_API_PORT가 정의되어 있는지 확인합니다.
APISEC_API_PORT 값을 1024보다 큰 사용 가능한 포트 번호로 업데이트합니다. 지정한 포트 번호를 GitLab 이 사용하고 있지는 않은지 확인합니다. GitLab 이 사용하는 전체 포트 목록은 패키지 기본값에서 확인할 수 있습니다.

`Application cannot determine the base URL for the target API`#

API 보안 테스트 job 이 일부 경로를 operation에서 제외함#

일부 경로가 operation에서 제외된다면 다음을 확인합니다.

테스트하려는 operation 이 제외되도록 APISEC_EXCLUDE_URLS 변수가 설정되어 있지는 않은지 확인합니다.
대상 정의 JSON 파일에 consumes 배열이 정의되어 있고 유효한 타입을 가지고 있는지 확인합니다.

정의 예시는 예제 프로젝트의 대상 정의 파일을 참고합니다.

정적 환경 해결 방법#

이 해결 방법은 대상 API URL 이 바뀌지 않는(정적인) 파이프라인에 적용합니다.

환경 변수 추가

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: http://test-deployment/
  APISEC_OPENAPI: test-api-specification.json

동적 환경 해결 방법#

동적 환경에서는 배포마다 대상 API가 달라집니다. 이 경우 해결 방법이 여럿 있으며, 동적 환경에서는 environment_url.txt 파일을 사용합니다.

environment_url.txt 사용

테스트 대상 배포 job을 수정해 프로젝트 루트의 environment_url.txt 파일에 기본 URL을 기록하도록 합니다.
테스트 대상 배포 job을 수정해 environment_url.txt를 아티팩트로 수집하도록 합니다.

예시는 다음과 같습니다.

deploy-test-target:
  script:
    # Perform deployment steps
    # Create environment_url.txt (example)
    - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt

  artifacts:
    paths:
      - environment_url.txt

유효하지 않은 스키마의 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 완화된 유효성 검사 활성화#

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_TARGET_URL: http://test-deployment/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_OPENAPI_RELAXED_VALIDATION: 'On'

`No operation in the OpenAPI document is consuming any supported media type`#

API 보안 테스트는 OpenAPI 문서에 지정된 미디어 타입으로 요청을 생성합니다. 지원되는 미디어 타입이 없어 요청을 만들 수 없으면 오류가 발생합니다.

오류 메시지

Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.

해결 방법

OpenAPI 규격 절에서 지원되는 미디어 타입을 확인합니다.
OpenAPI 문서를 편집해 최소한 하나의 operation 이 지원되는 미디어 타입 중 하나를 받도록 합니다. 또는 OpenAPI 문서 수준에 지원되는 미디어 타입을 설정해 모든 operation에 적용할 수도 있습니다. 이 단계에서는 애플리케이션이 해당 미디어 타입을 받아들이도록 애플리케이션을 수정해야 할 수 있습니다.

오류: `The SSL connection could not be established, see inner exception.`#

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

이 오류는 API 보안 테스트가 해당 URL의 서버와 보안 연결을 맺지 못했을 때 발생합니다.

문제를 해결하는 방법은 다음과 같습니다.

오류 메시지의 호스트가 비 TLS 연결을 지원한다면 설정에서 https://를 http://로 변경합니다. 예를 들어 다음 설정에서 오류가 발생했다고 가정합니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: https://specs/openapi.json

APISEC_OPENAPI의 접두사를 https://에서 http://로 변경합니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: https://test-deployment/
  APISEC_OPENAPI: http://specs/openapi.json

해당 URL에 비 TLS 연결로 접근할 수 없다면 Support 팀에 문의합니다.

testssl.sh 도구를 사용하면 조사를 앞당길 수 있습니다. bash 셸을 쓸 수 있고 해당 서버에 연결 가능한 머신에서 다음을 수행합니다.

https://github.com/testssl/testssl.sh/releases에서 최신 릴리스의 zip 또는 tar.gz 파일을 내려받아 압축을 풉니다.
./testssl.sh --log https://specs를 실행합니다.
로그 파일을 지원 티켓에 첨부합니다.

`ERROR: Job failed: failed to pull image`#

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

job 콘솔 출력에서는 다음과 같이 나타납니다.

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)

해결 방법

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 변수로 생성합니다.

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

연속된 스캔 간 취약점 결과 차이#

오류: `sudo: The "no new privileges" flag is set, which prevents sudo from running as root.`#

분석기 v5부터는 기본적으로 root가 아닌 사용자를 사용합니다. 따라서 권한이 필요한 동작을 수행할 때 sudo를 사용해야 합니다.

오류 메시지

이 문제는 before_script 또는 APISEC_PRE_SCRIPT를 실행할 때 나오는 다음 오류 메시지로 확인할 수 있습니다.

$ sudo apk add nodejs

sudo: The "no new privileges" flag is set, which prevents sudo from running as root.

sudo: If sudo is running in a container, you may need to adjust the container configuration to disable the flag.

해결 방법

이 문제는 다음 방법으로 우회할 수 있습니다.

api_security:
  image:
    name: $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
    docker:
      user: root
 before_script:
   - whoami

job 콘솔 출력 예시:

Executing "step_script" stage of the job script
Using docker image sha256:8b95f188b37d6b342dc740f68557771bb214fe520a5dc78a88c7a9cc6a0f9901 for registry.gitlab.com/security-products/api-security:5 with digest registry.gitlab.com/security-products/api-security@sha256:092909baa2b41db8a7e3584f91b982174772abdfe8ceafc97cf567c3de3179d1 ...
$ whoami
root
$ /peach/analyzer-api-security
17:17:14 [INF] API Security: Gitlab API Security
17:17:14 [INF] API Security: -------------------
17:17:14 [INF] API Security:
17:17:14 [INF] API Security: version: 5.7.0

컨테이너를 감싸서 빌드 시점에 필요한 의존성을 추가합니다. 이 방법은 root보다 낮은 권한으로 실행할 수 있어, 그것이 요구 사항인 고객에게 유리합니다.
1. 기존 이미지를 감싸는 새 Dockerfile을 만듭니다.
```
ARG SECURE_ANALYZERS_PREFIX
ARG APISEC_IMAGE
ARG APISEC_VERSION
ARG APISEC_IMAGE_SUFFIX
FROM $SECURE_ANALYZERS_PREFIX/$APISEC_IMAGE:$APISEC_VERSION$APISEC_IMAGE_SUFFIX
USER root

RUN pip install ...
RUN apk add ...

USER gitlab
```
2. API 보안 테스트 job 이 시작되기 전에 새 이미지를 빌드해 로컬 컨테이너 레지스트리에 푸시합니다. api_security job 이 끝난 뒤에는 이미지를 제거해야 합니다.
```
TARGET_NAME=apisec-$CI_COMMIT_SHA
docker build -t $TARGET_IMAGE \
  --build-arg "SECURE_ANALYZERS_PREFIX=$SECURE_ANALYZERS_PREFIX" \
  --build-arg "APISEC_IMAGE=$APISEC_IMAGE" \
  --build-arg "APISEC_VERSION=$APISEC_VERSION" \
  --build-arg "APISEC_IMAGE_SUFFIX=$APISEC_IMAGE_SUFFIX" \
  .
docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
docker push $TARGET_IMAGE
```
3. api_security job을 확장해 새 이미지 이름을 사용합니다.
```
api_security:
  image: apisec-$CI_COMMIT_SHA
```
4. 임시 컨테이너를 레지스트리에서 제거합니다. 컨테이너 이미지 제거 방법은 이 문서 페이지에서 확인합니다.
GitLab Runner 설정을 변경해 no-new-privileges 플래그를 비활성화합니다. 이 방법은 보안에 영향을 줄 수 있으므로 운영팀·보안팀과 논의해야 합니다.

`Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()`#

이 오류 메시지는 API 보안 테스트 분석기가 APISEC_REQUEST_HEADERS 또는 APISEC_REQUEST_HEADERS_BASE64 설정 변수의 값을 파싱하지 못했음을 뜻합니다.

오류 메시지

이 문제는 두 가지 오류 메시지로 확인할 수 있습니다. 첫 번째 오류 메시지는 job 콘솔 출력에, 두 번째는 gl-api-security-scanner.log 파일에 나타납니다.

job 콘솔의 오류 메시지:

05:48:38 [ERR] API Security: Testing failed: An unexpected exception occurred: Index was outside the bounds of the array.

gl_api_security-scanner.log의 오류 메시지:

08:45:43.616 [ERR]  Unexpected exception in WebRunnerMachine::Run()
System.IndexOutOfRangeException: Index was outside the bounds of the array.
   at Peach.Web.Runner.Services.RunnerOptions.GetHeaders() in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/[RunnerOptions.cs:line 362
   at Peach.Web.Runner.Services.RunnerService.Start(Job job, IRunnerOptions options) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Runner/Services/RunnerService.cs:line 67
   at Peach.Web.Core.Services.WebRunnerMachine.Run(IRunnerOptions runnerOptions, CancellationToken token) in /builds/gitlab-org/security-products/analyzers/api-fuzzing-src/web/PeachWeb/Core/Services/WebRunnerMachine.cs:line 321
08:45:43.634 [WRN]  * Session failed: An unexpected exception occurred: Index was outside the bounds of the array.
08:45:43.677 [INF]  Finished testing. Performed a total of 0 requests.

해결 방법

올바른 예시:

Authorization: Bearer XYZ
X-Custom: Value,Authorization: Bearer XYZ

잘못된 예시:

Header:,value
HeaderA: value,HeaderB:,HeaderC: value
Header

API 보안 테스트 job 문제 해결

API 보안 테스트 job 이 N시간 후 타임아웃됨#

API 보안 테스트 job 완료에 너무 오랜 시간이 걸림#

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

Failed to start scanner session (version header not found)#

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

Application cannot determine the base URL for the target API#

API 보안 테스트 job 이 일부 경로를 operation에서 제외함#

정적 환경 해결 방법#

동적 환경 해결 방법#

유효하지 않은 스키마의 OpenAPI 사용#

규격을 준수하지 않는 OpenAPI 파일 편집#

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

No operation in the OpenAPI document is consuming any supported media type#

오류: The SSL connection could not be established, see inner exception.#

ERROR: Job failed: failed to pull image#

연속된 스캔 간 취약점 결과 차이#

오류: sudo: The "no new privileges" flag is set, which prevents sudo from running as root.#

Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()#

API 보안 테스트 job 문제 해결

API 보안 테스트 job 이 N시간 후 타임아웃됨#

API 보안 테스트 job 완료에 너무 오랜 시간이 걸림#

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

Failed to start scanner session (version header not found)#

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

Application cannot determine the base URL for the target API#

API 보안 테스트 job 이 일부 경로를 operation에서 제외함#

정적 환경 해결 방법#

동적 환경 해결 방법#

유효하지 않은 스키마의 OpenAPI 사용#

규격을 준수하지 않는 OpenAPI 파일 편집#

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

No operation in the OpenAPI document is consuming any supported media type#

오류: The SSL connection could not be established, see inner exception.#

ERROR: Job failed: failed to pull image#

연속된 스캔 간 취약점 결과 차이#

오류: sudo: The "no new privileges" flag is set, which prevents sudo from running as root.#

Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()#

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

`Failed to start scanner session (version header not found)`#

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

`Application cannot determine the base URL for the target API`#

`No operation in the OpenAPI document is consuming any supported media type`#

오류: `The SSL connection could not be established, see inner exception.`#

`ERROR: Job failed: failed to pull image`#

오류: `sudo: The "no new privileges" flag is set, which prevents sudo from running as root.`#

`Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()`#

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

`Failed to start scanner session (version header not found)`#

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

`Application cannot determine the base URL for the target API`#

`No operation in the OpenAPI document is consuming any supported media type`#

오류: `The SSL connection could not be established, see inner exception.`#

`ERROR: Job failed: failed to pull image`#

오류: `sudo: The "no new privileges" flag is set, which prevents sudo from running as root.`#

`Index was outside the bounds of the array. at Peach.Web.Runner.Services.RunnerOptions.GetHeaders()`#