필수 조건:

• 다음 웹 API 유형 중 하나:

  • REST API
  • SOAP
  • GraphQL
  • Form bodies, JSON, or XML

• 테스트할 API를 제공하는 다음 자산 중 하나:

  • OpenAPI v2 또는 v3 API 정의
  • 테스트할 API 요청의 HTTP 아카이브 (HAR)
  • Postman Collection v2.0 또는 v2.1

  [!warning] 프로덕션 서버에 대해 절대 fuzz 테스팅을 실행하지 마세요. API가 수행할 수 있는 모든 기능을 수행할 수 있을 뿐만 아니라 API의 버그를 트리거할 수도 있습니다. 여기에는 데이터 수정 및 삭제와 같은 작업이 포함됩니다. 테스트 서버에 대해서만 fuzzing을 실행하세요.

웹 API fuzzing을 활성화하려면 웹 API fuzzing 구성 양식을 사용합니다.

• 수동 구성 지침은 API 유형에 따라 해당 섹션을 참조하세요:
  • OpenAPI 스펙
  • GraphQL 스키마
  • HTTP 아카이브 (HAR)
  • Postman Collection
• 그 외의 경우 웹 API fuzzing 구성 양식을 참조하세요.

API fuzzing 구성 파일은 리포지터리의 .gitlab 디렉토리에 있어야 합니다.

웹 API fuzzing 구성 양식#

API fuzzing 구성 양식은 프로젝트의 API fuzzing 구성을 생성하거나 수정하는 데 도움을 줍니다. 양식을 통해 가장 일반적인 API fuzzing 옵션의 값을 선택하고 GitLab CI/CD 구성에 붙여넣을 수 있는 YAML 스니펫을 생성합니다.

UI에서 웹 API fuzzing 구성#

API fuzzing 구성 스니펫을 생성하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Secure > 보안 구성을 선택합니다.
3. API Fuzzing 행에서 API Fuzzing 활성화를 선택합니다.
4. 필드를 입력합니다. 자세한 내용은 사용 가능한 CI/CD 변수를 참조하세요.
5. 코드 스니펫 생성을 선택합니다. 양식에서 선택한 옵션에 해당하는 YAML 스니펫이 포함된 대화 상자가 열립니다.
6. 다음 중 하나를 수행합니다:
   1. 스니펫을 클립보드에 복사하려면 코드만 복사를 선택합니다.
   2. 프로젝트의 .gitlab-ci.yml 파일에 스니펫을 추가하려면 코드 복사 및 .gitlab-ci.yml 파일 열기를 선택합니다. 파이프라인 편집기가 열립니다.
      1. .gitlab-ci.yml 파일에 스니펫을 붙여넣습니다.
      2. Lint 탭을 선택하여 편집된 .gitlab-ci.yml 파일이 유효한지 확인합니다.
      3. 편집 탭을 선택한 다음 변경 사항 커밋을 선택합니다.

스니펫이 .gitlab-ci.yml 파일에 커밋되면 파이프라인에 API fuzzing job이 포함됩니다.

OpenAPI 스펙#

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

API fuzzing은 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 fuzzing은 나열된 미디어 유형을 확인하고 지원되는 각 미디어 유형에 대한 샘플 데이터를 생성하려고 시도합니다.

• 기본 동작은 사용할 지원 미디어 유형 중 하나를 선택하는 것입니다. 목록에서 첫 번째 지원 미디어 유형이 선택됩니다. 이 동작은 구성 가능합니다.

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

환경 변수 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES를 사용하면 특정 작업에 대한 요청을 생성할 때 하나 대신 지원되는 모든 미디어 유형을 사용할지 여부를 지정할 수 있습니다. 환경 변수 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES가 임의의 값으로 설정되면, API fuzzing은 특정 작업에서 하나 대신 지원되는 모든 미디어 유형에 대한 요청을 생성하려고 시도합니다. 이렇게 하면 제공된 각 미디어 유형에 대해 테스트가 반복되므로 테스트가 더 오래 걸립니다.

또는 변수 FUZZAPI_OPENAPI_MEDIA_TYPES를 사용하여 각각 테스트되는 미디어 유형 목록을 제공합니다. 두 개 이상의 미디어 유형을 제공하면 선택한 각 미디어 유형에 대해 테스트가 수행되므로 테스트가 더 오래 걸립니다. 환경 변수 FUZZAPI_OPENAPI_MEDIA_TYPES가 미디어 유형 목록으로 설정되면, 요청 생성 시 나열된 미디어 유형만 포함됩니다.

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

환경 변수 FUZZAPI_OPENAPI_ALL_MEDIA_TYPES 및 FUZZAPI_OPENAPI_MEDIA_TYPES를 사용하면 미디어 유형을 처리하는 방법을 결정할 수 있습니다. 이러한 설정은 상호 배타적입니다. 둘 다 활성화된 경우 API fuzzing은 오류를 보고합니다.

OpenAPI 스펙으로 웹 API fuzzing 구성#

OpenAPI 스펙을 사용하여 GitLab에서 API fuzzing을 구성하려면:

1. .gitlab-ci.yml 파일에 fuzz 스테이지를 추가합니다.

2. .gitlab-ci.yml 파일에 API-Fuzzing.gitlab-ci.yml 템플릿을 포함합니다.

3. .gitlab-ci.yml 파일에 FUZZAPI_PROFILE CI/CD 변수를 추가하여 프로필을 제공합니다. 프로필은 실행되는 테스트의 수를 지정합니다. 선택한 프로필로 Quick-10을 대체합니다. 자세한 내용은 API fuzzing 프로필을 참조하세요.

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. OpenAPI 스펙의 위치를 제공합니다. 스펙을 파일 또는 URL로 제공할 수 있습니다. FUZZAPI_OPENAPI 변수를 추가하여 위치를 지정합니다.

5. 대상 API 인스턴스의 기본 URL을 제공합니다. FUZZAPI_TARGET_URL 변수 또는 environment_url.txt 파일을 사용합니다.

   프로젝트 루트의 environment_url.txt 파일에 URL을 추가하는 것은 동적 환경에서 테스트하는 데 적합합니다. GitLab CI/CD 파이프라인 중에 동적으로 생성된 애플리케이션에 대해 API fuzzing을 실행하려면 애플리케이션이 URL을 environment_url.txt 파일에 유지하도록 합니다. API fuzzing은 해당 파일을 자동으로 파싱하여 스캔 대상을 찾습니다. 이에 대한 예제는 Auto DevOps CI YAML에서 볼 수 있습니다.

OpenAPI 스펙을 사용하는 .gitlab-ci.yml 파일 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/

이것은 API fuzzing의 최소 구성입니다. 여기에서 다음을 수행할 수 있습니다:

• 첫 번째 스캔 실행
• 인증 추가
• 거짓 양성 처리 방법 알아보기

API fuzzing 구성 옵션에 대한 자세한 내용은 사용 가능한 CI/CD 변수를 참조하세요.

HTTP 아카이브 (HAR)#

HTTP 아카이브 형식 (HAR)은 HTTP 트랜잭션을 로깅하기 위한 아카이브 파일 형식입니다. GitLab API fuzzer와 함께 사용할 때, HAR에는 테스트할 웹 API 호출 레코드가 포함되어야 합니다. API fuzzer는 모든 요청을 추출하고 이를 사용하여 테스트를 수행합니다.

자세한 내용 및 HAR 파일 생성 방법은 HTTP 아카이브 형식을 참조하세요.

HAR 파일로 웹 API fuzzing 구성#

HAR 파일을 사용하도록 API fuzzing을 구성하려면:

1. .gitlab-ci.yml 파일에 fuzz 스테이지를 추가합니다.

2. .gitlab-ci.yml 파일에 API-Fuzzing.gitlab-ci.yml 템플릿을 포함합니다.

3. .gitlab-ci.yml 파일에 FUZZAPI_PROFILE CI/CD 변수를 추가하여 프로필을 제공합니다. 프로필은 실행되는 테스트의 수를 지정합니다. 선택한 프로필로 Quick-10을 대체합니다. 자세한 내용은 API fuzzing 프로필을 참조하세요.

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. HAR 스펙의 위치를 제공합니다. 스펙을 파일 또는 URL로 제공할 수 있습니다. FUZZAPI_HAR 변수를 추가하여 위치를 지정합니다.

5. 대상 API 인스턴스의 기본 URL도 필요합니다. FUZZAPI_TARGET_URL 변수 또는 environment_url.txt 파일을 사용하여 제공합니다.

   프로젝트 루트의 environment_url.txt 파일에 URL을 추가하는 것은 동적 환경에서 테스트하는 데 적합합니다. GitLab CI/CD 파이프라인 중에 동적으로 생성된 앱에 대해 API fuzzing을 실행하려면 앱이 도메인을 environment_url.txt 파일에 유지하도록 합니다. API fuzzing은 해당 파일을 자동으로 파싱하여 스캔 대상을 찾습니다. GitLab Auto DevOps CI YAML에서 이에 대한 예제를 볼 수 있습니다.

HAR 파일을 사용하는 .gitlab-ci.yml 파일 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_HAR: test-api-recording.har
  FUZZAPI_TARGET_URL: http://test-deployment/

이 예제는 API fuzzing의 최소 구성입니다. 여기에서 다음을 수행할 수 있습니다:

• 첫 번째 스캔 실행
• 인증 추가
• 거짓 양성 처리 방법 알아보기

API fuzzing 구성 옵션에 대한 자세한 내용은 사용 가능한 CI/CD 변수를 참조하세요.

GraphQL 스키마#

히스토리

• GitLab 15.4에서 GraphQL 스키마 지원이 도입되었습니다.

GraphQL은 API를 위한 쿼리 언어이며 REST API의 대안입니다. API fuzzing은 여러 방법으로 GraphQL 엔드포인트 테스팅을 지원합니다:

• GraphQL 스키마를 사용한 테스트. GitLab 15.4에서 도입되었습니다.
• GraphQL 쿼리의 레코딩(HAR)을 사용한 테스트
• GraphQL 쿼리가 포함된 Postman Collection을 사용한 테스트

이 섹션은 GraphQL 스키마를 사용하여 테스트하는 방법을 문서화합니다. API fuzzing의 GraphQL 스키마 지원은 인트로스펙션을 지원하는 엔드포인트에서 스키마를 쿼리할 수 있습니다. 인트로스펙션은 GraphiQL과 같은 도구가 작동할 수 있도록 기본적으로 활성화됩니다.

GraphQL 엔드포인트 URL로 API fuzzing 스캔#

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

테스트할 대상 API에 대한 정보를 제공하는 GraphQL 엔드포인트 URL을 사용하도록 API fuzzing을 구성하려면:

1. .gitlab-ci.yml 파일에 API-Fuzzing.gitlab-ci.yml 템플릿을 포함합니다.

2. GraphQL 엔드포인트 경로(예: /api/graphql)를 제공합니다. FUZZAPI_GRAPHQL 변수를 추가하여 경로를 지정합니다.

3. 대상 API 인스턴스의 기본 URL도 필요합니다. FUZZAPI_TARGET_URL 변수 또는 environment_url.txt 파일을 사용하여 제공합니다.

   프로젝트 루트의 environment_url.txt 파일에 URL을 추가하는 것은 동적 환경에서 테스트하는 데 적합합니다. 자세한 내용은 동적 환경 솔루션을 참조하세요.

GraphQL 엔드포인트 URL 사용의 완전한 구성 예제:

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_TARGET_URL: http://test-deployment/

이 예제는 API fuzzing의 최소 구성입니다. 여기에서 다음을 수행할 수 있습니다:

• 첫 번째 스캔 실행
• 인증 추가
• 거짓 양성 처리 방법 알아보기

GraphQL 스키마 파일로 API fuzzing#

API fuzzing은 GraphQL 스키마 파일을 사용하여 인트로스펙션이 비활성화된 GraphQL 엔드포인트를 이해하고 테스트할 수 있습니다. GraphQL 스키마 파일을 사용하려면 인트로스펙션 JSON 형식이어야 합니다. GraphQL 스키마는 온라인 서드파티 도구를 사용하여 인트로스펙션 JSON 형식으로 변환할 수 있습니다: https://transform.tools/graphql-to-introspection-json.

테스트할 대상 API에 대한 정보를 제공하는 GraphQL 스키마 파일을 사용하도록 API fuzzing을 구성하려면:

1. .gitlab-ci.yml 파일에 API-Fuzzing.gitlab-ci.yml 템플릿을 포함합니다.

2. GraphQL 엔드포인트 경로(예: /api/graphql)를 제공합니다. FUZZAPI_GRAPHQL 변수를 추가하여 경로를 지정합니다.

3. GraphQL 스키마 파일의 위치를 제공합니다. 위치를 파일 경로 또는 URL로 제공할 수 있습니다. FUZZAPI_GRAPHQL_SCHEMA 변수를 추가하여 위치를 지정합니다.

4. 대상 API 인스턴스의 기본 URL도 필요합니다. FUZZAPI_TARGET_URL 변수 또는 environment_url.txt 파일을 사용하여 제공합니다.

   프로젝트 루트의 environment_url.txt 파일에 URL을 추가하는 것은 동적 환경에서 테스트하는 데 적합합니다. 자세한 내용은 동적 환경 솔루션을 참조하세요.

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

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

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

stages:
  - fuzz

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

apifuzzer_fuzz:
  variables:
    FUZZAPI_GRAPHQL: /api/graphql
    FUZZAPI_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema
    FUZZAPI_TARGET_URL: http://test-deployment/

이 예제는 API fuzzing의 최소 구성입니다. 여기에서 다음을 수행할 수 있습니다:

• 첫 번째 스캔 실행
• 인증 추가
• 거짓 양성 처리 방법 알아보기

Postman Collection#

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

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

Postman Collection 파일로 웹 API fuzzing 구성#

Postman Collection 파일을 사용하도록 API fuzzing을 구성하려면:

1. .gitlab-ci.yml 파일에 fuzz 스테이지를 추가합니다.

2. .gitlab-ci.yml 파일에 API-Fuzzing.gitlab-ci.yml 템플릿을 포함합니다.

3. .gitlab-ci.yml 파일에 FUZZAPI_PROFILE CI/CD 변수를 추가하여 프로필을 제공합니다. 프로필은 실행되는 테스트의 수를 지정합니다. 선택한 프로필로 Quick-10을 대체합니다. 자세한 내용은 API fuzzing 프로필을 참조하세요.

   variables:
     FUZZAPI_PROFILE: Quick-10
   

4. Postman Collection 스펙의 위치를 제공합니다. 스펙을 파일 또는 URL로 제공할 수 있습니다. FUZZAPI_POSTMAN_COLLECTION 변수를 추가하여 위치를 지정합니다.

5. 대상 API 인스턴스의 기본 URL을 제공합니다. FUZZAPI_TARGET_URL 변수 또는 environment_url.txt 파일을 사용합니다.

   프로젝트 루트의 environment_url.txt 파일에 URL을 추가하는 것은 동적 환경에서 테스트하는 데 적합합니다. GitLab CI/CD 파이프라인 중에 동적으로 생성된 앱에 대해 API fuzzing을 실행하려면 앱이 도메인을 environment_url.txt 파일에 유지하도록 합니다. API fuzzing은 해당 파일을 자동으로 파싱하여 스캔 대상을 찾습니다. 이에 대한 예제는 GitLab Auto DevOps CI YAML에서 볼 수 있습니다.

Postman Collection 파일을 사용하는 .gitlab-ci.yml 파일 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json
  FUZZAPI_TARGET_URL: http://test-deployment/

이것은 API fuzzing의 최소 구성입니다. 여기에서 다음을 수행할 수 있습니다:

• 첫 번째 스캔 실행
• 인증 추가
• 거짓 양성 처리 방법 알아보기

API fuzzing 구성 옵션에 대한 자세한 내용은 사용 가능한 CI/CD 변수를 참조하세요.

Postman 변수#

히스토리

• GitLab 15.1에서 Postman 환경 파일 형식 지원이 도입되었습니다.
• GitLab 15.1에서 여러 변수 파일 지원이 도입되었습니다.
• GitLab 15.1에서 Postman 변수 범위(전역 및 환경) 지원이 도입되었습니다.

Postman Client의 변수#

Postman을 사용하면 개발자가 요청의 다른 부분에서 사용할 수 있는 자리 표시자를 정의할 수 있습니다. 이 자리 표시자는 변수 사용에 설명된 대로 변수라고 합니다. 요청 및 스크립트에서 값을 저장하고 재사용하는 데 변수를 사용할 수 있습니다. 예를 들어, 컬렉션을 편집하여 문서에 변수를 추가할 수 있습니다:

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

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

Postman은 좋은 UX 경험을 갖춘 기본 클라이언트 도구에서 스크립트로 API를 테스트하고, 보조 요청을 트리거하는 복잡한 컬렉션을 생성하고, 그 과정에서 변수를 설정하는 보다 복잡한 에코시스템으로 성장했습니다. Postman 에코시스템의 모든 기능이 지원되지는 않습니다. 예를 들어, 스크립트는 지원되지 않습니다. Postman 지원의 주요 초점은 Postman Client에서 사용하는 Postman Collection 정의와 작업 공간, 환경 및 컬렉션 자체에서 정의된 관련 변수를 수집하는 것입니다.

Postman은 다른 범위에서 변수를 생성할 수 있도록 합니다. 각 범위는 Postman 도구에서 다른 수준의 가시성을 가집니다. 예를 들어, 모든 작업 정의 및 작업 공간에서 볼 수 있는 전역 환경 범위에서 변수를 생성할 수 있습니다. 또한 특정 환경 범위에서만 표시되고 사용되는 변수를 생성할 수도 있습니다. 일부 범위는 항상 사용할 수 없습니다. 예를 들어, Postman 에코시스템에서 Postman Client에서 요청을 생성할 수 있으며, 이러한 요청은 로컬 범위가 없지만 테스트 스크립트에는 있습니다.

Postman의 변수 범위는 까다로운 주제가 될 수 있으며 모든 사람이 익숙하지는 않습니다. 계속 진행하기 전에 Postman 문서의 변수 범위를 읽어보세요.

앞서 언급했듯이 다양한 변수 범위가 있으며 각각 목적이 있고 Postman 문서에 더 많은 유연성을 제공하는 데 사용할 수 있습니다. 변수 값이 계산되는 방식에 대한 중요한 참고 사항이 있습니다:

다음은 Postman Client 및 API fuzzing에서 지원하는 변수 범위 요약입니다:

• 전역 환경(global) 범위는 작업 공간 전체에서 사용할 수 있는 특별히 미리 정의된 환경입니다. 전역 환경 범위는 전역 범위라고도 합니다. Postman Client에서 전역 환경을 JSON 파일로 내보낼 수 있으며, API fuzzing에 사용할 수 있습니다.
• 환경 범위는 Postman Client에서 사용자가 생성한 명명된 변수 그룹입니다. Postman Client는 전역 환경과 함께 단일 활성 환경을 지원합니다. 활성 사용자 생성 환경에 정의된 변수는 전역 환경에 정의된 변수보다 우선합니다. Postman Client에서 환경을 JSON 파일로 내보낼 수 있으며, API fuzzing에 사용할 수 있습니다.
• 컬렉션 범위는 특정 컬렉션에 선언된 변수 그룹입니다. 컬렉션 변수는 선언된 컬렉션과 중첩된 요청 또는 컬렉션에서 사용할 수 있습니다. 컬렉션 범위에 정의된 변수는 전역 환경 범위와 환경 범위보다 우선합니다. Postman Client는 하나 이상의 컬렉션을 JSON 파일로 내보낼 수 있으며, 이 JSON 파일에는 선택된 컬렉션, 요청, 컬렉션 변수가 포함됩니다.
• API fuzzing 범위는 사용자가 다른 지원 범위에서 정의된 변수를 제공하거나 재정의할 수 있도록 API fuzzing에서 추가한 새 범위입니다. 이 범위는 Postman에서 지원되지 않습니다. API fuzzing 범위 변수는 사용자 정의 JSON 파일 형식을 사용하여 제공됩니다.
  • 환경 또는 컬렉션에 정의된 값 재정의
  • 스크립트에서 변수 정의
  • 지원되지 않는 _data 범위_에서 단일 데이터 행 정의
• Data 범위는 JSON 또는 CSV 파일에서 이름과 값이 오는 변수 그룹입니다. Newman 또는 Postman Collection Runner와 같은 Postman 컬렉션 러너는 JSON 또는 CSV 파일의 항목 수만큼 컬렉션의 요청을 실행합니다. 이러한 변수의 좋은 사용 사례는 Postman에서 스크립트를 사용하여 테스트를 자동화하는 것입니다. API fuzzing은 CSV 또는 JSON 파일에서 데이터를 읽는 것을 지원하지 않습니다.
• Local 범위는 Postman 스크립트에서 정의된 변수입니다. API fuzzing은 Postman 스크립트를 지원하지 않으며 따라서 스크립트에서 정의된 변수도 지원하지 않습니다. 지원되는 범위 또는 사용자 정의 JSON 형식 중 하나에서 정의하여 스크립트 정의 변수에 대한 값을 여전히 제공할 수 있습니다.

API fuzzing에서 지원되지 않는 범위가 있으며 스크립트에서 정의된 변수는 지원되지 않습니다. 다음 표는 가장 넓은 범위에서 가장 좁은 범위 순으로 정렬되어 있습니다.

다양한 범위에서 변수를 정의하고 내보내는 방법에 대한 자세한 내용은 다음을 참조하세요:

• 컬렉션 변수 정의
• 환경 변수 정의
• 전역 변수 정의

Postman Client에서 내보내기#

Postman Client를 사용하면 다양한 파일 형식을 내보낼 수 있습니다. 예를 들어, Postman 컬렉션이나 Postman 환경을 내보낼 수 있습니다. 내보낸 환경은 전역 환경(항상 사용 가능) 또는 이전에 생성한 사용자 정의 환경일 수 있습니다. Postman Collection을 내보내면 컬렉션 및 로컬 범위 변수에 대한 선언만 포함될 수 있습니다. 환경 범위 변수는 포함되지 않습니다.

환경 범위 변수에 대한 선언을 얻으려면 해당 환경을 내보내야 합니다. 내보낸 각 파일에는 선택된 환경의 변수만 포함됩니다.

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

• 컬렉션 내보내기
• 환경 내보내기
• 전역 환경 다운로드

API fuzzing 범위, 사용자 정의 JSON 파일 형식#

사용자 정의 JSON 파일 형식은 각 객체 속성이 변수 이름을 나타내고 속성 값이 변수 값을 나타내는 JSON 객체입니다. 이 파일은 즐겨 사용하는 텍스트 편집기를 사용하여 생성하거나 파이프라인의 이전 job에서 생성할 수 있습니다.

이 예제는 API fuzzing 범위에서 두 개의 변수 base_url 및 token을 정의합니다:

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

API fuzzing과 범위 사용#

전역, 환경, 컬렉션 및 GitLab API fuzzing 범위는 GitLab 15.1 이상에서 지원됩니다. GitLab 15.0 이하는 컬렉션 및 GitLab API fuzzing 범위만 지원합니다.

다음 표는 범위 파일/URL을 API fuzzing 구성 변수에 매핑하는 빠른 참조를 제공합니다:

Postman Collection 문서는 컬렉션 범위 변수에 대한 모든 선언을 자동으로 포함합니다. Postman Collection은 구성 변수 FUZZAPI_POSTMAN_COLLECTION과 함께 제공됩니다. 이 변수는 단일 내보낸 Postman 컬렉션으로 설정할 수 있습니다.

다른 범위의 변수는 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다. 구성 변수는 GitLab 15.1 이상에서 쉼표(,) 구분 파일 목록을 지원합니다. GitLab 15.0 이하는 단일 파일만 지원합니다. 제공된 파일의 순서는 파일이 필요한 범위 정보를 제공하므로 중요하지 않습니다.

구성 변수 FUZZAPI_POSTMAN_COLLECTION_VARIABLES는 다음으로 설정할 수 있습니다:

• 내보낸 전역 환경
• 내보낸 환경
• API fuzzing 사용자 정의 JSON 형식

정의되지 않은 Postman 변수#

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

• data 또는 local 범위 변수를 사용하고 있으며 앞서 언급했듯이 이러한 범위는 API fuzzing에서 지원되지 않습니다. 따라서 API fuzzing 범위를 통해 이러한 변수의 값이 제공되지 않았다고 가정하면 data 및 local 범위 변수의 값이 정의되지 않습니다.
• 변수 이름이 잘못 입력되어 이름이 정의된 변수와 일치하지 않습니다.
• Postman Client는 API fuzzing에서 지원하지 않는 새로운 동적 변수를 지원합니다.

가능한 경우, API fuzzing은 정의되지 않은 변수를 처리할 때 Postman Client와 동일한 동작을 따릅니다. 변수 참조의 텍스트는 그대로 유지되며 텍스트 대체가 없습니다. 지원되지 않는 동적 변수에도 동일한 동작이 적용됩니다.

예를 들어, Postman Collection의 요청 정의가 변수 {{full_url}}을 참조하고 변수를 찾을 수 없는 경우 {{full_url}}이라는 값으로 변경되지 않고 유지됩니다.

동적 Postman 변수#

사용자가 다양한 범위 수준에서 정의할 수 있는 변수 외에도, Postman에는 동적 변수라고 하는 미리 정의된 변수 집합이 있습니다. 동적 변수는 이미 정의되어 있으며 이름 앞에 달러 기호($)가 붙습니다. 예를 들어, $guid와 같이 사용됩니다. 동적 변수는 다른 변수처럼 사용할 수 있으며, Postman Client에서는 요청/컬렉션 실행 중에 무작위 값을 생성합니다.

API fuzzing과 Postman 간의 중요한 차이점은 API fuzzing이 동일한 동적 변수의 각 사용에 대해 동일한 값을 반환한다는 것입니다. 이는 동일한 동적 변수의 각 사용에 무작위 값을 반환하는 Postman Client 동작과 다릅니다. 즉, API fuzzing은 동적 변수에 정적 값을 사용하는 반면 Postman은 무작위 값을 사용합니다.

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

예제: 전역 범위#

이 예제에서 전역 범위가 Postman Client에서 global-scope.json으로 내보내지고 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 API fuzzing에 제공됩니다.

FUZZAPI_POSTMAN_COLLECTION_VARIABLES 사용 예제:

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

예제: 환경 범위#

이 예제에서 환경 범위가 Postman Client에서 environment-scope.json으로 내보내지고 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 API fuzzing에 제공됩니다.

FUZZAPI_POSTMAN_COLLECTION_VARIABLES 사용 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

예제: 컬렉션 범위#

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

FUZZAPI_POSTMAN_COLLECTION 사용 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json

예제: API fuzzing 범위#

API fuzzing 범위는 두 가지 주요 목적으로 사용됩니다. API fuzzing에서 지원되지 않는 data 및 local 범위 변수를 정의하고 다른 범위에서 정의된 기존 변수의 값을 변경합니다. API fuzzing 범위는 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공됩니다.

FUZZAPI_POSTMAN_COLLECTION_VARIABLES 사용 예제:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

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

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

예제: 여러 범위#

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

• global-scope.json으로 전역 범위 내보내기
• environment-scope.json으로 환경 범위 내보내기
• 컬렉션 범위가 포함된 Postman Collection을 postman-collection.json으로 내보내기

Postman Collection은 FUZZAPI_POSTMAN_COLLECTION 변수를 사용하여 제공되고 다른 범위는 FUZZAPI_POSTMAN_COLLECTION_VARIABLES를 사용하여 제공됩니다. API fuzzing은 각 파일에 제공된 데이터를 사용하여 제공된 파일이 일치하는 범위를 식별할 수 있습니다.

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

예제: 변수 값 변경#

내보낸 범위를 사용할 때 API fuzzing과 함께 사용하기 위해 변수 값을 변경해야 하는 경우가 많습니다. 예를 들어, 컬렉션 범위 변수에 v2 값을 가진 api_version이라는 변수가 포함될 수 있지만 테스트에서는 v1 값이 필요합니다. 내보낸 컬렉션을 수정하여 값을 변경하는 대신 API fuzzing 범위를 사용하여 값을 변경할 수 있습니다. API fuzzing 범위는 다른 모든 범위보다 우선하기 때문에 작동합니다.

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

API fuzzing 범위는 FUZZAPI_POSTMAN_COLLECTION_VARIABLES 구성 변수를 통해 제공되지만 먼저 파일을 생성해야 합니다. api-fuzzing-scope.json 파일은 API fuzzing 사용자 정의 JSON 파일 형식을 사용합니다. 이 JSON은 속성의 키-값 쌍이 있는 객체입니다. 키는 변수 이름이고 값은 변수 값입니다. 예를 들어:

{
  "api_version": "v1"
}

CI 정의:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

예제: 여러 범위로 변수 값 변경#

내보낸 범위를 사용할 때 API fuzzing과 함께 사용하기 위해 변수 값을 변경해야 하는 경우가 많습니다. 예를 들어, 환경 범위에 v2 값을 가진 api_version이라는 변수가 포함될 수 있지만 테스트에서는 v1 값이 필요합니다. 내보낸 파일을 수정하여 값을 변경하는 대신 API fuzzing 범위를 사용할 수 있습니다. API fuzzing 범위는 다른 모든 범위보다 우선하기 때문에 작동합니다.

이 예제에서는 전역 범위, 환경 범위, 컬렉션 범위 및 API fuzzing 범위가 구성됩니다. 첫 번째 단계는 다양한 범위를 내보내고 생성하는 것입니다.

• global-scope.json으로 전역 범위 내보내기
• environment-scope.json으로 환경 범위 내보내기
• 컬렉션 범위가 포함된 Postman Collection을 postman-collection.json으로 내보내기

API fuzzing 범위는 API fuzzing 사용자 정의 JSON 파일 형식을 사용하여 api-fuzzing-scope.json 파일을 생성하여 사용합니다. 이 JSON은 속성의 키-값 쌍이 있는 객체입니다. 키는 변수 이름이고 값은 변수 값입니다. 예를 들어:

{
  "api_version": "v1"
}

Postman Collection은 FUZZAPI_POSTMAN_COLLECTION 변수를 사용하여 제공되고 다른 범위는 FUZZAPI_POSTMAN_COLLECTION_VARIABLES를 사용하여 제공됩니다. API fuzzing은 각 파일에 제공된 데이터를 사용하여 제공된 파일이 일치하는 범위를 식별할 수 있습니다.

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_POSTMAN_COLLECTION: postman-collection.json
  FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,api-fuzzing-scope.json
  FUZZAPI_TARGET_URL: http://test-deployment/

첫 번째 스캔 실행#

올바르게 구성된 경우 CI/CD 파이프라인에 fuzz 스테이지와 apifuzzer_fuzz 또는 apifuzzer_fuzz_dnd job이 포함됩니다. job은 유효하지 않은 구성이 제공된 경우에만 실패합니다. 일반적인 작업에서는 fuzz 테스팅 중에 결함이 식별되더라도 job은 항상 성공합니다.

결함은 suite 이름과 함께 Security 파이프라인 탭에 표시됩니다. 리포지터리의 기본 브랜치에 대해 테스트할 때 fuzzing 결함은 보안 및 컴플라이언스 취약점 보고서에도 표시됩니다.

과도한 수의 보고된 결함을 방지하기 위해 API fuzzing 스캐너는 보고하는 결함 수를 제한합니다.

fuzzing 결함 보기#

API fuzzing 분석기는 수집되어 GitLab 취약점 화면에 결함을 채우는 데 사용되는 JSON 보고서를 생성합니다 API fuzzing 취약점의 세부 정보 보기. Fuzzing 결함은 심각도가 Unknown인 취약점으로 표시됩니다.

API fuzzing이 찾은 결함은 수동 조사가 필요하며 특정 취약점 유형과 연관되지 않습니다. 결함이 보안 문제인지 여부와 수정해야 하는지 여부를 결정하기 위해 조사가 필요합니다. 보고된 거짓 양성 수를 제한하기 위해 변경할 수 있는 구성에 대한 정보는 거짓 양성 처리를 참조하세요.

API fuzzing 취약점의 세부 정보 보기#

API fuzzing이 감지한 결함은 라이브 웹 애플리케이션에서 발생하며 취약점인지 여부를 결정하기 위해 수동 조사가 필요합니다. Fuzzing 결함은 심각도가 Unknown인 취약점으로 포함됩니다. fuzzing 결함 조사를 용이하게 하기 위해 전송 및 수신된 HTTP 메시지와 수행된 수정 사항에 대한 설명과 함께 상세 정보가 제공됩니다.

fuzzing 결함의 세부 정보를 보려면 다음 단계를 따르세요:

1. 프로젝트 또는 머지 리퀘스트에서 결함을 볼 수 있습니다:

   • 프로젝트에서 프로젝트의 Secure > 취약점 보고서 페이지로 이동합니다. 이 페이지는 기본 브랜치의 모든 취약점만 표시합니다.
   • 머지 리퀘스트에서 머지 리퀘스트의 Security 섹션으로 이동하고 확장 버튼을 선택합니다. API fuzzing 결함은 API fuzzing이 N개의 잠재적 취약점을 감지했습니다 레이블의 섹션에서 사용할 수 있습니다. 결함 세부 정보를 표시하려면 제목을 선택합니다.

2. 결함의 세부 정보를 표시하려면 결함 제목을 선택합니다. 아래 표는 이러한 세부 정보를 설명합니다.

   필드	설명
   설명	수정된 내용을 포함한 결함 설명.
   프로젝트	취약점이 감지된 네임스페이스와 프로젝트.
   메서드	취약점을 감지하는 데 사용된 HTTP 메서드.
   URL	취약점이 감지된 URL.
   요청	결함을 일으킨 HTTP 요청.
   수정되지 않은 응답	수정되지 않은 요청의 응답. 일반적인 작업 응답은 수정되지 않은 응답처럼 보입니다.
   실제 응답	fuzz된 요청에서 받은 응답.
   증거	GitLab이 결함이 발생했다고 결정한 방법.
   식별자	이 결함을 찾는 데 사용된 fuzzing 검사.
   심각도	발견의 심각도는 항상 Unknown.
   스캐너 유형	테스트를 수행하는 데 사용된 스캐너.

보안 대시보드#

Fuzzing 결함은 심각도가 Unknown인 취약점으로 표시됩니다. 보안 대시보드는 그룹, 프로젝트 및 파이프라인의 모든 보안 취약점에 대한 개요를 얻기에 좋은 곳입니다. 자세한 내용은 보안 대시보드 문서를 참조하세요.

취약점과 상호 작용#

Fuzzing 결함은 심각도가 Unknown인 취약점으로 표시됩니다. 결함이 발견된 후 이와 상호 작용할 수 있습니다. 취약점 해결 방법에 대해 자세히 읽어보세요.

거짓 양성 처리#

거짓 양성은 두 가지 방법으로 처리할 수 있습니다:

• 거짓 양성을 생성하는 검사를 비활성화합니다. 이렇게 하면 검사가 결함을 생성하지 않습니다. 예제 검사는 JSONFuzzingCheck 및 FormBodyFuzzingCheck입니다.
• Fuzzing 검사에는 결함이 식별될 때 감지하는 여러 방법("어설션"이라고 함)이 있습니다. 어설션도 비활성화하고 구성할 수 있습니다. 예를 들어, API fuzzer는 기본적으로 HTTP 상태 코드를 사용하여 문제가 실제 문제인지 식별하는 데 도움을 줍니다. API가 테스트 중에 500 오류를 반환하면 결함이 생성됩니다. 일부 프레임워크가 500 오류를 자주 반환하므로 이것이 항상 바람직한 것은 아닙니다.

검사 비활성화#

검사는 특정 유형의 테스트를 수행하며 특정 구성 프로필에 대해 활성화 및 비활성화할 수 있습니다. 기본 구성 파일은 사용할 수 있는 여러 프로필을 정의합니다. 구성 파일의 프로필 정의는 스캔 중에 활성화된 모든 검사를 나열합니다. 특정 검사를 비활성화하려면 구성 파일의 프로필 정의에서 제거합니다. 프로필은 구성 파일의 Profiles 섹션에 정의됩니다.

프로필 정의 예제:

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true

GeneralFuzzingCheck를 비활성화하려면 이 줄을 제거합니다:

- Name: GeneralFuzzingCheck
  Configuration:
    FuzzingCount: 10
    UnicodeFuzzing: true

그 결과 다음 YAML이 생성됩니다:

- Name: Quick-10
  DefaultProfile: Quick
  Routes:
    - Route: *Route0
      Checks:
        - Name: FormBodyFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: JsonFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true
        - Name: XmlFuzzingCheck
          Configuration:
            FuzzingCount: 10
            UnicodeFuzzing: true

검사의 어설션 비활성화#

어설션은 검사에서 생성된 테스트의 결함을 감지합니다. 많은 검사는 로그 분석, 응답 분석, 상태 코드와 같은 여러 어설션을 지원합니다. 결함이 발견되면 사용된 어설션이 제공됩니다. 기본적으로 활성화된 어설션을 확인하려면 구성 파일의 검사 기본 구성을 참조하세요. 섹션은 Checks라고 합니다.

이 예제는 FormBodyFuzzingCheck를 보여줍니다:

Checks:
  - Name: FormBodyFuzzingCheck
    Configuration:
      FuzzingCount: 30
      UnicodeFuzzing: true
    Assertions:
      - Name: LogAnalysisAssertion
      - Name: ResponseAnalysisAssertion
      - Name: StatusCodeAssertion

여기서 세 개의 어설션이 기본적으로 활성화되어 있습니다. 거짓 양성의 일반적인 원인은 StatusCodeAssertion입니다. 비활성화하려면 Profiles 섹션에서 구성을 수정합니다. 이 예제는 다른 두 개의 어설션(LogAnalysisAssertion, ResponseAnalysisAssertion)만 제공합니다. 이렇게 하면 FormBodyFuzzingCheck가 StatusCodeAssertion을 사용하지 않습니다:

Profiles:
  - Name: Quick-10
    DefaultProfile: Quick
    Routes:
      - Route: *Route0
        Checks:
          - Name: FormBodyFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
            Assertions:
              - Name: LogAnalysisAssertion
              - Name: ResponseAnalysisAssertion
          - Name: GeneralFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: JsonFuzzingCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true
          - Name: XmlInjectionCheck
            Configuration:
              FuzzingCount: 10
              UnicodeFuzzing: true