구독 티어와 구성 방법에 따라 파이프라인 시크릿 탐지의 동작 방식을 변경할 수 있습니다.

분석기 동작 사용자 정의로 다음을 수행합니다.

• 분석기가 탐지하는 시크릿 유형을 변경합니다.
• 다른 분석기 버전을 사용합니다.
• 특정 방법으로 프로젝트를 스캔합니다.

분석기 룰셋 사용자 정의로 다음을 수행합니다.

• 사용자 정의 시크릿 유형을 탐지합니다.
• 기본 스캐너 규칙을 재정의합니다.

분석기 동작 사용자 정의#

분석기의 동작을 변경하려면 .gitlab-ci.yml의 variables 파라미터로 변수를 정의합니다.

새 패턴 추가#

리포지터리에서 다른 유형의 시크릿을 검색하려면 분석기 룰셋을 사용자 정의할 수 있습니다.

새 탐지 규칙 제안#

모든 파이프라인 시크릿 탐지 사용자를 위한 새 탐지 규칙은 두 가지 방법으로 제안할 수 있습니다.

• 새 규칙 요청: Secret Detection Pattern Change 이슈 템플릿으로 이슈를 만듭니다. GitLab 팀이 요청을 검토한 다음, 새 규칙을 언제 어떻게 구현할지 결정하기 위해 연락합니다.
• 새 규칙 기여: 규칙을 직접 기여하려면 Secret Detection Rules 리포지터리의 기여 지침을 따릅니다.

클라우드나 SaaS 제품을 운영하며 사용자를 더 잘 보호하기 위해 GitLab과 협력하고 싶다면 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로 설정합니다.

머지 리퀘스트 파이프라인에서 job 실행#

머지 리퀘스트 파이프라인에서 보안 스캔 도구 사용을 참고합니다.

분석기 job 재정의#

job 정의를 재정의하려면(예: variables나 dependencies 같은 속성 변경), 재정의할 secret_detection job과 같은 이름으로 job을 선언합니다. 이 새 job은 템플릿 포함 뒤에 두고 그 아래에 추가 키를 지정합니다.

다음 .gitlab-ci.yml 파일 발췌 예시에서는 이렇게 동작합니다.

• Jobs/Secret-Detection CI/CD 템플릿을 포함합니다.
• secret_detection job에서 CI/CD 변수 SECRET_DETECTION_HISTORIC_SCAN을 true로 설정합니다. 템플릿은 파이프라인 구성보다 먼저 평가되므로 변수의 마지막 언급이 우선하며, 따라서 기록 스캔이 수행됩니다.

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

secret_detection:
  variables:
    SECRET_DETECTION_HISTORIC_SCAN: "true"

사용 가능한 CI/CD 변수#

사용 가능한 CI/CD 변수를 정의해 파이프라인 시크릿 탐지의 동작을 변경합니다.

분석기 룰셋 사용자 정의#

히스토리

• GitLab 17.2에서 패스스루 체인 지원이 활성화되고 git과 url 패스스루 유형이 추가로 포함되었습니다.

스캔 대상 리포지터리나 원격 리포지터리에 사용자 정의 룰셋 구성 파일을 만들면, 파이프라인 시크릿 탐지가 탐지하는 시크릿 유형을 사용자 정의할 수 있습니다.

사용자 정의로 다음을 수행할 수 있습니다

• 기본 룰셋의 규칙 동작을 수정합니다.
• 기본 룰셋을 사용자 정의 룰셋으로 교체합니다.
• 기본 룰셋의 동작을 확장합니다.
• 시크릿과 경로를 무시합니다.

룰셋 구성 파일 만들기#

룰셋 구성 파일을 만드는 절차는 다음과 같습니다.

1. 프로젝트 루트에 .gitlab 디렉터리가 없으면 만듭니다.
2. .gitlab 디렉터리에 secret-detection-ruleset.toml이라는 파일을 만듭니다.

기본 룰셋의 규칙 수정#

기본 룰셋에 미리 정의된 규칙을 수정할 수 있습니다.

규칙을 수정하면 기존 워크플로나 도구에 맞게 파이프라인 시크릿 탐지를 조정할 수 있습니다. 예를 들어 탐지된 시크릿의 심각도를 재정의하거나, 특정 규칙이 아예 탐지되지 않도록 비활성화할 수 있습니다.

원격(Git 리포지터리나 웹사이트)에 저장된 룰셋 구성 파일로 미리 정의된 규칙을 수정할 수도 있습니다. 새 규칙은 사용자 정의 규칙 형식을 사용해야 합니다.

규칙 비활성화#

활성 상태로 두고 싶지 않은 규칙은 비활성화할 수 있습니다. 분석기 기본 룰셋의 규칙을 비활성화하는 절차는 다음과 같습니다.

1. 룰셋 구성 파일이 없으면 만듭니다.
2. ruleset 섹션 컨텍스트에서 disabled 플래그를 true로 설정합니다.
3. 하나 이상의 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"

규칙 재정의#

사용자 정의할 특정 규칙이 있으면 재정의할 수 있습니다. 예를 들어 특정 유형의 시크릿은 유출되면 워크플로에 더 큰 영향을 주기 때문에 그 시크릿의 심각도를 높일 수 있습니다.

분석기 기본 룰셋의 규칙을 재정의하는 절차는 다음과 같습니다.

1. 룰셋 구성 파일이 없으면 만듭니다.
2. 하나 이상의 ruleset.identifier 하위 섹션에 재정의할 규칙을 나열합니다. 모든 ruleset.identifier 섹션에는 다음이 있습니다.
   • 미리 정의된 규칙 식별자를 담는 type 필드.
   • 규칙 이름을 담는 value 필드.
3. 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"

원격 룰셋 사용#

원격 룰셋은 현재 리포지터리 외부에 저장된 구성 파일입니다. 여러 프로젝트에 걸쳐 규칙을 수정하는 데 사용할 수 있습니다.

원격 룰셋으로 미리 정의된 규칙을 수정하려면 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/CD 변수가 참조하는 리포지터리의 .gitlab/secret-detection-ruleset.toml 파일에 구성이 정의되어 있다고 가정합니다. 그 파일이 없으면 파일을 만들고 앞에서 설명한 대로 미리 정의된 규칙을 재정의하거나 비활성화하는 단계를 따릅니다.

SECRET_DETECTION_RULESET_GIT_REFERENCE 변수는 URI, 선택적 인증, 선택적 Git SHA를 지정하기 위해 Git URL과 비슷한 형식을 사용합니다. 변수는 다음 형식을 사용합니다.

:@@

구성 파일이 인증이 필요한 비공개 프로젝트에 저장되어 있으면, CI/CD 변수에 안전하게 저장한 그룹 액세스 토큰으로 원격 룰셋을 로드할 수 있습니다.

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, Developer, Maintainer 또는 Owner 권한이 있어야 합니다. 자세한 내용은 리포지터리 권한을 참고합니다.

그룹 액세스 토큰에 연결된 사용자 이름을 찾는 방법은 그룹의 봇 사용자를 참고합니다.

기본 룰셋 교체#

사용자 정의를 사용해 기본 룰셋 구성을 교체할 수 있습니다. 이러한 사용자 정의는 패스스루로 하나의 구성으로 결합할 수 있습니다.

패스스루로 다음을 수행할 수 있습니다.

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

인라인 룰셋 사용#

raw 패스스루로 기본 룰셋을 인라인으로 제공한 구성으로 교체할 수 있습니다.

같은 리포지터리에 저장된 .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개 문자가 붙은 문자열을 찾습니다.

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

로컬 룰셋 사용#

file 패스스루로 기본 룰셋을 현재 리포지터리에 커밋된 다른 파일로 교체할 수 있습니다.

같은 리포지터리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음을 추가하고, 로컬 룰셋 구성 파일의 경로를 가리키도록 value를 적절히 조정합니다.

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

이렇게 하면 기본 룰셋이 config/gitleaks.toml 파일에 정의된 구성으로 교체됩니다.

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

원격 룰셋 사용#

git과 url 패스스루로 기본 룰셋을 원격 Git 리포지터리에 정의된 구성이나 온라인 어딘가에 저장된 파일로 교체할 수 있습니다.

원격 룰셋은 여러 프로젝트에서 사용할 수 있습니다. 예를 들어 네임스페이스 중 하나에 있는 여러 프로젝트에 같은 룰셋을 적용하고 싶다면, 두 패스스루 유형 중 하나로 그 원격 룰셋을 로드해 여러 프로젝트에서 사용하게 할 수 있습니다. 또한 룰셋을 중앙에서 관리하면서 인가된 사람만 편집할 수 있게 됩니다.

git 패스스루를 사용하려면 리포지터리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음을 추가하고, Git 리포지터리의 주소를 가리키도록 value를 조정합니다.

# .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 패스스루로 기본 룰셋을 원격 룰셋 구성으로 교체할 수 있습니다.

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"

이 구성에서 분석기는 지정한 주소에 저장된 gitleaks.toml 파일에서 룰셋 구성을 로드합니다.

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

비공개 원격 룰셋 사용#

룰셋 구성이 비공개 리포지터리에 저장되어 있으면 패스스루의 auth 설정으로 리포지터리에 접근할 자격 증명을 제공해야 합니다.

비공개 리포지터리에 저장된 원격 룰셋을 사용하려면 리포지터리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음을 추가하고, Git 리포지터리의 주소를 가리키도록 value를 조정하고, 적절한 자격 증명을 사용하도록 auth를 갱신합니다.

[secrets]
  [[secrets.passthrough]]
    type   = "git"
    ref    = "main"
    auth   = "USERNAME:PASSWORD" # replace USERNAME and PASSWORD as appropriate
    subdir = "config"
    value  = "https://gitlab.com/user_group/central_repository_with_shared_ruleset"

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

베타 규칙 켜기#

베타 규칙은 기본 룰셋에 포함되지 않은 실험적 탐지 규칙입니다. 규칙이 기본 룰셋으로 승격되기 전에 베타 규칙으로 추가 시크릿 유형을 탐지합니다.

분석기 이미지에는 /beta.toml에 베타 룰셋이 포함되어 있습니다. 이 룰셋에는 모든 기본 규칙과 beta 성숙도 규칙이 함께 담겨 있습니다. 옵트인하지 않으면 분석기는 베타 룰셋을 로드하지 않습니다.

베타 규칙을 켜려면 file 패스스루로 기본 룰셋을 번들로 제공되는 베타 룰셋으로 교체합니다. 같은 리포지터리에 저장된 .gitlab/secret-detection-ruleset.toml 구성 파일에 다음을 추가합니다.

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

베타 룰셋에는 기본 규칙이 이미 포함되어 있으므로 기본 룰셋을 따로 확장하지 않습니다.

기본 룰셋 확장#

기본 룰셋 구성에 필요한 규칙을 추가해 확장할 수도 있습니다. 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]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[[rules]]
  id = "example_api_key"
  description = "Example Service API Key"
  regex = '''example_api_key'''

[[rules]]
  id = "example_api_secret"
  description = "Example Service API Secret"
  regex = '''example_api_secret'''

이 룰셋 구성에서 분석기는 정의된 정규 표현식 패턴과 일치하는 모든 문자열을 탐지합니다.

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

원격 룰셋 사용#

기본 룰셋을 원격 룰셋으로 교체할 수 있는 것과 마찬가지로, .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]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[[rules]]
  id = "example_api_key"
  description = "Example Service API Key"
  regex = '''example_api_key'''

[[rules]]
  id = "example_api_secret"
  description = "Example Service API Secret"
  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"

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

스캔 실행 정책 사용#

스캔 실행 정책으로 룰셋을 확장하고 적용하는 방법은 다음과 같습니다.

• 스캔 실행 정책으로 파이프라인 시크릿 탐지 구성 설정의 단계를 따릅니다.

패턴과 경로 무시#

파이프라인 시크릿 탐지가 특정 패턴이나 경로를 탐지하지 않도록 해야 하는 상황이 있을 수 있습니다. 예를 들어 테스트 스위트에서 사용할 가짜 시크릿이 담긴 파일이 있을 수 있습니다.

그런 경우 Gitleaks의 기본 [allowlist] 지시어로 특정 패턴이나 경로를 무시할 수 있습니다.

패턴을 무시하려면 같은 리포지터리에 저장된 .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에 저장된 확장 구성은 분석기가 사용하는 구성에 포함됩니다.

아래 예시는 무시("허용")할 시크릿과 일치하는 정규 표현식을 정의하는 [allowlist] 지시어를 추가합니다.

# extended-gitleaks-config.toml
[extend]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[allowlist]
  description = "allowlist of patterns to ignore in detection"
  regexTarget = "match"
  regexes = [
    '''glpat-[0-9a-zA-Z_\\-]{20}'''
  ]

이렇게 하면 glpat- 뒤에 숫자와 문자 20자가 붙은 문자열이 모두 무시됩니다.

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

# extended-gitleaks-config.toml
[extend]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[allowlist]
  description = "allowlist of patterns to ignore in detection"
  paths = [
    '''/gitleaks.toml''',
    '''(.*?)(jpg|gif|doc|pdf|bin|svg|socket)'''
  ]

이렇게 하면 /gitleaks.toml 파일이나 지정한 확장자 중 하나로 끝나는 파일에서 탐지된 시크릿이 모두 무시됩니다.

Gitleaks v8.20.0부터는 [allowlist]와 함께 regexTarget도 사용할 수 있습니다. 즉 기존 규칙을 재정의해 개인 액세스 토큰 접두사나 사용자 정의 인스턴스 접두사를 구성할 수 있습니다. 예를 들어 personal access tokens에는 다음과 같이 구성할 수 있습니다.

# extended-gitleaks-config.toml
[extend]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[[rules]]
# Rule id you want to override:
id = "gitlab_personal_access_token"
# all the other attributes from the default rule are inherited
    [[rules.allowlists]]
    regexTarget = "line"
    regexes = [ '''CUSTOMglpat-''' ]

[[rules]]
id = "gitlab_personal_access_token_with_custom_prefix"
regex = ''

기본 룰셋에 구성된 모든 규칙을 고려해야 한다는 점에 유의합니다.

사용할 패스스루 구문에 대한 자세한 내용은 스키마를 참고합니다.

인라인으로 시크릿 무시#

시크릿을 인라인으로 무시하고 싶은 경우가 있습니다. 예를 들어 예시나 테스트 스위트에 가짜 시크릿이 있을 수 있습니다. 이런 경우에는 시크릿이 취약점으로 보고되게 두는 대신 무시해야 합니다.

시크릿을 무시하려면 시크릿이 있는 줄에 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|;]|$)

이 정규 표현식이 일치시키는 대상은 다음과 같습니다.

1. pwd, passwd 또는 password로 시작하는, 대소문자를 구분하지 않는 식별자입니다. secret이나 key 같은 다른 변형으로 조정할 수 있습니다.
2. 식별자 뒤에 오는 접미사입니다. 접미사는 숫자, 문자, 기호의 조합이며 길이는 0자에서 23자 사이입니다.
3. =, :=, :, => 같이 흔히 쓰이는 할당 연산자입니다.
4. 시크릿 접두사로, 시크릿 탐지를 돕는 경계로 자주 쓰입니다.
5. 숫자, 문자, 기호로 이루어진 3자에서 50자 사이의 문자열입니다. 이것이 시크릿 자체입니다. 더 긴 문자열이 예상되면 길이를 조정할 수 있습니다.
6. 시크릿 접미사로, 경계로 자주 쓰입니다. 백틱, 줄바꿈, 개행 같은 흔한 끝부분과 일치합니다.

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

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]
# Extends default packaged ruleset, NOTE: do not change the path.
path = "/gitleaks.toml"

[[rules]]
  description = "Generic Password Rule"
  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"]

데모#

이러한 구성 옵션 일부를 보여 주는 데모 프로젝트가 있습니다.

다음은 데모 프로젝트와 관련 워크플로를 정리한 표입니다.

원격 룰셋 설정 과정을 보여 주는 동영상 데모도 있습니다.

• 로컬 및 원격 룰셋으로 시크릿 탐지

오프라인 구성#

오프라인 환경은 인터넷을 통한 외부 리소스 접근이 제한되거나 차단되거나 간헐적인 환경입니다. 그런 환경의 인스턴스에서 파이프라인 시크릿 탐지를 사용하려면 몇 가지 구성 변경이 필요합니다. 이 섹션의 지침은 오프라인 환경에 설명된 지침과 함께 완료해야 합니다.

GitLab Runner 구성#

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

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

로컬 파이프라인 시크릿 탐지 분석기 이미지 사용#

GitLab 컨테이너 레지스트리 대신 로컬 Docker 레지스트리에서 이미지를 가져오려면 로컬 파이프라인 시크릿 탐지 분석기 이미지를 사용합니다.

사전 요구 사항:

• Docker 이미지를 로컬 오프라인 Docker 레지스트리로 가져오는 방법은 네트워크 보안 정책에 따라 달라집니다. 외부 리소스를 가져오거나 일시적으로 접근하는 승인된 절차는 IT 담당자와 상의합니다.

1. registry.gitlab.com에서 기본 파이프라인 시크릿 탐지 분석기 이미지를 로컬 Docker 컨테이너 레지스트리로 가져옵니다.

   registry.gitlab.com/security-products/secrets:7
   

   파이프라인 시크릿 탐지 분석기 이미지는 주기적으로 업데이트되므로 로컬 복사본도 주기적으로 업데이트해야 합니다.

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

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

이제 파이프라인 시크릿 탐지 job은 인터넷 접근 없이 분석기 Docker 이미지의 로컬 복사본을 사용합니다.

사용자 정의 SSL CA 인증 기관 사용#

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