히스토리

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

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

개요는 플레이리스트 시크릿 푸시 보호 시작하기를 참조하세요.

보안을 더욱 강화하기 위해 파이프라인 시크릿 감지와 시크릿 푸시 보호를 함께 사용하세요.

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

시크릿 푸시 보호는 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만 스캔합니다. 시크릿이 이미 파일에 있고 변경 사항의 일부가 아닌 경우 감지되지 않습니다.

푸시 크기 임계값#

푸시가 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 기능 플래그도 추가로 활성화해야 합니다.

파일이 스캔되지 않음#

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