파이프라인 비밀 감지

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated Status: GA

파이프라인 비밀 감지는 커밋된 파일을 GitLab에 푸시한 후에 스캔합니다.

파이프라인 비밀 감지를 활성화하면 secret_detection이라는 CI/CD 작업에서 스캔이 실행됩니다. GitLab의 모든 계층에서 파이프라인 비밀 감지 JSON 보고서 artifacts를 실행하고 볼 수 있습니다.

GitLab Ultimate를 사용하면 파이프라인 비밀 감지 결과가 처리되어:

Merge Request 위젯, 파이프라인 보안 보고서, 그리고 취약점 보고서 UI에서 볼 수 있습니다.
승인 워크플로에서 사용할 수 있습니다.
보안 대시보드에서 검토할 수 있습니다.
공개 리포지터리의 누출에 자동으로 응답할 수 있습니다.

이 파이프라인 비밀 감지 설명서를 대화식으로 읽고 방법을 확인하려면:

기타 대화식 일기 및 사용 방법 설명서를 보려면 GitLab Application Security Playlist 시작하기를 확인하세요.

감지된 비밀

GitLab은 파이프라인 비밀 감지에 사용되는 감지 규칙을 유지합니다. 기본 규칙 집합에는 100가지 이상의 패턴이 포함되어 있습니다.

대부분의 파이프라인 비밀 감지 패턴은 특정 유형의 비밀을 찾습니다. 많은 서비스에서는 누출된 경우 식별할 수 있도록 비밀에 접두사나 기타 구조화된 세부 정보를 추가합니다. 예를 들어 GitLab은 기본적으로 프로젝트, 그룹 및 개인 액세스 토큰에 glpat- 접두사를 추가합니다.

더욱 신뢰할 수 있고 고신뢰도의 결과를 제공하기 위해 파이프라인 비밀 감지는 URL과 같은 특정 컨텍스트에서 비밀이나 다른 구조화되지 않은 비밀만 찾습니다.

커버리지

상황에 따라 파이프라인 비밀 감지는 코드의 다양한 측면을 스캔합니다. “기본 브랜치”를 제외한 모든 방법에서, 파이프라인 비밀 감지는 작업 트리가 아니라 커밋을 스캔합니다. 예를 들어, 파이프라인 비밀 감지는 비밀이 하나의 커밋에 추가되고 나중의 커밋에서 제거되었는지 감지할 수 있습니다.

Historical scan
SECRET_DETECTION_HISTORIC_SCAN 변수가 설정되어 있으면 모든 브랜치의 내용을 스캔합니다. 리포지터리의 내용을 스캔하기 전에 파이프라인 비밀 감지는 모든 브랜치의 내용을 가져오기 위해 git fetch --all 명령을 실행합니다.
Commit range
SECRET_DETECTION_LOG_OPTIONS 변수가 설정되어 있으면 비밀 감지 분석기는 파이프라인이 실행되는 브랜치나 참조의 전체 이력을 가져옵니다. 그런 다음 파이프라인 비밀 감지가 지정된 커밋 범위를 스캔합니다.
기본 브랜치
파이프라인 비밀 감지가 기본 브랜치에서 실행되면 Git 리포지터리는 일반 폴더로 취급됩니다. 현재 HEAD의 리포지터리의 내용만이 스캔됩니다. 커밋 이력은 스캔되지 않습니다.
푸시 이벤트
푸시 이벤트에서 파이프라인 비밀 감지는 러너에서 사용 가능한 정보를 통해 스캔할 커밋 범위를 결정합니다. 커밋 범위를 결정하기 위해 CI_COMMIT_SHA와 CI_COMMIT_BEFORE_SHA 변수가 중요합니다.
- CI_COMMIT_SHA는 지정된 브랜치의 HEAD에 대한 커밋입니다. 이 변수는 항상 푸시 이벤트에 대해 설정됩니다.
- CI_COMMIT_BEFORE_SHA는 대부분의 경우 설정됩니다. 그러나 새로운 브랜치에 대한 첫 번째 푸시 이벤트나 Merge된 파이프라인에 대해 설정되지 않습니다. 이러한 이유로 파이프라인 비밀 감지는 새로운 브랜치에 대해 여러 번의 커밋이 커밋될 때 보장할 수 없습니다.
Merge Request
Merge Request에서 파이프라인 비밀 감지는 소스 브랜치에서 수행된 모든 커밋을 스캔합니다. 이 기능을 사용하려면 최신 파이프라인 비밀 감지 템플릿을 사용해야 합니다. 이 템플릿은 Merge Request 파이프라인을 지원하므로 파이프라인 비밀 감지의 결과는 파이프라인이 완료된 후에만 사용할 수 있습니다.

완전한 이력 파이프라인 비밀 감지

기본적으로 파이프라인 비밀 감지는 Git 리포지터리의 현재 상태만 스캔합니다. 리포지터리 이력에 포함된 비밀은 감지되지 않습니다. 이 문제를 해결하기 위해 파이프라인 비밀 감지는 Git 리포지터리의 전체 이력을 스캔할 수 있습니다.

파이프라인 비밀 감지를 활성화한 후에 전체 이력 스캔을 한 번만 수행해야 합니다. 특히 Git 이력이 긴 큰 리포지터리의 경우 전체 이력 스캔에는 시간이 오래 걸릴 수 있습니다. 초기 전체 이력 스캔을 완료한 후에는 파이프라인 비밀 감지만을 사용해야 합니다.

고급 취약점 추적

Tier: Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab 17.0에서 도입.

개발자가 식별된 비밀을 포함하는 파일을 변경할 때, 이러한 비밀의 위치도 변하는 경우가 많습니다. Secret Detection 분석기는 이미 이러한 비밀을 취약점으로 플래그 처리했을 수 있으며, 취약점 보고서에서 추적됩니다. 이러한 취약점은 특정 비밀과 관련하여 쉽게 식별하고 조치할 수 있습니다. 그러나 식별된 비밀이 변동될 때 정확하게 추적되지 않으면 취약점을 관리하기가 어려워져 중복 취약점 보고서가 발생할 수 있습니다.

GitLab Secret Detection은 동일한 비밀이 리팩터링이나 관련없는 변경으로 파일 내에서 이동했을 때보다 정확하게 식별하기 위한 고급 취약점 추적 알고리즘을 사용합니다.

자세한 내용은 기밀 프로젝트 https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator를 참조하세요. 이 프로젝트의 내용은 GitLab 팀 멤버에게만 사용할 수 있습니다.

지원되지 않는 워크플로

기존 발견에 추적 서명이 없거나 새로운 발견이 동일한 위치를 공유하지 않는 워크플로는 알고리즘을 지원하지 않습니다.
Cryptographic Keys와 같은 특정 규칙 유형에 대해서 Secret Detection은 비밀 전체 값이 아닌 접두사와 일치시켜 누출을 식별합니다. 이러한 시나리오에서 알고리즘은 파일 내에서 동일한 규칙 유형의 다른 비밀을 개별적인 발견으로 다루는 대신, 하나의 발견으로 통합합니다. 예를 들어, SSH Private Key 규칙 유형은 값의 -----BEGIN OPENSSH PRIVATE KEY----- 접두사만 일치시킵니다. 파일 내에서 두 개의 독립된 SSH 개인 키가 있는 경우 알고리즘은 두 값을 동일하게 고려하고 두 개의 발견 대신 하나의 발견으로만 보고합니다.
알고리즘의 범위는 파일당 한정되어 있으며, 두 개의 다른 파일에 나타나는 동일한 비밀은 두 개의 별개의 발견으로 다뤄집니다.

구성

요구 사항

전제 조건:

docker 또는 kubernetes 실행자가 있는 Linux 기반 GitLab 러너. GitLab.com의 공유 러너를 사용하는 경우 기본적으로 활성화됩니다.
- Windows 러너는 지원되지 않습니다.
- amd64 이외의 CPU 아키텍처는 지원되지 않습니다.
사용자 고유의 러너를 사용하는 경우 설치된 Docker 버전이 19.03.0이 아닌지 확인하세요. 자세한 내용은 Docker 오류를 참조하세요.
GitLab CI/CD 구성(.gitlab-ci.yml)에 test 단계가 포함되어 있어야 합니다.

다양한 GitLab 티어에서 다양한 기능이 사용 가능합니다.

Analyzer 활성화

Pipeline Secret Detection을 활성화하려면 다음 중 하나를 수행하세요:

Auto DevOps를 활성화합니다. 이 기능에는 Auto Pipeline Secret Detection이 포함됩니다.
.gitlab-ci.yml 파일을 매뉴얼으로 편집합니다. 이 방법은 .gitlab-ci.yml 파일이 복잡한 경우에 사용합니다.
자동으로 구성된 Merge Request 사용합니다.

`.gitlab-ci.yml` 파일 매뉴얼으로 편집

이 방법은 기존의 .gitlab-ci.yml 파일을 매뉴얼으로 편집해야 합니다. GitLab CI/CD 구성 파일이 복잡한 경우에 사용합니다.

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
Build > 파이프라인 편집기를 선택합니다.
다음을 .gitlab-ci.yml 파일의 맨 아래에 복사하여 붙여넣기합니다:
```
include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml
```
유효성 검사 탭을 선택하고, 파이프라인 유효성 검사를 선택합니다. 메시지 시뮬레이션이 성공적으로 완료됨이 표시되면 파일이 유효함을 나타냅니다.
편집 탭을 선택합니다.
선택 사항. 커밋 메시지 텍스트 상자에서 커밋 메시지를 사용자 정의합니다.
브랜치 텍스트 상자에 기본 브랜치의 이름을 입력합니다.
변경 사항 커밋을 선택합니다.

이제 파이프라인에 Pipeline Secret Detection 작업이 포함됩니다.

자동으로 구성된 Merge Request 사용

GitLab 13.11에서 도입, 기본적으로 활성화된 피처 플래그 뒤에서 배포됨.
특성 플래그가 제거됨: GitLab 14.1에서.

이 방법은 .gitlab-ci.yml 파일에 Pipeline Secret Detection 템플릿이 포함된 Merge Request을 자동으로 준비합니다. 그런 다음 Merge Request을 통해 Pipeline Secret Detection을 활성화합니다.

이 방법은 기존의 .gitlab-ci.yml 파일이 없거나 최소한의 구성 파일이 있는 경우 가장 잘 작동합니다. 복잡한 GitLab 구성 파일을 사용하면 파싱에 실패할 수 있으며 오류가 발생할 수 있습니다. 이 경우 매뉴얼 방법을 대신 사용하십시오.

Pipeline Secret Detection을 활성화하려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
보안 > 보안 구성을 선택합니다.
Pipeline Secret Detection 행에서 Merge Request으로 구성을 선택합니다.
선택 사항. 필드를 완성합니다.
Merge Request 생성을 선택합니다.
Merge Request을 검토하고 Merge합니다.

이제 파이프라인에 Pipeline Secret Detection 작업이 포함됩니다.

Analyzer 설정 사용자 정의화

Pipeline Secret Detection 스캔 설정은 CI/CD 변수를 통해 변경할 수 있습니다. 이를 위해 .gitlab-ci.yml 파일의 variables 매개변수를 사용합니다.

GitLab 보안 스캔 도구의 모든 구성은 기본 브랜치로의 변경 사전에 Merge Request에서 테스트되어야 합니다. 이를 하지 않으면 예상치 못한 결과가 발생할 수 있습니다. 여기에는 거짓 긍정의 수가 많은 결과물이 포함됩니다.

새로운 패턴 추가

소프트웨어 리포지터리에서 다른 유형의 비밀을 검색하려면 사용자 정의 규칙 집합을 구성할 수 있습니다.

Pipeline Secret Detection의 모든 사용자를 대상으로 새로운 감지 규칙을 제안하려면 기본 규칙을 포함하는 파일에 대한 Merge Request을 만듭니다.

클라우드 또는 SaaS 제품을 운영하고 있고 GitLab과 파트너십을 맺어 사용자를 보다 잘 보호하고 싶은 경우, 저희의 누출된 자격 증명 알림을 위한 파트너 프로그램에 대해 자세히 알아보세요.

비밀 무시

일부 경우에는 비밀을 무시하려고 할 수 있습니다. 예를 들어 예제나 테스트 수트에 가짜 비밀이 있을 수 있습니다. 이러한 경우에는 해당 비밀을 신고하는 대신 무시하려고 할 수 있습니다.

비밀을 무시하려면 비밀이 포함된 줄에 주석으로 gitleaks:allow를 추가하십시오.

예를 들어:

 "A personal token for GitLab will look like glpat-JUST20LETTERSANDNUMB" #gitleaks:allow

특정 분석기 버전 고정

GitLab 관리형 CI/CD 템플릿은 주요 버전을 지정하고 해당 주요 버전 내에서 최신 분석기 릴리스를 자동으로 가져옵니다.

특정 버전을 사용해야 하는 경우가 있습니다. 예를 들어, 나중에 릴리스에서의 회귀를 피해야 하는 경우입니다.

자동 업데이트 동작을 재정의하려면, Secret-Detection.gitlab-ci.yml 템플릿을 포함한 후 CI/CD 구성 파일에서 SECRETS_ANALYZER_VERSION CI/CD 변수를 설정하십시오.

태그를 다음과 같이 설정할 수 있습니다:

4와 같은 주 버전: 이 경우 파이프라인은 이 주 버전 내에서 리릴리스된 모든 마이너나 패치 업데이트를 사용합니다.
4.5와 같은 마이너 버전: 이 경우 파이프라인은 이 마이너 버전 내에서 리릴리스된 모든 패치 업데이트를 사용합니다.
4.5.0와 같은 패치 버전: 이 경우 파이프라인은 어떠한 업데이트도 받지 않습니다.

다음 예시는 특정 마이너 버전의 분석기를 사용하는 방법을 보여줍니다:

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

secret_detection:
  variables:
    SECRETS_ANALYZER_VERSION: "4.5"

기본 구성 확장

다음은 Gitleaks의 extend 지원을 사용하여 기본 구성을 확장하는 방법을 보여줍니다.

다음 file 패스스루 예시에서, 문자열 glpat-1234567890abcdefghij는 Pipeline Secret Detection에서 무시됩니다. 해당 GitLab 개인 액세스 토큰 (PAT)은 테스트 케이스에서 사용됩니다. 이를 감지하는 것은 거짓 긍정일 것입니다.

secret-detection-ruleset.toml 파일은 extended-gitleaks-config.toml 파일을 포함하기로 정의합니다. extended-gitleaks-config.toml 파일은 사용자 지정 Gitleaks 구성을 정의합니다. allowlist 스탠자는 무시해야 하는 비밀을 정의하는 정규 표현식을 정의합니다.

### .gitlab/secret-detection-ruleset.toml
[secrets]
  description = 'secrets custom rules configuration'
  
  [[secrets.passthrough]]
    type  = "file"
    target = "gitleaks.toml"
    value = "extended-gitleaks-config.toml"

### extended-gitleaks-config.toml
title = "extension of gitlab's default gitleaks config"

[extend]
### Extends default packaged path
path = "/gitleaks.toml"

[allowlist]
  description = "allow list of test tokens to ignore in detection"
  regexTarget = "match"
  regexes = [
    '''glpat-1234567890abcdefghij''',
  ]

전체 히스토리 Pipeline Secret Detection 활성화

전체 히스토리 Pipeline Secret Detection을 활성화하려면 .gitlab-ci.yml 파일에서 SECRET_DETECTION_HISTORIC_SCAN 변수를 true로 설정하십시오.

Merge Request 파이프라인에서 작업 실행

Merge Request 파이프라인에서 보안 스캔 도구를 실행하는 방법에 대해서는 Merge Request 파이프라인에서 보안 스캔 도구 사용을 참조하십시오.

사용자 지정 규칙 집합

Tier: Ultimate

GitLab 13.5에서 도입.
GitLab 14.6에서 file, git, 및 url의 추가적인 passthrough 유형을 포함하여 지원이 확대됨.
GitLab 14.8에서 규칙 재정의를 지원함.

비밀이 GitLab UI에서보고되는 방식을 사용자 정의할 수 있습니다. 그러나 secret_detection 작업 로그에는 기본 Pipeline Secret Detection 규칙에 의해 감지된 비밀의 수가 항상 포함됩니다.

다음과 같은 사용자 지정 옵션들을 따로 또는 결합하여 사용할 수 있습니다 (원격 구성 파일을 사용할 때는 규칙을 비활성화하거나 재정의할 수 없습니다):

미리 정의된 규칙 비활성화.
미리 정의된 규칙 재정의.
사용자 지정 구성 합성.
원격 구성 파일 지정.

커스텀 구성 요약

기본 파이프라인 비밀 감지 규칙セット을 재정의하려면 패스스루(passthroughs)를 사용할 수 있습니다. secrets 분석기에서 지원하는 다음 패스스루 유형이 있습니다:

raw
file

패스스루를 정의하려면 다음 중 하나를 secret-detection-ruleset.toml 파일에 추가하세요:

인라인 (raw) 값 사용:

[secrets]
  description = '비밀 커스텀 규칙 구성'
    
  [[secrets.passthrough]]
    type  = "raw"
    target = "gitleaks.toml"
    value = """\
title = "gitleaks config"
### 정규식을 정규식 테이블에 추가
[[rules]]
description = "원시(Custom) 커스텀 규칙셋 테스트"
regex = '''원시 커스텀 규칙셋 T[est]{3}'''
"""

file 패스스루는 현재 리포지터리에 커밋된 외부 파일과만 작동합니다. 원격 구성 파일에서 커스텀 구성을 합성하는 데 사용할 수 없습니다.

현재 리포지터리에 커밋된 외부 file 사용:

[secrets]
  description = '비밀 커스텀 규칙 구성'
    
  [[secrets.passthrough]]
    type  = "file"
    target = "gitleaks.toml"
    value = "config/gitleaks.toml"

패스스루 구문에 대한 자세한 정보는 SAST 사용자 정의 규칙 페이지의 패스스루 섹션을 참조하세요.

원격 구성 파일 지정

프로젝트는 CI/CD 변수를 사용하여 현재 리포지터리 외부의 규칙셋 구성을 지정할 수 있습니다.

SECRET_DETECTION_RULESET_GIT_REFERENCE 변수는 URI, 선택적 인증 및 선택적 Git SHA를 지정하는 을 위한 SCP 스타일 구문을 사용합니다. 변수는 다음 형식을 사용합니다:

<AUTH_USER>:<AUTH_PASSWORD>@<PROJECT_PATH>@<GIT_SHA>

프로젝트 내의 로컬 .gitlab/secret-detection-ruleset.toml 파일이 SECRET_DETECTION_RULESET_GIT_REFERENCE보다 우선합니다.

다음 예는 프로젝트에 Pipeline Secret Detection 템플릿을 포함하고 별도 프로젝트 구성을 참조하기 위해 SECRET_DETECTION_RULESET_GIT_REFERENCE 변수를 지정하는 방법을 보여줍니다.

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

variables:
  SECRET_DETECTION_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"

원격 구성 구문에 대한 자세한 정보는 사용자 정의 규칙 페이지의 개인 원격 구성 파일 지정 예를 참조하세요.

분석기 작업 재정의

작업 정의를 재정의하려면(예: variables 또는 dependencies와 같은 속성 변경), 비밀 감지 작업과 동일한 이름의 작업을 선언하여 새 작업을 템플릿 포함 이후에 배치하고 추가 키를 지정하세요.

다음 .gitlab-ci.yml 파일의 예제는 다음을 보여줍니다:

파이프라인 비밀 감지 템플릿이 포함됨.
secret_detection 작업에서 CI/CD 변수 SECRET_DETECTION_HISTORIC_SCAN이 true로 설정됩니다. 템플릿은 파이프라인 구성 이전에 평가되므로 변수의 마지막 언급이 우선합니다.

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

secret_detection:
  variables:
    SECRET_DETECTION_HISTORIC_SCAN: "true"

미리 정의된 분석기 규칙 재정의

원격 규칙셋으로 규칙을 재정의할 수 있는 기능은 GitLab 16.0 및 이후 버전에서 활성화되었습니다.

특정 파이프라인 비밀 감지 규칙을 사용자 정의하려면 규칙을 재정의할 수 있습니다. 예를 들어, 특정 비밀의 심각도를 높일 수 있습니다.

규칙을 재정의하려면:

프로젝트의 루트에 .gitlab 디렉터리를 생성합니다(이미 있다면 제외).
.gitlab 디렉터리에 secret-detection-ruleset.toml이라는 사용자 정의 규칙 파일을 만듭니다(이미 있다면 제외).
하나 이상의 ruleset.identifier 하위 섹션에서 재정의할 규칙을 나열합니다. 모든 ruleset.identifier 섹션에는:
- 사전 정의된 규칙 식별자에 대한 type 필드.
- 규칙 이름에 대한 value 필드가 있습니다.
ruleset 섹션의 ruleset.override 컨텍스트에서 재정의할 키를 제공합니다. 키 조합은 재정의할 수 있습니다. 유효한 키는 다음과 같습니다:
- description
- message
- name
- severity (유효한 옵션: Critical, High, Medium, Low, Unknown, Info)

다음 예제 .gitlab 디렉터리의 secret-detection-ruleset.toml 파일에서 식별자 및 재정의 규칙을 일치시키고 재정의합니다:

[secrets]
  [[secrets.ruleset]]
    [secrets.ruleset.identifier]
      type = "gitleaks_rule_id"
      value = "RSA private key"
    [secrets.ruleset.override]
      description = "재정의된 설명"
      message = "재정의된 메시지"
      name = "재정의된 이름"
      severity = "Info"

미리 정의된 분석기 규칙 해제

원격 규칙셋으로 규칙을 비활성화할 수 있는 기능은 GitLab 16.0 및 이후 버전에서 활성화되었습니다.

활성화하지 않으려는 특정 파이프라인 비밀 감지 규칙이 있는 경우 비활성화할 수 있습니다.

분석기 규칙 비활성화:

프로젝트의 루트에 .gitlab 디렉터리를 생성합니다(이미 있다면 제외).
.gitlab 디렉터리에 secret-detection-ruleset.toml이라는 사용자 정의 규칙 파일을 만듭니다(이미 있다면 제외).
ruleset 섹션의 컨텍스트에서 disabled 플래그를 true로 설정합니다.
하나 이상의 ruleset.identifier 하위 섹션에서 비활성화할 규칙을 나열합니다. 모든 ruleset.identifier 섹션에는:
- 사전 정의된 규칙 식별자에 대한 type 필드.
- 규칙 이름에 대한 value 필드가 있습니다.

다음 예제 .gitlab 디렉터리의 secret-detection-ruleset.toml 파일에서 비활성화된 규칙을 할당합니다:

[secrets]
  [[secrets.ruleset]]
    disable = true
    [secrets.ruleset.identifier]
      type = "gitleaks_rule_id"
      value = "RSA private key"

사용 가능한 CI/CD 변수

파이프라인 비밀 감지는 다음과 같은 사용 가능한 CI/CD 변수를 정의하여 사용자 정의할 수 있습니다:

CI/CD 변수	기본값	설명
`SECRET_DETECTION_EXCLUDED_PATHS`	””	경로를 기반으로 출력에서 취약성을 제외합니다. 경로는 쉼표로 구분된 패턴 디렉터리입니다. 패턴은 와일드카드가 될 수 있습니다(지원하는 패턴은 `doublestar.Match`을 참조하세요) 또는 파일 또는 폴더 경로입니다(예: `doc,spec`). 상위 디렉터리도 패턴과 일치합니다. GitLab 13.3에서 도입되었습니다.
`SECRET_DETECTION_HISTORIC_SCAN`	false	과거의 Gitleaks 스캔을 활성화하는 플래그입니다.
`SECRET_DETECTION_IMAGE_SUFFIX`	””	이미지 이름에 추가되는 접미사입니다. `-fips`로 설정하면 스캔에 FIPS 활성화 이미지가 사용됩니다. 자세한 내용은 FIPS 활성화 이미지 사용를 참조하세요. GitLab 14.10에서 도입되었습니다.
`SECRET_DETECTION_LOG_OPTIONS`	””	커밋 범위를 정의하는 데 사용되는 `git log` 옵션입니다. GitLab 15.1에서 도입되었습니다.

이전 GitLab 버전에서 다음 변수도 사용할 수 있었습니다:

CI/CD 변수	기본값	설명
`SECRET_DETECTION_COMMIT_FROM`	-	Gitleaks 스캔을 시작하는 커밋입니다. GitLab 13.5에서 제거되었습니다. `SECRET_DETECTION_COMMITS`로 대체되었습니다.
`SECRET_DETECTION_COMMIT_TO`	-	Gitleaks 스캔을 끝내는 커밋입니다. GitLab 13.5에서 제거되었습니다. `SECRET_DETECTION_COMMITS`로 대체되었습니다.
`SECRET_DETECTION_COMMITS`	-	Gitleaks가 스캔해야하는 커밋 디렉터리입니다. GitLab 13.5에서 소멸되었습니다.

오프라인 구성

Tier: PREMIUM Offering: Self-Managed

오프라인 환경은 인터넷을 통해 외부 리소스에 제한적이거나 일시적으로 액세스할 수 있는 환경을 가지고 있습니다. 이와 같은 환경에서 Self-Managed형 GitLab 인스턴스의 경우, Pipeline Secret Detection을 위해 일부 구성 변경이 필요합니다. 이 섹션의 지침은 오프라인 환경의 지침과 함께 완료해아합니다.

GitLab 러너 구성

기본적으로 러너는 로컬 복사본이 있는 경우에도 GitLab 컨테이너 레지스트리에서 Docker 이미지를 가져오려고 시도합니다. Docker 이미지를 최신 상태로 유지하기 위해 이 기본 설정을 사용해야 합니다. 그러나 네트워크 연결이 없는 경우 기본 GitLab 러너 pull_policy 변수를 변경해야 합니다.

GitLab 러너 CI/CD 변수 pull_policy를 if-not-present로 구성하세요.

로컬 Pipeline Secret Detection 분석기 이미지 사용

GitLab 컨테이너 레지스트리 대신 로컬 Docker 레지스트리에서 이미지를 가져오려는 경우 로컬 Pipeline Secret Detection 분석기 이미지를 사용하세요.

전제 조건:

로컬 오프라인 Docker 레지스트리로 Docker 이미지를 가져오려면 네트워크 보안 정책에 따라 인가된 프로세스를 찾기 위해 IT 직원과 상의하세요.

registry.gitlab.com에서 기본 Pipeline Secret Detection 분석기 이미지를 로컬 Docker 컨테이너 레지스트리로 가져옵니다:
```
registry.gitlab.com/security-products/secrets:4
```
Pipeline Secret Detection 분석기 이미지는 정기적으로 업데이트되므로 주기적으로 로컬 복사본을 업데이트해아합니다.

CI/CD 변수 SECURE_ANALYZERS_PREFIX를 로컬 Docker 컨테이너 레지스트리로 설정하세요.

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml
   
variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

Pipeline Secret Detection 작업은 이제 인터넷 액세스 없이 로컬 복사본의 Secret Detection 분석기 Docker 이미지를 사용해아합니다.

사용자 정의 SSL CA 인증서 사용

사용자 정의 인증 기관을 신뢰하기 위해 ADDITIONAL_CA_CERT_BUNDLE 변수를 해당 인증서 번들로 설정하세요. 이는 .gitlab-ci.yml 파일, 파일 변수 또는 CI/CD 변수에서 수행할 수 있습니다.

.gitlab-ci.yml 파일을 사용하는 경우 ADDITIONAL_CA_CERT_BUNDLE 값은 X.509 PEM 공개 키 인증서의 텍스트 표현을 포함해야 합니다.

예:

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

파일 변수를 사용하는 경우 ADDITIONAL_CA_CERT_BUNDLE 값은 인증서의 경로여야 합니다.
변수를 사용하는 경우 ADDITIONAL_CA_CERT_BUNDLE 값을 인증서의 텍스트 표현으로 설정하세요.

FIPS 활성화 이미지

GitLab 14.10에서 도입됨.

기본 스캐너 이미지는 크기와 유지 관리를 위해 기본 Alpine 이미지에서 빌드됩니다. GitLab은 FIPS를 활성화한 Red Hat UBI 버전의 이미지를 제공합니다.

FIPS를 활성화한 이미지를 사용하려면 다음 중 하나를 수행하세요:

SECRET_DETECTION_IMAGE_SUFFIX CI/CD 변수를 -fips로 설정하세요.
기본 이미지 이름에 -fips 확장자를 추가하세요.

예를들면:

variables:
  SECRET_DETECTION_IMAGE_SUFFIX: '-fips'

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

문제 해결

디버그 수준 로깅

문제 해결 시 디버그 수준 로깅을 사용할 수 있습니다. 자세한 정보는 debug-level logging을 참조하세요.

경고: `gl-secret-detection-report.json: no matching files`

이에 대한 정보는 일반 애플리케이션 보안 문제 해결 섹션을 참조하세요.

오류: `Couldn't run the gitleaks command: exit status 2`

파이프라인 Secret Detection 분석기는 커밋 간의 패치를 생성하여 비밀을 스캔합니다. Merge Request의 커밋 수가 GIT_DEPTH CI/CD 변수의 값보다 큰 경우 Secret Detection은 비밀을 감지하지 못합니다.

예를들면, Merge Request에 60개의 커밋이 포함되어 있고 GIT_DEPTH 변수가 60보다 적게 설정된 경우, 파이프라인 Secret Detection 작업이 해당 클론에 모든 관련 커밋을 포함하지 않기 때문에 작업이 실패합니다. 현재 값을 확인하려면 파이프라인 구성을 참조하세요.

이러한 문제의 원인으로 확인하려면 debug-level logging을 활성화한 다음 파이프라인을 다시 실행하세요. 로그는 다음 예제와 유사해야 합니다. “object not found” 텍스트는 이러한 오류의 증상입니다.

ERRO[2020-11-18T18:05:52Z] object not found
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2

이 문제를 해결하려면 GIT_DEPTH CI/CD 변수를 더 높은 값으로 설정하세요. 이를 파이프라인 Secret Detection 작업에만 적용하려면 다음을 .gitlab-ci.yml 파일에 추가할 수 있습니다:

secret_detection:
  variables:
    GIT_DEPTH: 100

오류: `ERR fatal: ambiguous argument`

파이프라인 Secret Detection이 실행된 브랜치와 관련 있는 것이 아닌 리포지터리의 기본 브랜치와 관련된 경우 ERR fatal: ambiguous argument 오류로 작업에 실패할 수 있습니다. 자세한 내용은 !352014을 참조하세요.

이 문제를 해결하려면 리포지터리의 기본 브랜치를 설정하여 작업 중인 브랜치와 관련된 히스토리가 있는 브랜치로 설정하세요.

작업 로그에 `exec /bin/sh: exec format error` 메시지

GitLab 파이프라인 Secret Detection 분석기는 amd64 CPU 아키텍처에서만 지원합니다. 이 메시지는 작업이 arm과 같은 다른 아키텍처에서 실행되고 있는 것을 나타냅니다.

경고

유출된 비밀에 응답

비밀이 감지되면 즉시 회전해아합니다. GitLab은 일부 유출된 비밀을 자동으로 폐기하려고 시도합니다. 자동으로 폐기되지 않은 경우 매뉴얼으로 폐기해아합니다.

리포지터리 히스토리에서 비밀을 제거하는 것만으로는 유출된 비밀을 완전히 해결하지 못합니다. 원본 비밀은 리포지터리의 기존 포크나 복제에 계속 유지됩니다.

텍스트 콘텐츠의 잠재적인 누출에 대한 경고

GitLab 15.11에서 도입되었습니다.
개인 액세스 토큰의 사용자 지정 접두사가 포함된 감지는 GitLab 16.1에서 도입되었습니다. GitLab Self-Managed 전용입니다.

이슈를 생성하거나 Merge Request을 제안하거나 코멘트를 작성할 때 실수로 민감한 값이 게시될 수 있습니다. 예를 들어 API 요청의 세부 정보나 인증 토큰을 포함하는 환경 변수를 붙여 넣을 수 있습니다.

GitLab은 이슈 설명, Merge Request 설명, 코멘트 또는 답글의 텍스트에 민감한 토큰이 포함되어 있는지 확인합니다. 토큰이 발견되면 경고 메시지가 표시됩니다. 그런 다음 메시지를 게시하기 전에 편집할 수 있습니다. 이 확인은 메시지가 서버로 전송되기 전에 브라우저에서 수행됩니다. 이 확인은 항상 활성화되어 있으며 설정할 필요가 없습니다.

귀하의 텍스트는 다음 비밀 유형에 대해 확인됩니다:

GitLab 개인 액세스 토큰
- 개인 액세스 토큰 접두어가 구성되어 있으면 해당 접두어를 사용하는 토큰이 확인됩니다.
GitLab 피드 토큰

이 기능은 파이프라인 비밀 감지 검사와 별도이며, 이는 깃 리포지터리에서 누출된 비밀을 확인합니다. 이슈 405147에서 이 두 유형의 보호를 준비하는 노력이 추적됩니다.

파이프라인 비밀 감지

감지된 비밀

커버리지

완전한 이력 파이프라인 비밀 감지

고급 취약점 추적

지원되지 않는 워크플로

구성

요구 사항

Analyzer 활성화

.gitlab-ci.yml 파일 매뉴얼으로 편집

자동으로 구성된 Merge Request 사용

Analyzer 설정 사용자 정의화

새로운 패턴 추가

비밀 무시

특정 분석기 버전 고정

기본 구성 확장

전체 히스토리 Pipeline Secret Detection 활성화

Merge Request 파이프라인에서 작업 실행

사용자 지정 규칙 집합

커스텀 구성 요약

원격 구성 파일 지정

분석기 작업 재정의

미리 정의된 분석기 규칙 재정의

미리 정의된 분석기 규칙 해제

사용 가능한 CI/CD 변수

오프라인 구성

GitLab 러너 구성

로컬 Pipeline Secret Detection 분석기 이미지 사용

사용자 정의 SSL CA 인증서 사용

FIPS 활성화 이미지

문제 해결

디버그 수준 로깅

경고: gl-secret-detection-report.json: no matching files

오류: Couldn't run the gitleaks command: exit status 2

오류: ERR fatal: ambiguous argument

작업 로그에 exec /bin/sh: exec format error 메시지

경고

유출된 비밀에 응답

텍스트 콘텐츠의 잠재적인 누출에 대한 경고

도움말

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

도움받기

`.gitlab-ci.yml` 파일 매뉴얼으로 편집

경고: `gl-secret-detection-report.json: no matching files`

오류: `Couldn't run the gitleaks command: exit status 2`

오류: `ERR fatal: ambiguous argument`

작업 로그에 `exec /bin/sh: exec format error` 메시지