히스토리

• 스캔 실행 정책에서 미리 정의된 변수 재정의가 GitLab 16.10에서 allow_restricted_variables_at_policy_level이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화되어 있습니다. 기능 플래그 allow_restricted_variables_at_policy_level은 GitLab 17.5에서 제거되었습니다.

스캔 실행 정책은 기본 또는 최신 보안 CI/CD 템플릿을 기준으로 GitLab 보안 스캔을 강제합니다. 스캔 실행 정책은 파이프라인의 일부로 배포하거나 지정한 일정에 따라 배포할 수 있습니다.

스캔 실행 정책은 보안 정책 프로젝트에 연결된 모든 프로젝트에 보안 스캔을 강제합니다. .gitlab-ci.yml 파일이 없는 프로젝트나 AutoDevOps가 비활성화된 프로젝트에서는 보안 정책이 .gitlab-ci.yml 파일을 암묵적으로 생성합니다. 이 .gitlab-ci.yml 파일은 시크릿 탐지, 정적 분석, 또는 프로젝트에서 빌드가 필요하지 않은 다른 스캐너를 실행하는 정책이 항상 실행되고 강제될 수 있도록 보장합니다.

스캔 실행 정책과 파이프라인 실행 정책 모두 여러 프로젝트에 걸쳐 GitLab 보안 스캔을 구성해 보안과 컴플라이언스를 관리할 수 있습니다. 스캔 실행 정책은 구성이 더 빠르지만 사용자 정의할 수 없습니다. 다음 중 하나라도 해당한다면 파이프라인 실행 정책을 대신 사용합니다.

• 고급 구성 설정이 필요한 경우.
• 사용자 정의 CI/CD job이나 스크립트를 강제하려는 경우.
• 강제된 CI/CD job으로 서드파티 보안 스캔을 사용하려는 경우.

스캔 실행 정책 생성#

스캔 실행 정책을 생성할 때는 다음 자료를 활용할 수 있습니다.

• 영상으로 살펴보려면 How to set up Security Scan Policies in GitLab을 참고합니다.
• GitLab CI/CD 구성이 없는 프로젝트에 스캔 실행 정책 강제하기에서 자세히 알아봅니다.
• 스캔 실행 정책을 생성하는 방법은 튜토리얼: 스캔 실행 정책 설정을 참고합니다.

제한 사항#

• 각 정책에는 최대 5개의 규칙을 할당할 수 있습니다.
• 각 보안 정책 프로젝트에는 최대 5개의 스캔 실행 정책을 할당할 수 있습니다.
• 로컬 프로젝트 YAML 파일은 스캔 실행 정책을 재정의할 수 없습니다. 프로젝트의 CI/CD 구성에서 같은 job 이름을 사용하더라도, 스캔 실행 정책이 파이프라인에 정의된 어떤 구성보다 우선합니다.
• 예약 정책(type: schedule)은 예약된 cadence에 따라서만 실행됩니다. 정책을 업데이트해도 즉시 스캔이 트리거되지는 않습니다.
• (정책 편집기가 아니라 커밋이나 푸시로) YAML 구성 파일을 직접 수정한 정책 업데이트는 시스템 전체에 전파되기까지 최대 10분이 걸릴 수 있습니다. (이 제한에 대해 제안된 변경 사항은 이슈 512615를 참고합니다.)

job Stage#

DAST 스캔은 항상 dast Stage에서 실행됩니다. dast Stage가 없으면 GitLab이 파이프라인 끝에 dast Stage를 삽입합니다.

다른 모든 스캔의 정책 job은 파이프라인의 test Stage에서 실행됩니다. 기본 파이프라인에서 test Stage를 제거하면 job은 다음 규칙에 따라 scan-policies Stage에서 실행됩니다.

• scan-policies Stage가 아직 없으면 GitLab이 평가 시점에 CI/CD 파이프라인에 이 Stage를 삽입합니다.
• build Stage가 있으면 GitLab은 build Stage 바로 뒤에 scan-policies를 삽입합니다.
• build Stage가 없으면 GitLab은 파이프라인 시작 부분에 scan-policies를 삽입합니다.

job 이름 충돌을 피하기 위해 job 이름 뒤에 하이픈과 숫자가 붙습니다. 각 숫자는 정책 작업마다 고유한 값입니다. 예를 들어 secret-detection은 secret-detection-1이 됩니다.

스캔 실행 정책 편집기#

히스토리

• Merge Request Security Template:
• GitLab 18.2에서 flexible_scan_execution이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.3에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.
• GitLab 18.4에서 일반 공개되었습니다. 기능 플래그 flexible_scan_execution이 제거되었습니다.

스캔 실행 정책 편집기로 스캔 실행 정책을 생성하거나 편집합니다.

사전 요구 사항:

• 기본적으로 그룹, 하위 그룹, 프로젝트의 Owner만 보안 정책 프로젝트를 생성하거나 할당하는 데 필요한 권한을 가집니다. 또는 보안 정책 링크 관리 권한이 있는 사용자 정의 역할을 만들 수도 있습니다.

첫 스캔 실행 정책을 생성할 때는 일반적인 사용 사례를 위한 다음 템플릿 중에서 선택합니다.

• Merge Request Security
  • 사용 사례: 모든 커밋이 아니라 머지 리퀘스트가 생성될 때만 보안 스캔을 실행하려는 경우입니다.
  • 사용 시점: 기본 브랜치나 보호된 브랜치를 대상으로 하는 소스 브랜치에서 보안 스캔을 실행해야 하는 머지 리퀘스트 파이프라인을 사용하는 프로젝트에 적합합니다.
  • 적합한 용도: 머지 리퀘스트 승인 정책과 맞추고, 모든 브랜치에서 스캔하지 않음으로써 인프라 비용을 줄이는 경우입니다.
  • 파이프라인 소스: 주로 머지 리퀘스트 파이프라인입니다.
• Scheduled Scanning
  • 사용 사례: 코드 변경과 무관하게 일정(매일 또는 매주 등)에 따라 보안 스캔을 자동으로 실행하려는 경우입니다.
  • 사용 시점: 개발 활동과 무관하게 정기적인 주기로 보안 스캔을 수행할 때 적합합니다.
  • 적합한 용도: 컴플라이언스 요구 사항, 기준선 보안 모니터링, 또는 커밋이 드문 프로젝트입니다.
  • 파이프라인 소스: 예약된 파이프라인입니다.
• Release Security
  • 사용 사례: main 또는 릴리스 브랜치의 모든 변경에 대해 보안 스캔을 실행하려는 경우입니다.
  • 사용 시점: 릴리스 전에 또는 보호된 브랜치에서 포괄적인 스캔이 필요한 프로젝트에 적합합니다.
  • 적합한 용도: 릴리스 게이트 방식의 워크플로, 프로덕션 배포, 또는 높은 보안 수준이 필요한 환경입니다.
  • 파이프라인 소스: 보호된 브랜치로의 푸시 파이프라인, 릴리스 파이프라인입니다.

사용 가능한 템플릿이 요구 사항을 충족하지 않거나 더 많이 사용자 정의한 스캔 실행 정책이 필요하다면 다음을 할 수 있습니다.

• Custom 옵션을 선택해 사용자 정의 요구 사항에 맞는 스캔 실행 정책을 직접 만듭니다.
• 파이프라인 실행 정책으로 보안 스캔과 CI 강제에 대해 더 많은 사용자 정의 옵션을 사용합니다.

정책을 완성했으면 편집기 하단의 Configure with a merge request를 선택해 정책을 저장합니다. 프로젝트에 구성된 보안 정책 프로젝트의 머지 리퀘스트로 이동합니다. 프로젝트에 보안 정책 프로젝트가 연결되어 있지 않으면 GitLab이 자동으로 하나를 생성합니다. 편집기 하단의 Delete policy를 선택하면 편집기 화면에서 기존 정책을 제거할 수 있습니다. 이 작업은 policy.yml 파일에서 정책을 제거하는 머지 리퀘스트를 생성합니다.

대부분의 정책 변경은 머지 리퀘스트가 머지되는 즉시 적용됩니다. 머지 리퀘스트가 아니라 기본 브랜치에 직접 커밋한 변경은 정책 변경이 적용되기까지 최대 10분이 걸립니다.

스캔 실행 정책 전체 스키마#

스캔 실행 정책이 포함된 YAML 구성은 스캔 실행 정책 스키마와 일치하는 객체의 배열로 구성됩니다. 객체는 scan_execution_policy 키 아래에 중첩됩니다. scan_execution_policy 키 아래에는 최대 5개의 정책을 구성할 수 있습니다. 처음 5개 이후에 구성한 정책은 적용되지 않습니다.

새 정책을 저장하면 GitLab이 이 JSON 스키마에 대해 정책 내용을 검증합니다. JSON 스키마에 익숙하지 않다면 다음 섹션과 표를 참고할 수 있습니다.

스캔 실행 정책 스키마#

히스토리

• 정책당 작업 수 제한이 GitLab 17.4에서 scan_execution_policy_action_limit(프로젝트용)과 scan_execution_policy_action_limit_group(그룹용)이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 정책당 작업 수 제한이 GitLab 18.0에서 일반 공개되었습니다. 기능 플래그 scan_execution_policy_action_limit(프로젝트용)과 scan_execution_policy_action_limit_group(그룹용)이 제거되었습니다.

skip_ci 유형#

히스토리

• GitLab 17.9에서 도입되었습니다.

스캔 실행 정책은 누가 [skip ci] 지시문을 사용할 수 있는지 제어할 수 있습니다. 중요한 보안 및 컴플라이언스 점검은 계속 수행하면서, [skip ci]를 사용할 수 있는 특정 사용자나 서비스 계정을 지정할 수 있습니다.

skip_ci 키워드로 사용자가 파이프라인을 건너뛰기 위해 skip_ci 지시문을 적용할 수 있는지 여부를 지정합니다. 이 키워드를 지정하지 않으면 skip_ci 지시문은 무시되며, 모든 사용자가 파이프라인 실행 정책을 우회하지 못합니다.

no_pipeline 유형#

스캔 실행 정책은 누가 [no_pipeline] 지시문을 사용할 수 있는지 제어할 수 있습니다. 중요한 보안 및 컴플라이언스 점검은 계속 수행하면서, [no_pipeline]을 사용할 수 있는 특정 사용자나 서비스 계정을 지정할 수 있습니다.

no_pipeline 키워드로 사용자가 푸시 시 파이프라인을 생성하지 않도록 no_pipeline 지시문을 적용할 수 있는지 여부를 지정합니다. 이 키워드를 지정하지 않으면 no_pipeline 지시문은 무시되며, 모든 사용자가 파이프라인 실행 정책을 우회하지 못합니다.

pipeline 규칙 유형#

히스토리

• pipeline_sources 필드와 branch_type 옵션 target_default, target_protected:
• GitLab 18.2에서 flexible_scan_execution이라는 기능 플래그와 함께 도입되었습니다.
• GitLab 18.3에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.
• GitLab 18.4에서 일반 공개되었습니다. 기능 플래그 flexible_scan_execution이 제거되었습니다.

이 규칙은 선택한 브랜치에서 파이프라인이 실행될 때마다 정의된 작업을 강제합니다.

schedule 규칙 유형#

히스토리

• 예약된 스캔이 파이프라인을 생성하도록 하는 새 scan_execution_pipeline_worker 워커:
• GitLab 16.11에서 기능 플래그와 함께 도입되었습니다.
• GitLab 17.5에서 GitLab.com에서 활성화되었습니다.
• GitLab 17.6에서 일반 공개되었습니다. 기능 플래그 scan_execution_pipeline_worker가 제거되었습니다.
• 새 애플리케이션 설정 security_policy_scheduled_scans_max_concurrency:
• GitLab 17.1에서 도입되었습니다. 이 동시성 제한은 scan_execution_pipeline_worker와 scan_execution_pipeline_concurrency_control이 모두 활성화된 경우에 적용됩니다.
• GitLab 17.11에서 새 애플리케이션 설정 security_policy_scheduled_scans_max_concurrency가 제거되었습니다.
• 스캔 실행 예약 job의 동시성 제한:
• GitLab 17.3에서 scan_execution_pipeline_concurrency_control이라는 기능 플래그와 함께 도입되었습니다.
• GitLab 17.9에서 일반 공개되었습니다. 기능 플래그 scan_execution_pipeline_concurrency_control이 제거되었습니다.

schedule 규칙 유형으로 보안 스캐너를 일정에 따라 실행합니다.

예약된 파이프라인의 동작은 다음과 같습니다.

• 프로젝트의 .gitlab-ci.yml 파일에 정의된 job이 아니라, 정책에 정의된 스캐너만 실행합니다.
• cadence 필드에 정의된 일정에 따라 실행합니다.
• 프로젝트의 security_policy_bot 사용자 계정으로 실행되며, 이 계정은 Guest 권한과 CI/CD job에서 파이프라인을 생성하고 리포지터리 콘텐츠를 읽을 수 있는 권한을 가집니다. 이 계정은 정책이 그룹이나 프로젝트에 연결될 때 생성됩니다.
• GitLab.com에서는 스캔 실행 정책의 schedule 규칙 중 처음 10개만 강제됩니다. 이 제한을 초과한 규칙은 아무 효과가 없습니다.

Cadence#

히스토리

• GitLab 19.4에서 규칙 모드의 월간 주기 지원이 도입되었습니다.

cadence 필드로 정책의 작업을 언제 실행할지 예약합니다. cadence 필드는 cron 구문을 사용하지만 다음과 같은 제한이 있습니다.

• 다음 유형의 cron 구문만 지원합니다.
  • 지정한 시각 전후로 하루에 한 번 실행하는 일간 주기. 예: 0 18 * * *
  • 지정한 요일의 지정한 시각 전후로 주에 한 번 실행하는 주간 주기. 예: 0 13 * * 0
  • 한 달 중 지정한 하나 이상의 날짜의 지정한 시각 전후로 실행하는 월간 주기. 예: 0 0 1 * *, 여러 날짜는 일(day-of-month) 필드에 쉼표로 구분한 목록을 사용합니다. 예: 0 0 1,15 * *. 해당 월의 일수보다 큰 날짜는 그 달에 건너뛰므로, 31일로 예약한 스캔은 30일까지 있는 달에는 실행되지 않습니다.
• 분과 시에는 쉼표(,), 하이픈(-), 스텝 연산자(/)를 사용할 수 없습니다. 이 문자를 사용한 예약 파이프라인은 건너뜁니다.

cadence 필드의 값을 선택할 때는 다음을 고려합니다.

• 시각은 GitLab.com과 GitLab Dedicated에서는 UTC를 기준으로 하고, GitLab Self-Managed에서는 GitLab 호스트의 시스템 시각을 기준으로 합니다. 새 정책을 테스트할 때는 파이프라인이 로컬 시간대가 아니라 서버의 시간대로 예약되기 때문에 잘못된 시각에 실행되는 것처럼 보일 수 있습니다.
• 예약된 파이프라인은 생성에 필요한 리소스가 확보될 때까지 시작되지 않습니다. 즉, 파이프라인이 정책에 지정된 시각에 정확히 시작되지 않을 수 있습니다.

schedule 규칙 유형을 agents 필드와 함께 사용할 때는 다음과 같습니다.

• Kubernetes용 GitLab 에이전트는 30초마다 해당하는 정책이 있는지 확인합니다. 에이전트가 정책을 찾으면 정의된 cadence에 따라 스캔이 실행됩니다.
• cron 표현식은 Kubernetes 에이전트 Pod의 시스템 시각으로 평가됩니다.

schedule 규칙 유형을 branches 필드와 함께 사용할 때는 다음과 같습니다.

• cron 워커는 15분 간격으로 실행되며, 지난 15분 동안 실행이 예약되어 있던 파이프라인을 시작합니다. 따라서 예약된 파이프라인은 최대 15분까지 지연되어 실행될 수 있습니다.
• 정책이 많은 프로젝트나 브랜치에 강제되면 정책이 배치 단위로 처리되며, 모든 파이프라인을 생성하는 데 시간이 걸릴 수 있습니다.

agent 스키마#

이 스키마로 schedule 규칙 유형의 agents 객체를 정의합니다.

agent 예제#

- name: Enforce container scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces
  enabled: true
  rules:
  - type: schedule
    cadence: '0 10 * * *'
    agents:
      <agent-name>:
        namespaces:
        - 'default'
        - 'kube-system'
  actions:
  - scan: container_scanning

예약 규칙의 키는 다음과 같습니다.

• cadence(필수): 스캔이 실행될 시점을 정하는 Cron 표현식입니다.
• agents:<agent-name>(필수): 스캔에 사용할 에이전트의 이름입니다.
• agents:<agent-name>:namespaces(선택): 스캔할 Kubernetes 네임스페이스입니다. 생략하면 모든 네임스페이스를 스캔합니다.

time_window 스키마#

schedule 규칙 유형의 time_window 객체로 예약된 스캔을 시간에 걸쳐 어떻게 분산할지 정의합니다. time_window는 정책 편집기의 YAML 모드에서만 구성할 수 있습니다.

time_window 예제#

- name: Enforce container scanning with a time window of 1 hour
  enabled: true
  rules:
  - type: schedule
    cadence: '0 10 * * *'
    time_window:
      value: 3600
      distribution: random
  actions:
  - scan: container_scanning

대규모 프로젝트에서 예약된 파이프라인 최적화#

정책이 여러 프로젝트와 브랜치에 예약 파이프라인을 강제하면 파이프라인이 동시에 실행됩니다. 각 프로젝트에서 예약 파이프라인이 처음 실행될 때, 해당 프로젝트의 예약 실행을 담당하는 보안 봇 사용자가 생성됩니다.

대규모 프로젝트에서 성능을 최적화하는 방법은 다음과 같습니다.

• 예약 스캔 실행 정책을 일부 프로젝트부터 시작해 점진적으로 배포합니다. 보안 정책 범위를 활용해 특정 그룹, 프로젝트, 또는 특정 컴플라이언스 프레임워크 레이블이 있는 프로젝트를 대상으로 지정할 수 있습니다.
• 지정한 tag가 있는 러너에서 예약 실행이 이루어지도록 정책을 구성할 수 있습니다. 다른 러너에 미치는 영향을 줄이려면, 정책으로 강제된 예약 실행을 처리할 전용 러너를 각 프로젝트에 두는 방안을 고려합니다.
• 프로덕션에 배포하기 전에 스테이징이나 하위 환경에서 구현을 테스트합니다. 성능을 모니터링하고 결과에 따라 배포 계획을 조정합니다.

예약된 스캔 실행 정책의 최대 예약 기간 구성#

예약 스캔 실행 정책은 cadence 필드에 cron 표현식을 사용해 월 단위 예약을 지원합니다. time_window는 최대 2629746초(약 30일)까지 구성해, 그 기간 안에서 스캔을 무작위로 분산할 수 있습니다.

예를 들어 30일 분산 창으로 매월 스캔을 예약하려면 다음과 같이 작성합니다.

rules:
  - type: schedule
    cadence: '0 0 1 * *'  # Run on the first day of each month
    time_window:
      value: 2592000  # 30 days in seconds
      distribution: random

인스턴스 다운타임 중 예약된 스캔 이해#

예약된 스캔은 다음 실행 시각을 추적합니다. 스캔이 성공하면 시스템은 다음 스캔을 실행할 시점을 업데이트합니다. 예약된 스캔 시각에 (유지 관리, 장애, 재시작 등으로) GitLab 인스턴스를 사용할 수 없으면, 시스템은 이미 실행되었어야 하지만 실행되지 않은 스캔을 식별하고 인스턴스를 사용할 수 있게 되면 파이프라인을 생성합니다.

예약된 스캔이 있는 프로젝트 삭제#

프로젝트를 삭제하면 연결된 모든 예약 스캔도 삭제됩니다. 삭제된 프로젝트에서는 파이프라인이 실행되지 않습니다.

실행 중인 예약된 스캔 취소#

예약된 스캔을 취소하는 방법은 두 가지입니다.

• 개별 파이프라인 취소: 프로젝트에서 job을 취소할 권한이 있으면 파이프라인 보기에서 실행 중인 파이프라인을 직접 취소할 수 있습니다.
• Disable the policy: 정책 편집기에서 enabled: false로 설정해 스캔 실행 정책을 비활성화합니다. 이미 실행 중이거나 앞으로 약 15분 안에 실행되도록 예약된 스캔은 그대로 실행될 수 있습니다.

대규모 배포를 위한 권장 사항#

예약 스캔 실행 정책을 많은 프로젝트에 배포할 때는 다음 권장 사항을 고려합니다.

• 점진적 배포 사용: 소수의 프로젝트에서 시작해 점차 프로젝트를 추가합니다. 컴플라이언스 프레임워크 레이블로 특정 프로젝트 그룹에 정책 범위를 지정합니다.
• time_window 구성: 예약 정책에는 항상 time_window 매개변수를 설정합니다. 설정하지 않으면 모든 파이프라인이 같은 시각에 예약되어 성능 문제와 리소스 경합이 발생할 수 있습니다.
• 스테이징에서 테스트: 프로덕션에 배포하기 전에 스테이징 환경이나 하위 환경에서 정책 구성을 검증합니다. 성능을 모니터링하고 결과에 따라 조정합니다.
• 러너 용량 고려: 러너에 미치는 영향은 정책 구성, 러너 가용성, GitLab 인스턴스 배포 방식에 따라 달라집니다. 부하를 분산하려면 특정 태그가 있는 러너를 사용하도록 정책을 구성합니다.

예약된 스캔 최적화에 대한 자세한 내용은 대규모 프로젝트에서 예약된 파이프라인 최적화를 참고합니다.

동시성 제어#

time_window 속성을 설정하면 GitLab이 동시성 제어를 적용합니다.

동시성 제어는 정책에 정의된 time_window 설정에 따라 예약된 파이프라인을 분산합니다.

scan 작업 유형#

히스토리

• 주어진 작업에 대한 보안 템플릿 선택:
• GitLab 17.1에서 프로젝트에 대해 scan_execution_policies_with_latest_templates라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.2에서 그룹에 대해 scan_execution_policies_with_latest_templates_group이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.2에서 GitLab Self-Managed와 GitLab Dedicated에서 활성화되었습니다.
• GitLab 17.3에서 일반 공개되었습니다. 기능 플래그 scan_execution_policies_with_latest_templates와 scan_execution_policies_with_latest_templates_group이 제거되었습니다.
• dependency_scanning의 v2 템플릿 지원이 GitLab 18.4에서 도입되었습니다.
• GitLab 19.1에서 새 정책의 dependency_scanning 기본 템플릿이 v2로 변경되었습니다.

이 작업은 정의된 정책의 규칙 중 최소 하나의 조건이 충족될 때 선택한 scan을 추가 매개변수와 함께 실행합니다.

스캐너 템플릿 버전#

template 필드는 모든 스캐너 유형에 대해 default와 latest를 허용합니다. 일부 스캐너는 추가로 버전별 템플릿을 지원합니다. 권장 기본값은 스캐너마다 다르므로, 이 필드를 설정하기 전에 스캐너 문서를 확인합니다.

스캐너 동작#

일부 스캐너는 scan 작업에서 일반 CI/CD 파이프라인 스캔과 다르게 동작합니다.

• 정적 애플리케이션 보안 테스트(SAST): 리포지터리에 SAST가 지원하는 파일이 있을 때만 실행됩니다.
• 시크릿 탐지:
  • 기본적으로 기본 룰셋의 규칙만 지원합니다.
  • 룰셋 구성을 사용자 정의하려면 다음 중 하나를 수행합니다.
    • 기본 룰셋을 수정합니다. 스캔 실행 정책으로 SECRET_DETECTION_RULESET_GIT_REFERENCE CI/CD 변수를 지정합니다. 이 변수는 기본적으로 기본 룰셋의 규칙을 재정의하거나 비활성화하기만 하는 원격 구성 파일을 가리킵니다. 이 변수만 사용하면 기본 규칙 집합을 확장하거나 교체할 수 없습니다.
    • 기본 룰셋을 확장하거나 교체합니다. 스캔 실행 정책으로 SECRET_DETECTION_RULESET_GIT_REFERENCE CI/CD 변수와, 기본 룰셋을 확장하거나 교체하기 위해 Git 패스스루를 사용하는 원격 구성 파일을 지정합니다. 자세한 안내는 How to set up a centrally managed pipeline secret detection configuration을 참고합니다.
  • scheduled 스캔 실행 정책에서는 시크릿 탐지가 기본적으로 먼저 historic 모드(SECRET_DETECTION_HISTORIC_SCAN = true)로 실행됩니다. 이후의 모든 예약 스캔은 마지막 실행과 현재 SHA 사이의 커밋 범위로 SECRET_DETECTION_LOG_OPTIONS를 설정한 기본 모드로 실행됩니다. 스캔 실행 정책에서 CI/CD 변수를 지정해 이 동작을 재정의할 수 있습니다. 자세한 내용은 전체 히스토리 파이프라인 시크릿 탐지를 참고합니다.
  • triggered 스캔 실행 정책에서는 시크릿 탐지가 .gitlab-ci.yml에서 직접 구성한 일반 스캔과 똑같이 동작합니다.
• 컨테이너 스캐닝: pipeline 규칙 유형으로 구성한 스캔은 agents 객체에 정의된 에이전트를 무시합니다. agents 객체는 schedule 규칙 유형에서만 고려됩니다. agents 객체에 이름이 지정된 에이전트는 해당 프로젝트에 대해 생성하고 구성해야 합니다.

DAST 프로파일#

동적 애플리케이션 보안 테스트(DAST)를 강제할 때는 다음 요구 사항이 적용됩니다.

• 정책 범위에 속한 모든 프로젝트에 지정한 사이트 프로파일과 스캐너 프로파일이 있어야 합니다. 이들을 사용할 수 없으면 정책이 적용되지 않고, 대신 오류 메시지가 있는 job이 생성됩니다.
• 활성화된 스캔 실행 정책에서 DAST 사이트 프로파일이나 스캐너 프로파일을 지정하면, 해당 프로파일은 수정하거나 삭제할 수 없습니다. 프로파일을 편집하거나 삭제하려면 먼저 정책 편집기에서 정책을 Disabled로 설정하거나 YAML 모드에서 enabled: false로 설정해야 합니다.
• 예약된 DAST 스캔이 있는 정책을 구성할 때는 보안 정책 프로젝트 리포지터리의 커밋 작성자가 스캐너 프로파일과 사이트 프로파일에 액세스할 수 있어야 합니다. 그렇지 않으면 스캔이 정상적으로 예약되지 않습니다.

스캔 설정#

scan_settings 매개변수는 다음 설정을 지원합니다.

CI/CD 변수#

스캔 실행 정책에 정의된 변수는 표준 CI/CD 변수 우선순위를 따릅니다.

스캔 실행 정책이 강제된 프로젝트에서는 다음 CI/CD 변수에 미리 구성된 값이 사용됩니다. 이 값은 정책만 재정의할 수 있습니다. 그룹 또는 프로젝트 CI/CD 변수로는 이 변수들을 재정의할 수 없습니다.

DS_EXCLUDED_PATHS: '**/spec,**/test,**/tests,**/tmp,**/node_modules,**/.bundle,**/vendor,**/.git'
SAST_EXCLUDED_PATHS: spec, test, tests, tmp
SECRET_DETECTION_EXCLUDED_PATHS: ''
SECRET_DETECTION_HISTORIC_SCAN: false
SAST_EXCLUDED_ANALYZERS: ''
DEFAULT_SAST_EXCLUDED_PATHS: spec, test, tests, tmp
DS_EXCLUDED_ANALYZERS: ''
ADVANCED_SAST_PARTIAL_SCAN: false

정책 범위 스키마#

정책 강제를 사용자 정의하려면, 지정한 프로젝트·그룹·컴플라이언스 프레임워크 레이블을 포함하거나 제외하도록 정책의 범위를 정의할 수 있습니다. 자세한 내용은 범위를 참고합니다.

정책 업데이트 전파#

정책을 업데이트하면 업데이트 방식에 따라 변경이 다르게 전파됩니다.

• 보안 정책 프로젝트에서 머지 리퀘스트로 업데이트: 머지 리퀘스트가 머지된 직후에 변경이 적용됩니다.
• .gitlab/security-policies/policy.yml에 직접 커밋: 변경이 적용되기까지 최대 10분이 걸릴 수 있습니다.

트리거 동작#

파이프라인 기반 정책(type: pipeline)을 업데이트해도 즉시 파이프라인이 트리거되지 않고, 이미 진행 중인 파이프라인에도 영향을 주지 않습니다. 정책 변경은 이후 파이프라인 실행에 적용됩니다.

예약된 정책의 규칙은 예약된 주기 외에 수동으로 트리거할 수 없습니다.

예제 보안 정책 프로젝트#

이 예제는 보안 정책 프로젝트에 저장된 .gitlab/security-policies/policy.yml 파일에서 사용할 수 있습니다.

---
scan_execution_policy:
- name: Enforce DAST in every release pipeline
  description: This policy enforces pipeline configuration to have a job with DAST scan for release branches
  enabled: true
  rules:
  - type: pipeline
    branches:
    - release/*
  actions:
  - scan: dast
    scanner_profile: Scanner Profile A
    site_profile: Site Profile B
- name: Enforce DAST and secret detection scans every 10 minutes
  description: This policy enforces DAST and secret detection scans to run every 10 minutes
  enabled: true
  rules:
  - type: schedule
    branches:
    - main
    cadence: "*/10 * * * *"
  actions:
  - scan: dast
    scanner_profile: Scanner Profile C
    site_profile: Site Profile D
  - scan: secret_detection
    scan_settings:
      ignore_default_before_after_script: true
- name: Enforce secret detection and container scanning in every default branch pipeline
  description: This policy enforces pipeline configuration to have a job with secret detection and container scanning scans for the default branch
  enabled: true
  rules:
  - type: pipeline
    branches:
    - main
  actions:
  - scan: secret_detection
  - scan: sast
    variables:
      SAST_EXCLUDED_ANALYZERS: brakeman
  - scan: container_scanning

이 예제의 동작은 다음과 같습니다.

• release/* 와일드카드와 일치하는 브랜치(예: release/v1.2.1 브랜치)에서 실행되는 모든 파이프라인에 대해
  • DAST 스캔이 Scanner Profile A와 Site Profile B로 실행됩니다.
• DAST 스캔과 시크릿 탐지 스캔이 10분마다 실행됩니다. DAST 스캔은 Scanner Profile C와 Site Profile D로 실행됩니다.
• main 브랜치에서 실행되는 모든 파이프라인에 대해 시크릿 탐지, 컨테이너 스캐닝, SAST 스캔이 실행됩니다. SAST 스캔은 SAST_EXCLUDED_ANALYZER 변수를 "brakeman"으로 설정해 실행됩니다.

스캔 실행 정책 편집기 예제#

이 예제는 스캔 실행 정책 편집기의 YAML 모드에서 사용할 수 있습니다. 앞선 예제의 단일 객체에 해당합니다.

name: Enforce secret detection and container scanning in every default branch pipeline
description: This policy enforces pipeline configuration to have a job with secret detection and container scanning scans for the default branch
enabled: true
rules:
  - type: pipeline
    branches:
      - main
actions:
  - scan: secret_detection
  - scan: container_scanning

중복 스캔 방지#

프로젝트의 .gitlab-ci.yml 파일에 스캔 job을 포함하면, 스캔 실행 정책 때문에 같은 유형의 스캐너가 두 번 이상 실행될 수 있습니다.

이 중복 스캔은 의도된 동작입니다. 스캐너는 서로 다른 변수와 설정으로 여러 번 실행될 수 있기 때문입니다. 예를 들어 정책으로 강제한 변수와 다른 변수로 SAST 스캔을 실행할 수 있습니다. 이 경우 파이프라인에서 두 개의 SAST job이 실행됩니다.

• 사용자 정의 변수를 사용하는 job.
• 정책으로 강제한 변수를 사용하는 job.

중복 스캔을 막으려면 프로젝트의 .gitlab-ci.yml 파일에서 스캔 중 하나를 제거하거나, 변수로 로컬 job을 건너뛸 수 있습니다. job을 건너뛰어도 스캔 실행 정책으로 정의된 보안 job은 계속 실행됩니다.

변수로 스캔 job을 건너뛰려면 다음을 사용할 수 있습니다.

• SAST job을 건너뛰려면 SAST_DISABLED: "true".
• DAST job을 건너뛰려면 DAST_DISABLED: "true".
• 컨테이너 스캐닝 job을 건너뛰려면 CONTAINER_SCANNING_DISABLED: "true".
• 시크릿 탐지 job을 건너뛰려면 SECRET_DETECTION_DISABLED: "true".
• 의존성 스캐닝 job을 건너뛰려면 DEPENDENCY_SCANNING_DISABLED: "true".

job을 건너뛸 수 있는 모든 변수의 개요는 CI/CD 변수 문서를 참고합니다.

문제 해결#

스캔 실행 정책으로 작업할 때 다음 문제가 발생할 수 있습니다.

스캔 실행 정책 파이프라인이 생성되지 않음#

스캔 실행 정책이 type: pipeline에 정의된 파이프라인을 예상대로 생성하지 않는다면, 프로젝트의 .gitlab-ci.yml 파일에 정책이 파이프라인을 생성하지 못하게 막는 workflow:rules가 있을 수 있습니다.

type: pipeline 규칙이 있는 스캔 실행 정책은 병합된 CI/CD 구성을 기반으로 파이프라인을 생성합니다. 프로젝트의 workflow:rules가 파이프라인을 전부 걸러내면 스캔 실행 정책은 파이프라인을 생성할 수 없습니다.

예를 들어 다음 workflow:rules 구성은 모든 파이프라인 생성을 막습니다.

# .gitlab-ci.yml
workflow:
  rules:
  - if: $CI_PIPELINE_SOURCE == "push"
    when: never

해결 방법:

이 문제를 해결하려면 다음 방법 중 하나를 사용할 수 있습니다.

• 스캔 실행 정책이 파이프라인을 생성할 수 있도록 프로젝트의 .gitlab-ci.yml 파일에서 workflow:rules를 수정합니다. $CI_PIPELINE_SOURCE 변수로 정책이 트리거한 파이프라인을 식별할 수 있습니다.

  workflow:
    rules:
    - if: $CI_PIPELINE_SOURCE == "security_orchestration_policy"
    - if: $CI_PIPELINE_SOURCE == "push"
      when: never
  

• type: pipeline 규칙 대신 type: schedule 규칙을 사용합니다. 예약된 스캔 실행 정책은 workflow:rules의 영향을 받지 않고, 정의된 일정에 따라 파이프라인을 생성합니다.

• CI/CD 파이프라인에서 보안 스캔이 언제 어떻게 실행되는지 더 세밀하게 제어하려면 파이프라인 실행 정책을 사용합니다.

Footnotes

1. branches 또는 branch_type 중 하나를 지정해야 하며, 둘 다 지정할 수는 없습니다. ↩ ↩²

2. 일부 옵션은 flexible_scan_execution 기능 플래그가 활성화된 경우에만 사용할 수 있습니다. 자세한 내용은 히스토리를 참고합니다. ↩ ↩² ↩³

3. branch_type 옵션 target_default 또는 target_protected를 지정하면 pipeline_sources:including 필드는 merge_request_event와 push 필드만 지원합니다. ↩ ↩²

4. branches, branch_type, agents 중 하나만 지정해야 합니다. ↩ ↩² ↩³