[Opensource] Gitleaks 이해하고 활용하기 -1 : homebrew를 이용한 간단 스캔 방법

해당 글에서는 OpenSouce 중 Gitleaks를 이해하고 이를 이용하여 민감정보를 찾는 간단한 스캔방법에 대해 알아봅니다

 

1) Gitleaks

---

💡 Gitleaks

- Git 저장소(Repository) 내에 포함된 민감 정보(API Key, 비밀번호, 토큰, 인증서, 개인키 등)를 탐지하는 보안 도구를 의미합니다. 민감정보를 탐지하여 실수로 소스코드 내에 커밋이 된 내용들을 빠르게 찾아낼 수 있습니다.

- 특히, 이미 원격 저장소 내에 Commit & Push 작업을 수행하면 저장소 내에 이력으로 모든 기록이 남기 때문에, 잘못 올린 한 번 잘못 올린 민감정보는 파일을 삭제하더라도 히스토리에 남아있습니다.
- 그렇기에, 원격 저장소 내에 민감정보를 올리지 않도록 해야 합니다.

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

GitHub - gitleaks/gitleaks: Find secrets with Gitleaks 🔑

 

 

💡 [참고] 아래와 같이 Commit & Push로 원격 저장소에 올라간 파일을 삭제하더라도, Git 히스토리 내에서는 민감정보가 남아있습니다.

 

 

💡[참고] 이전에 원격 저장소에 Commit & Push 된 히스토리를 삭제하는 방법은 아래를 이용하여서 제거하였습니다

[Github] 원격 저장소의 Commit 내용 지우기 : API 키 노출 시 해결 방법

 

 

1. 사용 목적

---

💡 사용 목적

- Gitleak을 사용하는 목적은 아래와 같은 문제점을 사전에 방지할 수 있습니다.

문제점	Gitleak 해결 방법
개발자가 실수로 키 커밋	커밋 전에 자동 탐지하여 push 차단할 수 있습니다.
이미 히스토리에 포함된 키	전체 Repo 스캔하여 위치 표시가 됩니다.
팀원들이 기준 없이 비밀정보 관리	.gitleaks.toml 규칙으로 일관된 정책 유지할 수 있습니다.
CI/CD에서 Secret 유출 위험	GitHub Actions/GitLab CI에서 자동 검증을 수행 할 수 있습니다.

 

 

[더 알아보기]

💡 커밋 전에 자동 탐지를 해서 push 자체를 차단한다는 게 뭘까?

- 커밋 전에 사전에 자동으로 탐지하여 commit, push 자체를 차단하는 pre-commit, pre-push 작업을 수행할 수 있습니다.

1. pre-commit
- 커밋(commit) 직전에 실행이 됩니다. 스테이지 된 파일의 경우 커밋을 실패하는 경우 커밋을 수행하지 못하게 막습니다.
ex) 코드 포맷팅, lint, 테스트, Gitleaks 검사 등에 사용이 됩니다.

2. pre-push
- 푸시(push) 직전에 실행이 됩니다. 로컬 저장소에서 원격 저장소로 파일을 올리는 push 과정에서 푸시 자체를 수행하지 못하게 막습니다.
ex) 민감 정보가 있는 커밋을 원격으로 올리는 것을 방지하고 싶은 경우에 사용이 됩니다.

- 결론적으로, 사전에 정의해 둔 Git Hook을 통해서 각각의 단계를 감지하여서 사전 검증을 수행하는 방식으로 진행을 합니다.

 

https://azure.github.io/AKS-DevSecOps-Workshop/modules/Module2/Lab-2c.html

 

[더 알아보기]

💡 pre-commit과 pre-push 과정은 언제 발생하는 것일까?

- Git Hook 과정에서 수행이 됩니다. Git이 내부적으로 이미 준비해 둔 특정 타이밍에 해당되는 스크립트로 pre-commit과 pre-push를 감지하여서 수행이 됩니다.
- .git 내에 hook 파일을 구성하여서 hook을 구성할 수 있습니다.

Git - Git Hooks

 

2. 탐지 대상

---

💡 탐지 대상

- 기본적으로 Gitleaks에서 탐지하는 ‘민감정보’ 대상입니다. 이뿐만 아니라 gitleaks의 toml을 이용하여서 특정 패턴, 특정 민감 정보, 규칙을 정의하여서 추가적 탐지 및 제외가 가능합니다.

항목	설명
AWS Access Key / Secret Key	AWS 계정에 접근하기 위한 인증 키. Secret Key가 유출되면 S3, EC2, RDS 등 전체 리소스가 탈취되거나 삭제될 수 있음.
GitHub Personal Access Token(PAT)	GitHub API 사용 및 private repo 접근을 위한 인증 토큰. 유출되면 코드 유출, 저장소 삭제, 악성코드 삽입 가능.
Database URL & Password	DB 접속 주소, 계정, 비밀번호. 유출되면 데이터 조회·변조·삭제 가능. 개인정보 포함 DB일수록 위험 증가.
OAuth Token (Google, Kakao, Naver 등)	외부 서비스 계정을 대신 사용하도록 허용하는 토큰. 악용 시 사용자 정보 조회, API 사용료 폭증 위험.
Private Key (id_rsa 등)	SSH 접속용 개인키. 유출되면 서버에 직접 로그인 가능. 비밀번호보다 훨씬 위험.
JWT Secret / Signing Key	JWT 서명에 사용되는 비밀 값. 유출되면 공격자가 임의의 JWT 생성 가능 → 모든 인증 우회 가능.
Slack Webhook URL	Slack 특정 채널에 메시지를 보낼 수 있는 URL. 유출되면 스팸/피싱 메시지 자동 발송에 악용됨.
사용자 정의 정규식 기반 Secret (Custom Regex)	기업/프로젝트마다 특정 패턴으로 생성되는 고유 키들(API Key, 내부 인증 토큰 등). 유출 시 시스템 전체가 위험해질 수 있음.

 

 

[ 더 알아보기 ]

💡 Gitleaks Configuration File(=toml)

- Gitleaks가 “어떤 정보를 어떻게 탐지할지 정의하는 규칙 파일”입니다.
- 즉, Gitleaks의 탐지 엔진을 직접 커스터마이징 하는 설정 파일을 의미합니다.

title = "프로젝트에 맞는 Gitleaks 설정"

[[rules]]         # 탐지 규칙(여러 개 가능): API Key, Token, Password 패턴 정의
[allowlist]       # 제외 규칙: 특정 파일, 경로, 문자열 무시
[whitelist]       # 제외할 파일/폴더/정규식
[global]          # 전체 글로벌 설정

 

 

2) Gitleaks 설치 및 활용 -1: homebrew

---

 

1. 로컬 설치

---

💡 로컬 설치

- MacOS 내에서 homebrew를 이용하여서 간단하게 설치를 합니다.

 

 

gitleaks

 

 

3) Gitleak 스캔

---

 

💡 Gitleak 스캔

- Git 저장소 또는 로컬 파일들 안에 있는 민감정보(Secrets)를 자동으로 탐지하는 보안 스캐너를 의미합니다. 이를 통해서 API Key, Password, Token, Private Key, 인증 정보가 실수로 커밋되었을 때에 대한 탐지를 수행합니다.

항목	현재 브랜치 내 소스코만 스캔 방식	모든 히스토리 포함 방식
현재 디렉토리의 모든 파일	스캔	스캔
서브폴더 모든 파일	스캔	스캔
.git 내부(소스 히스토리)	스캔 안 함	스캔
과거 커밋(전체 history)	스캔 안 함	스캔
stash	스캔 안 함	스캔 안 함
submodule	스캔	스캔
LFS	파일 자체는 스캔(단, 히스토리 X)	스캔

 

1. 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)

---

💡 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)

- 현재 디렉터리 전체를 스캔하지만, Git 히스토리(과거 커밋 기록)는 완전히 무시하고 현재 파일만 검사합니다.

 

항목 스캔	범위
현재 디렉토리의 모든 파일	스캔
서브폴더 모든 파일	스캔
.git 내부(소스 히스토리)	스캔 안 함
과거 커밋(전체 history)	스캔 안 함
stash	스캔 안 함
submodule	스캔
LFS	스캔

 

# 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)
$ gitleaks detect --source . --no-git

 

 

[ 더 알아보기 ]

💡 Git history가 뭘까
- 과거에 Commit & Push 한 기록들 전체를 의미합니다.

 

2. 전체 스캔(Git Commit & Push 이력 포함)

---

💡 전체 스캔(Git Commit & Push 이력 포함)

- 현재 디렉터리 전체 파일을 스캔합니다. 즉, 프로젝트 루트(.) 안에 모든 파일을 확인하고 수행합니다.
- 숨김파일도 포함하여서 스캔을 합니다.

항목	스캔 여부
현재 디렉토리의 모든 파일	스캔
서브폴더 모든 파일	스캔
.git 내부(소스 히스토리)	스캔
과거 커밋(전체 history)	스캔
stash	스캔 안 함
submodule	스캔
LFS	스캔

 

# 전체 스캔
$ gitleaks detect --source .

 

 

 

[ 더 알아보기 ]

💡 git 히스토리를 포함하지 않은 게 포함한 것보다 많이 나왔는데 왜 그럴까?

- gitignore로 인해 git 히스토리에는 포함하지 않지만 로컬에는 포함하는 경우에 이에 해당이 될 수 있습니다.

 

 

3. 전체 스캔 결과 JSON 파일로 저장

---

💡 전체 스캔 결과 JSON 파일로 저장

- Commit & Push에 대한 Git 이력을 gitleaks-report.json 파일로 루트 경로에 저장을 합니다.

# 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외) 결과를 gitleaks-report.json 파일로 루트 경로에 저장
$ gitleaks detect --source . --no-git --report-path gitleaks-report.json

# 전체 스캔(Git Commit & Push 이력 포함) 결과를 gitleaks-report.json 파일로 루트 경로에 저장
$ gitleaks detect --source . --report-path gitleaks-report.json

 

 

3.1. 전체 스캔 결과 및 JSON 파일 확인

---

💡 전체 스캔 결과 및 JSON 파일 확인

- 루트 경로에 스캔 정보를 확인할 수 있고, 리포트를 json으로 받아볼 수 있게끔 명령어를 실행하였고, 프로젝트의 루트 경로에 gitleaks-report.json 파일이 생성이 됩니다.

 

 

3.2. JSON 파일 확인

---

💡 JSON 파일 확인

- json 파일을 확인하였을 때 아래와 같이 민감정보에 해당하는 정보들이 탐지가 되었습니다.

 

 

 

 

 

오늘도 감사합니다. 😀