소스 코드용 GitLab Secret Scanning
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
GitLab Secret Scanning for Source Code는 파이프라인 시크릿 탐지를 위한 대체 분석기입니다. 이 분석기는 GitLab이 개발한 독점 스캔 엔진을 사용합니다. 베타 기간 동안 분석기는 다음을 제공합니다.
GitLab Secret Scanning for Source Code는 파이프라인 시크릿 탐지를 위한 대체 분석기입니다.
기본 분석기와 같은 secret_detection CI/CD 잡에서 실행되지만, 일반 시크릿 탐지와
오탐 감소를 포함한 추가 기능을 제공합니다.
GitLab Secret Scanning for Source Code의 차이점#
이 분석기는 GitLab이 개발한 독점 스캔 엔진을 사용합니다. 기존의 패턴 매칭 기법에 의존하지 않고 휴리스틱을 사용하여 표준 GitLab 시크릿 탐지 규칙을 넘어서는 비정형 시크릿과 비밀번호를 탐지합니다. 여러 휴리스틱 기법을 결합하여 오탐을 줄입니다.
베타 기간 동안 분석기는 다음을 제공합니다.
- 일반 시크릿 탐지: 표준 GitLab 시크릿 탐지 규칙이 다루는 범위를 넘어서는 컨텍스트 기반 시크릿을 포함하여 비정형 시크릿과 비밀번호를 식별합니다.
- 오탐 감소: 여러 휴리스틱 기법을 결합하여 시크릿과 그 주변 컨텍스트를 모두 평가함으로써 스캔 결과의 노이즈를 줄입니다.
- 인코딩된 시크릿 탐지: 일반 텍스트가 아니라 인코딩되어 저장된 시크릿을 탐지합니다. base64로 인코딩된 문자열을 지원합니다.
분석기 켜기#
사전 요구 사항:
docker또는kubernetes실행기를 사용하는 Linux 기반 러너가 있어야 합니다. GitLab.com의 호스티드 러너를 사용하는 경우 기본적으로 활성화되어 있습니다.- Windows 러너는 지원되지 않습니다.
arm64및amd64CPU 아키텍처만 지원됩니다.
test스테이지를 포함하는.gitlab-ci.yml파일이 있어야 합니다.
분석기를 켜려면 최신 시크릿 탐지 템플릿을 사용하고
SECRET_DETECTION_ENABLE_GSS CI/CD 변수를 true로 설정합니다.
include:
- template: Jobs/Secret-Detection.latest.gitlab-ci.yml
secret_detection:
variables:
SECRET_DETECTION_ENABLE_GSS: "true"
기본적으로 분석기는 신뢰도가 높은 발견 사항만 보고합니다. 취약점 보고서의 노이즈를 최소화하기 위해 신뢰도가 중간 및 낮은 발견 사항은 필터링됩니다. 예상한 시크릿이 결과에 나타나지 않으면 신뢰도가 중간 또는 낮음으로 표시되었을 가능성이 높습니다. 이러한 발견 사항을 보고하려면 신뢰도 수준을 참조합니다. 억제된 발견 사항을 검토하려면 신뢰도 임계값으로 억제된 발견 사항 보기를 참조합니다.
분석기를 처음 실행#
GitLab Secret Scanning for Source Code를 처음 실행할 때는 이력 스캔을 실행해야 합니다. 분석기는 모든 커밋을 스캔하고, 파이프라인 시크릿 탐지의 기존 발견 사항을 이어받는 것을 포함하여 취약점 보고서를 가장 최근의 발견 사항으로 업데이트합니다.
이력 스캔을 실행하려면 다음을 수행합니다.
- 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
- New pipeline을 선택합니다.
- CI/CD 변수를 추가합니다.
- 드롭다운 목록에서 Variable을 선택합니다.
- Input variable key 상자에
SECRET_DETECTION_HISTORIC_SCAN을 입력합니다. - Input variable value 상자에
true를 입력합니다.
- New pipeline을 선택합니다.
.gitlab-ci.yml 파일에서 SECRET_DETECTION_HISTORIC_SCAN을 true로 설정한 경우에는 스캔이 완료된 후
변수를 제거합니다. 그렇지 않으면 모든 파이프라인이 전체 리포지터리 이력을 스캔합니다.
기본 구성#
분석기를 켜면 다음 구성으로 실행됩니다.
| 설정 | 기본값 | 변경 방법 |
|---|---|---|
| 일반 시크릿 탐지 | 켜짐 | SECRET_DETECTION_GSS_ENABLE_GENERIC_SECRETS를 false로 설정합니다. 일반 시크릿을 참조합니다. |
| 오탐 감소 | 켜짐 | 구성할 수 없습니다. |
| 최소 신뢰도 | 높음 | SECRET_DETECTION_GSS_MIN_CONFIDENCE를 설정합니다. 신뢰도 수준을 참조합니다. |
| 규칙 | 기본 GitLab 시크릿 탐지 규칙 세트 | 규칙 사용자 지정을 참조합니다. |
일반 시크릿#
분석기를 켜면 일반 시크릿 탐지가 기본적으로 켜집니다.
일반 시크릿 탐지를 끄려면 SECRET_DETECTION_GSS_ENABLE_GENERIC_SECRETS CI/CD
변수를 false로 설정합니다.
include:
- template: Jobs/Secret-Detection.latest.gitlab-ci.yml
secret_detection:
variables:
SECRET_DETECTION_ENABLE_GSS: "true"
SECRET_DETECTION_GSS_ENABLE_GENERIC_SECRETS: "false"
신뢰도 수준#
분석기는 각 발견 사항에 low, medium, high 중 하나의 신뢰도 수준을 지정합니다. 최소 신뢰도 수준
이상인 발견 사항만 보고합니다. 기본값은 high입니다.
더 많은 발견 사항을 보고하려면 SECRET_DETECTION_GSS_MIN_CONFIDENCE CI/CD 변수를 medium
또는 low로 설정합니다.
include:
- template: Jobs/Secret-Detection.latest.gitlab-ci.yml
secret_detection:
variables:
SECRET_DETECTION_ENABLE_GSS: "true"
SECRET_DETECTION_GSS_MIN_CONFIDENCE: "medium"
신뢰도 수준이 낮을수록 더 많은 시크릿이 보고되지만 오탐도 더 많아집니다.
규칙 사용자 지정#
리포지터리의 .gitlab/secret-detection-ruleset.toml 파일로 GitLab Secret Scanning for Source Code에
스캔 사용자 지정을 적용할 수 있습니다. 이 파일을 만들려면
룰셋 구성 파일 만들기를 참조합니다.
다음을 수행할 수 있습니다.
- 기본 룰셋의 규칙을 비활성화합니다.
- 직접 만든 규칙으로 기본 룰셋을 확장합니다. 새 규칙은 사용자 지정 규칙 형식을 따라야 합니다.
- 허용 목록으로 정규식 또는 파일 경로에 해당하는 시크릿을 무시합니다.
예를 들어 기본 룰셋을 확장하고 정규식 또는 파일 경로로 시크릿을 무시하려면,
확장 구성 파일을 가리키는 file 패스스루를 사용합니다. 이 패스스루를
.gitlab/secret-detection-ruleset.toml 파일에 추가합니다.
# .gitlab/secret-detection-ruleset.toml
[secrets]
[[secrets.passthrough]]
type = "file"
target = "gss.toml"
value = "extended-gss-config.toml"
확장 구성 파일에서는 [extend]로 기본 룰셋을 기반으로 확장하고, 하나 이상의
[[allowlists]] 테이블로 발견 사항을 무시합니다. 각 허용 목록은 regexes로 시크릿 값을,
paths로 파일 경로를 일치시킬 수 있습니다.
# extended-gss-config.toml
[extend]
# Extends the default packaged ruleset. Do not change the path.
path = "/gitleaks.toml"
[[allowlists]]
description = "Ignore known test values and fixture paths"
regexes = [
'''glpat-[0-9a-zA-Z_\-]{20}''',
]
paths = [
'''spec/fixtures/.*''',
]
허용 목록의 regexes와 paths는 논리적 OR로 결합됩니다. 시크릿이 regexes 중 하나와 일치하거나
파일 경로가 paths 중 하나와 일치하면 발견 사항이 무시됩니다.
시크릿 인라인 무시#
시크릿을 무시하려면 시크릿이 포함된 줄에 gss:allow를 주석으로 추가합니다.
분석기는 해당 줄의 모든 시크릿을 무시합니다.
예시:
db_password = "example-password-1234" # gss:allow
분석기는 기본 분석기가 사용하는 gitleaks:allow 주석도 허용합니다.
기본 분석기에서 마이그레이션하기 전에 인라인으로 무시한 시크릿은
계속 무시됩니다.
기본 분석기에서 마이그레이션#
GitLab Secret Scanning for Source Code는 secret_detection 잡에서 기본 분석기를 대체합니다.
SECRET_DETECTION_ENABLE_GSS CI/CD 변수가 true로 설정되면 GitLab Secret Scanning
for Source Code만 실행됩니다.
기본 분석기에서 마이그레이션하려면 다음을 수행합니다.
- 기능 브랜치에서 GitLab Secret Scanning for Source Code를 켭니다.
- 파이프라인을 실행하고 기본 분석기를 사용한 스캔과 발견 사항을 비교합니다.
- 룰셋 사용자 지정을 검토합니다. 사용 가능한 옵션은 규칙 사용자 지정을 참조합니다.
- 결과에 만족하면 기본 브랜치에서 분석기를 켭니다.
마이그레이션 후의 기존 발견 사항#
기본 브랜치에서 GitLab Secret Scanning for Source Code를 켜면, 두 분석기가 모두 탐지한 시크릿은 이 분석기가 이어받습니다. 이러한 발견 사항을 기본 분석기가 이전에 보고한 취약점과 대응시킵니다. 기존 취약점 레코드는 새 발견 사항으로 다시 보고되지 않고 그대로 이어집니다.
기본 분석기가 이전에 보고했지만 GitLab Secret Scanning for Source Code가 탐지하지 못하는 발견 사항은 변경되지 않고 유지됩니다.
FIPS 지원 이미지#
GitLab Secret Scanning for Source Code가 베타인 동안에는 FIPS 지원 이미지가 게시되지 않습니다.
SECRET_DETECTION_IMAGE_SUFFIX CI/CD 변수를 -fips로 설정하면 이미지를 가져올 수 없어
secret_detection 잡이 실패합니다.
FIPS 지원 이미지로 스캔하려면 파이프라인 시크릿 탐지의 기본 분석기를 사용합니다.
문제 해결#
파이프라인 시크릿 탐지의 일반적인 문제는 문제 해결 문서를 참조합니다.
이 분석기는 Gitleaks 기반 분석기와 같은 방식으로 커밋을 가져옵니다.
Gitleaks 기반 분석기는 v7.41.0 버전을 사용합니다. 이를 이 분석기의 대응 버전인
v0.34.0으로 바꿉니다.
신뢰도 임계값으로 억제된 발견 사항 보기#
분석기는 최소 신뢰도 수준에 미치지 못하는 발견 사항을 억제합니다.
기본값인 high에서는 신뢰도가 중간 및 낮은 발견 사항을 억제합니다.
억제된 발견 사항을 검토하려면 secret_detection 잡에서 SECRET_DETECTION_GSS_DEBUG_REPORT
CI/CD 변수를 true로 설정합니다. 이 변수는
gl-secret-detection-report.debug.json이라는 두 번째 잡 아티팩트를 생성하며,
잡 아티팩트에서 다운로드할 수 있습니다.
디버그 보고서에는 신뢰도 때문에 억제된 발견 사항만 포함됩니다.
제외 항목(허용 목록 및 인라인 주석)으로 억제된 발견 사항은 포함되지 않습니다.
취약점 보고서는 변경되지 않으며 여전히 최소 신뢰도 수준 이상의 발견 사항만 표시합니다.
변수가 설정되지 않았거나 false이면 디버그 보고서가 생성되지 않습니다. 스캐너는
잡 상태에 영향을 주지 않는 경고를 로그에 기록합니다.
피드백 제공#
이슈 609578에서 피드백을 공유합니다.