탐지된 비밀
범위
전체 이력 파이프라인 비밀 탐지
고급 취약성 추적
- 지원되지 않는 워크플로우
출력
구성
FIPS 지원 이미지
문제 해결
- 디버그 수준 로깅
경고
- 유출된 비밀에 대응하기

파이프라인 비밀 탐지

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

파이프라인 비밀 탐지는 Git 리포지토리에 커밋되고 GitLab에 푸시된 파일을 스캔합니다.

파이프라인 비밀 탐지 기능을 활성화 한 후, secret_detection이라는 CI/CD 작업에서 스캔이 실행됩니다.

모든 GitLab 티어에서 스캔을 실행하고 파이프라인 비밀 탐지 JSON 보고서 아티팩트를 볼 수 있습니다.

GitLab Ultimate에서는 파이프라인 비밀 탐지 결과가 추가로 처리되어 다음과 같은 작업을 수행할 수 있습니다:

병합 요청 위젯, 파이프라인 보안 보고서, 취약점 보고서 UI에서 확인합니다.
승인 워크플로에서 사용합니다.
보안 대시보드에서 검토합니다.
공개 리포지토리의 유출에 자동으로 응답합니다.
보안 정책을 사용하여 프로젝트 전반에 걸쳐 일관된 비밀 탐지 규칙을 시행합니다.

이 파이프라인 비밀 탐지 문서의 대화형 읽기 및 시연을 보려면:

다른 대화형 읽기 및 시연을 보려면 GitLab 애플리케이션 보안 시작하기 재생목록를 참조하세요.

탐지된 비밀

GitLab은 파이프라인 비밀 탐지에 사용되는 탐지 규칙을 유지 관리합니다. 기본 규칙 세트에는 100개 이상의 패턴이 포함되어 있습니다.

대부분의 파이프라인 비밀 탐지 패턴은 특정 유형의 비밀을 검색합니다.

많은 서비스가 유출되는 경우 식별할 수 있도록 비밀에 접두사나 기타 구조적 세부정보를 추가합니다.
예를 들어, GitLab은 프로젝트, 그룹 및 개인 액세스 토큰에 기본적으로 glpat- 접두사를 추가합니다.

보다 신뢰할 수 있는 높은 확신의 결과를 제공하기 위해, 파이프라인 비밀 탐지는 URL과 같은 특정 문맥에서만 비밀번호나 기타 비구조적 비밀을 찾습니다.

탐지된 비밀은 스캔된 파일에서 비밀이 제거된 후에도 “여전히 감지됨”으로 취약점 보고서에 남아 있습니다.
이는 비밀이 Git 리포지토리의 히스토리에 남아 있기 때문입니다.
탐지된 비밀을 해결하려면 유출을 수정한 후 취약점을 분류해야 합니다.

범위

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

역사적 스캔

SECRET_DETECTION_HISTORIC_SCAN 변수가 설정된 경우, 모든 브랜치의 내용이 스캔됩니다.
리포지토리 내용을 스캔하기에 앞서, 파이프라인 비밀 탐지는 git fetch --all 명령을 실행하여 모든 브랜치의 내용을 가져옵니다.
커밋 범위

SECRET_DETECTION_LOG_OPTIONS 변수가 설정된 경우, 비밀 분석기는 파이프라인이 실행되고 있는 브랜치 또는 참조의 전체 히스토리를 가져옵니다.
그 후 파이프라인 비밀 탐지가 실행되며 지정된 커밋 범위를 스캔합니다.
기본 브랜치

기본 브랜치에서 파이프라인 비밀 탐지가 실행될 때, Git 리포지토리는 일반 폴더로 취급됩니다.
현재 HEAD의 리포지토리 내용만 스캔됩니다. 커밋 히스토리는 스캔되지 않습니다.
푸시 이벤트

푸시 이벤트가 발생하면, 파이프라인 비밀 탐지는 사용할 수 있는 정보에 따라 스캔할 커밋 범위를 결정합니다.
커밋 범위를 결정하기 위해, CI_COMMIT_SHA와 CI_COMMIT_BEFORE_SHA 변수가 중요합니다.
- CI_COMMIT_SHA는 특정 브랜치의 HEAD에 해당하는 커밋입니다.
  이 변수는 푸시 이벤트에 대해 항상 설정됩니다.
- CI_COMMIT_BEFORE_SHA는 대부분의 경우 설정됩니다.
  그러나 새로운 브랜치에 대한 첫 번째 푸시 이벤트나 병합 파이프라인에서는 설정되지 않습니다.
  이로 인해 여러 커밋이 새로운 브랜치에 커밋될 때 파이프라인 비밀 탐지를 보장할 수 없습니다.
병합 요청

병합 요청에서 파이프라인 비밀 탐지는 소스 브랜치에서 수행된 모든 커밋을 스캔합니다.
이 기능을 사용하려면 latest 파이프라인 비밀 탐지 템플릿을 사용해야 합니다.
이는 병합 요청 파이프라인을 지원합니다.
파이프라인 비밀 탐지의 결과는 파이프라인이 완료된 후에만 제공됩니다.

전체 이력 파이프라인 비밀 탐지

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

전체 이력 스캔은 파이프라인 비밀 탐지를 활성화한 후 한 번만 수행해야 합니다. 전체 이력 스캔은 특히 긴 Git 이력을 가진 대규모 저장소의 경우 오랜 시간이 걸릴 수 있습니다. 초기 전체 이력 스캔이 완료된 후에는 파이프라인의 일환으로 표준 파이프라인 비밀 탐지만 사용하세요.

고급 취약성 추적

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

도입됨 GitLab 17.0에.

개발자가 식별된 비밀이 있는 파일을 변경하면, 이러한 비밀의 위치도 바뀔 가능성이 높습니다. 파이프라인 비밀 탐지는 이미 이러한 비밀을 취약점으로 플래그했을 수 있으며, 이는 취약성 보고서에서 추적됩니다. 이러한 취약점은 식별 및 조치가 용이하도록 특정 비밀과 관련이 있습니다. 그러나 탐지된 비밀이 이동하면서 정확하게 추적되지 않으면, 취약성 관리가 어려워지고, 중복된 취약성 보고서가 발생할 수 있습니다.

파이프라인 비밀 탐지는 동일한 비밀이 리팩토링이나 관련 없는 변경으로 인해 파일 내에서 이동했을 때 보다 정확하게 식별하기 위해 고급 취약성 추적 알고리즘을 사용합니다.

자세한 내용은 기밀 프로젝트 https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator를 참조하세요. 이 프로젝트의 콘텐츠는 GitLab 팀원에게만 제공됩니다.

지원되지 않는 워크플로우

알고리즘은 기존 발견 사항에 추적 서명이 없고 새로 탐지된 발견 사항과 동일한 위치를 공유하지 않는 워크플로우를 지원하지 않습니다.
암호화 키와 같은 일부 규칙 유형의 경우, 파이프라인 비밀 탐지는 전체 비밀 값이 아닌 비밀의 접두사를 일치시켜 유출을 식별합니다. 이 경우 알고리즘은 파일 내에서 동일한 규칙 유형의 서로 다른 비밀을 하나의 발견으로 통합하며, 각 개별 비밀을 별도의 발견으로 취급하지 않습니다. 예를 들어, SSH 개인 키 규칙 유형은 SSH 개인 키의 존재를 확인하기 위해 값의 -----BEGIN OPENSSH PRIVATE KEY----- 접두사만 일치시킵니다. 동일한 파일 내에 두 개의 서로 다른 SSH 개인 키가 있는 경우, 알고리즘은 두 값을 동일하다고 간주하고 두 개가 아닌 하나의 발견만 보고합니다.
알고리즘의 범위는 파일 단위로 제한되며, 두 개의 서로 다른 파일에서 동일한 비밀이 나타나는 경우 두 개의 별도 발견 사항으로 취급됩니다.

출력

파이프라인 비밀 탐지는 파일 gl-secret-detection-report.json을 작업 아티팩트로 출력합니다. 이 파일에는 탐지된 비밀이 포함되어 있습니다. 파일을 다운로드하여 GitLab 외부에서 처리할 수 있습니다.

자세한 내용은 다음을 참조하세요:

구성

요구 사항

필수 조건:

docker 또는 kubernetes 실행기가 있는 Linux 기반 GitLab Runner. GitLab.com의 공유 러너를 사용하는 경우 기본적으로 활성화되어 있습니다.
- Windows 러너는 지원되지 않습니다.
- amd64 이외의 CPU 아키텍처는 지원되지 않습니다.
GitLab CI/CD 구성(.gitlab-ci.yml)에는 test 단계가 포함되어야 합니다.

다양한 기능은 서로 다른 GitLab 티어에서 사용할 수 있습니다.

기능	Free & Premium	Ultimate
분석기 활성화	예	예
분석기 설정 사용자 지정	예	예
출력 다운로드	예	예
병합 요청 위젯에서 새로운 발견 보기	아니오	예
파이프라인의 보안 탭에서 식별된 비밀 보기	아니오	예
취약성 관리	아니오	예
보안 대시보드 접근	아니오	예
분석기 규칙 집합 사용자 지정	아니오	예
보안 정책 활성화	아니오	예

분석기 활성화

파이프라인 비밀 감지를 활성화하려면 다음 중 하나를 선택합니다:

Auto DevOps를 활성화합니다. 여기에는 자동 비밀 감지가 포함됩니다.
.gitlab-ci.yml 파일을 수동으로 편집합니다. .gitlab-ci.yml 파일이 복잡한 경우 이 방법을 사용하세요.
자동으로 구성된 병합 요청 사용합니다.

`.gitlab-ci.yml` 파일을 수동으로 편집

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

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

이제 파이프라인에 비밀 감지 작업이 포함됩니다.

자동으로 구성된 병합 요청 사용

GitLab 13.11에서 도입되었으며, 기능 플래그 뒤에서 배포되고 기본값으로 활성화됩니다.

GitLab 14.1에서 기능 플래그가 제거되었습니다.

이 방법은 .gitlab-ci.yml 파일에 파이프라인 비밀 감지 템플릿이 포함된 병합 요청을 자동으로 준비합니다. 그런 다음 병합 요청을 병합하여 파이프라인 비밀 감지를 활성화합니다.

참고: 이 방법은 기존의 .gitlab-ci.yml 파일이 없거나 최소한의 구성 파일이 있을 때 가장 잘 작동합니다. 복잡한 GitLab 구성 파일이 있는 경우 성공적으로 구문 분석되지 않을 수 있으며 오류가 발생할 수 있습니다. 그런 경우 수동 방법을 대신 사용하세요.

파이프라인 비밀 감지를 활성화하려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
보안 > 보안 구성을 선택합니다.
파이프라인 비밀 감지 행에서 병합 요청으로 구성을 선택합니다.
선택 사항입니다. 필드를 완료합니다.
병합 요청 만들기를 선택합니다.
병합 요청을 검토하고 병합합니다.

이제 파이프라인에 비밀 감지 작업이 포함됩니다.

분석기 설정 사용자 정의

파이프라인 비밀 감지 스캔 설정은 .gitlab-ci.yml의 variables 매개변수를 사용하여 CI/CD 변수를 통해 변경할 수 있습니다.

경고: GitLab 보안 스캐닝 도구의 모든 구성은 기본 브랜치에 이러한 변경 사항을 병합하기 전에 병합 요청에서 테스트해야 합니다. 그렇지 않으면 많은 허위 긍정 결과가 포함된 예기치 않은 결과가 발생할 수 있습니다.

새로운 패턴 추가

구성 요소에서 다른 유형의 비밀을 검색하려면 분석기 규칙 집합을 사용자 정의할 수 있습니다.

모든 파이프라인 비밀 감지 사용자에 대해 새로운 감지 규칙을 제안하려면 기본 규칙이 포함된 파일에 대한 병합 요청을 생성하세요.

클라우드 또는 SaaS 제품을 운영하고 있고 사용자를 더 잘 보호하기 위해 GitLab과 협력하고 싶다면, 유출된 인증 정보 알림을 위한 파트너 프로그램에 대해 자세히 알아보세요.

특정 분석기 버전에 고정

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"

전체 기록 스캔 활성화

전체 기록 스캔을 활성화하려면, .gitlab-ci.yml 파일에서 SECRET_DETECTION_HISTORIC_SCAN 변수를 true로 설정합니다.

병합 요청 파이프라인에서 작업 실행

병합 요청 파이프라인에서 보안 스캔 도구 사용하기를 참조하세요.

분석기 작업 무시

작업 정의를 무시하려면 (변수 또는 종속성과 같은 속성을 변경하는 예) secret_detection 작업과 동일한 이름으로 작업을 선언하여 무시합니다. 이 새로운 작업은 템플릿 포함 이후에 배치하고 그 아래에 추가 키를 지정합니다.

다음은 .gitlab-ci.yml 파일의 추출 예제입니다:

Jobs/Secret-Detection CI 템플릿이 포함됨.
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"

분석기 규칙 집합 사용자 정의

Tier: Ultimate

GitLab 13.5에서 도입됨.

GitLab 14.6에서 file 및 raw의 추가 패스스루 유형을 포함하도록 확장됨.

GitLab 14.8에서 규칙 무시 지원이 활성화됨.

GitLab 17.2에서 패스스루 체인 지원이 활성화됨 및 추가 패스스루 유형으로 git 및 url 포함됨.

파이프라인 비밀 탐지의 동작을 사용자 정의하려면 규칙 집합 구성 파일 만들기를 통해, 스캔 중인 리포지토리 또는 원격 리포지토리에서 작업할 수 있습니다. 사용자 정의를 통해 기본 규칙 집합을 수정, 교체 또는 확장할 수 있습니다.

여러 가지 사용자 정의가 가능합니다:

기본 규칙 집합에서 미리 정의된 규칙의 동작 수정. 여기에는 다음이 포함됩니다:
패스스루를 사용하여 기본 규칙 집합을 사용자 정의 규칙 집합으로 교체합니다. 여기에는 다음이 포함됩니다:
패스스루를 사용하여 기본 규칙 집합의 동작을 확장합니다. 여기에는 다음이 포함됩니다:
- 로컬 규칙 집합에서 구성 사용.
- 원격 규칙 집합에서 구성 사용.
Gitleaks 기본 기능을 사용하여 비밀 및 경로 무시. 여기에는 다음이 포함됩니다:
- Gitleaks' [allowlist] 지시문을 사용하여 패턴 및 경로 무시.
- gitleaks:allow 주석을 사용하여 인라인 비밀 무시.

규칙 집합 구성 파일 생성

규칙 집합 구성 파일을 생성하려면:

프로젝트의 루트에 .gitlab 디렉토리를 만듭니다. 이미 존재하지 않는 경우에만 생성합니다.
.gitlab 디렉토리에 secret-detection-ruleset.toml이라는 이름의 파일을 생성합니다.

기본 규칙 집합의 규칙 수정

기본 제공된 기본 규칙 집합의 규칙을 수정할 수 있습니다.

규칙을 수정하면 기존 워크플로 또는 도구에 파이프라인 비밀 감지를 조정하는 데 도움이 될 수 있습니다. 예를 들어 감지된 비밀의 심각도를 오버라이드하거나 규칙이 전혀 감지되지 않도록 비활성화할 수 있습니다.

또한 원격(즉, 원격 Git 리포지토리나 웹사이트)에 저장된 규칙 집합 구성 파일을 사용하여 미리 정의된 규칙을 수정할 수 있습니다.

규칙 비활성화

원격 규칙 집합으로 규칙을 비활성화하는 기능이 활성화되었습니다 GitLab 16.0 이상에서.

활성화하지 않으려는 규칙을 비활성화할 수 있습니다. 분석기 기본 규칙 집합에서 규칙을 비활성화하려면:

규칙 집합 구성 파일을 생성하십시오, 이미 존재하지 않는 경우에 한하여.
ruleset 섹션의 컨텍스트에서 disabled 플래그를 true로 설정합니다.
하나 이상의 ruleset.identifier 하위 섹션에 비활성화할 규칙을 나열합니다. 모든 ruleset.identifier 섹션에는:
- 미리 정의된 규칙 식별자를 위한 type 필드.
- 규칙 이름을 위한 value 필드.

다음의 secret-detection-ruleset.toml 파일 예제에서 비활성화된 규칙은 식별자의 type과 value로 일치합니다:

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

규칙 오버라이드

원격 규칙 집합으로 규칙을 오버라이드하는 기능이 활성화되었습니다 GitLab 16.0 이상에서.

특정 규칙을 사용자 정의하려는 경우 이를 오버라이드할 수 있습니다. 예를 들어, 특정 유형의 비밀이 유출되는 경우 워크플로에 미치는 영향이 더 크기 때문에 그 심각도를 높일 수 있습니다.

분석기 기본 규칙 집합에서 규칙을 오버라이드하려면:

규칙 집합 구성 파일을 생성하십시오, 이미 존재하지 않는 경우에 한하여.
하나 이상의 ruleset.identifier 하위 섹션에 오버라이드할 규칙을 나열합니다. 모든 ruleset.identifier 섹션에는:
- 미리 정의된 규칙 식별자를 위한 type 필드.
- 규칙 이름을 위한 value 필드.
ruleset 섹션의 ruleset.override 컨텍스트에서 오버라이드할 키를 제공합니다. 어떤 조합의 키도 오버라이드할 수 있습니다. 유효한 키는:
- description
- message
- name
- severity (유효한 옵션은: Critical, High, Medium, Low, Unknown, Info)

다음의 secret-detection-ruleset.toml 파일에서 규칙은 식별자의 type과 value로 일치한 다음 오버라이드됩니다:

[secrets]
  [[secrets.ruleset]]
    [secrets.ruleset.identifier]
      type  = "gitleaks_rule_id"
      value = "RSA private key"
    [secrets.ruleset.override]
      description = "OVERRIDDEN description"
      message     = "OVERRIDDEN message"
      name        = "OVERRIDDEN name"
      severity    = "Info"

원격 규칙 세트 사용하기

A 원격 규칙 세트는 현재 저장소 외부에 저장된 구성 파일입니다. 이를 통해 여러 프로젝트에서 규칙을 수정할 수 있습니다.

원격 규칙 세트를 사용하여 미리 정의된 규칙을 수정하려면 SECRET_DETECTION_RULESET_GIT_REFERENCE CI/CD 변수를 사용할 수 있습니다:

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

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

파이프라인 비밀 탐지는 CI 변수가 참조하는 저장소의 .gitlab/secret-detection-ruleset.toml 파일에 구성 내용이 정의되어 있다고 가정합니다. 해당 파일이 존재하지 않으면, 반드시 하나를 생성하고 위에서 설명한 대로 미리 정의된 규칙을 재정의 하거나 비활성화 하는 단계를 따라야 합니다.

참고: 로컬 .gitlab/secret-detection-ruleset.toml 파일은 기본적으로 SECRET_DETECTION_RULESET_GIT_REFERENCE보다 우선 적용됩니다. 이는 SECURE_ENABLE_LOCAL_CONFIGURATION이 true로 설정되어 있기 때문입니다.

SECURE_ENABLE_LOCAL_CONFIGURATION을 false로 설정하면, 로컬 파일은 무시되고 기본 구성이나 설정된 SECRET_DETECTION_RULESET_GIT_REFERENCE가 사용됩니다.

SECRET_DETECTION_RULESET_GIT_REFERENCE 변수는 URI, 선택적 인증 및 선택적 Git SHA를 지정하는 데 Git URL과 유사한 형식을 사용합니다. 변수 형식은 다음과 같습니다:

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

구성 파일이 인증이 필요한 비공개 프로젝트에 저장된 경우, Group Access Token을 사용하여 원격 규칙 세트를 안전하게 로드할 수 있습니다:

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

variables:
  SECRET_DETECTION_RULESET_GIT_REFERENCE: "group_2504721_bot_7c9311ffb83f2850e794d478ccee36f5:$GROUP_ACCESS_TOKEN@gitlab.com/example-group/remote-ruleset-project"

그룹 접근 토큰은 read_repository 범위를 가지고 최소한 Reporter 역할을 가져야 합니다. 자세한 내용은 레포지토리 권한을 참조하십시오.

그룹 접근 토큰과 연결된 사용자 이름을 찾는 방법은 그룹의 봇 사용자를 참조하십시오.

기본 규칙 세트 교체하기

다양한 사용자 정의를 사용하여 기본 규칙 세트 구성을 교체할 수 있습니다. 이러한 사용자 정의는 패스스루를 사용하여 단일 구성으로 결합할 수 있습니다.

패스스루를 사용하여 다음을 수행할 수 있습니다:

미리 정의된 규칙을 교체하거나 확장하기 위해 최대 20개의 패스스루를 단일 구성을 연결합니다.
패스스루에 환경 변수를 포함시킵니다.
패스스루 평가에 대한 타임아웃을 설정합니다.
각 정의된 패스스루에서 사용된 TOML 구문을 검증합니다.

인라인 규칙 집합 사용하기

raw passthrough를 사용하여 기본 규칙 집합을 인라인으로 제공된 구성으로 대체할 수 있습니다.

이를 위해, 동일한 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음 내용을 추가하고, [[rules]] 아래 정의된 규칙을 적절하게 조정하세요:

[secrets]
  [[secrets.passthrough]]
    type   = "raw"
    target = "gitleaks.toml"
    value  = """
title = "replace default ruleset with a raw passthrough"

[[rules]]
description = "Test for Raw Custom Rulesets"
regex = '''Custom Raw Ruleset T[est]{3}'''
"""

위의 예제는 기본 규칙 집합을 Custom Raw Ruleset T로 시작하고, 문자열의 끝에서 e, s, t 중 하나의 문자로 3자를 포함하는 정규식을 확인하는 규칙으로 대체합니다.

사용할 passthrough 구문에 대한 자세한 내용은 Schema를 참조하세요.

로컬 규칙 집합 사용하기

file passthrough를 사용하여 기본 규칙 집합을 현재 리포지토리에 커밋된 다른 파일로 대체할 수 있습니다.

이를 위해, 동일한 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음 내용을 추가하고, 로컬 규칙 집합 구성 파일의 경로를 가리키도록 value를 적절히 조정하세요:

[secrets]
  [[secrets.passthrough]]
    type   = "file"
    target = "gitleaks.toml"
    value  = "config/gitleaks.toml"

이렇게 하면 기본 규칙 집합이 config/gitleaks.toml 파일에 정의된 구성으로 대체됩니다.

사용할 passthrough 구문에 대한 자세한 내용은 Schema를 참조하세요.

원격 규칙 집합 사용하기

기본 규칙 집합을 원격 Git 리포지토리에서 정의된 구성이나 온라인에 저장된 파일로 대체할 수 있습니다. 이때 각각 git 및 url passthrough를 사용합니다.

원격 규칙 집합은 여러 프로젝트에서 사용할 수 있습니다. 예를 들어, 하나의 네임스페이스 내의 여러 프로젝트에 동일한 규칙 집합을 적용할 수 있으며, 이 경우 두 가지 passthrough 중 하나를 사용하여 원격 규칙 집합을 불러오고 여러 프로젝트에서 사용할 수 있습니다. 이를 통해 규칙 집합을 중앙에서 관리할 수 있으며, 권한이 있는 사람만 편집할 수 있습니다.

git passthrough를 사용하려면, 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음 내용을 추가하고, value를 Git 리포지토리의 주소를 가리키도록 조정하세요:

# .gitlab/secret-detection-ruleset.toml in https://gitlab.com/user_group/basic_repository
[secrets]
  [[secrets.passthrough]]
    type   = "git"
    ref    = "main"
    subdir = "config"
    value  = "https://gitlab.com/user_group/central_repository_with_shared_ruleset"

이 구성에서 분석기는 user_group/central_repository_with_shared_ruleset 리포지토리의 main 브랜치 내 config 디렉토리에 있는 gitleaks.toml 파일에서 규칙 집합을 불러옵니다. 그러면 user_group/basic_repository 이외의 프로젝트에서도 동일한 구성을 포함할 수 있습니다.

또는, 기본 규칙 집합을 원격 규칙 집합 구성으로 대체하기 위해 url passthrough를 사용할 수 있습니다.

url passthrough를 사용하려면, 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음 내용을 추가하고, value를 원격 파일의 주소를 가리키도록 조정하세요:

# .gitlab/secret-detection-ruleset.toml in https://gitlab.com/user_group/basic_repository
[secrets]
  [[secrets.passthrough]]
    type   = "url"
    target = "gitleaks.toml"
    value  = "https://example.com/gitleaks.toml"

이 구성에서 분석기는 제공된 주소에 저장된 gitleaks.toml 파일에서 규칙 집합 구성을 불러옵니다.

사용할 passthrough 구문에 대한 자세한 내용은 Schema를 참조하세요.

비공식 원격 규칙 세트 사용

규칙 세트 구성파일이 개인 저장소에 저장되어 있는 경우, auth 설정을 사용하여 저장소에 접근할 수 있는 자격 증명을 제공해야 합니다.

참고:

auth 설정은 git 패스스루와만 작동합니다.

개인 저장소에 저장된 원격 규칙 세트를 사용하려면, 다음 내용을 저장소에 저장된 .gitlab/secret-detection-ruleset.toml 구성파일에 추가하고, value를 Git 저장소의 주소를 가리키도록 조정한 다음, 적절한 자격 증명을 사용하여 auth를 업데이트합니다:

[secrets]
  [[secrets.passthrough]]
    type   = "git"
    ref    = "main"
    auth   = "USERNAME:PASSWORD" # USERNAME 및 PASSWORD를 적절히 바꾸세요.
    subdir = "config"
    value  = "https://gitlab.com/user_group/central_repository_with_shared_ruleset"

경고:

이 기능을 사용할 때 자격 증명이 유출되지 않도록 주의하세요. 환경 변수를 사용하여 위험을 최소화하는 방법에 대한 예시를 보려면 이 섹션을 확인하세요.

사용할 패스스루 구문에 대한 자세한 내용은 Schema를 참조하세요.

기본 규칙 세트 확장

필요에 따라 추가 규칙으로 기본 규칙 세트 구성을 확장할 수도 있습니다. 이는 기본 규칙 세트에서 GitLab이 유지 관리하는 높은 신뢰도의 미리 정의된 규칙의 이점을 여전히 주장하면서, 자신의 프로젝트 및 네임스페이스에서 사용할 수 있는 비밀 유형에 대한 규칙을 추가하고 싶을 때 유용할 수 있습니다.

로컬 규칙 세트 사용

기본 규칙 세트를 확장하여 추가 규칙을 추가하기 위해 file 패스스루를 사용할 수 있습니다.

다음 내용을 같은 저장소에 저장된 .gitlab/secret-detection-ruleset.toml 구성파일에 추가하고, 적절히 value를 확장된 구성 파일의 경로를 가리키도록 조정합니다:

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

extended-gitleaks-config.toml에 저장된 확장 구성은 CI/CD 파이프라인의 분석기에 의해 사용되는 구성에 포함됩니다.

다음 예시에서는 감지할 정규 표현식을 정의하는 여러 개의 새로운 [[rules]] 섹션을 추가합니다:

# extended-gitleaks-config.toml
[extend]
# 기본 패키지 규칙 세트를 확장합니다. 주의: 경로를 변경하지 마세요.
path = "/gitleaks.toml"

[[rules]]
  description = "예시 서비스 API 키"
  regex = '''example_api_key'''

[[rules]]
  description = "예시 서비스 API 비밀"
  regex = '''example_api_secret'''

이 규칙 세트 구성으로 분석기는 정의된 두 개의 정규 표현식 패턴과 일치하는 문자열을 감지합니다.

사용할 패스스루 구문에 대한 자세한 내용은 Schema를 참조하세요.

원격 규칙 세트 사용

기본 규칙 세트를 원격 규칙 세트로 교체하는 방법과 유사하게, .gitlab/secret-detection-ruleset.toml 구성 파일이 저장된 저장소 외부에 저장된 원격 Git 저장소 또는 파일로 기본 규칙 세트를 확장할 수도 있습니다.

이것은 이전에 논의된 git 또는 url 패스스루를 사용하여 달성할 수 있습니다.

git 패스스루를 사용하여 이를 수행하려면, 같은 저장소에 저장된 .gitlab/secret-detection-ruleset.toml 구성파일에 다음을 추가하고, value, ref, 및 subdir을 적절히 조정하여 확장된 구성 파일의 경로를 가리키도록 합니다:

# .gitlab/secret-detection-ruleset.toml in https://gitlab.com/user_group/basic_repository
[secrets]
  [[secrets.passthrough]]
    type   = "git"
    ref    = "main"
    subdir = "config"
    value  = "https://gitlab.com/user_group/central_repository_with_shared_ruleset"

파이프라인 비밀 탐지는 원격 규칙 세트 구성 파일이 gitleaks.toml이라고 가정하고, 참조된 저장소의 main 브랜치에 있는 config 디렉토리에 저장되어 있다고 가정합니다.

기본 규칙 세트를 확장하기 위해 gitleaks.toml 파일은 위의 예시와 유사한 [extend] 지시문을 사용해야 합니다:

# https://gitlab.com/user_group/central_repository_with_shared_ruleset/-/raw/main/config/gitleaks.toml
[extend]
# 기본 패키지 규칙 세트를 확장합니다. 주의: 경로를 변경하지 마세요.
path = "/gitleaks.toml"

[[rules]]
  description = "예시 서비스 API 키"
  regex = '''example_api_key'''

[[rules]]
  description = "예시 서비스 API 비밀"
  regex = '''example_api_secret'''

url 패스스루를 사용하려면, 같은 저장소에 저장된 .gitlab/secret-detection-ruleset.toml 구성파일에 다음을 추가하고, 확장된 구성 파일의 경로를 가리키도록 적절히 value를 조정합니다:

# .gitlab/secret-detection-ruleset.toml in https://gitlab.com/user_group/basic_repository
[secrets]
  [[secrets.passthrough]]
    type   = "url"
    target = "gitleaks.toml"
    value  = "https://example.com/gitleaks.toml"

사용할 패스스루 구문에 대한 자세한 내용은 Schema를 참조하세요.

패턴 및 경로 무시

파이프라인 비밀 탐지에서 특정 패턴이나 경로를 무시해야 하는 상황이 발생할 수 있습니다. 예를 들어, 테스트 스위트에서 사용하기 위해 가짜 비밀이 포함된 파일이 있을 수 있습니다.

이 경우, 특정 패턴이나 경로를 무시하기 위해 Gitleaks의 네이티브 [allowlist] 지시어를 활용할 수 있습니다.

이 기능은 로컬 또는 원격 규칙 집합 구성 파일을 사용 여부와 관계없이 작동합니다. 아래의 예시는 file 패스스루를 사용한 로컬 규칙 집합을 활용합니다.

패턴을 무시하려면, 동일한 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음을 추가하고, value를 적절하게 조정하여 확장된 구성 파일의 경로를 지정합니다:

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

extended-gitleaks-config.toml에 저장된 확장된 구성은 분석기에 의해 사용되는 구성에 포함됩니다.

아래의 예제에서는 무시할 비밀을 정의하는 regex를 가진 [allowlist] 지시어를 추가합니다(“allowed”):

# extended-gitleaks-config.toml
[extend]
# 기본 번들 규칙 집합을 확장합니다. NOTE: 경로를 변경하지 마세요.
path = "/gitleaks.toml"

[allowlist]
  description = "탐지에서 무시할 패턴의 allowlist"
  regexTarget = "match"
  regexes = [
    '''glpat-[0-9a-zA-Z_\\-]{20}'''
  ]

이것은 glpat-로 시작하고 20개의 숫자 및 문자로 이어지는 문자열을 무시합니다.

마찬가지로, 특정 경로를 스캔에서 제외할 수 있습니다. 아래의 예제에서는 [allowlist] 지시어 아래에 무시할 경로 배열을 정의합니다. 경로는 정규 표현식 또는 특정 파일 경로가 될 수 있습니다:

# extended-gitleaks-config.toml
[extend]
# 기본 번들 규칙 집합을 확장합니다. NOTE: 경로를 변경하지 마세요.
path = "/gitleaks.toml"

[allowlist]
  description = "탐지에서 무시할 패턴의 allowlist"
  paths = [
    '''/gitleaks.toml''',
    '''(.*?)(jpg|gif|doc|pdf|bin|svg|socket)'''
  ]

이것은 /gitleaks.toml 파일이나 지정된 확장자 중 하나로 끝나는 파일에서 탐지된 비밀을 무시합니다.

사용할 패스스루 구문에 대한 더 많은 정보는 Schema를 참조하세요.

인라인 비밀 무시

일부 경우, 비밀을 인라인으로 무시하려고 할 수도 있습니다. 예를 들어, 예제나 테스트 스위트에 가짜 비밀이 있을 수 있습니다. 이러한 경우, 비밀을 보고하는 대신 무시하려고 할 것입니다.

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

예를 들면:

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

복잡한 문자열 탐지

기본 규칙 집합은 낮은 오탐률로 구조화된 문자열을 탐지하는 패턴을 제공합니다.

그러나 암호와 같은 더 복잡한 문자열을 탐지하고 싶을 수 있습니다. Gitleaks는 lookahead 또는 lookbehind를 지원하지 않기 때문에, 비구조화된 문자열을 탐지하기 위한 신뢰할 수 있는 일반 규칙을 작성하는 것은 불가능합니다.

모든 복잡한 문자열을 탐지할 수는 없지만, 특정 사용 사례에 맞게 규칙 집합을 확장할 수 있습니다.

예를 들어, 이 규칙은 Gitleaks 기본 규칙 집합의 generic-api-key 규칙을 수정합니다:

(?i)(?:pwd|passwd|password)(?:[0-9a-z\-_\t .]{0,20})(?:[\s|']|[\s|"]){0,3}(?:=|>|=:|:{1,3}=|\|\|:|<=|=>|:|\?=)(?:'|\"|\s|=|\x60){0,5}([0-9a-z\-_.=\S_]{3,50})(?:['|\"|\n|\r|\s|\x60|;]|$)

이 정규 표현식은 다음을 일치시킵니다:

pwd, passwd 또는 password로 시작하는 대소문자를 구분하지 않는 식별자. secret 또는 key와 같은 다른 변형을 조정할 수 있습니다.
식별자 뒤에 오는 접미사. 접미사는 숫자, 문자 및 기호의 조합이며, 길이는 0에서 23자 사이입니다.
=, :=, :, 또는 =>와 같은 일반적으로 사용되는 할당 연산자.
비밀 접두사, 종종 비밀 탐지에 도움을 주기 위한 경계로 사용됩니다.
숫자, 문자 및 기호의 문자열로, 길이는 3자에서 50자 사이입니다. 더 긴 문자열을 예상한다면 길이를 조정할 수 있습니다.
비밀 접미사, 종종 경계로 사용됩니다. 이는 일반적인 종료 문자열인 틱, 줄 바꿈 및 새 줄과 일치합니다.

다음은 이 정규 표현식과 일치하는 문자열의 예입니다:

pwd = password1234
passwd = 'p@ssW0rd1234'
password = thisismyverylongpassword
password => mypassword
password := mypassword
password: password1234
"password" = "p%ssward1234"
'password': 'p@ssW0rd1234'

이 정규 표현식을 사용하려면, 이 페이지에 문서화된 방법 중 하나로 규칙 집합을 확장하세요.

예를 들어, 이 규칙을 포함하는 로컬 규칙 집합으로 기본 규칙 집합을 확장하고 싶다고 가정해 보겠습니다.

다음 내용을 동일한 리포지토리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 추가하세요. value를 확장된 구성 파일의 경로를 가리키도록 조정합니다:

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

extended-gitleaks-config.toml 파일에 사용하려는 정규 표현식이 포함된 새로운 [[rules]] 섹션을 추가합니다:

# extended-gitleaks-config.toml
[extend]
# 기본 번들 규칙 집합을 확장합니다. NOTE: 경로를 변경하지 마세요.
path = "/gitleaks.toml"

[[rules]]
  description = "일반 비밀번호 규칙"
  id = "generic-password"
  regex = '''(?i)(?:pwd|passwd|password)(?:[0-9a-z\-_\t .]{0,20})(?:[\s|']|[\s|"]){0,3}(?:=|>|=:|:{1,3}=|\|\|:|<=|=>|:|\?=)(?:'|\"|\s|=|\x60){0,5}([0-9a-z\-_.=\S_]{3,50})(?:['|\"|\n|\r|\s|\x60|;]|$)'''
  entropy = 3.5
  keywords = ["pwd", "passwd", "password"]

이 구성 예시는 편의성을 위해 제공되며, 모든 사용 사례에 대해 작동하지 않을 수 있습니다. 복잡한 문자열을 탐지하도록 규칙 집합을 구성하면, 많은 수의 오탐이 발생하거나 특정 패턴을 놓칠 수 있습니다.

사용 가능한 CI/CD 변수

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

CI/CD 변수	기본값	설명
`SECRET_DETECTION_EXCLUDED_PATHS`	””	경로를 기반으로 출력에서 취약점을 제외합니다. 경로는 쉼표로 구분된 패턴 목록입니다. 패턴은 glob일 수 있습니다 (지원되는 패턴은 `doublestar.Match` 참조), 또는 파일 또는 폴더 경로일 수 있습니다 (예: `doc,spec`). 상위 디렉토리도 패턴과 일치합니다. 소개됨 GitLab 13.3에서.
`SECRET_DETECTION_HISTORIC_SCAN`	false	역사적인 Gitleaks 스캔을 활성화하는 플래그입니다.
`SECRET_DETECTION_IMAGE_SUFFIX`	””	이미지 이름에 추가되는 접미사입니다. `-fips`로 설정하면 `FIPS-enabled` 이미지가 스캔에 사용됩니다. FIPS-enabled 이미지 사용에서 더 많은 세부 정보를 참조하세요. 소개됨 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에서. 제거됨 GitLab 15.0에서.

오프라인 구성

Tier: PREMIUM
Offering: Self-managed

오프라인 환경은 인터넷을 통한 외부 리소스 접근이 제한적이거나 간헐적입니다. 이러한 환경의 자가 관리 GitLab 인스턴스에서는 파이프라인 비밀 감지를 위해 일부 구성 변경이 필요합니다. 이 섹션의 지침은 오프라인 환경에서 자세히 설명된 지침과 함께 완료되어야 합니다.

GitLab Runner 구성

기본적으로, 러너는 로컬 복사본이 있더라도 GitLab 컨테이너 레지스트리에서 Docker 이미지를 가져오려고 합니다. Docker 이미지가 최신 상태를 유지할 수 있도록 이 기본 설정을 사용하는 것이 좋습니다.

하지만 네트워크 연결이 없는 경우 기본 GitLab Runner pull_policy 변수를 변경해야 합니다.

GitLab Runner CI/CD 변수 pull_policy를 if-not-present로 구성합니다.

로컬 파이프라인 비밀 탐지 분석기 이미지 사용

GitLab 컨테이너 레지스트리가 아닌 로컬 Docker 레지스트리에서 이미지를 가져오려면 로컬 파이프라인 비밀 탐지 분석기 이미지를 사용하세요.

사전 조건:

로컬 오프라인 Docker 레지스트리에 Docker 이미지를 가져오는 것은 귀하의 네트워크 보안 정책에 따라 다릅니다. IT 직원에게 상담하여 외부 리소스를 가져오거나 임시로 접근하기 위한 승인된 프로세스를 확인하세요.

registry.gitlab.com에서 기본 파이프라인 비밀 탐지 분석기 이미지를 로컬 Docker 컨테이너 레지스트리로 가져옵니다:
```
registry.gitlab.com/security-products/secrets:4
```
파이프라인 비밀 탐지 분석기의 이미지는 주기적으로 업데이트 됩니다 따라서 로컬 복사본을 주기적으로 업데이트해야 합니다.

CI/CD 변수 SECURE_ANALYZERS_PREFIX를 로컬 Docker 컨테이너 레지스트리로 설정합니다.

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

variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

이제 파이프라인 비밀 탐지 작업은 인터넷 접근 없이 로컬 복사본의 분석기 Docker 이미지를 사용해야 합니다.

사용자 지정 SSL CA 인증서 권한 사용

사용자 지정 인증 기관을 신뢰하려면 신뢰하는 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의 값을 인증서의 텍스트 표현으로 설정합니다.

데모

일부 구성 옵션을 설명하는 데모 프로젝트가 있습니다.

아래는 데모 프로젝트와 그에 연결된 워크플로우를 보여주는 표입니다:

작업/워크플로우	적용 대상/통한	인라인 또는 로컬 규칙 집합 포함	원격 규칙 집합 포함
규칙 비활성화	미리 정의된 규칙	로컬 규칙 집합 / 프로젝트	원격 규칙 집합 / 프로젝트
규칙 무시	미리 정의된 규칙	로컬 규칙 집합 / 프로젝트	원격 규칙 집합 / 프로젝트
기본 규칙 집합 교체	파일 통과	로컬 규칙 집합 / 프로젝트	적용 불가
기본 규칙 집합 교체	원시 통과	인라인 규칙 집합 / 프로젝트	적용 불가
기본 규칙 집합 교체	Git 통과	적용 불가	원격 규칙 집합 / 프로젝트
기본 규칙 집합 교체	URL 통과	적용 불가	원격 규칙 집합 / 프로젝트
기본 규칙 집합 확장	파일 통과	로컬 규칙 집합 / 프로젝트	적용 불가
기본 규칙 집합 확장	Git 통과	적용 불가	원격 규칙 집합 / 프로젝트
기본 규칙 집합 확장	URL 통과	적용 불가	원격 규칙 집합 / 프로젝트
경로 무시	파일 통과	로컬 규칙 집합 / 프로젝트	적용 불가
경로 무시	Git 통과	적용 불가	원격 규칙 집합 / 프로젝트
경로 무시	URL 통과	적용 불가	원격 규칙 집합 / 프로젝트
패턴 무시	파일 통과	로컬 규칙 집합 / 프로젝트	적용 불가
패턴 무시	Git 통과	적용 불가	원격 규칙 집합 / 프로젝트
패턴 무시	URL 통과	적용 불가	원격 규칙 집합 / 프로젝트
값 무시	파일 통과	로컬 규칙 집합 / 프로젝트	적용 불가
값 무시	Git 통과	적용 불가	원격 규칙 집합 / 프로젝트
값 무시	URL 통과	적용 불가	원격 규칙 집합 / 프로젝트

원격 규칙 집합 설정을 안내하는 비디오 데모도 있습니다:

로컬 및 원격 규칙 집합을 이용한 비밀 탐지

FIPS 지원 이미지

GitLab 14.10에서 도입됨.

기본 스캐너 이미지는 크기와 유지 관리 용이성을 위해 알파인 이미지를 기반으로 구축됩니다. GitLab은 FIPS 지원이 포함된 Red Hat UBI 버전의 이미지를 제공합니다.

FIPS 지원 이미지를 사용하려면 다음 중 하나를 선택하세요:

SECRET_DETECTION_IMAGE_SUFFIX CI/CD 변수를 -fips로 설정합니다.
기본 이미지 이름에 -fips 확장을 추가합니다.

예를 들어:

변수:
  SECRET_DETECTION_IMAGE_SUFFIX: '-fips'

포함:
  - 템플릿: Jobs/Secret-Detection.gitlab-ci.yml

문제 해결

디버그 수준 로깅

디버그 수준 로깅은 문제를 해결할 때 유용할 수 있습니다. 자세한 내용은 디버그 수준 로깅을 참조하세요.

경고: `gl-secret-detection-report.json: 일치하는 파일 없음`

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

오류: `gitleaks 명령을 실행할 수 없습니다: 종료 상태 2`

파이프라인 비밀 탐지 분석기는 커밋 간의 패치를 생성하여 콘텐츠를 스캔하는 데 의존합니다. 병합 요청의 커밋 수가 GIT_DEPTH CI/CD 변수의 값보다 많으면 비밀 탐지에서 비밀을 감지하는 데 실패합니다.

예를 들어, 60개의 커밋을 포함하는 병합 요청에서 트리거된 파이프라인이 있을 수 있으며, GIT_DEPTH 변수가 60보다 작은 값으로 설정되어 있을 수 있습니다. 이 경우 파이프라인 비밀 탐지 작업이 실패하는데, 이는 복제본이 모든 관련 커밋을 포함하기에 충분히 깊지 않기 때문입니다. 현재 값을 확인하려면 파이프라인 구성을 참조하세요.

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

ERRO[2020-11-18T18:05:52Z] object not found
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ gitleaks 명령을 실행할 수 없습니다: 종료 상태 2
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks 분석 실패: 종료 상태 2

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

secret_detection:
  변수:
    GIT_DEPTH: 100

오류: `ERR fatal: ambiguous argument`

파이프라인 비밀 탐지가 ERR fatal: ambiguous argument 메시지와 함께 실패할 수 있습니다. 이것은 저장소의 기본 브랜치가 작업이 트리거된 브랜치와 관련이 없는 경우 발생할 수 있습니다. 자세한 내용은 문제 !352014를 참조하세요.

문제를 해결하려면 저장소에서 기본 브랜치를 올바르게 설정해야 합니다. 비밀 탐지 작업을 실행하는 브랜치와 관련된 이력을 가진 브랜치로 설정해야 합니다.

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

GitLab 파이프라인 비밀 탐지 분석기는 단지 지원합니다 amd64 CPU 아키텍처에서 실행됩니다.

이 메시지는 작업이 arm과 같은 다른 아키텍처에서 실행되고 있다는 것을 나타냅니다.

경고

유출된 비밀에 대응하기

비밀이 감지되면 즉시 교체해야 합니다. GitLab은 일부 유형의 유출된 비밀을 자동으로 취소하려고 시도합니다. 자동으로 취소되지 않는 경우, 수동으로 취소해야 합니다.

레포지토리의 기록에서 비밀 삭제하기는 유출 문제를 완전히 해결하지 않습니다. 원래 비밀은 레포지토리의 기존 포크나 복제본에 남아 있습니다.

파이프라인 비밀 탐지

탐지된 비밀

범위

전체 이력 파이프라인 비밀 탐지

고급 취약성 추적

지원되지 않는 워크플로우

출력

구성

요구 사항

분석기 활성화

.gitlab-ci.yml 파일을 수동으로 편집

자동으로 구성된 병합 요청 사용

분석기 설정 사용자 정의

새로운 패턴 추가

특정 분석기 버전에 고정

전체 기록 스캔 활성화

병합 요청 파이프라인에서 작업 실행

분석기 작업 무시

분석기 규칙 집합 사용자 정의

규칙 집합 구성 파일 생성

기본 규칙 집합의 규칙 수정

규칙 비활성화

규칙 오버라이드

원격 규칙 세트 사용하기

기본 규칙 세트 교체하기

인라인 규칙 집합 사용하기

로컬 규칙 집합 사용하기

원격 규칙 집합 사용하기

비공식 원격 규칙 세트 사용

기본 규칙 세트 확장

로컬 규칙 세트 사용

원격 규칙 세트 사용

패턴 및 경로 무시

인라인 비밀 무시

복잡한 문자열 탐지

사용 가능한 CI/CD 변수

오프라인 구성

GitLab Runner 구성

로컬 파이프라인 비밀 탐지 분석기 이미지 사용

사용자 지정 SSL CA 인증서 권한 사용

데모

FIPS 지원 이미지

문제 해결

디버그 수준 로깅

경고: gl-secret-detection-report.json: 일치하는 파일 없음

오류: gitleaks 명령을 실행할 수 없습니다: 종료 상태 2

오류: ERR fatal: ambiguous argument

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

경고

유출된 비밀에 대응하기

도움말

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

도움받기

`.gitlab-ci.yml` 파일을 수동으로 편집

경고: `gl-secret-detection-report.json: 일치하는 파일 없음`

오류: `gitleaks 명령을 실행할 수 없습니다: 종료 상태 2`

오류: `ERR fatal: ambiguous argument`

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