히스토리

• GitLab 16.7에서 GitLab Dedicated 고객을 위한 실험 기능으로 도입되었습니다.
• GitLab 17.1에서 베타로 변경되었고 GitLab.com에서 사용할 수 있게 되었습니다.
• GitLab 17.2에서 pre_receive_secret_detection_beta_release와 pre_receive_secret_detection_push_check라는 기능 플래그와 함께 GitLab Self-Managed에 활성화되었습니다.
• 기능 플래그 pre_receive_secret_detection_beta_release가 GitLab 17.4에서 제거되었습니다.
• GitLab 17.5에서 일반 공개되었습니다.
• 기능 플래그 pre_receive_secret_detection_push_check가 GitLab 17.7에서 제거되었습니다.

시크릿 푸시 보호는 키나 API 토큰 같은 시크릿이 GitLab으로 푸시되는 것을 차단합니다.

개요는 재생 목록 Get Started with Secret Push Protection을 참고합니다.

파이프라인 시크릿 탐지를 시크릿 푸시 보호와 함께 사용하면 보안을 한층 더 강화할 수 있습니다.

시크릿 푸시 보호 워크플로#

시크릿 푸시 보호는 pre-receive 훅에서 동작합니다. GitLab으로 변경 사항을 푸시하면 푸시 보호가 각 파일이나 커밋에서 시크릿을 검사합니다. 기본적으로 시크릿이 탐지되면 푸시가 차단됩니다.

푸시가 차단되면 GitLab 이 다음 내용을 포함한 메시지를 표시합니다.

• 시크릿이 포함된 커밋 ID
• 시크릿이 포함된 파일 이름과 줄
• 시크릿 유형

예를 들어 다음은 Git CLI를 사용한 푸시가 차단되었을 때 반환되는 메시지의 일부입니다. GitLab Web IDE를 포함한 다른 클라이언트를 사용하면 메시지 형식은 다르지만 내용은 같습니다.

remote: PUSH BLOCKED: Secrets detected in code changes
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
remote:
remote: -- test.txt:2 GitLab Personal Access Token
remote:
remote: To push your changes you must remove the identified secrets.

커밋에서 시크릿이 탐지되지 않으면 아무 메시지도 표시되지 않습니다.

감지되는 시크릿#

시크릿 푸시 보호는 파일이나 커밋에서 특정 패턴을 검사합니다. 각 패턴은 특정 유형의 시크릿에 대응합니다. 시크릿 푸시 보호가 탐지하는 시크릿은 감지되는 시크릿에서 확인합니다. 커밋을 푸시할 때의 지연과 오탐 건수를 최소화하기 위해 시크릿 푸시 보호에는 신뢰도가 높은 패턴만 선정했습니다. 예를 들어 사용자 지정 접두사를 사용하는 개인 액세스 토큰은 시크릿 푸시 보호가 탐지하지 않습니다. 특정 시크릿은 시크릿 푸시 보호의 탐지 대상에서 제외할 수 있습니다.

시작하기#

GitLab Dedicated와 GitLab Self-Managed 인스턴스에서는 다음 작업이 필요합니다.

1. 인스턴스 전체에서 시크릿 푸시 보호 사용을 허용합니다.
2. 시크릿 푸시 보호를 활성화합니다. 다음 중 하나를 수행합니다.
   • 특정 프로젝트에서 시크릿 푸시 보호를 활성화합니다.
   • API로 그룹 내 모든 프로젝트에 시크릿 푸시 보호를 활성화합니다.

GitLab 인스턴스에서 시크릿 푸시 보호 사용 허용#

GitLab Dedicated와 GitLab Self-Managed 인스턴스에서는 프로젝트에서 시크릿 푸시 보호를 활성화하기 전에 먼저 사용을 허용해야 합니다.

사전 요구 사항:

• GitLab 인스턴스의 관리자여야 합니다.

GitLab 인스턴스에서 시크릿 푸시 보호 사용을 허용하려면 다음 단계를 수행합니다.

1. 관리자 계정으로 GitLab 인스턴스에 로그인합니다.
2. 오른쪽 위에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > Security and compliance를 선택합니다.
4. Secret detection에서 Allow secret push protection을 선택하거나 해제합니다.

이제 인스턴스에서 시크릿 푸시 보호 사용이 허용됩니다. 이 기능을 사용하려면 프로젝트마다 활성화해야 합니다.

프로젝트에서 시크릿 푸시 보호 활성화#

사전 요구 사항:

• 프로젝트에 대한 Security Manager, Maintainer, Owner 권한 중 하나가 있어야 합니다.
• GitLab Dedicated와 GitLab Self-Managed에서는 인스턴스에서 시크릿 푸시 보호 사용을 허용해야 합니다.

프로젝트에서 시크릿 푸시 보호를 활성화하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.
3. Secret push protection 토글을 켭니다.

API 로 그룹 내 모든 프로젝트에 시크릿 푸시 보호를 활성화할 수도 있습니다.

커버리지#

히스토리

• GitLab 17.11에서 diff만 스캔하도록 변경되었습니다.

다음의 경우 시크릿 푸시 보호가 시크릿을 차단하지 않습니다.

• 커밋을 푸시할 때 시크릿 푸시 보호 건너뛰기 옵션을 사용한 경우
• 해당 시크릿이 시크릿 푸시 보호 대상에서 제외된 경우
• 해당 시크릿이 제외 항목으로 정의된 경로에 있는 경우

다음의 경우 시크릿 푸시 보호가 커밋 내 파일을 검사하지 않습니다.

• 해당 파일이 바이너리 파일인 경우
• 파일이나 diff 패치가 1 MiB를 초과하는 경우
• 콘텐츠 변경 없이 파일의 이름이 바뀌거나 삭제되거나 이동된 경우
• 파일의 콘텐츠가 소스 코드의 다른 파일 콘텐츠와 동일한 경우
• 리포지터리를 생성한 최초 푸시에 파일이 포함된 경우
• 푸시의 총 변경 줄 수가 350,000 줄을 초과하는 경우

Diff 스캔#

히스토리

• GitLab 17.5에서 spp_scan_diffs라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.6에서 GitLab.com에 활성화되었습니다.
• GitLab 17.10에서 secret_checks_for_web_requests라는 기능 플래그와 함께 Web IDE 푸시 지원이 추가되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.11에서 일반 공개되었습니다. 기능 플래그 spp_scan_diffs가 제거되었습니다.
• GitLab 17.11에서 secret_checks_for_web_requests 기능 플래그가 제거되었습니다.

시크릿 푸시 보호는 HTTP(S)와 SSH로 푸시된 커밋의 diff만 스캔합니다. 시크릿이 이미 파일에 있고 변경 사항에 포함되지 않았다면 탐지되지 않습니다.

감사 이벤트#

히스토리

• GitLab 19.3에서 도입되었습니다.
• 푸시 차단 이벤트가 GitLab 19.4에서 도입되었습니다.

다음의 경우 감사 이벤트가 기록됩니다.

• 시크릿 푸시 보호가 변경 사항에서 시크릿을 탐지해 푸시를 차단한 경우
• 푸시에 변경 경로가 너무 많아 시크릿 푸시 보호를 건너뛴 경우
• 푸시가 변경하는 줄이 너무 많아 시크릿 푸시 보호를 건너뛴 경우
• 시크릿 푸시 보호 스캔이 타임아웃되어 GitLab 이 푸시를 수락한 경우
• 시크릿 푸시 보호에서 룰셋 구문 분석 또는 컴파일 오류가 발생한 경우
• 스캔이 잘못된 입력을 받아 시크릿 푸시 보호를 건너뛴 경우
• 시크릿 푸시 보호에서 예기치 않은 스캔 오류가 발생한 경우

푸시 크기 임계값#

푸시가 3,150 개를 넘는 경로 또는 350,000 줄을 변경하면 시크릿 푸시 보호를 건너뜁니다. 이 임계값은 시크릿 푸시 보호가 스캔하는 파일(제외 항목으로 정의된 경로를 뺀 뒤)에만 적용됩니다. 이 임계값은 대규모 변경 집합을 푸시할 때 푸시 타임아웃을 방지합니다.

결과 이해#

시크릿 푸시 보호는 다음과 같은 여러 범주의 시크릿을 식별할 수 있습니다.

• API 키와 토큰: 서비스별 인증 자격 증명
• 데이터베이스 연결 문자열: 자격 증명이 포함된 URL
• 개인 키: 인증이나 암호화에 사용하는 암호화 키
• 엔트로피가 높은 일반 문자열: 무작위로 생성된 시크릿으로 보이는 패턴

푸시가 차단되면 시크릿 푸시 보호는 탐지된 시크릿을 찾아 처리할 수 있도록 상세 정보를 제공합니다.

• 커밋 ID: 시크릿이 포함된 커밋입니다. Git 히스토리에서 변경 사항을 추적할 때 유용합니다.
• 파일 경로와 줄 번호: 탐지된 패턴의 정확한 위치로, 빠르게 이동할 수 있습니다.
• 시크릿 유형: 탐지된 패턴의 분류입니다. 예를 들어 GitLab Personal Access Token 이나 AWS Access Key 입니다.

일반적인 감지 카테고리#

모든 탐지 결과가 즉시 조치를 요구하지는 않습니다. 결과를 평가할 때 다음을 고려합니다.

• 정탐: 교체하고 제거해야 하는 실제 시크릿입니다. 예를 들면 다음과 같습니다.
  • 유효한 API 키나 토큰
  • 운영 데이터베이스 자격 증명
  • 개인 암호화 키
  • 무단 접근을 허용할 수 있는 모든 자격 증명
• 오탐: 실제 시크릿이 아닌데 탐지된 패턴입니다. 예를 들면 다음과 같습니다.
  • 시크릿처럼 보이지만 실제 가치가 없는 테스트 데이터
  • 구성 템플릿의 자리 표시자 값
  • 문서의 예시 자격 증명
  • 시크릿 패턴과 일치하는 해시 값이나 체크섬

이후 평가를 간소화할 수 있도록 조직에서 자주 나타나는 오탐 패턴을 문서로 남깁니다.

최적화#

시크릿 푸시 보호를 널리 배포하기 전에, 오탐을 줄이고 자사 환경에 맞는 정확도를 확보하도록 구성을 최적화합니다.

오탐 줄이기#

오탐은 개발자 생산성에 큰 영향을 주고 보안 피로를 유발할 수 있습니다.

오탐을 줄이려면 다음과 같이 대응합니다.

• 제외 항목을 구성할 때 전략적으로 접근합니다.
  • 테스트 디렉터리, 문서, 서드파티 의존성에 대해 경로 기반 제외 항목을 만듭니다.
  • 코드베이스에 특유한 오탐 패턴에는 패턴 기반 제외 항목을 사용합니다.
  • 제외 규칙을 문서로 남기고 정기적으로 검토합니다.
• 자리 표시자 값과 테스트 자격 증명에 대한 표준을 만듭니다. 이 표준은 제외 규칙과는 일치하되 기본 룰셋과는 일치하지 않아야 합니다.
• 오탐 비율을 모니터링하고 그에 맞춰 제외 항목을 계속 조정합니다.

성능 최적화#

대규모 리포지터리나 잦은 푸시는 성능에 영향을 줄 수 있습니다.

시크릿 푸시 보호의 성능을 최적화하려면 다음과 같이 대응합니다.

• 배포 전에 푸시 시간을 모니터링해 기준 지표를 확보합니다.
• 대용량 바이너리 자산이 있는 리포지터리에는 파일 크기 제한을 검토합니다.
• 시크릿이 포함될 가능성이 낮은 디렉터리에는 제외 항목을 적용합니다.

기존 워크플로와의 통합#

시크릿 푸시 보호가 기존 개발 방식을 보완하도록 다음 사항을 확인합니다.

• 심층 방어를 확보하도록 파이프라인 시크릿 탐지와 시크릿 푸시 보호를 함께 구성합니다.
• 시크릿 푸시 보호 절차를 개발자 문서에 반영합니다.
• 시크릿 유출을 최소화하는 안전한 코딩 방식을 개발자에게 교육하도록 보안 교육과 연계합니다.

롤아웃#

시크릿 푸시 보호를 대규모로 배포하려면 면밀한 계획과 단계적 적용이 필요합니다.

1. 활발히 개발 중인 중요도 낮은 프로젝트 두세 개를 선정해 기능을 시험하고 개발자 워크플로에 미치는 영향을 파악합니다.
2. 선정한 테스트 프로젝트에서 시크릿 푸시 보호를 켜고 개발자 피드백을 모니터링합니다.
3. 차단된 푸시를 처리하는 절차를 문서로 남기고 개발 팀에 새 워크플로를 교육합니다.
4. 파일럿 단계에서 탐지된 시크릿 수, 오탐 비율, 개발자 경험 피드백을 추적합니다.

충분한 데이터를 모으고 확대 배포 전에 필요한 워크플로 조정 사항을 파악하려면 파일럿 단계를 2주에서 4주 동안 진행하는 것이 좋습니다.

파일럿을 마친 다음에는 확대 롤아웃을 위해 다음 단계를 검토합니다.

1. 얼리 어답터 (3~6주차)
   • 보안에 민감한 리포지터리를 우선해 활성 프로젝트의 10~20%에 적용합니다.
   • 보안 인식이 높고 참여 의지가 있는 팀에 집중합니다.
   • 성능 영향과 개발자 경험을 모니터링합니다.
   • 실제 사용 결과를 바탕으로 절차를 다듬습니다.
2. 광범위 배포 (7~12주차)
   • 남은 프로젝트에 배치 단위로 점진적으로 적용합니다.
   • 개발 팀에 지속적인 지원과 교육을 제공합니다.
   • 시스템 성능을 모니터링하고 필요하면 인프라를 확장합니다.
   • 사용 패턴을 바탕으로 제외 규칙을 계속 최적화합니다.
3. 전체 적용 (13~16주차)
   • 남은 모든 프로젝트에 시크릿 푸시 보호를 활성화합니다.
   • 지속적인 유지 관리와 검토 절차를 마련합니다.
   • 제외 규칙과 탐지 패턴을 정기적으로 감사합니다.

차단된 푸시 해결#

시크릿 푸시 보호가 푸시를 차단하면 다음 중 하나를 수행할 수 있습니다.

• 시크릿을 제거합니다.
• 시크릿 푸시 보호를 건너뜁니다.

시크릿 푸시 보호 건너뛰기#

경우에 따라 시크릿 푸시 보호를 건너뛰어야 할 수 있습니다. 예를 들어 개발자가 테스트를 위해 자리 표시자 시크릿을 커밋해야 하거나, Git 작업 타임아웃 때문에 시크릿 푸시 보호를 건너뛰어야 할 수 있습니다.

시크릿 푸시 보호를 건너뛰면 감사 이벤트가 기록됩니다. 감사 이벤트 상세 정보에는 다음 항목이 포함됩니다.

• 사용한 건너뛰기 방식
• GitLab 계정 이름
• 시크릿 푸시 보호를 건너뛴 날짜와 시각
• 시크릿이 푸시된 프로젝트의 이름
• 대상 브랜치 (GitLab 17.4에서 도입)
• 시크릿 푸시 보호를 건너뛴 커밋 (GitLab 17.9에서 도입)

파이프라인 시크릿 탐지가 활성화되어 있으면 모든 커밋의 콘텐츠가 리포지터리에 푸시된 뒤 스캔됩니다.

푸시에 포함된 모든 커밋에 대해 시크릿 푸시 보호를 건너뛰려면 다음 중 하나를 수행합니다.

• Git CLI 클라이언트를 사용한다면 시크릿 푸시 보호를 건너뛰도록 Git에 지시합니다.
• 다른 클라이언트를 사용한다면 커밋 메시지 중 하나에 [skip secret push protection]을 추가합니다.

Git CLI 클라이언트의 경우#

명령줄에서 시크릿 푸시 보호를 건너뛰려면 다음과 같이 수행합니다.

• secret_push_protection.skip_all 푸시 옵션을 사용합니다.

  예를 들어 여러 커밋 중 하나에 시크릿이 포함되어 있어 푸시가 차단된 상황을 가정합니다. 시크릿 푸시 보호를 건너뛰려면 Git 명령에 푸시 옵션을 덧붙입니다.

  git push -o secret_push_protection.skip_all
  

모든 Git 클라이언트의 경우#

시크릿 푸시 보호를 건너뛰려면 다음과 같이 수행합니다.

• 커밋 메시지 중 하나에 기존 줄이나 새 줄로 [skip secret push protection]을 추가한 다음 커밋을 푸시합니다.

  예를 들어 GitLab Web IDE를 사용 중이고 여러 커밋 중 하나에 시크릿이 포함되어 있어 푸시가 차단된 상황을 가정합니다. 시크릿 푸시 보호를 건너뛰려면 최신 커밋 메시지를 편집해 [skip secret push protection]을 추가한 다음 커밋을 푸시합니다.

문제 해결#

시크릿 푸시 보호를 사용할 때 다음과 같은 상황이 발생할 수 있습니다.

예상치 못한 푸시 차단#

GitLab 17.11 이전에는 시크릿 푸시 보호가 수정된 모든 파일의 콘텐츠를 스캔했습니다. 이 때문에 시크릿이 diff에 포함되어 있지 않더라도 수정된 파일에 시크릿이 있으면 푸시가 예상치 못하게 차단될 수 있습니다.

GitLab 17.10 이하에서는 새로 커밋된 변경 사항만 스캔되도록 spp_scan_diffs 기능 플래그를 활성화합니다. 시크릿이 포함된 파일의 Web IDE 변경 사항을 푸시하려면 secret_checks_for_web_requests 기능 플래그도 함께 활성화해야 합니다.

파일이 스캔되지 않음#

일부 파일은 스캔에서 제외됩니다. 자세한 내용은 커버리지를 참고합니다.