OpenAPI Specification
OpenAPI 및 미디어 유형
- OpenAPI Specification을 사용하여 API 보안 테스트 구성
HTTP Archive (HAR)
- HAR 파일을 사용한 API 보안 테스트 스캔
GraphQL 스키마
- GraphQL 엔드포인트 URL을 사용한 API 보안 테스트 스캔
- GraphQL 스키마 파일을 사용한 API 보안 테스트 스캔
Postman Collection
- Postman Collection 파일을 사용한 API 보안 테스트 스캔
- Postman 변수
첫 번째 스캔 실행
API 보안 테스트 취약점 보기

Analyzer 활성화

다음을 사용하여 스캔하려는 API를 지정할 수 있습니다.

OpenAPI v2 또는 v3 Specification
GraphQL Schema
HTTP Archive (HAR)
Postman Collection v2.0 또는 v2.1

OpenAPI Specification

OpenAPI Specification (이전 Swagger Specification)은 REST API를 위한 API 설명 형식입니다. 이 섹션에서는 API 보안 테스트 스캔 구성 방법 및 대상 API에 대한 정보를 제공하는 OpenAPI Specification을 사용하는 방법을 보여줍니다. OpenAPI Specifications은 파일 시스템 리소스 또는 URL로 제공됩니다. JSON 및 YAML OpenAPI 형식이 모두 지원됩니다.

API 보안 테스트는 OpenAPI 문서를 사용하여 요청 본문을 생성합니다. 요청 본문이 필요한 경우, 본문 생성은 다음과 같은 본문 유형으로 제한됩니다:

application/x-www-form-urlencoded
multipart/form-data
application/json
application/xml

OpenAPI 및 미디어 유형

미디어 유형(이전 MIME 유형)은 파일 형식 및 형식 내용을 식별하는 식별자입니다. OpenAPI 문서를 사용하면 특정 작업이 다른 미디어 유형을 허용할 수 있도록 지정할 수 있으므로 특정 요청은 서로 다른 파일 콘텐츠를 사용하여 데이터를 전송할 수 있습니다. 예를 들어 PUT /user 작업은 XML(미디어 유형 application/xml) 또는 JSON(미디어 유형 application/json) 형식의 데이터를 허용할 수 있습니다. OpenAPI 2.x에서는 전역적으로 또는 작업 당으로 허용된 미디어 유형을 지정하고, OpenAPI 3.x에서는 각 작업 당으로 허용된 미디어 유형을 지정할 수 있습니다. API 보안 테스트는 나열된 미디어 유형을 확인하고 각 지원되는 미디어 유형에 대한 샘플 데이터를 생성하려고 시도합니다.

기본 동작은 지원되는 미디어 유형 중 하나를 선택하는 것입니다. 지원되는 미디어 유형 중에서 첫 번째 지원되는 미디어 유형이 목록에서 선택됩니다. 이 동작은 구성할 수 있습니다.

동일한 작업(예: POST /user)을 다른 미디어 유형(예: application/json 및 application/xml)을 사용하여 테스트하는 것은 항상 바람직하지는 않습니다. 예를 들어, 대상 애플리케이션이 요청 콘텐츠 유형과 상관없이 동일한 코드를 실행하는 경우 테스트 세션을 완료하는 데 더 많은 시간이 걸리고 대상 앱에 따라 요청 본문과 관련된 중복 취약점이 보고될 수 있습니다.

환경 변수 APISEC_OPENAPI_ALL_MEDIA_TYPES을 사용하면 특정 작업에 대한 요청을 생성할 때 하나가 아닌 모든 지원되는 미디어 유형을 사용할지 여부를 지정할 수 있습니다. 환경 변수 APISEC_OPENAPI_ALL_MEDIA_TYPES이 어떤 값을 설정하면 API 보안 테스트는 특정 작업에 대해 하나가 아닌 모든 지원되는 미디어 유형을 생성하려고 시도합니다. 이로 인해 각 제공된 미디어 유형에 대해 테스트가 반복되므로 시간이 더 많이 소요됩니다.

또는 변수 APISEC_OPENAPI_MEDIA_TYPES를 사용하여 각각 테스트할 미디어 유형 목록을 제공할 수 있습니다. 하나 이상의 미디어 유형을 제공하면, 각 미디어 유형에 대해 테스트가 수행되므로 시간이 더 많이 소요됩니다. 변수 APISEC_OPENAPI_MEDIA_TYPES가 미디어 유형 목록으로 설정된 경우, 요청 생성 시 포함될 미디어 유형만 해당 목록에 포함됩니다.

APISEC_OPENAPI_MEDIA_TYPES의 여러 미디어 유형은 콜론(:)으로 구분됩니다. 예를 들어 요청 생성을 application/x-www-form-urlencoded 및 multipart/form-data 미디어 유형으로 제한하려면 환경 변수 APISEC_OPENAPI_MEDIA_TYPES를 application/x-www-form-urlencoded:multipart/form-data로 설정합니다. 이 목록에서 지원되지 않는 미디어 유형은 항상 건너뛰지만, 해당 목록에서 지원되는 미디어 유형만 생성 요청에 포함됩니다. 미디어 유형 텍스트에는 다양한 섹션이 포함될 수 있습니다. 예를 들어 application/vnd.api+json; charset=UTF-8는 type "/" [tree "."] subtype ["+" suffix]* [";" parameter]의 복합입니다. 필터링된 미디어 유형에서 요청 생성을 수행할 때는 매개변수가 고려되지 않습니다.

환경 변수APISEC_OPENAPI_ALL_MEDIA_TYPES 및APISEC_OPENAPI_MEDIA_TYPES을 사용하여 미디어 유형을 처리하는 방법을 결정할 수 있습니다. 이러한 설정은 상호 배타입니다. 둘 다 활성화되어 있으면 API 보안 테스트에서 오류를 보고합니다.

OpenAPI Specification을 사용하여 API 보안 테스트 구성

OpenAPI Specification을 사용하여 API 보안 테스트 스캔을 구성하려면 다음을 수행하세요.

.gitlab-ci.yml 파일에 API-Security.gitlab-ci.yml 템플릿을 포함합니다.
여러 테스트 프로필이 다양한 체크가 활성화된 상태로 구성 파일에 정의되어 있습니다. Quick 프로필로 시작하는 것이 좋습니다. 해당 프로필로 테스트를 수행하면 빠르게 완료되어 구성 유효성을 더 쉽게 확인할 수 있습니다. .gitlab-ci.yml 파일에 APISEC_PROFILE CI/CD 변수를 추가하여 프로필을 제공하세요.
OpenAPI Specification의 위치를 파일 또는 URL로 제공해야 합니다. APISEC_OPENAPI 변수를 추가하여 위치를 지정하세요.
대상 API 인스턴스의 기본 URL이 필요합니다. APISEC_TARGET_URL 변수 또는 environment_url.txt 파일을 사용하여 제공하세요.
프로젝트 루트에 있는 environment_url.txt 파일에 URL을 추가하면 동적 환경에서 효과적으로 테스트할 수 있습니다. GitLab CI/CD 중에 동적으로 생성된 응용 프로그램에 대한 API 보안 테스트를 실행하려면 응용 프로그램이 URL을 environment_url.txt 파일에 지속적으로 저장하도록 합니다. API 보안 테스트는 해당 파일을 구문 분석하여 스캔 대상을 찾습니다. Auto DevOps CI YAML의 예을 참조하세요.

OpenAPI Specification을 사용하여 API 보안 테스트를 구성한 완전한 구성 예시:

stages:
  - dast

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

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

이것은 API 보안 테스트를 위한 최소 구성입니다. 여기서부터 다음을 수행할 수 있습니다.

첫 번째 스캔 실행.
인증 추가하기
잘못된 양성 처리하는 방법 배우기

HTTP Archive (HAR)

HTTP 아카이브 형식 (HAR)은 HTTP 트랜잭션을 기록하는 아카이브 파일 형식입니다. GitLab API 보안 테스트 스캐너와 함께 사용될 때, HAR 파일에는 웹 API를 호출하는 레코드가 포함되어야 합니다. API 보안 테스트 스캐너는 모든 요청을 추출하여 테스트에 사용합니다.

HAR 파일을 생성하는 다양한 도구를 사용할 수 있습니다:

Insomnia Core: API 클라이언트
Chrome: 브라우저
Firefox: 브라우저
Fiddler: 웹 디버깅 프록시
GitLab HAR Recorder: 명령줄

경고: HAR 파일에는 인증 토큰, API 키, 세션 쿠키 등과 같은 민감한 정보가 포함될 수 있습니다. 해당 파일을 저장소에 추가하기 전에 파일 내용을 검토하는 것을 권장합니다.

HAR 파일을 사용한 API 보안 테스트 스캔

대상 API에 대한 정보를 제공하는 HAR 파일을 사용하여 API 보안 테스트를 구성하려면 다음을 수행합니다:

.gitlab-ci.yml 파일에 API-Security.gitlab-ci.yml 템플릿을 포함합니다.
구성 파일에는 여러 테스트 프로필이 정의되어 다양한 확인 사항이 활성화됩니다. Quick 프로필을 시작하는 것을 권장합니다. 이 프로필로 테스트하면 설정 유효성 검사가 쉬워집니다.
.gitlab-ci.yml 파일에 APISEC_PROFILE CI/CD 변수를 추가하여 프로필을 제공합니다.
HAR 파일의 위치를 제공합니다. 파일 경로나 URL로 위치를 지정할 수 있습니다. APISEC_HAR 변수를 추가하여 위치를 지정합니다.
대상 API 인스턴스의 기본 URL도 필요합니다. 이를 APISEC_TARGET_URL 변수나 environment_url.txt 파일을 사용하여 제공합니다.
프로젝트 루트에 environment_url.txt 파일에 URL을 추가하면 동적 환경에서 테스트하는 데 유용합니다. GitLab CI/CD 파이프라인에서 동적으로 생성된 응용프로그램에 대해 API 보안 테스트를 실행하려면 해당 응용프로그램에서 URL을 environment_url.txt 파일에 유지하도록 하면 됩니다. API 보안 테스트는 이 파일을 자동으로 구문 분석하여 스캔 대상을 찾습니다. 이에 대한 예시는 Auto DevOps CI YAML에서 확인할 수 있습니다.

HAR 파일을 사용한 구성의 완전한 예시:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_HAR: test-api-recording.har
  APISEC_TARGET_URL: http://test-deployment/

여기서부터 다음 작업을 수행할 수 있습니다:

첫 번째 스캔 실행.
인증 추가.
거짓 양성 처리.

GraphQL 스키마

GraphQL 스키마 지원은 GitLab 15.4에서 소개되었습니다.

GraphQL은 API의 쿼리 언어이자 REST API의 대안입니다. API 보안 테스트는 GraphQL 엔드포인트를 여러 가지 방법으로 테스트할 수 있습니다:

GraphQL 스키마를 사용하여 테스트. GitLab 15.4에서 소개됨.
GraphQL 쿼리의 녹화 (HAR)를 사용하여 테스트.
GraphQL 쿼리를 포함하는 Postman Collection을 사용하여 테스트.

이 섹션에서는 GraphQL 스키마를 사용하는 방법에 대해 다룹니다. API 보안 테스트의 GraphQL 스키마 지원은 내성을 지원하는 엔드포인트에서 스키마에 대한 쿼리를 수행할 수 있습니다. 내성은 GraphiQL과 같은 도구가 작동하도록 기본적으로 활성화되어 있습니다. 내성을 활성화하는 방법의 자세한 내용은 GraphQL 프레임워크 설명서를 참조하십시오.

GraphQL 엔드포인트 URL을 사용한 API 보안 테스트 스캔

API 보안 테스트의 GraphQL 지원은 스키마를 위해 GraphQL 엔드포인트에 쿼리를 수행할 수 있습니다.

참고: 이 방법을 올바르게 사용하려면 GraphQL 엔드포인트는 내성 쿼리를 지원해야 합니다.

API 보안 테스트가 대상 API에 대한 정보를 제공하는 GraphQL 엔드포인트 URL을 사용하도록 구성하려면 다음을 수행합니다:

.gitlab-ci.yml 파일에 API-Security.gitlab-ci.yml 템플릿을 포함합니다.
GraphQL 엔드포인트의 경로를 제공합니다. /api/graphql과 같이 지정하고 APISEC_GRAPHQL 변수를 추가하여 위치를 지정합니다.
대상 API 인스턴스의 기본 URL도 필요합니다. 이를 APISEC_TARGET_URL 변수나 environment_url.txt 파일을 사용하여 제공합니다.
프로젝트 루트에 environment_url.txt 파일에 URL을 추가하면 동적 환경에서 테스트하는 데 유용합니다. 자세한 내용은 문서의 동적 환경 솔루션 섹션을 참조하십시오.

GraphQL 엔드포인트 경로를 사용한 구성의 완전한 예시:

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_TARGET_URL: http://test-deployment/

여기서부터 다음 작업을 수행할 수 있습니다:

첫 번째 스캔 실행.
인증 추가.
거짓 양성 처리.

GraphQL 스키마 파일을 사용한 API 보안 테스트 스캔

API 보안 테스트는 내성을 비활성화한 GraphQL 엔드포인트의 이해와 테스트를 위해 GraphQL 스키마 파일을 사용할 수 있습니다. GraphQL 스키마 파일을 사용하려면 내성 JSON 형식이어야 합니다. GraphQL 스키마는 온라인 3rd party 도구를 사용하여 내성 JSON 형식으로 변환할 수 있습니다: https://transform.tools/graphql-to-introspection-json.

대상 API에 대한 정보를 제공하는 GraphQL 스키마 파일을 사용하여 API 보안 테스트를 구성하려면 다음을 수행합니다:

.gitlab-ci.yml 파일에 API-Security.gitlab-ci.yml 템플릿을 포함합니다.
GraphQL 엔드포인트의 경로를 제공합니다. /api/graphql과 같이 지정하고 APISEC_GRAPHQL 변수를 추가하여 위치를 지정합니다.
GraphQL 스키마 파일의 위치를 제공합니다. 파일 경로나 URL로 위치를 지정할 수 있습니다. APISEC_GRAPHQL_SCHEMA 변수를 추가하여 위치를 지정합니다.
대상 API 인스턴스의 기본 URL도 필요합니다. 이를 APISEC_TARGET_URL 변수나 environment_url.txt 파일을 사용하여 제공합니다.
프로젝트 루트에 environment_url.txt 파일에 URL을 추가하면 동적 환경에서 테스트하는 데 유용합니다. 자세한 내용은 문서의 동적 환경 솔루션 섹션을 참조하십시오.

GraphQL 스키마 파일을 사용한 구성의 완전한 예시:

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

GraphQL 스키마 파일 URL을 사용한 구성의 완전한 예시:

stages:
  - dast

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

api_security:
  variables:
    APISEC_GRAPHQL: /api/graphql
    APISEC_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    APISEC_TARGET_URL: http://test-deployment/

여기서부터 다음 작업을 수행할 수 있습니다:

첫 번째 스캔 실행.
인증 추가.
거짓 양성 처리.

Postman Collection

Postman API Client은 개발자와 테스터들이 다양한 유형의 API를 호출하는 데 사용하는 인기 있는 도구입니다. API 정의는 Postman Collection 파일로 내보낼 수 있습니다 API 보안 테스트에 사용하기 위해서입니다. 내보낼 때, 지원되는 Postman Collection 버전인 v2.0 또는 v2.1을 선택해야 합니다.

GitLab API 보안 테스트 스캐너와 함께 사용할 때, Postman Collection에는 유효한 데이터로 테스트할 웹 API의 정의가 포함되어 있어야 합니다. API 보안 테스트 스캐너는 모든 API 정의를 추출하여 테스트를 수행합니다.

경고: Postman Collection 파일에는 인증 토큰, API 키, 세션 쿠키와 같은 개인 정보가 포함될 수 있습니다. 저장소에 추가하기 전에 Postman Collection 파일 내용을 검토하는 것을 권장합니다.

Postman Collection 파일을 사용한 API 보안 테스트 스캔

타깃 API에 대한 정보를 제공하는 Postman Collection 파일을 사용하여 API 보안 테스트를 구성하려면 다음을 수행하세요:

API-Security.gitlab-ci.yml 템플릿을 포함시킵니다.
구성 파일에는 여러 테스트 프로필이 정의되어 있으며, 서로 다른 체크가 활성화되어 있습니다. Quick 프로필부터 시작하는 것을 권장합니다. 이 프로필로 테스트하면 더 빠르게 완료되어 구성 유효성을 더 쉽게 검증할 수 있습니다.
.gitlab-ci.yml 파일에 APISEC_PROFILE CI/CD 변수를 추가하여 프로필을 제공합니다.
Postman Collection 파일의 위치를 파일 또는 URL로 제공해야 합니다. APISEC_POSTMAN_COLLECTION 변수를 추가하여 위치를 지정하십시오.
타깃 API 인스턴스의 기본 URL도 필요합니다. APISEC_TARGET_URL 변수 또는 environment_url.txt 파일을 사용하여 제공합니다.
프로젝트 루트에 environment_url.txt 파일에 URL을 추가하면 동적 환경에서의 테스트에 좋습니다. GitLab CI/CD 중에 동적으로 생성된 앱에서 API 보안 테스트를 실행하려면 해당 앱의 URL을 environment_url.txt 파일에 유지하도록 합니다. API 보안 테스트는 해당 파일을 구문 분석하여 스캔 대상을 찾습니다. 이에 대한 예시는 Auto DevOps CI YAML에서 확인할 수 있습니다.

Postman Collection 사용 구성의 완전한 예시입니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection_serviceA.json
  APISEC_TARGET_URL: http://test-deployment/

이것은 API 보안 테스트의 최소 구성입니다. 여기서부터 다음을 수행할 수 있습니다:

첫 번째 스캔 실행.
인증 추가.
잘못된 긍정적인 항목 처리 방법.

Postman 변수

Postman 환경 파일 형식 지원은 GitLab 15.1에서 도입되었습니다.
여러 변수 파일 지원은 GitLab 15.1에서 도입되었습니다.
Postman 변수 범위 지원: Global 및 Environment는 GitLab 15.1에서 도입되었습니다.

Postman 클라이언트의 변수

Postman은 개발자가 요청의 여러 부분에서 사용할 수 있는 플레이스홀더를 정의할 수 있게 합니다. 이러한 플레이스홀더는 변수라고 불리며, 변수 사용에서 설명된 대로 요청 및 스크립트에서 값 저장 및 재사용에 사용할 수 있습니다. 예를 들어, 변수를 추가하여 문서에 변수를 추가할 수 있습니다:

또는 환경에 변수를 추가할 수 있습니다:

그런 다음 URL, 헤더 및 기타 섹션에서 변수를 사용할 수 있습니다:

Postman은 멋진 UX 경험을 제공하는 기본적인 클라이언트 도구에서부터 스크립트로 API를 테스트하고, 부수적인 요청을 트리거하는 복잡한 컬렉션을 만들고 그 동안 변수를 설정할 수 있는 복잡한 생태계로 성장했습니다. Postman 생태계의 모든 기능이 지원되는 것은 아닙니다. 예를 들어, 스크립트는 지원되지 않습니다. Postman 지원의 주요 중점은 Postman 클라이언트와 해당 관련 변수에서 사용되는 Postman Collection 정의를 수용하는 데 있습니다.

Postman은 다른 범위에서 변수를 생성할 수 있게 합니다. 각 범위는 Postman 도구에서 다른 수준의 가시성을 가지고 있습니다. 예를 들어, Postman 클라이언트에서 전역 환경 범위에 변수를 생성할 수 있으며, 이 변수를 선택한 환경에서만 사용하는 범위 변수입니다. 일부 범위는 항상 사용할 수 있는 것은 아니며, 예를 들어 Postman 생태계에서 Postman 클라이언트에서 요청을 생성할 수 있지만 로컬 범위는 가지고 있지 않지만, 테스트 스크립트는 그렇습니다.

Postman의 변수 범위는 복잡한 주제일 수 있으며, 모든 사람이 그것을 공부한 것은 아닙니다. 이어서 진행하기 전에 Postman 문서의 Variable Scopes를 꼭 읽으실 것을 강력히 권장합니다.

위에서 언급한대로, 다양한 변수 범위가 있으며, 각각은 Postman 문서에 따라 값을 계산하는 중요한 참고 사항이 있습니다:

동일한 이름의 변수가 두 가지 다른 범위에서 선언되면, 가장 좁은 범위에 있는 변수의 값이 사용됩니다. 예를 들어 전역 변수인 username과 로컬 변수인 username이 있는 경우, 요청 실행 시에 로컬 값이 사용됩니다.

다음은 Postman 클라이언트 및 API 보안 테스팅에서 지원되는 변수 범위를 요약한 것입니다:

글로벌 환경(Global) 범위는 워크스페이스 전체에서 사용할 수 있는 특별하게 정의된 환경입니다. Postman 클라이언트는 전역 환경을 JSON 파일로 내보낼 수 있으며, 이는 API 보안 테스트와 함께 사용될 수 있습니다.
환경(Environment) 범위은 사용자가 Postman 클라이언트에서 생성한 변수의 명명된 그룹입니다. Postman 클라이언트는 전역 환경과 함께 사용할 수 있는 단일 활성 환경을 지원합니다. 활성 사용자가 생성한 환경에 정의된 변수는 전역 환경에 정의된 변수보다 우선시됩니다. Postman 클라이언트는 환경을 JSON 파일로 내보낼 수 있으며, 이는 API 보안 테스트와 함께 사용될 수 있습니다.
컬렉션(Collection) 범위은 주어진 컬렉션에 선언된 변수의 그룹입니다. 컬렉션 변수는 해당 컬렉션 및 중첩된 요청 또는 컬렉션에서 사용 가능합니다. 컬렉션 범위에 정의된 변수는 글로벌 환경 범위 및 환경 범위보다 우선시됩니다. Postman 클라이언트는 선택한 컬렉션, 요청 및 컬렉션 변수가 포함된 JSON 파일을 내보낼 수 있습니다.
API 보안 테스트 범위는 API 보안 테스팅에서 추가 변수를 제공하거나 다른 지원된 범위에서 정의된 변수를 덮어쓸 수 있도록 하는 새로운 범위입니다. 이 범위는 Postman에서 지원하지 않습니다. API 보안 테스팅 범위 변수는 사용자 지정 JSON 파일 형식을 사용하여 제공됩니다.
- 환경 또는 컬렉션에 정의된 값 덮어쓰기
- 스크립트에서 정의된 변수 정의
- 지원되지 않는 _data 범위_에서 데이터 단일 행을 정의
데이터(Data) 범위는 JSON 또는 CSV 파일에서 이름과 값을 가져오는 변수 그룹입니다. Postman 컬렉션 실행기(예: Newman 또는 Postman Collection Runner)는 JSON 또는 CSV 파일이 갖는 항목 수많큼 컬렉션의 요청을 실행합니다. 이러한 변수에 대한 좋은 사용 사례는 Postman에서 스크립트를 사용하여 테스트를 자동화하는 것입니다. API 보안 테스트는 CSV 또는 JSON 파일에서 데이터를 읽는 것을 지원하지 않습니다.
로컬(Local) 범위는 Postman 스크립트에서 정의된 변수입니다. API 보안 테스트는 Postman 스크립트 및 이에 따라 스크립트에서 정의된 변수를 지원하지 않습니다. 그러나 지원되는 범위 중 하나에 값을 정의하여 스크립트로 정의된 변수에 대한 값들을 제공할 수 있습니다.

모든 범위가 API 보안 테스팅에서 지원되는 것은 아니며, 스크립트에서 정의된 변수도 지원되지 않습니다. 다음 표는 가장 광범위한 범위부터 가장 좁은 범위까지 정렬되어 있습니다.

범위	Postman	API 보안 테스트	설명
글로벌 환경(Global)	Yes	Yes	특별하게 정의된 전역 환경
환경(Environment)	Yes	Yes	명명된 환경
컬렉션(Collection)	Yes	Yes	Postman 클라이언트에 정의된 컬렉션
API 보안 테스트 범위	No	Yes	API 보안 테스트에서 추가된 사용자 정의 범위
데이터(Data)	Yes	No	CSV 또는 JSON 형식의 외부 파일
로컬(Local)	Yes	No	스크립트에서 정의된 변수

다양한 범위에서 변수를 정의하고 내보내려면 다음을 참조하세요:

Postman Client의 내보내기

Postman 클라이언트를 사용하면 다양한 파일 형식으로 내보낼 수 있습니다. 예를 들어, Postman 컬렉션 또는 Postman 환경을 내보낼 수 있습니다.

내보낸 환경은 전역 환경(항상 사용 가능)이거나 이전에 만든 사용자 정의 환경일 수 있습니다. Postman 컬렉션을 내보낼 때는 컬렉션 및 로컬 범위 변수만 포함될 수 있으며 환경 범위 변수는 포함되지 않습니다.

다른 지원되는 범위에서 변수를 내보내는 자세한 내용은 다음을 참조하세요:

API 보안 테스팅 범위, 사용자 정의 JSON 파일 형식

우리의 사용자 정의 JSON 파일 형식은 JSON 객체로, 각 객체 속성은 변수 이름을 나타내고 속성 값은 변수 값으로 나타냅니다. 이 파일은 좋아하는 텍스트 편집기를 사용하여 만들거나 이전에 파이프라인 작업에서 생성할 수 있습니다.

이 예제는 API 보안 테스팅 범위에서 base_url 및 token 두 가지 변수를 정의합니다:

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

API 보안 테스팅에서 범위 사용

스코프인 전역, 환경, 컬렉션, GitLab API 보안 테스팅_은 GitLab 15.1 이후에서만 지원됩니다. 이전 버전인 GitLab 15.0 및 이전 버전에서는 _컬렉션, GitLab API 보안 테스팅 스코프만 지원됩니다.

다음 표는 스코프 파일/URL을 API 보안 테스팅 구성 변수에 매핑하는 빠른 참조를 제공합니다:

스코프	제공 방법
전역 환경	APISEC_POSTMAN_COLLECTION_VARIABLES
환경	APISEC_POSTMAN_COLLECTION_VARIABLES
컬렉션	APISEC_POSTMAN_COLLECTION
API 보안 테스팅 범위	APISEC_POSTMAN_COLLECTION_VARIABLES
데이터	지원 안 됨
로컬	지원 안 됨

Postman 컬렉션 문서에는 자동으로 컬렉션 범위 변수가 포함됩니다. Postman 컬렉션은 구성 변수 APISEC_POSTMAN_COLLECTION과 함께 제공됩니다. 이 변수는 단일 내보낸 Postman 컬렉션으로 설정할 수 있습니다.

다른 스코프의 변수는 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다. 이 구성 변수는 GitLab 15.1 이후에서 쉼표(,)로 구분된 파일 목록을 지원합니다. GitLab 15.0 및 이전 버전에서는 단일 파일만 지원됩니다. 제공된 파일의 순서는 중요하지 않으며 파일이 필요한 스코프 정보를 제공합니다.

구성 변수 APISEC_POSTMAN_COLLECTION_VARIABLES은 다음과 같이 설정할 수 있습니다:

정의되지 않은 Postman 변수

API 보안 테스팅 엔진이 Postman 컬렉션 파일에서 사용하는 모든 변수 참조를 찾지 못할 수 있습니다. 이 경우가 있을 수 있습니다:

데이터 또는 로컬 범위 변수를 사용하고 있으며, 이러한 범위가 API 보안 테스팅에서 지원되지 않습니다. 따라서, 데이터 및 로컬 범위 변수의 값을 API 보안 테스팅 범위를 통해 제공하지 않았다면, 데이터 및 로컬 범위 변수의 값은 정의되지 않은 상태입니다.
변수 이름이 잘못 입력되었으며, 이름이 정의된 변수와 일치하지 않는 경우.
Postman 클라이언트가 지원하는 새로운 동적 변수를 사용하는 경우 API 보안 테스팅에서는 동일한 동작을 따릅니다.

가능한 경우 API 보안 테스팅은 정의되지 않은 변수에 대해 Postman 클라이언트가 다루는 것과 동일한 동작을 따릅니다. 변수 참조 텍스트는 그대로 유지되며 텍스트 대체가 없습니다. 동일한 동적 변수 사용에도 동일한 동작이 적용됩니다.

예를 들어, Postman 컬렉션의 요청 정의에서 변수 {{full_url}}을 참조하고 해당 변수를 찾지 못한 경우 {{full_url}} 값은 변경되지 않은 채로 남아 있습니다.

동적 Postman 변수

사용자가 다양한 범위 수준에서 정의할 수 있는 변수 외에도, Postman에는 동적 변수 라고 불리는 미리 정의된 변수 세트가 있습니다. 동적 변수는 이미 정의되어 있으며 이름 앞에 달러 기호($)가 붙습니다. 예를 들어 $guid와 같이 나타납니다. 동적 변수는 다른 변수와 마찬가지로 사용할 수 있으며, Postman 클라이언트에서는 요청/컬렉션 실행 중에 무작위 값이 생성됩니다.

API 보안 테스팅과 Postman 사이의 중요한 차이점은 API 보안 테스팅이 동일한 동적 변수 사용에 대해 각 사용에서 동일한 값이 반환된다는 것입니다. 이는 Postman 클라이언트의 동작과 달리 API 보안 테스팅이 동적 변수에 대해 정적 값으로 반환한다는 것입니다. 다시 말해, API 보안 테스팅은 동적 변수에 대해 무작위 값을 반환하는 대신에 정적 값을 사용합니다.

스캐닝 프로세스 중 지원되는 동적 변수는 다음과 같습니다:

변수	값
`$guid`	`611c2e81-2ccb-42d8-9ddc-2d0bfa65c1b4`
`$isoTimestamp`	`2020-06-09T21:10:36.177Z`
… (이하 생략) …	… (이하 생략) …

예시: 전역 범위

이 예에서, 전역 범위는 Postman 클라이언트에서 global-scope.json으로 내보내어 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 API 보안 테스트에 제공됩니다.

APISEC_POSTMAN_COLLECTION_VARIABLES 사용 예시는 다음과 같습니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  APISEC_TARGET_URL: http://test-deployment/

예시: 환경 범위

이 예에서, 환경 범위는 Postman 클라이언트에서 environment-scope.json으로 내보내어 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 API 보안 테스트에 제공됩니다.

APISEC_POSTMAN_COLLECTION_VARIABLES 사용 예시는 다음과 같습니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

예시: 컬렉션 범위

컬렉션 범위 변수는 내보낸 Postman 컬렉션 파일에 포함되어 APISEC_POSTMAN_COLLECTION 구성 변수를 통해 제공됩니다.

APISEC_POSTMAN_COLLECTION 사용 예시는 다음과 같습니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_TARGET_URL: http://test-deployment/

예시: API 보안 테스트 범위

API 보안 테스트 범위는 두 가지 주요 목적으로 사용됩니다. API 보안 테스트에서 지원되지 않는 데이터 및 로컬 범위 변수를 정의하고 다른 범위에서 정의된 기존 변수의 값을 변경합니다. API 보안 테스트 범위는 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다.

APISEC_POSTMAN_COLLECTION_VARIABLES 사용 예시는 다음과 같습니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

파일 dast-api-scope.json은 사용자 정의 JSON 파일 형식을 사용합니다. 이 JSON은 속성에 대한 키-값 쌍을 가지는 객체입니다. 키는 변수 이름이고 값은 변수의 값입니다. 예를 들어:

{
  "base_url": "http://127.0.0.1/",
  "token": "Token 84816165151"
}

예시: 여러 범위

이 예에서는 전역 범위, 환경 범위 및 컬렉션 범위가 구성됩니다. 첫 번째 단계는 여러 범위를 내보내는 것입니다.

전역 범위를 내보내기: global-scope.json
환경 범위를 내보내기: environment-scope.json
컬렉션 범위를 포함하는 Postman 컬렉션을 postman-collection.json로 내보냅니다.

Postman 컬렉션은 APISEC_POSTMAN_COLLECTION 변수를 사용하여 제공되며, 다른 범위는 APISEC_POSTMAN_COLLECTION_VARIABLES를 사용하여 제공됩니다. API 보안 테스트는 각 파일에서 제공된 데이터를 사용하여 제공된 파일이 어떤 범위와 일치하는지 확인할 수 있습니다.

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  APISEC_TARGET_URL: http://test-deployment/

예시: 변수 값 변경

내보낸 범위를 사용할 때 종종 변수의 값이 API 보안 테스트에 사용되도록 변경해야 할 때가 있습니다. 예를 들어, 컬렉션 범위 변수에는 api_version이라는 변수가 v2라는 값으로 포함될 수 있으며, 테스트에는 v1의 값이 필요할 수 있습니다. 내보낸 컬렉션을 변경하여 값이 변경될 수 있지만, API 보안 테스트 범위를 사용하여 값을 변경할 수 있습니다. 이는 API 보안 테스트 범위가 모든 다른 범위보다 우선되기 때문에 작동합니다.

컬렉션 범위 변수는 내보낸 Postman 컬렉션 파일에 포함되어 APISEC_POSTMAN_COLLECTION 구성 변수를 통해 제공됩니다.

API 보안 테스트 범위는 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다. 하지만 먼저 파일을 생성해야 합니다. 파일 dast-api-scope.json은 사용자 정의 JSON 파일 형식을 사용합니다. 이 JSON은 속성에 대한 키-값 쌍을 가지는 객체입니다. 키는 변수 이름이고 값은 변수의 값입니다. 예를 들어:

{
  "api_version": "v1"
}

저희 CI 정의는 다음과 같습니다:

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

예시: 여러 범위에서 변수 값 변경

내보낸 범위를 사용할 때 종종 변수의 값이 API 보안 테스트에 사용되도록 변경해야 할 때가 있습니다. 예를 들어, 환경 범위에는 api_version이라는 변수가 v2라는 값으로 포함될 수 있으며, 테스트에는 v1의 값이 필요할 수 있습니다. 내보낸 파일을 변경하여 값을 변경하는 대신, API 보안 테스트 범위를 사용할 수 있습니다. 이는 API 보안 테스트 범위가 모든 다른 범위보다 우선되기 때문에 작동합니다.

이 예에서는 전역 범위, 환경 범위, 컬렉션 범위 및 API 보안 테스트 범위가 구성됩니다. 첫 번째 단계는 여러 범위를 내보내고 생성하는 것입니다.

전역 범위를 내보내기: global-scope.json
환경 범위를 내보내기: environment-scope.json
컬렉션 범위를 포함하는 Postman 컬렉션을 postman-collection.json로 내보냅니다

API 보안 테스트 범위는 APISEC_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다. 이를 위해 dast-api-scope.json 파일을 생성해야 합니다. 이 JSON은 속성에 대한 키-값 쌍을 가지는 객체입니다. 키는 변수 이름이고 값은 변수의 값입니다. 예를 들어:

{
  "api_version": "v1"
}

stages:
  - dast

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

variables:
  APISEC_PROFILE: Quick
  APISEC_POSTMAN_COLLECTION: postman-collection.json
  APISEC_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,dast-api-scope.json
  APISEC_TARGET_URL: http://test-deployment/

첫 번째 스캔 실행

정확하게 구성된 경우 CI/CD 파이프라인에는 dast 단계와 dast_api 작업이 포함됩니다. 작업은 잘못된 구성이 제공될 때에만 실패합니다. 일반적인 운영 중에는 취약점이 식별되더라도 항상 성공합니다.

보안(Security) 파이프라인 탭에서 취약점은 스위트 이름과 함께 표시됩니다. 저장소의 기본 브랜치에 대해 테스트할 때 API 보안 테스트 취약점은 보안 및 규정 준수의 취약점 보고서 페이지에도 표시됩니다.

보고된 취약점 수를 과도하게 막기 위해 API 보안 테스트 스캐너는 작업 당 보고되는 취약점의 수를 제한합니다.

API 보안 테스트 취약점 보기

API 보안 테스트 분석기는 수집되어 사용되는 JSON 보고서를 생성합니다. GitLab 취약점 화면에 취약점을 채우기 위해 사용됩니다.

false positives(잘못된 양성) 처리에 관한 정보는 잘못된 양성이 보고되는 수를 제한할 수 있는 구성 변경에 대한 자세한 내용을 확인하세요.

API 보안 테스트 취약점 세부 정보 보기

다음 단계를 따라 취약점의 세부 정보를 확인하세요:

프로젝트 또는 병합 요청에서 취약점을 확인할 수 있습니다:
- 프로젝트의 보안(Secure) > 취약점 보고서(Vulnerability report) 페이지에서 확인할 수 있습니다. 이 페이지는 기본 브랜치에서의 모든 취약점을 보여줍니다.
- 병합 요청에서 보안(Security) 섹션으로 이동하고 확장(Expand) 버튼을 선택하세요. API 보안 테스트 취약점은 DAST detected N potential vulnerabilities로 표시되며 제목을 선택하여 취약점 세부 정보를 확인할 수 있습니다.

세부 정보를 확인하려면 취약점의 제목을 선택하세요. 아래 표에서 이러한 세부 내용을 설명합니다.

필드	설명
설명	어떤 수정이 있었는지를 포함한 취약성에 대한 설명
프로젝트	취약성이 감지된 네임스페이스 및 프로젝트
방법	취약성을 감지하는 데 사용된 HTTP 메서드
URL	취약성이 감지된 URL
요청	취약성을 유발한 HTTP 요청
수정되지 않은 응답	수정되지 않은 요청의 응답. 전형적인 작동 응답의 형태입니다.
실제 응답	테스트 요청에서 받은 응답
근거	취약성이 발생했음을 어떻게 확인했는지
식별자	이 취약성을 찾기 위해 사용된 API 보안 테스트 확인
심각도	취약성의 심각도
스캐너 유형	테스트를 수행하는 데 사용된 스캐너

보안 대시보드

보안 대시보드는 그룹, 프로젝트, 및 파이프라인의 모든 보안 취약점에 대한 개요를 제공하는 좋은 장소입니다. 추가 정보는 보안 대시보드 설명서를 참조하세요.

취약점과 상호 작용

취약점을 발견하면 해당 취약점과 상호 작용할 수 있습니다. 취약점 주소 지정 방법에 대해 자세히 알아보세요.

잘못된 양성 처리

잘못된 양성은 여러 가지 방법으로 처리할 수 있습니다:

취약점을 해제합니다.
일부 확인은 취약점이 식별되었을 때 감지하는 여러 가지 방법, 즉 _Assertions_이 있습니다. Assertions는 끄거나 구성할 수도 있습니다. 예를 들어, API 보안 테스트 스캐너는 기본적으로 HTTP 상태 코드를 사용하여 실제 문제일 때를 식별하는 데 사용됩니다. 테스트 중에 API가 500 오류를 반환하면 이것은 취약성을 생성합니다. 이는 항상 원하는 것은 아니며, 몇몇 프레임워크는 자주 500 오류를 반환합니다.
잘못된 양성을 생성하는 확인을 중지합니다. 이렇게 하면 해당 확인이 어떤 취약점도 생성하지 못합니다. 예제 확인에는 SQL Injection Check 및 JSON Hijacking Check 등이 있습니다.

확인 중지

확인은 특정 유형의 테스트를 수행하고 특정 구성 프로필에 대해 켜고 끌 수 있습니다. 제공된 구성 파일에서는 사용할 수 있는 여러 프로필을 정의합니다. 구성 파일의 프로필 정의에서 스캔 중에 활성화된 모든 확인을 나열합니다. 특정 확인을 중지하려면 구성 파일의 프로필 정의에서 해당 확인을 제거합니다. 프로필은 구성 파일의 Profiles 섹션에 정의됩니다.

예시 프로필 정의:

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
          - Name: TokenCheck
          - Name: XmlInjectionCheck

JSON Hijacking Check을 중지하려면 이 줄을 제거할 수 있습니다:

          - Name: JsonHijackingCheck

이로 인해 다음 YAML이 생성됩니다:

- Name: Quick
  DefaultProfile: Empty
  Routes:
    - Route: *Route0
      Checks:
        - Name: ApplicationInformationCheck
        - Name: CleartextAuthenticationCheck
        - Name: FrameworkDebugModeCheck
        - Name: HtmlInjectionCheck
        - Name: InsecureHttpMethodsCheck
        - Name: JsonInjectionCheck
        - Name: SensitiveInformationCheck
        - Name: SessionCookieCheck
        - Name: SqlInjectionCheck
        - Name: TokenCheck
        - Name: XmlInjectionCheck

확인을 위한 Assertion 중지

Assertions는 확인에 의해 생성된 테스트의 취약성을 감지합니다. 많은 확인은 Log Analysis, Response Analysis, 및 Status Code와 같은 여러 가지 Assertions을 지원합니다. 취약성이 발견되면 사용된 Assertion이 제공됩니다. 기본적으로 켜져 있는 확인을 확인하려면 구성 파일에서 확인의 기본 구성을 보세요. 이 섹션은 Checks 라고 부릅니다.

다음의 예시는 SQL Injection Check를 보여줍니다:

- Name: SqlInjectionCheck
  Configuration:
    UserInjections: []
  Assertions:
    - Name: LogAnalysisAssertion
    - Name: ResponseAnalysisAssertion
    - Name: StatusCodeAssertion

여기에서 기본적으로 세 가지 Assertion이 켜져 있습니다. 잘못된 양성의 일반적인 원인은 StatusCodeAssertion입니다. 이것을 해제하려면 구성 파일에서 해당 확인에 대한 설정을 수정합니다. 이 예제에서는 SqlInjectionCheck가 StatusCodeAssertion을 사용하지 않도록 합니다 (LogAnalysisAssertion, ResponseAnalysisAssertion만 사용합니다):

Profiles:
  - Name: Quick
    DefaultProfile: Empty
    Routes:
      - Route: *Route0
        Checks:
          - Name: ApplicationInformationCheck
          - Name: CleartextAuthenticationCheck
          - Name: FrameworkDebugModeCheck
          - Name: HtmlInjectionCheck
          - Name: InsecureHttpMethodsCheck
          - Name: JsonHijackingCheck
          - Name: JsonInjectionCheck
          - Name: SensitiveInformationCheck
          - Name: SessionCookieCheck
          - Name: SqlInjectionCheck
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: TokenCheck
          - Name: XmlInjectionCheck

Analyzer 활성화

OpenAPI Specification

OpenAPI 및 미디어 유형

OpenAPI Specification을 사용하여 API 보안 테스트 구성

HTTP Archive (HAR)

HAR 파일을 사용한 API 보안 테스트 스캔

GraphQL 스키마

GraphQL 엔드포인트 URL을 사용한 API 보안 테스트 스캔

GraphQL 스키마 파일을 사용한 API 보안 테스트 스캔

Postman Collection

Postman Collection 파일을 사용한 API 보안 테스트 스캔

Postman 변수

Postman 클라이언트의 변수

Postman Client의 내보내기

API 보안 테스팅 범위, 사용자 정의 JSON 파일 형식

API 보안 테스팅에서 범위 사용

정의되지 않은 Postman 변수

동적 Postman 변수

예시: 전역 범위

예시: 환경 범위

예시: 컬렉션 범위

예시: API 보안 테스트 범위

예시: 여러 범위

예시: 변수 값 변경

예시: 여러 범위에서 변수 값 변경

첫 번째 스캔 실행

API 보안 테스트 취약점 보기

API 보안 테스트 취약점 세부 정보 보기

보안 대시보드

취약점과 상호 작용

잘못된 양성 처리

확인 중지

확인을 위한 Assertion 중지

도움말

기능 사용 가능성과 제품 평가판

도움받기