분석기 설정 사용자 정의

API 퍼징 동작은 CI/CD 변수를 통해 변경할 수 있습니다.

API 퍼징 구성 파일은 귀하의 리포지터리의 .gitlab 디렉터리에 있어야 합니다.

GitLab 보안 스캔 도구의 모든 사용자 정의는 기본 브랜치로 변경하기 전에 Merge Request을 통해 테스트해야 합니다. 이를 하지 않으면 예상치 못한 결과가 발생할 수 있으며, 오검지 양성이 많아질 수 있습니다.

인증

인증은 인증 토큰을 헤더나 쿠키로 제공함으로써 처리됩니다. 인증 흐름을 수행하거나 토큰을 계산하는 스크립트를 제공할 수 있습니다.

HTTP 기본 인증

HTTP 기본 인증은 HTTP 프로토콜에 내장된 인증 방법으로 전송 계층 보안(TLS)과 함께 사용됩니다.

비밀번호를 위한 CI/CD 변수(예: TEST_API_PASSWORD)를 생성하고 이를 마스킹 설정으로 설정하는 것이 좋습니다. GitLab 프로젝트 페이지의 설정 > CI/CD에서 CI/CD 변수를 생성할 수 있습니다. 마스킹된 변수에 대한 제한 사항이 있으므로 변수를 추가하기 전에 비밀번호를 Base64로 인코딩해야 합니다.

마지막으로 두 개의 CI/CD 변수를 .gitlab-ci.yml 파일에 추가하세요:

FUZZAPI_HTTP_USERNAME: 인증을 위한 사용자 이름
FUZZAPI_HTTP_PASSWORD_BASE64: 인증을 위해 Base64로 인코딩된 비밀번호

stages:
    - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick-10
  FUZZAPI_HAR: test-api-recording.har
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_HTTP_USERNAME: testuser
  FUZZAPI_HTTP_PASSWORD_BASE64: $TEST_API_PASSWORD

원시 비밀번호

패스워드를 Base64로 인코딩하고 싶지 않은 경우(또는 GitLab 15.3 이전 버전을 사용하는 경우) FUZZAPI_HTTP_PASSWORD_BASE64 대신에 원시 비밀번호 FUZZAPI_HTTP_PASSWORD를 제공할 수 있습니다.

Bearer 토큰

Bearer 토큰은 OAuth2 및 JSON 웹 토큰(JWT)을 포함한 여러 다양한 인증 메커니즘에서 사용됩니다. Bearer 토큰은 Authorization HTTP 헤더를 사용하여 전송됩니다. API 퍼징과 함께 Bearer 토큰을 사용하려면 다음 중 하나가 필요합니다:

만료되지 않는 토큰
테스트 기간 동안 계속 유효한 토큰 생성 방법
API 퍼징이 토큰을 생성할 수 있는 Python 스크립트

토큰이 만료되지 않음

토큰이 만료되지 않는 경우 FUZZAPI_OVERRIDES_ENV 변수를 사용하여 제공하세요. 이 변수의 내용은 API 퍼징의 외부 HTTP 요청에 추가할 헤더 및 쿠키를 제공하는 JSON 스니펫입니다.

FUZZAPI_OVERRIDES_ENV로 베어러 토큰을 제공하려면 다음 단계를 따르세요:

예를 들어, "headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}(사용자의 토큰으로 바꿔 넣으세요) 값을 갖는 CI/CD 변수(예: TEST_API_BEARERAUTH)를 [GitLab 프로젝트 페이지의 설정 > CI/CD]에서 생성하세요.
.gitlab-ci.yml 파일에서 FUZZAPI_OVERRIDES_ENV를 방금 생성한 변수로 설정하세요:

stages:
  - fuzz

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

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

인증이 작동하는지 확인하려면 API 퍼징 테스트를 실행하고 퍼징 로그 및 테스트 API 애플리케이션 로그를 확인하세요. 더 많은 정보는 overrides section을 참고하세요.

테스트 실행 중에 생성된 토큰

토큰이 생성되고 테스트하는 동안 만료되지 않는 경우, 토큰을 포함한 파일을 API 퍼징에 제공할 수 있습니다. 이 파일을 생성하는 것은 이전 단계 및 작업 또는 API 퍼징 작업의 일부로 이루어질 수 있습니다.

API 퍼징은 다음과 같은 구조의 JSON 파일을 받기를 기대합니다:

{
  "headers" : {
    "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
  }
}

.gitlab-ci.yml 파일에서 FUZZAPI_OVERRIDES_FILE를 설정하세요:

stages:
  - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json

인증이 작동하는지 확인하려면 API 퍼징 테스트를 실행하고 퍼징 로그와 테스트 API 응용프로그램 로그를 확인하세요.

토큰이 짧은 유효 기간을 갖는 경우

토큰이 생성되고 스캔이 완료되기 전에 만료되는 경우, API 패징이 제공한 간격에서 실행하는 프로그램 또는 스크립트를 제공할 수 있습니다. 이 제공된 스크립트는 Python 3 및 Bash가 설치된 Alpine Linux 컨테이너에서 실행됩니다. Python 스크립트가 추가 패키지를 요구하는 경우, 이를 실행 시간에 감지하고 패키지를 설치해야 합니다.

스크립트는 다음과 같은 형식의 베어러 토큰을 포함하는 JSON 파일을 만들어야 합니다:

{
  "headers" : {
    "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
  }
}

올바른 작동을 위해 다음과 같이 세 개의 CI/CD 변수를 제공해야 합니다:

FUZZAPI_OVERRIDES_FILE: 제공된 명령이 생성하는 JSON 파일
FUZZAPI_OVERRIDES_CMD: JSON 파일을 생성하는 명령
FUZZAPI_OVERRIDES_INTERVAL: 명령을 실행하는 간격(초)

API 퍼징 프로필

GitLab은 여러 테스트 프로필을 수행하는 구성 파일을 제공합니다. 각 프로필의 실행 시간은 테스트 수가 증가함에 따라 증가합니다.

프로필	퍼징 테스트 수(매개변수당)
Quick-10	10
Medium-20	20
Medium-50	50
Long-100	100

Overrides

API 퍼징은 요청에서 특정 항목을 추가하거나 재정의하기 위한 메커니즘을 제공합니다. 예를 들어:

헤더
쿠키
쿼리 문자열
형식 데이터
JSON 노드
XML 노드

이를 통해 의미론적 버전 헤더, 인증 등을 삽입할 수 있습니다. authentication section에는 해당 목적을 위한 재정의 사용 예가 포함되어 있습니다.

재정의는 각 재정의 유형을 나타내는 JSON 객체로 표현된 JSON 문서를 사용합니다:

{
  "headers": {
    "header1": "value",
    "header2": "value"
  },
  "cookies": {
    "cookie1": "value",
    "cookie2": "value"
  },
  "query": {
    "query-string1": "value",
    "query-string2": "value"
  },
  "body-form": {
    "form-param1": "value",
    "form-param2": "value"
  },
  "body-json": {
    "json-path1": "value",
    "json-path2": "value"
  },
  "body-xml": {
    "xpath1": "value",
    "xpath2": "value"
  }
}

단일 헤더 설정의 예:

{
  "headers": {
    "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
  }
}

헤더와 쿠키 설정의 예:

{
  "headers": {
    "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
  },
  "cookies": {
    "flags": "677"
  }
}

body-form 재정의를 설정하는 예:

{
  "body-form": {
    "username": "john.doe"
  }
}

재정의 엔진은 요청 본문이 형식 데이터 콘텐츠만 포함하는 경우 body-form을 사용합니다.

body-json 재정의를 설정하는 예:

{
  "body-json": {
    "$.credentials.access-token": "iddqd!42.$"
  }
}

객체 body-json의 각 JSON 속성 이름은 JSON Path 표현식으로 설정되어 있습니다. JSON Path 표현식인 $.credentials.access-token은 값 iddqd!42.$로 재정의될 노드를 식별합니다. 재정의 엔진은 요청 본문이 JSON 콘텐츠만 포함하는 경우 body-json을 사용합니다.

예를 들어, 본문이 다음과 같은 JSON으로 설정된 경우:

{
    "credentials" : {
        "username" :"john.doe",
        "access-token" : "non-valid-password"
    }
}

다음과 같이 변경됩니다:

{
    "credentials" : {
        "username" :"john.doe",
        "access-token" : "iddqd!42.$"
    }
}

body-xml 재정의를 설정하는 예입니다. 첫 번째 항목은 XML 속성을, 두 번째 항목은 XML 엘리먼트를 재정의합니다:

{
  "body-xml" : {
    "/credentials/@isEnabled": "true",
    "/credentials/access-token/text()" : "iddqd!42.$"
  }
}

객체 body-xml의 각 JSON 속성 이름은 XPath v2 표현식으로 설정되어 있습니다. XPath 표현식인 /credentials/@isEnabled은 값 true로 재정의될 속성 노드를 식별합니다. XPath 표현식인 /credentials/access-token/text()은 값 iddqd!42.$로 재정의될 엘리먼트 노드를 식별합니다. 재정의 엔진은 요청 본문이 XML 콘텐츠만 포함하는 경우 body-xml을 사용합니다.

예를 들어, 본문이 다음과 같은 XML로 설정된 경우:

<credentials isEnabled="false">
  <username>john.doe</username>
  <access-token>non-valid-password</access-token>
</credentials>

다음과 같이 변경됩니다:

<credentials isEnabled="true">
  <username>john.doe</username>
  <access-token>iddqd!42.$</access-token>
</credentials>

이 JSON 문서를 파일 또는 환경 변수로 제공할 수 있습니다. 또한 만료되는 값에 대한 지원을 위해 JSON 문서를 생성하는 명령을 제공할 수 있습니다. 명령은 값이 만료될 때 실행되도록 인터벌로 설정될 수 있습니다.

파일 사용

오버라이드 JSON을 파일로 제공하려면 FUZZAPI_OVERRIDES_FILE CI/CD 변수를 설정합니다. 경로는 작업의 현재 작업 디렉터리를 기준으로 상대적입니다.

다음은 .gitlab-ci.yml의 예시입니다:

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json

CI/CD 변수 사용

오버라이드 JSON을 CI/CD 변수로 제공하려면 FUZZAPI_OVERRIDES_ENV 변수를 사용합니다. 이를 통해 마스킹 및 보호할 수 있는 변수로 JSON을 배치할 수 있습니다.

다음은 .gitlab-ci.yml의 예시에서 FUZZAPI_OVERRIDES_ENV 변수가 JSON으로 직접 설정된 것입니다:

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}'

다음은 예시의 .gitlab-ci.yml에서 SECRET_OVERRIDES 변수가 JSON을 제공한 것입니다. 이것은 UI에서 정의된 그룹 또는 인스턴스 수준의 CI/CD 변수입니다:

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_OVERRIDES_ENV: $SECRET_OVERRIDES

명령어 사용

값이 생성되거나 만료되어 재생성해야 하는 경우, API 퍼저가 지정된 간격으로 실행할 프로그램이나 스크립트를 제공할 수 있습니다. 제공된 스크립트는 Python 3와 Bash가 설치된 Alpine Linux 컨테이너에서 실행됩니다.

프로그램 또는 스크립트를 실행하려면 환경 변수 FUZZAPI_OVERRIDES_CMD를 설정해야 합니다. 제공된 명령어는 이전에 정의된 대로 오버라이드 JSON 파일을 작성합니다.

NodeJS나 Ruby와 같은 기타 스크립팅 런타임을 설치하거나 오버라이드 명령어의 의존성을 설치해야 할 수도 있습니다. 이 경우, FUZZAPI_PRE_SCRIPT를 설치하는 데 사용할 스크립트의 파일 경로로 설정하는 것이 좋습니다. FUZZAPI_PRE_SCRIPT에서 제공된 스크립트는 분석기가 시작되기 전에 한 번 실행됩니다.

Alpine Linux 패키지 관리 페이지에서 Alpine Linux 패키지를 설치하는 정보를 확인하세요.

올바른 작동을 위해 세 가지 CI/CD 변수를 제공해야 합니다:

FUZZAPI_OVERRIDES_FILE: 제공된 명령어에 의해 생성된 파일
FUZZAPI_OVERRIDES_CMD: 오버라이드 JSON 파일을 주기적으로 생성하는 오버라이드 명령어
FUZZAPI_OVERRIDES_INTERVAL: 명령어 실행 간격(초)

선택적으로: - FUZZAPI_PRE_SCRIPT: 분석기가 시작되기 전에 런타임이나 의존성을 설치하는 스크립트

Alpine Linux에서 스크립트를 실행하려면 먼저 chmod 명령을 사용하여 실행 권한을 설정해야 합니다. 예를 들어 script.py의 실행 권한을 모든 사용자에게 부여하려면 다음과 같이 사용합니다: chmod a+x script.py. 필요한 경우, 실행 권한이 이미 설정된 script.py에 버전을 부여할 수 있습니다.

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json
  FUZZAPI_OVERRIDES_CMD: renew_token.py
  FUZZAPI_OVERRIDES_INTERVAL: 300

오버라이드 디버깅

기본적으로 오버라이드 명령의 출력은 숨겨집니다. 오버라이드 명령이 0이 아닌 종료 코드를 반환하면 해당 명령이 작업 출력의 일부로 표시됩니다. 선택적으로, FUZZAPI_OVERRIDES_CMD_VERBOSE 변수를 임의의 값으로 설정하여 오버라이드 명령의 출력을 생성될 때 표시할 수 있습니다. 이렇게 하면 오버라이드 스크립트를 테스트할 때 유용하지만 테스트 속도를 늦추므로 테스트 후에는 비활성화해야 합니다.

스크립트에서 로그 파일에 메시지를 작성하여 작업이 완료되거나 실패한 후 수집될 수 있는 로그 파일을 작성할 수도 있습니다. 로그 파일은 특정 위치에 만들어지고 특정한 명명 규칙을 따라야 합니다.

오버라이드 스크립트에 기본적인 로깅을 추가하면 작업이 일반적으로 실행 중 예상치 못하게 실패할 때 유용합니다. 로그 파일은 작업의 아티팩트로 자동으로 포함되어 작업이 완료된 후 다운로드할 수 있습니다.

위의 예시에서 FUZZAPI_OVERRIDES_CMD 환경 변수에 renew_token.py를 제공했습니다. 스크립트에서 주목해야 할 두 가지 사항:

로그 파일은 CI_PROJECT_DIR 환경 변수에 지정된 디렉터리에 저장됩니다.
로그 파일 이름은 gl-*.log와 일치해야 합니다.

#!/usr/bin/env python

# 오버라이드 명령의 예시

# 오버라이드 명령은 새로운 사용할 값으로 오버라이드 JSON 파일을 업데이트할 수 있습니다. 
# 이는 테스트 중에 만료될 수 있는 인증 토큰을 업데이트하는 좋은 방법입니다.

import logging
import json
import os
import requests
import backoff

# [1] 로그 파일은 env var CI_PROJECT_DIR에 지정된 디렉터리에 저장합니다
working_directory = os.environ.get( 'CI_PROJECT_DIR')
overrides_file_name = os.environ.get('FUZZAPI_OVERRIDES_FILE', 'api-fuzzing-overrides.json')
overrides_file_path = os.path.join(working_directory, overrides_file_name)

# [2] 파일 이름은 패턴과 일치해야 합니다: gl-*.log
log_file_path = os.path.join(working_directory, 'gl-user-overrides.log')

# 로거 설정
logging.basicConfig(filename=log_file_path, level=logging.DEBUG)

# 일시적 오류의 경우 재시도하기 위해 `backoff` 데코레이터를 사용합니다.
@backoff.on_exception(backoff.expo,
                      (requests.exceptions.Timeout,
                       requests.exceptions.ConnectionError),
                       max_time=30)
def get_auth_response():
    authorization_url = 'https://authorization.service/api/get_api_token'
    return requests.get(
        f'{authorization_url}',
        auth=(os.environ.get('AUTH_USER'), os.environ.get('AUTH_PWD'))
    )

# 예제에서는 액세스 토큰을 지정된 엔드포인트에서 검색합니다
try:
    
    # http 요청 수행, 응답 샘플:
    # { "Token" : "abcdefghijklmn" }
    response = get_auth_response()
    
    # 요청이 성공했는지 확인. `requests.exceptions.HTTPError`가 발생할 수 있습니다.
    response.raise_for_status()
    
    # JSON 데이터 가져오기
    response_body = response.json()

# 필요할 경우, 특정 예외를 처리할 수 있습니다
# requests.ConnectionError                  : 네트워크 연결 오류가 발생함
# requests.HTTPError                        : HTTP 요청이 실패 상태 코드를 반환함. [Response.raise_for_status()]
# requests.ConnectTimeout                   : 요청이 원격 서버에 연결하려는 동안 시간이 초과됨
# requests.ReadTimeout                      : 서버가 일정 시간 동안 데이터를 보내지 않음.
# requests.TooManyRedirects                 : 요청이 구성된 최대 리디렉션 횟수를 초과함
# requests.exceptions.RequestException      : Requests와 관련된 모든 예외
except json.JSONDecodeError as json_decode_error:
    # JSON 응답 디코딩과 관련된 오류 기록
    logging.error(f'오류, JSON 응답 디코딩 중 실패. 오류 메시지: {json_decode_error}')
    raise
except requests.exceptions.RequestException as requests_error:
    # `Requests`와 관련된 예외 기록
    logging.error(f'오류, HTTP 요청 수행 중 실패. 오류 메시지: {requests_error}')
    raise
except Exception as e:
    # 다른 오류 기록
    logging.error(f'오류, 알 수 없는 오류로 인해 액세스 토큰을 검색하는 중 실패. 오류 메시지: {e}')
    raise

# 오버라이드 파일 콘텐츠를 보유하는 객체를 계산합니다.
# 요청에서 검색된 데이터를 사용합니다
overrides_data = {
    "headers": {
        "Authorization": f"Token {response_body['Token']}"
    }
}

# 파일 오버라이드 계산에 대한 로그 항목
logging.info("Overrides 파일 생성 중: %s" % overrides_file_path)

# 파일을 덮어쓰려고 시도합니다.
try:
    if os.path.exists(overrides_file_path):
        os.unlink(overrides_file_path)
    
    # 업데이트된 딕셔너리로 파일 덮어쓰기
    with open(overrides_file_path, "wb+") as fd:
        fd.write(json.dumps(overrides_data).encode('utf-8'))
except Exception as e:
    # 다른 오류 기록
    logging.error(f'오류, 파일 덮어쓰기 중 알 수 없는 오류 발생. 오류 메시지: {e}')
    raise

# 오버라이드가 성공적으로 완료되었음을 기록하는 로그
logging.info("오버라이드 파일이 업데이트되었습니다")

# 종료

오버라이드 명령 예시에서 Python 스크립트는 backoff 라이브러리에 의존합니다. Python 스크립트를 실행하기 전에 라이브러리가 설치되어 있는지 확인하려면 FUZZAPI_PRE_SCRIPT를 오버라이드 명령의 의존성을 설치하는 스크립트의 파일 경로로 설정해야 합니다. 예를 들어, 다음 스크립트 user-pre-scan-set-up.sh:

#!/bin/bash

# user-pre-scan-set-up.sh
# 파이썬 의존성을 설치합니다

echo "**** 파이썬 의존성 설치 ****"

python3 -m ensurepip
pip3 install --no-cache --upgrade \
    pip \
    requests \
    backoff

echo "**** 파이썬 의존성 설치 완료 ****"

# 종료

구성을 업데이트하여 FUZZAPI_PRE_SCRIPT를 새로운 user-pre-scan-set-up.sh 스크립트로 설정해야 합니다. 예를 들어:

stages:
     - fuzz

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

variables:
  FUZZAPI_PROFILE: Quick
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_TARGET_URL: http://test-deployment/
  FUZZAPI_PRE_SCRIPT: user-pre-scan-set-up.sh
  FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json
  FUZZAPI_OVERRIDES_CMD: renew_token.py
  FUZZAPI_OVERRIDES_INTERVAL: 300

제외 경로

API를 테스트할 때는 특정 경로를 제외하는 것이 유용할 수 있습니다. 예를 들어, 인증 서비스나 API의 이전 버전을 테스트에서 제외할 수 있습니다. 경로를 제외하려면 FUZZAPI_EXCLUDE_PATHS CI/CD 변수를 사용하십시오. 이 변수는 .gitlab-ci.yml 파일에서 지정됩니다. 여러 경로를 제외하려면 ; 문자를 사용하여 항목을 구분하십시오. 제공된 경로에서는 단일 문자 와일드카드 ?와 다중 문자 와일드카드 *를 사용할 수 있습니다.

제외된 경로가 올바르게 제외되었는지 확인하려면 작업 출력의 테스트된 작업(Tested Operations) 및 제외된 작업(Excluded Operations) 부분을 검토하십시오. 테스트된 작업 아래에 제외된 경로가 나열되어 있지 않아야 합니다.

2021-05-27 21:51:08 [INF] API Fuzzing: --[ 테스트된 작업 ]-------------------------
2021-05-27 21:51:08 [INF] API Fuzzing: 201 POST http://target:7777/api/users CREATED
2021-05-27 21:51:08 [INF] API Fuzzing: ------------------------------------------------
2021-05-27 21:51:08 [INF] API Fuzzing: --[ 제외된 작업 ]-----------------------
2021-05-27 21:51:08 [INF] API Fuzzing: GET http://target:7777/api/messages
2021-05-27 21:51:08 [INF] API Fuzzing: POST http://target:7777/api/messages
2021-05-27 21:51:08 [INF] API Fuzzing: ------------------------------------------------

경로 제외의 예

이 예에서는 /auth 리소스를 제외합니다. 이는 하위 리소스(/auth/child)는 제외하지 않습니다.

variables:
  FUZZAPI_EXCLUDE_PATHS: /auth

/auth 및 하위 리소스(/auth/child)를 제외하려면 와일드카드를 사용합니다.

variables:
  FUZZAPI_EXCLUDE_PATHS: /auth*

여러 경로를 제외하려면 ; 문자를 사용합니다. 이 예에서는 /auth* 및 /v1/*를 제외합니다.

variables:
  FUZZAPI_EXCLUDE_PATHS: /auth*;/v1/*

매개변수 제외

API를 테스트하는 동안 매개변수 (쿼리 문자열, 헤더 또는 본문 요소)를 제외할 수도 있습니다. 이는 매개변수가 항상 실패를 유발하거나 테스트를 느리게 만드는 경우 또는 기타 이유로 필요할 수 있습니다. 매개변수를 제외하려면 다음 변수 중 하나를 사용할 수 있습니다: FUZZAPI_EXCLUDE_PARAMETER_ENV 또는 FUZZAPI_EXCLUDE_PARAMETER_FILE.

FUZZAPI_EXCLUDE_PARAMETER_ENV를 사용하면 제외된 매개변수가 포함된 JSON 문자열을 제공할 수 있습니다. 이 옵션은 JSON이 짧고 자주 변경되지 않을 때 좋은 선택입니다. 또 다른 옵션은 FUZZAPI_EXCLUDE_PARAMETER_FILE 변수를 사용하는 것입니다. 이 변수는 리포지터리에 확인할 수 있는 파일 경로로 설정됩니다. 이 파일은 리포지터리에 체크인하거나 다른 작업에서 생성되거나 FUZZAPI_PRE_SCRIPT를 사용하여 런타임에서 생성할 수 있습니다.

JSON 문서를 사용하여 매개변수 제외

JSON 문서에는 제외해야 하는 매개변수를 식별하기 위해 특정 속성을 사용하는 JSON 객체가 포함됩니다. 스캔 프로세스 중 특정 매개변수를 제외하기 위해 다음 속성을 제공할 수 있습니다:

헤더: 이 속성을 사용하여 특정 헤더를 제외합니다. 속성 값은 제외할 헤더 이름의 배열입니다. 이름은 대소문자를 구분하지 않습니다.
쿠키: 이 속성 값은 특정 쿠키를 제외합니다. 속성 값은 제외할 쿠키 이름의 배열입니다. 이름은 대소문자를 구분합니다.
쿼리: 이 속성을 사용하여 쿼리 문자열에서 특정 필드를 제외합니다. 속성 값은 제외할 쿼리 문자열의 필드 이름 배열입니다. 이름은 대소문자를 구분합니다.
본문-폼: application/x-www-form-urlencoded 미디어 유형을 사용하는 요청에서 본문의 특정 필드를 제외합니다. 속성 값은 본문에서 제외할 필드 이름의 배열입니다. 이름은 대소문자를 구분합니다.
본문-JSON: application/json 미디어 유형을 사용하는 요청에서 특정 JSON 노드를 제외합니다. 속성 값은 배열이며 배열의 각 항목은 JSON Path 표현식입니다.
본문-XML: application/xml 미디어 유형을 사용하는 요청에서 특정 XML 노드를 제외합니다. 속성 값은 배열이며 배열의 각 항목은 XPath v2 표현식입니다.

다음 JSON 문서는 제외할 매개변수의 예상 구조의 예입니다.

{
  "헤더": [
    "헤더1",
    "헤더2"
  ],
  "쿠키": [
    "쿠키1",
    "쿠키2"
  ],
  "쿼리": [
    "쿼리-문자열1",
    "쿼리-문자열2"
  ],
  "본문-폼": [
    "폼-매개변수1",
    "폼-매개변수2"
  ],
  "본문-JSON": [
    "JSON-경로-표현식-1",
    "JSON-경로-표현식-2"
  ],
  "본문-XML" : [
    "XML-경로-표현식-1",
    "XML-경로-표현식-2"
  ]
}

예시

단일 헤더 제외

Upgrade-Insecure-Requests 헤더를 제외하려면 header 속성의 값을 헤더 이름이 포함된 배열로 설정하십시오: [ "Upgrade-Insecure-Requests" ]. 예를 들어, 다음과 같이 JSON 문서가 됩니다:

{
  "헤더": [ "Upgrade-Insecure-Requests" ]
}

헤더 이름은 대소문자를 구분하지 않으므로 UPGRADE-INSECURE-REQUESTS 헤더 이름은 Upgrade-Insecure-Requests와 동등합니다.

헤더와 두 개의 쿠키를 제외

Authorization 헤더 및 PHPSESSID와 csrftoken 쿠키를 제외하려면 headers 속성의 값에 헤더 이름 배열 [ "Authorization" ]을 설정하고 cookies 속성의 값에 쿠키 이름 배열 [ "PHPSESSID", "csrftoken" ]을 설정하십시오. 예를 들어, 다음과 같이 JSON 문서가 됩니다:

{
  "헤더": [ "Authorization" ],
  "쿠키": [ "PHPSESSID", "csrftoken" ]
}

`본문-폼` 매개변수 제외

application/x-www-form-urlencoded 콘텐츠 유형을 사용하는 요청에서 password 필드를 제외하려면 body-form 속성의 값에 필드 이름 배열 [ "password" ]을 설정하십시오. 예를 들어, 다음과 같이 JSON 문서가 됩니다:

{
  "body-form":  [ "password" ]
}

제외 매개변수는 요청이 application/x-www-form-urlencoded 콘텐츠 유형을 사용하는 경우 body-form을 사용합니다.

JSON Path를 사용하여 특정 JSON 노드 제외

루트 객체의 schema 속성을 제외하려면 body-json 속성의 값을 JSON Path 표현식 배열 [ "$.schema" ]로 설정하십시오. JSON Path 표현식은 JSON 노드를 식별하기 위해 특별한 구문을 사용합니다: $는 JSON 문서의 루트를 나타내고 .는 현재 객체를 나타냅니다 (우리의 경우 루트 객체), 그리고 텍스트 schema는 속성 이름을 나타냅니다. 따라서 JSON 경로 표현식 $.schema는 루트 객체의 schema 속성을 나타냅니다. 예를 들어, 다음과 같이 JSON 문서가 됩니다:

{
  "body-json": [ "$.schema" ]
}

제외 매개변수는 요청이 application/json 콘텐츠 유형을 사용하는 경우 body-json을 사용합니다. body-json의 각 항목은 JSON Path 표현식으로 예상됩니다. JSON Path에서 $, *, . 등의 문자는 특별한 의미를 가지고 있습니다.

JSON Path를 사용한 여러 개의 JSON 노드 제외

배열 users의 각 항목에서 password 속성을 제외하려면 body-json 속성의 값을 다음과 같이 JSON Path 표현식으로 설정합니다: [ "$.users[*].paswword" ].

JSON Path 표현식은 $로 시작하여 루트 노드를 참조하고, .을 사용하여 현재 노드를 참조합니다. 그런 다음 users를 사용하여 속성을 참조하고 문자 [와 ]를 사용하여 숫자 대신 *을 사용하여 해당 배열의 모든 인덱스를 지정합니다. 인덱스 참조 후 .password로 각 선택된 인덱스의 속성 password를 참조합니다.

예를 들어, 다음과 같은 JSON 문서가 있습니다:

{
  "body-json": [ "$.users[*].paswword" ]
}

요청이 콘텐츠 유형 application/json을 사용하는 경우, 제외 매개변수는 body-json을 사용합니다. body-json의 각 항목은 JSON Path 표현식으로 이루어져 있다. JSON Path에서 $, *, . 등의 문자는 특별한 의미를 가집니다.

XML 속성 제외

루트 요소 credentials에 포함된 isEnabled이름의 속성을 제외하려면 body-xml 속성의 값을 다음과 같이 XPath 표현식으로 설정합니다: [ "/credentials/@isEnabled" ].

XPath 표현식 /credentials/@isEnabled은 /로 시작하여 XML 문서의 루트를 나타내고, 다음에는 요소 이름을 나타내는 credentials가 오며, 이전 XML 요소의 노드를 참조하기 위해 /을 사용하고, isEnable 이름이 속성임을 나타내기 위해 @를 사용합니다.

예를 들어, 다음과 같은 JSON 문서가 있습니다:

{
  "body-xml": [
    "/credentials/@isEnabled"
  ]
}

요청이 콘텐츠 유형 application/xml을 사용하는 경우, 제외 매개변수는 body-xml을 사용합니다. body-xml의 각 항목은 XPath v2 표현식으로 이루어져 있습니다. XPath 표현식에서 @, /, :, [, ] 등의 문자는 특별한 의미를 가집니다.

(이하 생략)

예시

URL 및 하위 리소스 제외

다음 예는 http://target/api/auth URL과 해당 하위 리소스를 제외합니다.

stages:
  - fuzz

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

variables:
  FUZZAPI_TARGET_URL: http://target/
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_EXCLUDE_URLS: http://target/api/auth

두 개의 URL 제외 및 이들의 하위 리소스 허용

URL http://target/api/buy 및 http://target/api/sell을 제외하고 이들의 하위 리소스를 스캔하는 것을 허용하려면, 예를 들어, http://target/api/buy/toy 또는 http://target/api/sell/chair와 같은 하위 리소스를 스캔할 수 있도록 해당 URL과 그 하위 리소스를 허용하려면 http://target/api/buy/$,http://target/api/sell/$ 값을 사용할 수 있습니다. 이 값은 두 개의 정규 표현식을 사용하며 각각을 , 문자로 구분합니다. 따라서 http://target/api/buy$ 및 http://target/api/sell$를 포함합니다. 각 정규 표현식에서, 끝에 매칭되어야 하는 URL을 나타내는 $ 문자가 포함되어 있습니다.

stages:
  - fuzz

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

variables:
  FUZZAPI_TARGET_URL: http://target/
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$

두 개의 URL과 그 하위 리소스 제외

http://target/api/buy 및 http://target/api/sell URL 및 해당 하위 리소스를 제외하려면, 여러 URL을 제공하기 위해 , 문자를 사용합니다:

stages:
  - fuzz

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

variables:
  FUZZAPI_TARGET_URL: http://target/
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell

정규 표현식을 사용하여 URL 제외

https://target/api/v1/user/create 및 https://target/api/v2/user/create를 정확히 제외하거나 다른 버전 (v3,v4 등)을 제외하려면 https://target/api/v.*/user/create$를 사용할 수 있습니다. 이전의 정규 표현식에서:

.는 모든 문자를 나타냅니다.
*는 0회 이상을 나타냅니다.
$는 URL이 거기서 끝나야 함을 나타냅니다.

stages:
  - fuzz

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

variables:
  FUZZAPI_TARGET_URL: http://target/
  FUZZAPI_OPENAPI: test-api-specification.json
  FUZZAPI_EXCLUDE_URLS: https://target/api/v.*/user/create$

Header Fuzzing

많은 기술 스택에서 많은 거짓 긍정이 발생하므로 헤더 퍼징은 기본적으로 비활성화되어 있습니다. 헤더 퍼징을 활성화하려면 퍼징에 포함할 헤더 디렉터리을 지정해야 합니다.

기본 구성 파일의 각 프로필에는 GeneralFuzzingCheck에 대한 항목이 있습니다. 이 항목은 헤더 퍼징을 수행합니다. Configuration 섹션에는 HeaderFuzzing 및 Headers 설정을 변경하여 헤더 퍼징을 활성화해야 합니다.

다음 스니펫은 헤더 퍼징이 비활성화된 Quick-10 프로필의 기본 구성을 보여줍니다:

- Name: Quick-10
  DefaultProfile: Empty
  Routes:
  - Route: *Route0
    Checks:
    - Name: FormBodyFuzzingCheck
      Configuration:
        FuzzingCount: 10
        UnicodeFuzzing: true
    - Name: GeneralFuzzingCheck
      Configuration:
        FuzzingCount: 10
        UnicodeFuzzing: true
        HeaderFuzzing: false
        Headers:
    - Name: JsonFuzzingCheck
      Configuration:
        FuzzingCount: 10
        UnicodeFuzzing: true
    - Name: XmlFuzzingCheck
      Configuration:
        FuzzingCount: 10
        UnicodeFuzzing: true

HeaderFuzzing은 헤더 퍼징을 활성화 또는 비활성화하는 부울 값입니다. 기본 설정은 꺼져 있는 false입니다. 헤더 퍼징을 활성화하려면 이 설정을 true로 변경하세요:

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

Headers는 퍼징할 헤더 디렉터리입니다. 나열된 헤더만 퍼집니다. API에서 사용하는 헤더를 퍼징하려면 사용법에 맞게 해당 헤더에 대한 항목을 추가하면 됩니다. 예를 들어 사용자 정의 헤더 X-Custom를 퍼징하려면 - Name: X-Custom을 추가하세요:

    - Name: GeneralFuzzingCheck
      Configuration:
        FuzzingCount: 10
        UnicodeFuzzing: true
        HeaderFuzzing: true
        Headers:
          - Name: X-Custom

이제 X-Custom 헤더를 퍼징할 구성이 준비되었습니다. 추가 헤더를 나열하려면 동일한 방법을 사용하세요. 필요에 따라 각 프로필에 대해 이 구성을 반복하세요.

분석기 설정 사용자 정의

인증

HTTP 기본 인증

원시 비밀번호

Bearer 토큰

토큰이 만료되지 않음

테스트 실행 중에 생성된 토큰

토큰이 짧은 유효 기간을 갖는 경우

API 퍼징 프로필

Overrides

파일 사용

CI/CD 변수 사용

명령어 사용

오버라이드 디버깅

제외 경로

경로 제외의 예

매개변수 제외

JSON 문서를 사용하여 매개변수 제외

예시

단일 헤더 제외

헤더와 두 개의 쿠키를 제외

`본문-폼` 매개변수 제외

JSON Path를 사용하여 특정 JSON 노드 제외

JSON Path를 사용한 여러 개의 JSON 노드 제외

XML 속성 제외

예시

URL 및 하위 리소스 제외

두 개의 URL 제외 및 이들의 하위 리소스 허용

두 개의 URL과 그 하위 리소스 제외

정규 표현식을 사용하여 URL 제외

Header Fuzzing

도움말

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

도움받기

분석기 설정 사용자 정의

인증

HTTP 기본 인증

원시 비밀번호

Bearer 토큰

토큰이 만료되지 않음

테스트 실행 중에 생성된 토큰

토큰이 짧은 유효 기간을 갖는 경우

API 퍼징 프로필

Overrides

파일 사용

CI/CD 변수 사용

명령어 사용

오버라이드 디버깅

제외 경로

경로 제외의 예

매개변수 제외

JSON 문서를 사용하여 매개변수 제외

예시

단일 헤더 제외

헤더와 두 개의 쿠키를 제외

본문-폼 매개변수 제외

JSON Path를 사용하여 특정 JSON 노드 제외

JSON Path를 사용한 여러 개의 JSON 노드 제외

XML 속성 제외

예시

URL 및 하위 리소스 제외

두 개의 URL 제외 및 이들의 하위 리소스 허용

두 개의 URL과 그 하위 리소스 제외

정규 표현식을 사용하여 URL 제외

Header Fuzzing

도움말

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

도움받기

`본문-폼` 매개변수 제외