본문으로 건너뛰기

시크릿 스캔

실수로 커밋한 API 키나 비밀번호가 Git 저장소에 그대로 남아 있다면 어떻게 될까요? 시크릿 스캔은 소스 코드와 커밋 이력 전체에서 노출된 자격증명을 자동으로 탐지하여, 공격자보다 먼저 문제를 발견할 수 있게 합니다.

시크릿 스캔이 왜 중요한가요?

한 번 커밋된 시크릿은 이후 커밋에서 삭제하더라도 Git 히스토리에 영구히 남습니다. 공개 저장소라면 노출 즉시 자동화된 봇이 키를 수집해 악용할 수 있습니다. 시크릿 스캔은 현재 코드뿐 아니라 과거 커밋까지 검사하여 이런 위험을 찾아냅니다.

시크릿 스캔 결과

개요​

  • 분석 대상: Git 저장소의 소스 코드 및 커밋 이력 전체
  • 분석 엔진: Gitleaks
  • 분석 기준: Gitleaks 정규식 룰셋 (API 키 · 토큰 · 비밀번호 패턴)
  • 탐지 값 처리: 탐지된 시크릿은 마스킹되어 표시 · 저장되며 원본은 저장하지 않습니다
커밋 이력 전체를 검사합니다

시크릿 스캔은 현재 시점의 파일뿐 아니라 커밋 이력 전체를 검사합니다. 따라서 과거에 잠깐 커밋되었다가 삭제된 시크릿도 탐지됩니다.

Step 1: 시크릿 스캔 진입​

  1. 사이드바의 "보안" 그룹 > [보안 분석] 메뉴를 클릭합니다.
  2. 페이지 상단의 카드 캐러셀에서 분석할 서비스를 선택합니다.
  3. 시크릿 탭을 선택합니다.
URL로 바로 진입하기

/security?id={서비스ID}&area=secrets URL로 진입하면 해당 서비스의 시크릿 탭이 바로 열립니다.

Step 2: 스캔 입력 항목​

시크릿 탭 상단의 트리거 바에서는 다음 항목을 사용합니다.

  • Git 저장소 URL (필수): 검사할 저장소 URL
  • 브랜치 (선택, 기본 main): 검사할 브랜치명
  • Git 토큰 (선택, Private Repo용): 저장소 읽기 권한이 있는 토큰

Git URL, 브랜치, 토큰은 설정 탭에서 SAST/IaC/시크릿 공통으로 등록할 수 있습니다. 설정 탭에 등록해두면 시크릿 스캔 시 자동으로 사용됩니다.

Git 토큰 폴백 동작

Git 토큰을 직접 입력하지 않으면, 백엔드는 설정 탭이나 기관/조직 설정에 저장된 토큰을 자동으로 사용합니다.

Step 3: 스캔 실행​

스캔 시작 버튼을 클릭하면 Gitleaks가 저장소를 클론하여 코드와 커밋 이력을 검사합니다. 진행률은 WebSocket을 통해 실시간으로 표시됩니다.

Gitleaks는 정규식 룰셋으로 다음과 같은 시크릿 패턴을 탐지합니다.

  • 클라우드 서비스 액세스 키 (AWS, GCP, Azure 등)
  • API 키 및 토큰 (GitHub, Slack, Stripe 등)
  • 비밀번호, 데이터베이스 접속 문자열
  • 개인 키 (PEM, SSH 키 등)

스캔이 완료되면 결과 화면이 자동으로 갱신됩니다.

Step 4: 결과 확인​

4.1 결과 요약​

스캔이 완료되면 다음 정보를 확인할 수 있습니다.

  • 총 탐지 수: 발견된 노출 시크릿의 총 개수
  • 유형별 분류: 탐지된 시크릿이 어떤 유형(API 키, 토큰, 비밀번호 등)인지 (매핑되지 않은 항목은 '미분류'로 표시)
  • 심각도별 분류: 탐지된 시크릿의 심각도 분포 (Critical/High/Medium/Low/Unknown) — 심각도가 확인되지 않은 항목은 Unknown으로 분류됩니다.
  • 검사한 저장소 URL 및 스캔 시각

4.2 탐지 항목 상세​

각 탐지 항목에서 다음 정보를 확인할 수 있습니다.

  • 위치: 시크릿이 발견된 파일 경로와 커밋
  • 시크릿 유형: 탐지된 자격증명의 유형
  • 마스킹된 탐지 값: 시크릿 값은 마스킹되어 표시됩니다 (원본은 저장하지 않음)

4.3 스캔 이력​

시크릿 탭의 스캔 이력 테이블에서는 시점별 시크릿 탐지 추세를 확인할 수 있습니다. 매 스캔마다 결과가 누적되므로 보안 개선 상황을 시계열로 추적할 수 있습니다.

  • 스캔 일시: 각 스캔 실행 시각
  • Critical/High/Medium/Low: 각 심각도별 탐지 건수
  • 탐지 총계: 누적 탐지 수와 이전 스캔 대비 증감 표시 (▲/▼)
  • 보는 중: 현재 결과 영역에 표시 중인 시점을 마크

이력 테이블의 행을 클릭하면 그 시점의 상세 결과(탐지된 시크릿 목록)가 결과 영역에 표시됩니다. 특정 시점의 노출된 자격증명 목록을 정확히 확인할 수 있습니다.

노출된 시크릿 대응 절차​

시크릿이 노출된 것이 확인되면 다음 순서로 대응하세요.

  1. 즉시 폐기 및 교체: 노출된 키/토큰은 코드에서 지우는 것만으로는 부족합니다. 해당 자격증명을 발급 기관에서 즉시 폐기(revoke) 하고 새 값으로 교체합니다.

  2. 코드에서 제거: 새 값은 코드에 직접 작성하지 말고 환경 변수나 시크릿 관리 도구로 주입합니다.

  3. 히스토리 정리 검토: 커밋 이력에 남은 시크릿은 코드 수정만으로 사라지지 않습니다. 필요 시 히스토리 재작성을 검토하되, 이미 폐기된 키라면 우선순위는 낮습니다.

코드에서 지우는 것만으로는 부족합니다

시크릿을 커밋에서 삭제해도 이전 커밋에는 그대로 남아 있습니다. 가장 확실한 대응은 노출된 자격증명 자체를 폐기하고 새로 발급하는 것입니다.

시크릿 노출 예방​

  • 환경 변수 사용: 자격증명은 코드가 아닌 환경 변수나 시크릿 관리 도구로 주입합니다.
  • .gitignore 활용: .env, 키 파일 등 시크릿이 담긴 파일은 .gitignore에 등록합니다.
  • 커밋 전 점검: 커밋 전 단계에서 시크릿을 점검하는 습관을 들이세요.
  • 정기 스캔: 시크릿 스캔을 정기적으로 실행하여 새로 유입된 노출을 빠르게 발견하세요.

문제 해결​

스캔 실패​

  • 코드 접근 불가: Git 토큰에 저장소 읽기 권한이 있는지 확인하세요. 설정 탭이나 기관 설정의 저장된 토큰이 자동으로 사용됩니다.

  • 타임아웃: 커밋 이력이 매우 긴 저장소는 검사 시간이 오래 걸릴 수 있습니다. 분석 범위를 특정 브랜치로 제한하세요.

오탐 (False Positive)​

테스트용 더미 키나 예시 값이 시크릿으로 탐지될 수 있습니다. 탐지 항목이 실제 자격증명인지 확인하고, 더미 값이라면 코드에 명확한 예시 표기를 남겨 혼동을 줄이세요.

관련 가이드​