• 인증
  • HTTP 기본 인증
    • Raw 비밀번호
  • Bearer 토큰
    • 토큰이 만료되지 않음
    • 테스트 실행 중 생성된 토큰
    • 토큰이 짧은 만료 기간을 가짐
• 오버라이드
  • 파일 사용
  • CI/CD 변수 사용
  • 명령 사용
  • 디버깅 오버라이드
• 요청 헤더
  • Base64
  • 예시: 일반 텍스트를 사용하여 각 요청에 헤더 목록 추가
  • 예시: 마스크된 CI/CD 변수 사용
• 제외 경로
  • 예시
  • 매개변수 제외
    • JSON 문서를 사용하여 매개변수 제외하기
    • 예시
      • 단일 헤더 제외
      • 헤더와 두 개의 쿠키 제외
      • body-form 매개변수 제외
      • JSON Path를 사용하여 특정 JSON 노드 제외
      • JSON Path를 사용하여 여러 개의 JSON 노드 제외
      • XML 속성 제외
      • XML 텍스트 요소 제외
      • XML 요소 제외
      • 네임스페이스가 포함된 XML 노드 제외
    • JSON 문자열 사용
    • 파일 사용
  • URL 제외
    • 예시
      • URL 및 하위 자원 제외
      • 두 개의 URL 제외 및 하위 자원 허용
      • 두 개의 URL 및 그 하위 자원 제외
      • 정규 표현식을 사용하여 URL 제외

분석기 설정 사용자 정의

인증

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

HTTP 기본 인증

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

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

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

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

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/
  APISEC_HTTP_USERNAME: testuser
  APISEC_HTTP_PASSWORD_BASE64: $TEST_API_PASSWORD

Raw 비밀번호

비밀번호를 Base64로 인코딩하지 않으려면(또는 GitLab 15.3 이전 버전을 사용하는 경우), APISEC_HTTP_PASSWORD_BASE64 대신에 원시 비밀번호 APISEC_HTTP_PASSWORD를 제공할 수 있습니다.

Bearer 토큰

Bearer 토큰은 OAuth2 및 JSON Web Tokens (JWT)을 포함한 여러 인증 메커니즘에서 사용됩니다. Bearer 토큰은 Authorization HTTP 헤더를 사용하여 전송됩니다. API 보안 테스트에 Bearer 토큰을 사용하려면 다음 중 하나가 필요합니다:

• 만료되지 않는 토큰
• 테스트 기간 동안 유효한 토큰을 생성하는 방법
• API 보안 테스트가 호출할 Python 스크립트

토큰이 만료되지 않음

Bearer 토큰이 만료되지 않는 경우, APISEC_OVERRIDES_ENV 변수를 사용하여 제공합니다. 이 변수의 내용은 API 보안 테스트를 위해 발신 HTTP 요청에 추가할 헤더 및 쿠키를 제공하는 JSON 스니펫입니다.

APISEC_OVERRIDES_ENV를 사용하여 Bearer 토큰을 제공하려면 다음 단계를 따르세요:

1. CI/CD 변수를 만듭니다, 예를 들어 TEST_API_BEARERAUTH로 값을 {"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}} (토큰을 대체합니다) 설정합니다. Settings > CI/CD의 Variables 섹션에서 CI/CD 변수를 만들 수 있습니다. TEST_API_BEARERAUTH의 형식 때문에 해당 변수를 마스킹하는 것은 불가능합니다. 마스킹된 값을 얻으려면 토큰 값으로 두 번째 변수를 만들고, TEST_API_BEARERAUTH를 토큰 값($MASKED_VARIABLE)으로 정의합니다.

2. .gitlab-ci.yml 파일에서 APISEC_OVERRIDES_ENV를 방금 만든 변수로 설정합니다:

   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/
     APISEC_OVERRIDES_ENV: $TEST_API_BEARERAUTH
   

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

테스트 실행 중 생성된 토큰

Bearer 토큰이 생성되고 테스트 도중에 만료되지 않는 경우, 이 토큰을 포함하는 파일을 API 보안 테스트에 제공할 수 있습니다. 이 파일은 이전 단계 및 작업 또는 API 보안 테스트 작업의 일부가 생성할 수 있습니다.

API 보안 테스트가 다음 구조의 JSON 파일을 받도록 기대합니다:

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

이 파일은 이전 단계에서 생성되어 APISEC_OVERRIDES_FILE CI/CD 변수를 통해 API 보안 테스트에 제공됩니다.

.gitlab-ci.yml 파일에서 APISEC_OVERRIDES_FILE을 설정하세요:

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/
  APISEC_OVERRIDES_FILE: dast-api-overrides.json

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

토큰이 짧은 만료 기간을 가짐

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

스크립트는 특정 형식의 Bearer 토큰을 포함하는 JSON 파일을 생성해야 합니다:

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

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

• APISEC_OVERRIDES_FILE: 제공된 명령이 생성하는 JSON 파일
• APISEC_OVERRIDES_CMD: JSON 파일을 생성하는 명령
• APISEC_OVERRIDES_INTERVAL: 명령을 실행하는 간격(초)입니다.

예를 들어:

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/
  APISEC_OVERRIDES_FILE: dast-api-overrides.json
  APISEC_OVERRIDES_CMD: renew_token.py
  APISEC_OVERRIDES_INTERVAL: 300

인증이 작동하는지 확인하려면 API 보안 테스트를 실행하고 작업 로그와 테스트 API 응용 프로그램 로그를 확인하세요. overrides section에서 override 명령에 대한 자세한 내용을 확인하세요.

오버라이드

API 보안 테스트는 요청에서 특정 항목을 추가하거나 오버라이드하는 방법을 제공합니다. 예를 들어 다음과 같습니다.

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

이를 사용하여 semantic 버전 헤더, 인증 등을 주입할 수 있습니다. 인증 섹션에는 해당 목적으로 오버라이드를 사용하는 예시가 포함되어 있습니다.

오버라이드는 다음과 같은 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.$"
  }
}

오브젝트 내의 각 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.$"
  }
}

오브젝트 내의 각 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 문서를 파일이나 환경 변수로 제공할 수 있습니다. 또한 만료되는 값들을 지원하기 위해 일정 간격으로 명령을 실행할 수 있습니다.

파일 사용

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

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

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/
  APISEC_OVERRIDES_FILE: dast-api-overrides.json

CI/CD 변수 사용

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

다음은 .gitlab-ci.yml의 예시입니다. APISEC_OVERRIDES_ENV 변수가 JSON으로 직접 설정됩니다.

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/
  APISEC_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}'

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

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/
  APISEC_OVERRIDES_ENV: $SECRET_OVERRIDES

명령 사용

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

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

NodeJS 또는 Ruby와 같은 다른 스크립트 런타임을 설치하거나 오버라이드 명령에 대한 종속성을 설치해야 할 수 있습니다. 이 경우, APISEC_PRE_SCRIPT를 해당 필수 항목을 제공하는 스크립트의 파일 경로로 설정해야 합니다. APISEC_PRE_SCRIPT에서 제공한 스크립트는 분석기가 시작되기 전에 한 번 실행됩니다.

참고: 권한이 필요한 작업을 수행하는 경우 sudo 명령을 사용하십시오. 예를 들어, sudo apk add nodejs와 같이 사용합니다.

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

다음은 상황에 맞는 세 가지 CI/CD 변수를 제공해야 합니다:

• APISEC_OVERRIDES_FILE: 제공된 명령에 의해 생성된 파일.
• APISEC_OVERRIDES_CMD: 주기적으로 오버라이드 JSON 파일을 생성하는 오버라이드 명령.
• APISEC_OVERRIDES_INTERVAL: 명령을 실행하는 간격(초)입니다.

옵션:

• APISEC_PRE_SCRIPT: 스캔 시작 전에 런타임이나 종속성을 설치하는 스크립트.

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

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

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/
  APISEC_OVERRIDES_FILE: dast-api-overrides.json
  APISEC_OVERRIDES_CMD: renew_token.py
  APISEC_OVERRIDES_INTERVAL: 300

디버깅 오버라이드

기본적으로 오버라이드 명령의 출력은 숨겨집니다. 옵션으로 변수 APISEC_OVERRIDES_CMD_VERBOSE를 설정하여 오버라이드 명령의 출력을 gl-api-security-scanner.log 작업 artifact 파일에 로깅할 수 있습니다. 이것은 오버라이드 스크립트를 테스트하는 경우에 유용하지만, 테스트가 느려지므로 테스트를 마친 후에는 비활성화해야 합니다.

작업이 완료되거나 실패한 경우 수집되는 로그 파일에 스크립트에서 메시지를 작성하는 것도 가능합니다. 로그 파일은 특정 위치에 생성되고 명명 규칙을 따라야 합니다.

오버라이드 스크립트에 기본적인 로깅을 추가하는 것은 작업의 표준 실행 중 예기치 않게 작업이 실패하는 경우 유용합니다. 로그 파일은 작업의 artifact로 자동으로 포함되어 작업이 완료된 후 다운로드할 수 있습니다.

예를 들어, 우리가 renew_token.py를 환경 변수 APISEC_OVERRIDES_CMD에 제공했습니다. 스크립트에서 다음 두 가지 사항을 주목해보세요:

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

#!/usr/bin/env python

# 오버라이드 명령의 예시

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

import logging
import json
import os
import requests
import backoff

# [1] 로그 파일을 환경 변수 CI_PROJECT_DIR에 지정된 디렉토리에 저장
working_directory = os.environ.get( 'CI_PROJECT_DIR')
overrides_file_name = os.environ.get('APISEC_OVERRIDES_FILE', 'dast-api-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("오버라이드 파일 생성: %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'오류, {overrides_file_path} 파일 덮어쓰기 중 알 수 없는 오류 발생. 오류 메시지: {e}')
    raise

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

# end

오버라이드 명령 예시에서 이 파이썬 스크립트는 backoff 라이브러리에 의존합니다. 파이썬 스크립트를 실행하기 전에 해당 라이브러리가 설치되어 있는지 확인하려면 APISEC_PRE_SCRIPT를 오버라이드 명령의 종속성을 설치하는 스크립트로 설정하세요. 예를 들어, 다음 스크립트 user-pre-scan-set-up.sh를 사용할 수 있습니다.

#!/bin/bash

# user-pre-scan-set-up.sh
# 파이썬 종속성이 설치되어 있는지 확인

echo "**** 파이썬 종속성 설치 ****"

sudo pip3 install --no-cache --upgrade --break-system-packages \
    backoff

echo "**** 파이썬 종속성 설치 완료 ****"

# end

기존의 설정을 업데이트하여 APISEC_PRE_SCRIPT를 새로운 user-pre-scan-set-up.sh 스크립트로 설정해야 합니다. 예를 들어,

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/
  APISEC_PRE_SCRIPT: ./user-pre-scan-set-up.sh
  APISEC_OVERRIDES_FILE: dast-api-overrides.json
  APISEC_OVERRIDES_CMD: renew_token.py
  APISEC_OVERRIDES_INTERVAL: 300

앞의 예시에서 user-pre-scan-set-up.sh 스크립트를 사용하여 후에 오버라이드 명령에서 사용할 새 실행 시간 또는 애플리케이션을 설치할 수도 있습니다.

요청 헤더

요청 헤더 기능을 사용하면 스캔 세션 중에 헤더에 대한 고정된 값을 지정할 수 있습니다. 예를 들어 APISEC_REQUEST_HEADERS 구성 변수를 사용하여 Cache-Control 헤더에 고정된 값을 설정할 수 있습니다. 필요한 헤더에는 Authorization 헤더와 같이 민감한 값을 포함할 경우 마스킹된 변수 기능과 변수 APISEC_REQUEST_HEADERS_BASE64를 함께 사용하세요.

Authorization 헤더나 다른 헤더 중 스캔 중에 업데이트해야 하는 경우에는 오버라이드 기능을 고려해보세요.

변수 APISEC_REQUEST_HEADERS를 사용하면 쉼표로 구분된 (,) 헤더 목록을 지정할 수 있습니다. 이러한 헤더들은 스캐너가 수행하는 각 요청에 포함됩니다. 목록의 각 헤더 엔트리는 이름 다음에 콜론(:)을 두고 그 값으로 구성됩니다. 키 또는 값 앞의 공백은 무시됩니다. 예를 들어, Cache-Control 헤더 이름과 값 max-age=604800를 선언하려면 헤더 엔트리는 Cache-Control: max-age=604800입니다. 두 개의 헤더를 사용하려면 Cache-Control: max-age=604800 및 Age: 100을 설정하면 됩니다.

변수 APISEC_REQUEST_HEADERS에 제공되는 다른 헤더의 순서가 결과에 영향을 미치지 않습니다. APISEC_REQUEST_HEADERS를 Cache-Control: max-age=604800, Age: 100로 설정하든, Age: 100, Cache-Control: max-age=604800로 설정하든 동일한 결과가 나옵니다.

Base64

APISEC_REQUEST_HEADERS_BASE64 변수는 APISEC_REQUEST_HEADERS와 동일한 헤더 목록을 허용하지만, 변수의 전체 값이 Base64로 인코딩되어야 한다는 차이점만 있습니다. 예를 들어 APISEC_REQUEST_HEADERS_BASE64 변수를 Authorization: QmVhcmVyIFRPS0VO, Cache-control: bm8tY2FjaGU=로 설정하려면 목록을 해당 Base64 등가물로 변환해야 합니다: QXV0aG9yaXphdGlvbjogUW1WaGNtVnlJRlJQUzBWTywgQ2FjaGUtY29udHJvbDogYm04dFkyRmphR1U9 사용되어야 합니다. 이것은 마스크된 변수에 비밀 헤더 값을 저장할 때 유용합니다.

경고: Base64는 마스크된 변수 기능을 지원하기 위해 사용됩니다. 민감한 값은 쉽게 디코딩될 수 있기 때문에, Base64 인코딩 자체는 보안 조치가 아닙니다.

예시: 일반 텍스트를 사용하여 각 요청에 헤더 목록 추가

다음 .gitlab-ci.yml 예제에서 APISEC_REQUEST_HEADERS 구성 변수는 요청 헤더에서 설명한대로 두 개의 헤더 값을 제공하도록 설정됩니다.

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/
  APISEC_REQUEST_HEADERS: 'Cache-control: no-cache, Save-Data: on'

예시: 마스크된 CI/CD 변수 사용

다음 .gitlab-ci.yml 예제는 UI에서 정의된 그룹 또는 인스턴스 CI/CD 변수로 정의된 마스크된 변수 SECRET_REQUEST_HEADERS_BASE64을 가정합니다. SECRET_REQUEST_HEADERS_BASE64의 값은 X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb의 Base64로 인코딩된 텍스트 버전인 WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=로 설정됩니다. 그런 다음, 다음과 같이 사용할 수 있습니다.

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/
  APISEC_REQUEST_HEADERS_BASE64: $SECRET_REQUEST_HEADERS_BASE64

마스크된 변수에 문자 집합 제한이 있기 때문에 APISEC_REQUEST_HEADERS_BASE64를 사용할 때 고비밀 헤더 값을 저장하는 것이 좋습니다.

제외 경로

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

경로가 제외되었는지 확인하려면 작업 결과의 테스트된 작업(Tested Operations) 및 제외된 작업(Excluded Operations) 부분을 검토하십시오. Tested Operations`에 나열된 제외된 경로를 보지 못해야 합니다.

2021-05-27 21:51:08 [INF] API SECURITY: --[ Tested Operations ]-------------------------
2021-05-27 21:51:08 [INF] API SECURITY: 201 POST http://target:7777/api/users CREATED
2021-05-27 21:51:08 [INF] API SECURITY: ------------------------------------------------
2021-05-27 21:51:08 [INF] API SECURITY: --[ Excluded Operations ]-----------------------
2021-05-27 21:51:08 [INF] API SECURITY: GET http://target:7777/api/messages
2021-05-27 21:51:08 [INF] API SECURITY: POST http://target:7777/api/messages
2021-05-27 21:51:08 [INF] API SECURITY: ------------------------------------------------

예시

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

variables:
  APISEC_EXCLUDE_PATHS: /auth

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

variables:
  APISEC_EXCLUDE_PATHS: /auth*

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

variables:
  APISEC_EXCLUDE_PATHS: /auth*;/v1/*

경로 내에서 하나 이상의 중첩된 수준을 제외하려면 **를 사용합니다. 이 예에서는 /api/v1/ 및 /api/v2/를 테스트합니다. planet, moon, star, satellite 객체의 mass, brightness, coordinates 데이터를 요청하는 데이터 쿼리의 /api/v1/ 및 /api/v2/를 테스트합니다. 스캔할 수 있는 예상 경로는 다음과 같습니다:

• /api/v2/planet/coordinates
• /api/v1/star/mass
• /api/v2/satellite/brightness

이 예에서는 brightness 엔드포인트만 테스트합니다.

variables:
  APISEC_EXCLUDE_PATHS: /api/**/mass;/api/**/coordinates

매개변수 제외

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

APISEC_EXCLUDE_PARAMETER_ENV를 사용하면 제외된 매개변수를 포함하는 JSON 문자열을 제공할 수 있습니다. 이것은 JSON이 짧고 자주 변경되지 않는 경우에 좋은 옵션입니다. 다른 옵션은 APISEC_EXCLUDE_PARAMETER_FILE입니다. 이 변수는 저장소에 체크인하거나, 다른 작업에서 아티팩트로 생성되거나, 사전 스크립트를 사용하여 런타임에 생성된 파일 경로로 설정할 수 있습니다.

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

JSON 문서에는 JSON 객체가 포함되어 있으며, 해당 객체는 매개변수 제외를 식별하기 위해 특정 속성들을 사용합니다. 스캔 프로세스 중에 특정 매개변수를 제외하려면 다음과 같은 속성을 제공할 수 있습니다.

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

따라서 다음 JSON 문서는 매개변수를 제외하기 위한 예상된 구조의 예시입니다.

{
  "headers": [
    "header1",
    "header2"
  ],
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "query": [
    "query-string1",
    "query-string2"
  ],
  "body-form": [
    "form-param1",
    "form-param2"
  ],
  "body-json": [
    "json-path-expression-1",
    "json-path-expression-2"
  ],
  "body-xml" : [
    "xpath-expression-1",
    "xpath-expression-2"
  ]
}

예시

단일 헤더 제외

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

{
  "headers": [ "Upgrade-Insecure-Requests" ]
}

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

헤더와 두 개의 쿠키 제외

Authorization 헤더와 PHPSESSID, csrftoken 쿠키를 제외하려면 headers 속성의 값을 헤더 이름이 포함된 배열로 [ "Authorization" ] 설정하고, cookies 속성의 값을 쿠키 이름이 포함된 배열로 [ "PHPSESSID", "csrftoken" ] 설정합니다. 예를 들어, JSON 문서는 다음과 같습니다.

{
  "headers": [ "Authorization" ],
  "cookies": [ "PHPSESSID", "csrftoken" ]
}

body-form 매개변수 제외

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 path 표현식 $ .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[*].password" ] 설정합니다.

JSON Path 표현식은 $로 루트 노드를 참조하고, .로 현재 노드를 참조합니다. 그런 다음, users를 사용하여 속성을 가리키고 배열에서 인덱스를 포함하는 대신 *를 사용하여 모든 인덱스를 지정합니다. 인덱스 참조 후, 해당 인덱스를 가리키는 .과 속성 이름 password가 이어집니다.

예를 들어, JSON 문서는 다음과 같습니다.

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

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

XML 속성 제외

루트 엘리먼트 credentials에 위치한 isEnabled이라는 속성을 제외하려면 body-xml 속성의 값을 XPath 식이 포함된 배열로 설정합니다 [ "/credentials/@isEnabled" ].

XPath 식 /credentials/@isEnabled은 XML 문서의 루트를 나타내는 /로 시작하고, 일치해야 하는 엘리먼트의 이름인 credentials를 뒤따릅니다. 이전 XML 엘리먼트의 노드를 가리키기 위해 /를 사용하고, 속성 이름인 isEnabled 앞에 @를 사용합니다.

예를 들어, JSON 문서는 다음과 같습니다.

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

요청이 application/xml 콘텐츠 유형을 사용할 때, 매개변수 제외는 body-xml을 사용합니다. body-xml의 각 항목은 XPath v2 식으로 예상됩니다. XPath 식에는 @, /, :, [, ] 등의 문자가 특별한 의미를 가집니다.

XML 텍스트 요소 제외

루트 노드 credentials에 포함된 username 요소의 텍스트를 제외하려면 body-xml 속성값을 XPath 표현식 [/credentials/username/text()" ]의 배열로 설정하세요.

XPath 표현식 /credentials/username/text()에서 첫 번째 문자 /는 루트 XML 노드를 가리키며, 그 뒤에는 XML 요소 이름 credentials을 나타냅니다. 유사하게 문자 /는 현재 요소를 가리킨 후 새 XML 요소 이름 username이 옵니다. 마지막 부분에는 현재 요소의 텍스트를 식별하는 XPath 함수 인 text()가 사용됩니다.

예를 들어, JSON 문서는 다음과 같습니다:

{
  "body-xml": [
    "/credentials/username/text()"
  ]
}

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

XML 요소 제외

루트 노드 credentials에 포함된 username 요소를 제외하려면 body-xml 속성값을 XPath 표현식 [/credentials/username" ]의 배열로 설정하세요.

XPath 표현식 /credentials/username에서 첫 번째 문자 /는 루트 XML 노드를 가리키며, 그 뒤에는 XML 요소 이름 credentials을 나타냅니다. 유사하게 문자 /는 현재 요소를 가리키므로 새 XML 요소 이름 username이 나오게 됩니다.

예를 들어, JSON 문서는 다음과 같습니다:

{
  "body-xml": [
    "/credentials/username"
  ]
}

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

네임스페이스가 포함된 XML 노드 제외

네임스페이스 s에 정의된 login XML 요소를 루트 노드 credentials에 포함한 경우, body-xml 속성값을 XPath 표현식 [ "/credentials/s:login" ]의 배열로 설정하세요.

XPath 표현식 /credentials/s:login에서 첫 번째 문자 /는 루트 XML 노드를 가리키며, 그 뒤에는 XML 요소 이름 credentials을 나타냅니다. 유사하게 문자 /는 현재 요소를 가리키며, 이어서 새 XML 요소 이름 s:login이 나옵니다. 이름에 문자 :가 포함된 점에 주목하세요. 이 문자는 네임스페이스를 노드 이름과 구분합니다.

네임스페이스 이름은 본문 요청에 포함된 XML 문서에 정의되어 있어야 합니다. 네임스페이스는 명세 문서인 HAR, OpenAPI 또는 Postman Collection 파일에서 확인할 수 있습니다.

{
  "body-xml": [
    "/credentials/s:login"
  ]
}

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

JSON 문자열 사용

제외 JSON 문서를 제공하려면 변수 APISEC_EXCLUDE_PARAMETER_ENV에 JSON 문자열을 설정하세요. 다음 예에서 .gitlab-ci.yml에서 APISEC_EXCLUDE_PARAMETER_ENV 변수가 JSON 문자열로 설정되어 있습니다:

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/
  APISEC_EXCLUDE_PARAMETER_ENV: '{ "headers": [ "Upgrade-Insecure-Requests" ] }'

파일 사용

제외 JSON 문서를 제공하려면 변수 APISEC_EXCLUDE_PARAMETER_FILE에 JSON 파일 경로를 설정하세요. 파일 경로는 작업의 현재 작업 디렉토리를 기준으로 상대적입니다. 다음 예에서 .gitlab-ci.yml의 내용 중 APISEC_EXCLUDE_PARAMETER_FILE 변수가 JSON 파일 경로로 설정되어 있습니다:

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/
  APISEC_EXCLUDE_PARAMETER_FILE: dast-api-exclude-parameters.json

dast-api-exclude-parameters.json은 제외 매개변수 문서의 구조를 따르는 JSON 문서입니다.

URL 제외

경로별로 제외하는 대신, .gitlab-ci.yml 파일에서 APISEC_EXCLUDE_URLS CI/CD 변수를 사용하여 URL의 다른 구성 요소로 필터링할 수 있습니다. 이 변수는 여러 값, 즉 쉼표(,)로 구분된 여러 정규 표현식을 저장할 수 있습니다. 각 값은 정규 표현식입니다. 각 항목이 정규 표현식인 경우 .*와 같은 항목은 모든 것을 일치시키는 정규 표현식이므로 모든 URL을 제외합니다.

작업 출력에서 APISEC_EXCLUDE_URLS에서 제공된 정규 표현식과 일치하는 URL이 있는지 확인할 수 있습니다. 일치 작업은 제외된 작업 섹션에 나열됩니다. 제외된 작업에 나열된 작업은 테스트된 작업 섹션에 나열되어서는 안 됩니다. 예를 들어, 다음과 같이 작업 출력에서 확인할 수 있습니다:

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

참고: APISEC_EXCLUDE_URLS의 각 값은 정규 표현식입니다. ., *, $와 같은 문자는 정규 표현식에서 특별한 의미를 갖습니다.

예시

URL 및 하위 자원 제외

다음 예제는 http://target/api/auth URL과 해당 하위 자원을 제외합니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: http://target/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_EXCLUDE_URLS: http://target/api/auth

두 개의 URL 제외 및 하위 자원 허용

http://target/api/buy 및 http://target/api/sell URL을 제외하고 하위 자원을 스캔할 수 있도록 하려면, 예를 들어 http://target/api/buy/toy 또는 http://target/api/sell/chair와 같은 자원을 스캔하도록 허용합니다. http://target/api/buy/$,http://target/api/sell/$ 값을 사용할 수 있습니다. 이 값은 각각 쉼표로 구분된 두 개의 정규 표현식을 사용하며, 따라서 http://target/api/buy$ 및 http://target/api/sell$를 포함합니다. 각 정규 표현식에서 $ 문자는 일치하는 URL이 끝나는 위치를 나타냅니다.

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: http://target/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$

두 개의 URL 및 그 하위 자원 제외

http://target/api/buy 및 http://target/api/sell URL 및 그 하위 자원을 제외합니다. 여러 개의 URL을 제공하기 위해 , 문자를 사용합니다:

stages:
  - dast

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

variables:
  APISEC_TARGET_URL: http://target/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_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:
  - dast

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

variables:
  APISEC_TARGET_URL: http://target/
  APISEC_OPENAPI: test-api-specification.json
  APISEC_EXCLUDE_URLS: https://target/api/v.*/user/create$