API 키·토큰 유출 방지! GitLab Secret Detection 활용법

DevOps Engineer

2025년 3월 19일 · 약 12분

개발 과정에서 API 키, 데이터베이스 비밀번호, 접근 토큰과 같은 민감한 정보를 안전하게 관리하지 않으면 보안에 위협이 됩니다. 특히 .env 파일에 민감한 정보가 있는데, 실수로 Git에 커밋하는 경우, 보안 문제가 생길 수 있습니다.

GitLab의 Secret Detection을 활용하면 위와 같은 문제를 예방할 수 있습니다. 이 기능은 리포지터리에서 민감한 정보를 자동으로 탐지해 사용자가 빠르게 대응하도록 지원합니다. 이로써 보안 사고를 방지하고, 문제를 신속히 해결할 수 있습니다.

이 글에서는 GitLab Secret Detection의 동작 방식과 사용법을 자세히 알아보겠습니다.

Secret Detection 개념과 필요성

GitLab의 Secret Detection은 개인 키, 토큰과 같은 시크릿(Secret)*의 유출을 방지하고, 유출 시 빠르게 대응하도록 사용자 활동을 모니터링하는 기능입니다.

시크릿은 Git 리포지터리에 실수로 종종 커밋될 때가 있죠. 민감한 값이 원격 리포지터리에 push 되면, 리포지터리에 액세스할 수 있는 사람은 누구나 이 시크릿을 사용해 권한 있는 사용자를 사칭할 수 있습니다. Secret Detection은 이러한 위험을 방지합니다.

GitLab 샘플 리포지터리

위 샘플 리포지터리를 예시로 Secret Detection의 필요성을 더 짚어보겠습니다. 이 프로젝트에는 현재 README.md 파일만 있고, 다른 파일은 없습니다. 누군가는 ‘여기에 시크릿이 어디 있냐?’고 생각할 수 있죠. 그러나 과거 커밋이나 다른 브랜치에 시크릿이 포함된 파일이 있을 수 있습니다. 따라서 ‘이 프로젝트에 시크릿이 없다’고 단정할 수만 없습니다.

커밋과 브랜치가 적은 프로젝트에서는 수동으로 시크릿을 비교적 수월하게 찾을 수 있죠. 그러나 수천 개의 커밋과 수십 개의 브랜치가 있는 대규모 프로젝트에서는 수동 확인에 시간이 오래 걸리고, 비효율적입니다. Secret Detection을 활용하면 자동화로 이러한 비효율을 줄이고, 시크릿 탐지 과정을 간소화할 수 있습니다.

한편, Secret Detection은 GitLab.com(SaaS), Self-managed, Dedicated 환경에서 Free, Premium, Ultimate 요금제 사용자 모두 이용할 수 있습니다.

*시크릿(Secret): 애플리케이션은 CI/CD 서비스, 데이터베이스, 외부 저장소를 포함한 외부 리소스를 사용할 수 있음. 이러한 리소스에 액세스하려면 일반적으로 개인 키, 토큰과 같은 정적 방법을 사용하는 인증이 필요함. 이러한 방법은 다른 사람과 공유해선 안 되므로 ‘시크릿’이라고 부름

Secret Detection 세부 기능

Secret Detection의 세부 기능은 다음과 같습니다.

Pipeline Secret Detection: 프로젝트의 CI/CD 파이프라인 일부로 실행됩니다. 이는 리포지터리의 기본 브랜치에 대한 커밋에서 시크릿을 스캔합니다. Pipeline Secret Detection을 Merge request 파이프라인에서 활성화하면, 개발 브랜치에 대한 커밋에서 시크릿을 스캔해 기본 브랜치에 커밋하기 전에 대응할 수 있습니다.
Secret Push Protection: GitLab에 변경 사항을 push 할 때, 커밋에서 시크릿을 스캔합니다. Secret Push Protection을 건너뛰지 않는 한, 시크릿을 탐지할 때 push가 차단됩니다.
Client-side Secret Detection: GitLab에 저장하기 전에 이슈와 Merge request의 설명과 댓글에서 시크릿을 스캔합니다. 시크릿을 탐지하면 입력을 편집해 시크릿을 제거하거나, 거짓 긍정(false-positive)일 때 설명 또는 댓글을 저장하도록 선택할 수 있습니다.

이 글에서는 Pipeline Secret Detection을 활용해 시크릿을 탐지하는 방법을 주로 살펴보겠습니다.

Pipeline Secret Detection 동작법

Pipeline Secret Detection은 파일이 Git 리포지터리에 커밋되고 GitLab에 push 되면 파일을 스캔합니다. Pipeline Secret Detection을 활성화하면, secret_detection이라는 이름의 CI/CD job에서 스캔이 실행됩니다. 스캔을 실행하고, 모든 GitLab 티어에서 Pipeline Secret Detection JSON 보고서 아티팩트를 볼 수 있습니다.

특히 GitLab Ultimate를 사용하면, Pipeline Secret Detection 결과를 다음과 같이 처리할 수 있습니다.

Merge request 위젯, Pipeline Security Report, Vulnerability Report에서 결과를 볼 수 있습니다.
승인 워크플로에서 결과를 활용할 수 있습니다.
보안 대시보드에서 결과를 리뷰할 수 있습니다.
공개 리포지터리의 유출에 자동 대응할 수 있습니다.
보안 정책을 사용해 프로젝트 전체에 일관된 Secret Detection rules를 적용할 수 있습니다.

Pipeline Secret Detection 사용법

다음 순서에 따라 Pipeline Secret Detection을 실행하고, 시크릿을 탐지할 수 있습니다.

GitLab에서 Build > Pipeline Editor를 클릭합니다.
.gitlab-ci.yml에 아래 스크립트를 추가합니다.
```
include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml
secret_detection:
  variables:
    SECRET_DETECTION_HISTORIC_SCAN: "true"
```
SECRET_DETECTION_HISTORIC_SCAN 변수를 true로 설정하면, GitLab의 Secret Detection 기능이 리포지터리의 모든 브랜치와 커밋을 스캔합니다. 이로써 피처 브랜치나 과거 커밋에 남은 시크릿을 누락하지 않고 탐지할 수 있습니다.
변경된 .gitlab-ci.yml 파일을 저장해 커밋하고, 파이프라인이 실행되는 걸 확인합니다.
.gitlab-ci.yml에 Secret Detection이 적용된 모습

Secret Detection을 적용한 뒤, 파이프라인이 실행되는 모습
파이프라인 로그에서 스캔한 커밋 수, 스캔한 데이터 크기와 소요 시간, 발견된 유출(leaks) 수를 확인합니다. 이러한 정보를 기반으로 보고서를 생성할 수 있습니다.
파이프라인 로그
해당 파이프라인 실행이 완료되면, 발견된 취약점은 Vulnerability report에 저장됩니다. Secure > Vulnerability report에서 취약점을 확인합니다.
Vulnerability report 페이지
각 항목을 클릭해 보고서를 열고 정보가 노출된 파일과 관련 내용, 프로젝트 위치와 파일 내에 위치한 줄 번호를 파악합니다. 이러한 정보를 바탕으로 API 키를 재발급받고, 해당 키를 변수 처리하는 등 조치를 취합니다.
Vulnerability report에 나온 취약점의 상세 설명
해당 보고서를 토대로 이슈를 바로 생성하려면 Create Issue 버튼을 클릭합니다. 이슈를 생성하면 개발팀이 취약점을 신속하게 확인하고 수정할 수 있습니다.
Create Issue 버튼을 클릭해 이슈 생성 창으로 이동한 모습

맺음말

지금까지 GitLab Secret Detection의 동작 방식과 사용법을 알아봤습니다. Secret Detection은 휴먼 에러를 방지하고 보안 사고를 예방하는 강력한 기능입니다. 이 글에서 다룬 Pipeline Secret Detection 외에도 다양한 Secret Detection 기능으로 보안 위협에 철저히 대응할 수 있습니다.

여러분도 Secret Detection을 활용해 자기도 모르게 발생한 취약점을 신속하게 찾아 문제를 해결하시길 바랍니다. 이상으로 글을 마칩니다. 읽어주셔서 감사합니다. 🙂