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

분석기 동작 사용자 정의로 다음을 수행하세요:

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

분석기 룰셋 사용자 정의로 다음을 수행하세요:

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

분석기 동작 사용자 정의#

분석기의 동작을 변경하려면 .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로 설정하세요.

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

Merge request 파이프라인으로 보안 스캔 도구 사용을 참조하세요.

분석기 작업 재정의#

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

다음 .gitlab-ci.yml 파일 발췌 예제에서:

• Jobs/Secret-Detection CI/CD 템플릿이 포함됩니다.
• 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"

사용 가능한 CI/CD 변수#

사용 가능한 CI/CD 변수를 정의하여 파이프라인 시크릿 감지의 동작을 변경하세요:

이전 GitLab 버전에서는 다음 변수도 사용 가능했습니다:

분석기 룰셋 사용자 정의#

히스토리

• GitLab 13.5에서 도입되었습니다.
• GitLab 14.6에서 file 및 raw의 추가 패스스루 유형을 포함하도록 확장되었습니다.
• GitLab 14.8에서 규칙 재정의 지원이 활성화되었습니다.
• GitLab 17.2에서 패스스루 체인 지원이 활성화되고 git 및 url의 추가 패스스루 유형이 포함되었습니다.

저장소에 커밋되거나 원격 저장소에 있는 사용자 정의 룰셋 구성 파일을 만들어 파이프라인 시크릿 감지로 감지되는 시크릿 유형을 사용자 정의할 수 있습니다.

사용자 정의를 통해 다음을 수행할 수 있습니다:

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

룰셋 구성 파일 만들기#

룰셋 구성 파일을 만들려면:

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

기본 룰셋의 규칙 수정#

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

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

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

규칙 비활성화#

히스토리

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

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

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"

규칙 재정의#

히스토리

• 원격 룰셋으로 규칙을 재정의하는 기능이 GitLab 16.0 이상에서 활성화되었습니다.

사용자 정의가 필요한 특정 규칙이 있는 경우 재정의할 수 있습니다. 예를 들어, 특정 유형의 시크릿이 유출되면 워크플로에 더 큰 영향을 미치기 때문에 해당 시크릿의 심각도를 높이고 싶을 수 있습니다.

분석기 기본 룰셋에서 규칙을 재정의하려면:

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}'''
"""

이전 예제는 정의된 regex를 확인하는 규칙으로 기본 룰셋을 교체합니다 - e, s, t 문자 중 하나의 3자리 접미사를 가진 Custom Raw Ruleset T.

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

로컬 룰셋 사용#

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"

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

기본 룰셋 확장#

추가 규칙으로 기본 룰셋 구성을 확장할 수도 있습니다. 이는 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'''

이 룰셋 구성으로 분석기는 해당 regex 패턴과 일치하는 모든 문자열을 감지합니다.

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

원격 룰셋 사용#

원격 룰셋으로 기본 룰셋을 교체할 수 있는 것처럼, .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에 저장된 확장된 구성은 분석기가 사용하는 구성에 포함됩니다.

아래 예제는 무시("허용")될 시크릿과 일치하는 regex를 정의하는 [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도 사용할 수 있습니다. 이를 통해 기존 규칙을 재정의하여 개인 액세스 토큰 접두사나 사용자 정의 인스턴스 접두사를 구성할 수 있습니다. 예를 들어, 개인 액세스 토큰에 대해 다음과 같이 구성할 수 있습니다:

# 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는 룩어헤드 또는 룩비하인드를 지원하지 않으므로, 비구조화 문자열을 감지하는 높은 신뢰도의 일반 규칙을 작성하는 것이 불가능합니다.

모든 복잡한 문자열을 감지할 수는 없지만, 특정 사용 사례를 충족하도록 룰셋을 확장할 수 있습니다.

예를 들어, 이 규칙은 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'

이 regex를 사용하려면 이 페이지에 문서화된 방법 중 하나로 룰셋을 확장하세요.

예를 들어, 이 규칙을 포함하는 로컬 룰셋으로 기본 룰셋을 확장하려는 경우를 가정합니다.

동일한 저장소에 저장된 .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"
   

이제 파이프라인 시크릿 감지 작업이 인터넷 액세스 없이 로컬 분석기 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 값을 인증서의 텍스트 표현으로 설정하세요.