gitleaks 딥다이브
— 코드에 숨은 비밀을 찾는 탐지기의 설계

1프로젝트 한줄 요약

Gitleaks는 소스 코드에 하드코딩한 비밀번호·API 키·토큰 등의 노출 후보를 찾아주는 프로그램입니다. 현재 파일과 과거 커밋을 따로 살피고, 의심스러운 문자열을 규칙과 문맥으로 걸러 보고서로 남깁니다. 사용자는 명령 하나를 실행하지만, 내부에서는 입력 읽기·규칙 선택·위치 계산·예외 처리·결과 출력이 각자의 역할을 합니다.

1-1. 세 명령은 서로 다른 범위를 검사한다

명령의 시작점은 cmd/git.go:runGit, cmd/directory.go:runDirectory, cmd/stdin.go:runStdIn입니다. 셋 모두 Detector.DetectSource를 호출합니다. 이 공통 지점을 찾으면 처음부터 모든 패키지를 읽을 필요가 없습니다.

# 설치된 Gitleaks로 실행하는 사용 예시
# Git 이력을 검사하고, 결과의 비밀값을 가린다
gitleaks git . --redact --report-format json --report-path findings.json

# 현재 디렉터리만 검사한다
gitleaks dir . --redact

# 텍스트를 표준입력으로 연결한다
printf '%s\n' '설정 예시 텍스트' | gitleaks stdin --redact

2왜 주목받는가

2-1. 유출을 찾는 위치가 개발자와 가깝다

2026-10-23 GitHub Trending Go Weekly #3에 오른 저장소입니다. 다만 순위만으로 특정 사건이나 기능이 인기 상승의 원인이라고 단정할 수는 없습니다. 여기서 살펴볼 것은 소스에 드러난 도입 편의성과 학습 가치입니다.

.pre-commit-hooks.yaml의 실행 명령은 gitleaks git --pre-commit --redact --staged --verbose입니다. 커밋 전에 스테이징한 변경을 검사하도록 연결합니다. .github/workflows/gitleaks.yml은 자신의 저장소를 Gitleaks Action으로 검사하며, 체크아웃에 fetch-depth: 0을 지정합니다. 이력의 깊이가 검사 범위를 결정하기 때문입니다.

이 도구의 매력은 탐지 알고리즘 하나보다, 같은 검사를 로컬 커밋 전과 CI에 반복해서 넣을 수 있다는 데 있습니다. 이것은 트렌딩 원인에 대한 통계적 증명이 아니라, 구현과 배포 경로에서 읽어낸 장점입니다.

2-2. 비슷한 도구와 비교하면 무엇이 보일까

경쟁 도구의 설명은 TruffleHog 공식 문서와 detect-secrets 공식 문서 기준입니다. 이 표는 속도나 정확도 순위가 아닙니다. 동일한 데이터·규칙·실행 조건으로 측정한 비교 수치는 없습니다.

2-3. 초보자가 읽기에도 구조가 알맞다

• 입구가 분명하다. main.go에서 cmd.Execute로 이어지고, 하위 명령마다 입력 소스를 선택합니다.
• 성능 기법이 눈에 보인다. 키워드 사전, 정규식, 조각 읽기, 동시성 제한을 각각 파일과 함수로 확인할 수 있습니다.
• 규칙도 소프트웨어처럼 검증한다. 규칙 생성 함수는 탐지되어야 할 예제와 오탐 예제를 함께 둡니다.
• 출력 규격이 다양하다. JSON·CSV·JUnit·SARIF·사용자 템플릿을 같은 결과 구조에서 만듭니다.

3기술 스택 전체 지도

3-1. 백엔드에 해당하는 핵심 처리부

상시 실행하는 애플리케이션 서버 대신 Go 프로세스가 입력을 읽고 결과를 만듭니다. go.mod의 모듈 경로는 현재 GitHub 조직명과 다른 github.com/zricethezav/gitleaks/v8이며, Go 지시문은 go 1.24.11입니다. 소스의 import를 따라갈 때는 이 모듈 경로를 기준으로 봐야 합니다.

모두 go.mod에 선언된 버전입니다. 선언 버전은 실행 측정값이나 최신 버전 추천을 뜻하지 않습니다. 데이터베이스에 탐지 결과를 쌓는 구조도 아니며, 기본 결과는 메모리의 []report.Finding에 모입니다.

3-2. 프론트엔드에 해당하는 사용자 접점

React·Vue 같은 SPA는 없습니다. 사용자 접점은 터미널이며, charmbracelet/lipgloss v0.5.0으로 발견 결과의 색과 강조를 표현합니다. 정적 보고서는 report/template.go의 Go text/template과 Masterminds/sprig/v3 v3.3.0을 사용합니다.

NewTemplateReporter는 Sprig 함수 중 env, expandenv, getHostByName을 제거합니다. 한편 text/template은 HTML 자동 이스케이프를 제공하지 않습니다. 새 HTML 보고서를 설계할 때는 입력 문자열을 어떤 문맥에 출력하는지 별도로 검토해야 합니다.

3-3. 인프라·빌드: 파일마다 버전과 경로가 다르다

의존성 파일의 Go 버전, CI의 Go 버전, 배포 이미지의 Go 버전은 각각 다른 약속이므로 따로 읽어야 합니다. Docker 빌드 명령은 gore2regex 태그를 지정하지 않습니다. 따라서 이 Dockerfile 경로는 regexp/stdlib_regex.go를, GoReleaser 설정은 regexp/wasilibs_regex.go를 선택합니다.

4아키텍처 심화 분석

4-0. 시스템 구조도

아래 그림은 일반적인 텍스트 검사 경로입니다. 압축 파일은 별도의 내부 파일 읽기를 거친 뒤 같은 경로로 합류합니다. 화살표는 데이터 흐름이며, 각 상자가 모두 별도 프로세스라는 뜻은 아닙니다.

4-1. 패턴 ① 입력 어댑터: 탐지기는 입력의 출신을 몰라도 된다

sources/source.go의 핵심 계약은 메서드 하나입니다. 구현체는 조각을 준비할 때마다 콜백인 yield를 부릅니다. 채널 전체를 탐지기 인터페이스로 노출하지 않고, 읽는 쪽의 차이를 이 계약 뒤에 둡니다.

// sources/source.go의 인터페이스
type FragmentsFunc func(fragment Fragment, err error) error

type Source interface {
    Fragments(ctx context.Context, yield FragmentsFunc) error
}

sources.Fragment에는 Raw, Bytes, FilePath, StartLine, CommitInfo 등이 있습니다. DetectSource는 이것을 받아 DetectContext에 넘깁니다. 새로운 입력원을 추가한다면 먼저 이 형식으로 바꾸는 방법을 생각하면 됩니다.

sources/git.go:Git.Fragments는 텍스트 패치에서 textFragment.Raw(gitdiff.OpAdd)로 추가된 행을 꺼냅니다. 기본 Git 명령은 git -C <저장소> log -p -U0 --full-history --all --diff-filter=tuxdb입니다. -U0은 변경 주변의 문맥 행을 0으로 설정합니다. 저장된 모든 커밋의 파일 전체를 매번 다시 여는 방식과 다릅니다.

sources/file.go:fileFragments는 기본 100 * 1_000바이트 버퍼로 읽고, readUntilSafeBoundary가 최대 25 * 1_000바이트를 더 읽어 빈 줄 경계(공백·탭·CR을 사이에 허용한 두 LF)를 찾습니다. sources/common.go의 주석에는 10KB라고 적혀 있지만 상수의 실제 값은 25,000입니다. 경계를 완벽하게 보장하는 알고리즘이 아니라, 문자열을 중간에서 자를 가능성을 줄이는 절충입니다.

4-2. 패턴 ② 단계별 필터: 비싼 검사 전에 후보를 줄인다

NewDetectorContext는 모든 규칙의 키워드로 Aho-Corasick 트라이를 만듭니다. DetectContext는 현재 검사 문자열을 소문자로 바꾸고 그 사전을 검색합니다. 키워드가 없는 규칙은 항상 검사하고, 키워드가 있는 규칙은 그중 하나라도 발견될 때 정규식을 실행합니다.

키워드는 정답을 판정하는 규칙이 아니라, 정규식을 실행할 대상을 줄이는 사전 필터입니다. 검사 조각에 없는 키워드만 규칙에 넣으면 정규식이 정확해도 검사를 건너뛸 수 있습니다.

// cmd/generate/config/rules/github.go:GitHubPat의 핵심 필드
// 설명 문자열과 예외 목록 등은 생략
RuleID:   "github-pat",
Regex:    regexp.MustCompile(`ghp_[0-9a-zA-Z]{36}`),
Entropy:  3,
Keywords: []string{"ghp_"},

detectRule는 정규식 일치 구간을 찾고 원문 위치를 계산한 뒤, SecretGroup이 지정되어 있으면 해당 캡처 그룹을 비밀값으로 선택합니다. 지정하지 않았는데 캡처 그룹이 있다면 첫 번째 비어 있지 않은 그룹을 사용합니다. 그래서 정규식 전체에 일치한 Match와 실제 비밀값인 Secret은 다를 수 있습니다.

그다음 detect/utils.go:shannonEntropy로 문자 분포를 계산합니다. 임계값이 0이 아니면 entropy <= r.Entropy인 후보를 버립니다. GitHubPat의 3은 확률이나 신뢰도 3점을 뜻하지 않습니다.

전역·규칙별 허용 목록과 gitleaks:allow 표시도 탐지 결과를 제외할 수 있습니다. processRequiredRules는 보조 규칙이 같은 조각에서 함께 발견되는지 확인하며, 설정된 행·열 거리 조건도 적용합니다. 이 복합 규칙은 같은 조각에서 문맥을 찾으므로, 파일이 나뉘거나 패치에서 문맥이 빠지면 결과도 달라집니다.

filter는 같은 행에서 더 구체적인 규칙이 찾은 비밀값에 포함되는 범용 규칙 결과를 줄입니다. 모든 중복을 전역적으로 제거하는 만능 집합 연산은 아닙니다. 또한 검사 문자열을 디코딩하면 codec.AdjustMatchIndex로 원문 좌표에 맞춥니다.

4-3. 패턴 ③ 제한된 동시성: 작업 수와 공유 상태를 따로 관리한다

detect/detect.go:NewDetectorContext의 초기화에는 semgroup.NewGroup(ctx, 40)이 있습니다. sources.Files.Fragments와 sources.Git.Fragments는 이 그룹에 작업을 넣고 sync.WaitGroup으로 완료를 기다립니다. 파일 수만큼 작업을 무제한으로 동시에 실행하는 설계가 아닙니다.

40은 CPU 코어 요구량이 아닙니다. 이 세마포어 그룹에서 동시에 실행하는 작업 수의 상한입니다. 규칙마다 고루틴을 하나씩 만드는 것도 아닙니다. DetectContext의 규칙 루프와, 입력 소스 쪽의 동시 실행 위치를 구분해 읽어야 합니다.

뮤텍스가 있다고 결과 순서까지 고정되지는 않습니다. 규칙은 map에 담기고 여러 입력 작업이 함께 진행됩니다. JSON 보고서의 행 순서보다 규칙 ID·파일·위치·개수로 결과를 비교하는 편이 적절합니다.

4-4. 패턴 ④ 검증을 거치는 설정 생성: 규칙도 제품의 일부다

config/gitleaks.toml은 생성된 기본 설정입니다. 원본 규칙은 cmd/generate/config/rules/의 Go 함수들입니다. cmd/generate/config/main.go가 이 함수들을 모으고, cmd/generate/config/rules/config.tmpl을 통해 TOML로 내보냅니다.

utils.Validate는 탐지되어야 하는 예제에서 결과가 나오는지, 오탐 예제에서는 결과가 나오지 않는지 실제 탐지기 호출로 확인하는 함수입니다. 생성기의 main은 규칙 검증과 ID 중복 검사도 수행합니다. CI는 go generate ./... && git diff --exit-code로 생성 결과가 저장된 파일과 같은지 확인합니다.

실행할 때는 cmd/root.go:initConfig가 설정 출처를 선택하고, config/config.go:ViperConfig.Translate가 문자열 정규식을 컴파일하며 키워드를 정규화합니다. 외부 설정 모양과 내부 실행 구조를 나눈 점도 배울 만합니다. maxExtendDepth = 2로 설정 확장의 깊이를 제한합니다.

마지막 출력은 report.Reporter 인터페이스의 Write로 연결됩니다. cmd/root.go:findingSummaryAndExit는 보고서 출력을 요청한 경우 보고서를 쓴 뒤, 발견 결과가 있으면 기본 종료 코드 1로 프로세스를 종료합니다. 검사 오류도 1이 될 수 있으므로, 자동화에서는 종료 코드와 로그를 함께 읽어야 합니다.

5디렉토리 구조 해부

5-1. 처음 읽을 파일 여섯 개

첫 회독에는 범위가 넓은 cmd/root.go를 통째로 외우려 하지 않아도 됩니다. 표준입력 한 줄이 JSON 결과가 되는 흐름을 먼저 그린 뒤 Git 입력으로 넓히면 됩니다. detect/git.go 등에는 이전 API와의 호환 경로도 있으므로 현재 CLI가 실제로 호출하는 함수를 출발점으로 삼으세요.

5-2. 줄 수를 책임별로 나누면 읽기 부담이 달라진다

전체는 Git이 추적하는 Go 파일이며 빈 줄·주석을 포함합니다. 런타임 비테스트는 cmd/generate/와 testdata/, _test.go를 제외한 수치입니다. 생성기 영역에는 테스트 파일도 들어 있어 일부 행은 서로 겹칩니다. 이 표를 단순 합산하면 안 되며, 테스트 줄 수가 곧 테스트 커버리지도 아닙니다.

6학습 포인트 (기술별)

6-1. Go 인터페이스: 작고 구체적인 계약부터

Source와 Reporter는 각각 입력과 출력의 경계를 정합니다. 전자는 조각을 내보내고, 후자는 발견 목록을 기록합니다. Go는 명시적으로 구현을 선언하지 않아도 필요한 메서드가 있으면 인터페이스를 만족합니다.

// report/json.go의 컴파일 시 인터페이스 만족 검사
var _ Reporter = (*JsonReporter)(nil)

// report/report.go의 출력 계약
type Reporter interface {
    Write(w io.WriteCloser, findings []Finding) error
}

실습 아이디어: 파일을 열지 않는 가상의 입력 소스를 종이에 설계하세요. 문자열 배열을 순서대로 Fragment로 내보낼 때 어떤 필드를 채워야 할까요? 파일 위치가 없다는 사실을 결과에서 어떻게 표현할지도 함께 정합니다.

6-2. 정규식과 알고리즘: 최종 판정과 사전 필터를 분리하기

키워드 검색은 후보 규칙을 좁히고, 정규식은 모양을 확인하며, 엔트로피는 일부 단순한 값을 걸러냅니다. Go 정규식 공식 문서는 입력 크기에 선형인 실행 시간을 설명합니다. 그렇더라도 규칙 수·디코딩 횟수·매치 수가 늘면 전체 비용은 커집니다. 정규식 한 번의 성질과 프로그램 전체의 성능은 구분해야 합니다.

실습 아이디어: 규칙에 올바른 키워드, 엉뚱한 키워드, 빈 키워드 목록을 각각 넣었을 때를 비교하세요. 탐지 여부가 바뀌는 이유를 DetectContext의 분기와 연결하면 사전 필터의 책임이 분명해집니다.

shannonEntropy는 문자 수를 map[rune]int로 세면서 분모는 len(data)를 씁니다. Go에서 문자열의 len은 바이트 수입니다. ASCII 시크릿과 다중 바이트 문자열에서 의미가 어떻게 달라질지 손으로 계산해 보세요. 변수명만 보고 “문자 수”라고 읽지 않는 연습이 됩니다.

6-3. Git과 스트리밍: 전체 파일 대신 변경 조각 다루기

NewGitLogCmdContext는 exec.CommandContext로 Git을 실행합니다. Git 저장 형식을 직접 구현하는 대신 Git의 패치 출력과 전용 파서를 조합한 것입니다. 반면 파일 입력은 io.Reader를 읽으므로 표준입력도 같은 타입으로 받을 수 있습니다.

실습 아이디어: 같은 가짜 토큰이 파일에 남은 경우, 커밋 후 파일에서 지운 경우, 이력까지 없는 얕은 저장소인 경우를 표로 비교하세요. “검사 결과가 0”이라는 숫자가 세 경우에서 같은 보장을 뜻하는지 설명해 봅니다.

6-4. 동시성과 오류: 성공·부분 검사·중단을 구분하기

컨텍스트는 종료 요청을 전파하고, 세마포어 그룹은 동시 작업량을 제한하며, 뮤텍스는 공유 상태를 보호합니다. 서로 다른 문제를 푸는 도구들입니다. DetectSource는 조각 콜백으로 받은 오류를 기록하고 다음 조각으로 진행하는 경로도 있습니다.

실습 아이디어: 실제 실행 없이 오류 경로를 색연필 세 색으로 표시해 보세요. 즉시 종료하는 곳, 오류를 반환하는 곳, 로그만 남기고 계속하는 곳을 구분합니다. 종료 코드만으로 검사 완전성을 판단하기 어려운 이유를 찾을 수 있습니다.

6-5. 테스트와 생성 코드: 오탐도 명세에 넣기

config/config_test.go:TestTranslate는 입력 설정·기대 결과·기대 오류를 묶은 표 형식 테스트입니다. sources/common_test.go:Test_readUntilSafeBoundary는 LF·CRLF·공백·안전 경계가 없는 경우를 다룹니다. detect/codec/decoder_test.go:TestDecode는 인코딩과 중첩 변환을 확인합니다.

실습 아이디어: 새 규칙을 만든다고 가정하고 탐지할 예제 3개와 제외할 예제 3개를 먼저 적으세요. 같은 값이 JSON·YAML·환경변수 문법에 들어갔을 때를 포함하면 문자열 하나보다 풍부한 명세가 됩니다. GenerateSampleSecrets가 여러 설정 문법의 예제를 만드는 이유도 여기에 있습니다.

6-6. 데이터 식별과 출력 규격: 지문은 해시가 아니다

AddFinding의 지문은 파일 경로·규칙 ID·시작 행을 연결한 문자열이며, 커밋이 있으면 앞에 커밋 ID도 붙입니다. 내용 자체를 암호학적 해시로 만든 값이 아닙니다. 줄이 이동하면 같은 비밀값이라도 식별 문자열이 달라질 수 있습니다.

# 파일 검사 지문 형태
fixtures/demo.txt:demo-token:1

# Git 검사 지문 형태 — COMMIT은 실제 커밋 ID 자리
COMMIT:demo.txt:demo-token:1

detect/baseline.go:IsNew는 지문 하나만 비교하지 않고 위치·메시지·엔트로피 등 여러 필드를 직접 비교합니다. report/sarif.go:SarifReporter.Write는 같은 발견 결과를 SARIF 2.1.0으로 표현합니다. 내부 식별 정책과 외부 교환 형식이 각각 필요하다는 예입니다.

좋은 학습 목표는 함수 이름을 외우는 것이 아니라, 입력 범위·판정 조건·예외·출력 사이의 계약을 설명하는 것입니다. 같은 설계는 로그 검사기, 코드 린터, 데이터 검증 CLI에도 응용할 수 있습니다.

7하드웨어 / 시스템 요구사항

README와 빌드 설정에는 CPU·RAM의 공식 최소 수치가 없습니다. GPU·모델 가중치·데이터베이스 서버는 이 탐지 경로의 필수 구성요소가 아닙니다. 실제 자원 사용량은 검사하는 파일·패치·규칙·디코딩·압축 깊이·발견 개수에 따라 달라집니다.

7-1. 제한 옵션은 속도와 검사 범위를 함께 바꾼다

sources.Files는 파일 전체 크기를 바이트 단위로 확인하지만, detectRule의 크기 확인은 현재 문자열 길이를 1,000,000으로 나눈 값을 사용합니다. 서로 다른 계층의 검사이므로 모든 모드에 같은 정밀도의 전역 메모리 상한이 생기는 것은 아닙니다.

7-2. 큰 저장소에서는 처리량보다 측정 조건부터

sources/file.go:extractorFragments는 ZIP·7z 입력이 임의 위치 읽기를 지원하지 않으면 임시 파일에 복사하는 경로가 있습니다. 또 발견 결과는 보고서를 쓰기 전까지 슬라이스에 쌓입니다. 따라서 100KB 입력 버퍼 하나만 보고 전체 메모리가 고정이라고 판단하면 안 됩니다.

cmd/diagnostics.go는 CPU·메모리 프로파일과 실행 추적을 지원합니다. 먼저 같은 커밋·규칙·입력 범위·빌드 태그로 조건을 맞추고 한 항목씩 바꿔 측정하세요. 선택적 HTTP 진단 모드는 localhost:6060에 프로파일 서버를 엽니다. CLI 제품에 웹 프론트엔드가 있다는 뜻은 아닙니다.

8직접 해볼 수 있는 실습 과제

다음 명령은 Gitleaks 실행 파일이 준비된 독자를 위한 실습입니다. Bash·zsh 계열 셸을 기준으로 하며, 보조 파일 생성에는 Python 3을 사용합니다. 실제 계정의 키는 필요 없습니다. 새로 만든 gitleaks-lab 안에서 순서대로 진행하고, 모든 예제는 임의로 정한 가짜 형식 DEMO_를 검사합니다.

발견 결과가 있으면 기본 종료 코드는 1입니다. 자동 종료 옵션을 켠 셸에서는 예상된 탐지 때문에 다음 줄이 실행되지 않을 수 있으므로 명령별로 확인하세요. 아래의 예상 결과는 규칙과 소스 흐름에서 도출한 것이며, 배포 버전 차이는 먼저 gitleaks version으로 기록합니다.

mkdir -p gitleaks-lab/fixtures gitleaks-lab/reports
cd gitleaks-lab
gitleaks version

cat > demo.toml <<'EOF'
title = "학습용 가짜 토큰 검사"

[[rules]]
id = "demo-token"
description = "학습용 DEMO 토큰"
regex = '''DEMO_([A-Z0-9]{12})'''
secretGroup = 1
keywords = ["DEMO_"]
EOF

printf '%s\n' 'DEMO_A1B2C3D4E5F6' > fixtures/demo.txt
gitleaks dir fixtures --config demo.toml --redact \
  --max-decode-depth 0 --report-format json --report-path reports/first.json

# 바로 직전 검사의 종료 코드를 확인한다. 예상: 1
printf '종료 코드: %s\n' "$?"

# 동일한 가짜 값을 표준입력으로 검사한다
printf '%s\n' 'DEMO_A1B2C3D4E5F6' | \
  gitleaks stdin --config demo.toml --redact --max-decode-depth 0

gitleaks dir fixtures --config keyword.toml --redact --max-decode-depth 0
gitleaks dir fixtures --config entropy.toml --redact --max-decode-depth 0

mkdir history-lab
cd history-lab
git init -q
git config user.name '학습자'
git config user.email 'learner@example.invalid'
printf '%s\n' 'DEMO_A1B2C3D4E5F6' > demo.txt
git add demo.txt
git commit -q -m '학습용 가짜 토큰 추가'
printf '%s\n' '공개 가능한 예제' > demo.txt
git add demo.txt
git commit -q -m '현재 파일에서 가짜 토큰 제거'
cd ..

gitleaks dir history-lab --config demo.toml --redact --max-decode-depth 0
gitleaks git history-lab --config demo.toml --redact --max-decode-depth 0

python3 - <<'PY'
from pathlib import Path
import base64
import zipfile
fake = b'DEMO_A1B2C3D4E5F6'
Path('encoded.txt').write_text(base64.b64encode(fake).decode() + '\n')
with zipfile.ZipFile('bundle.zip', 'w', compression=zipfile.ZIP_DEFLATED) as z:
    z.writestr('demo.txt', fake + b'\n')
PY

# Base64 원문만 볼 때와 한 번 해제할 때
gitleaks dir encoded.txt --config demo.toml --redact --max-decode-depth 0
gitleaks dir encoded.txt --config demo.toml --redact --max-decode-depth 1 \
  --report-format json --report-path reports/decoded.json

# 압축 내부 탐색은 별도의 옵션이다
gitleaks dir bundle.zip --config demo.toml --redact --max-archive-depth 0
gitleaks dir bundle.zip --config demo.toml --redact --max-archive-depth 1 --verbose

# 최초 결과 1개를 기준선으로 기록. 예상 종료 코드: 1
gitleaks dir fixtures --config demo.toml --redact --max-decode-depth 0 \
  --report-format json --report-path reports/base.json

# 같은 입력과 같은 가림 정책. 예상 발견: 0개
gitleaks dir fixtures --config demo.toml --redact --max-decode-depth 0 \
  --baseline-path reports/base.json

# 새 행에 다른 가짜 토큰 추가
printf '%s\n' 'DEMO_Z9Y8X7W6V5U4' >> fixtures/demo.txt

# 신규 결과만 보고서에 기록. 예상 발견: 1개
gitleaks dir fixtures --config demo.toml --redact --max-decode-depth 0 \
  --baseline-path reports/base.json \
  --report-format json --report-path reports/new.json

실습에서 가장 중요한 기록은 발견 개수와 함께 남긴 검사 범위·설정·버전입니다. 결과가 예상과 다르면 기본값, 설정 출처, 경로, 이력 깊이, 허용 목록 순서로 확인하세요.

9관련 기술 심화 학습 로드맵

주당 3~5시간을 가정한 학습 제안입니다. 공식 소요 시간이 아닙니다. Go 문법을 처음 접한다면 1주차를 늘리고, 이미 CLI를 만들어 봤다면 3주차부터 시작해도 좋습니다.

9-1. 다음 단계는 다른 입력을 가진 작은 검사기

Gitleaks 전체를 복제하기보다, 학습용 로그에서 금지된 패턴을 찾는 CLI를 설계해 보세요. 입력은 파일·표준입력 두 가지, 결과는 JSON 하나로 시작합니다. 규칙·입력·보고서를 서로 분리하고, 오류와 발견을 구분하는 계약을 먼저 적습니다.

• 인터페이스 기준: 새 입력을 추가할 때 기존 탐지 코드를 바꿔야 하는가?
• 정확성 기준: 무엇을 못 찾는지, 어떤 예외로 건너뛰는지 설명할 수 있는가?
• 성능 기준: 시간·메모리에 영향을 줄 변수를 구분하고 한 번에 하나씩 측정하는가?
• 운영 기준: 같은 버전과 정책을 로컬·CI에서 재현하고 부분 검사 로그를 구별하는가?

10핵심 키워드 사전

영어 식별자를 모두 번역해서 기억할 필요는 없습니다. Source는 조각을 만들고, Detector는 발견을 만들며, Reporter는 결과를 기록한다는 세 문장을 출발점으로 삼으세요.

11참고 링크

11-1. 공식 저장소·사용 문서

• Gitleaks 공식 저장소 — 소개·현재 유지 방침·사용 방법
• 분석 커밋의 README — 명령·설정·복합 규칙·디코딩 설명
• v8.30.1 릴리스 — 배포 버전의 기준점
• Go 패키지 문서 — 코드의 모듈 경로와 공개 타입 확인
• Gitleaks Action — CLI와 별도로 배포되는 GitHub 통합
• MIT 라이선스 원문 — 사용·수정·배포 시 확인할 조건

11-2. 본문에서 따라간 소스

• cmd/root.go — 플래그 기본값·설정 우선순위·보고서·종료 처리
• sources/source.go · sources/git.go — 입력 계약과 Git 패치 처리
• sources/file.go · sources/common.go — 조각 읽기·압축 내부 처리·경계 탐색
• detect/detect.go · detect/utils.go — 핵심 판정·엔트로피·결과 조정
• detect/baseline.go · detect/codec/decoder.go — 기준선 비교·인코딩 해제
• config/config.go · config/gitleaks.toml — 설정 변환과 222개 기본 규칙
• cmd/generate/config/rules/github.go · cmd/generate/config/utils/validate.go — 대표 규칙과 탐지·오탐 예제 검증
• report/template.go · report/sarif.go — 사용자 템플릿과 SARIF 출력
• go.mod · Dockerfile · .goreleaser.yml — 의존성과 빌드 경로
• 테스트 CI — 경쟁 상태 검사·운영체제 매트릭스·설정 생성물 검증

11-3. 관련 기술을 더 읽을 곳

• Go 공식 학습 안내 · io 패키지 · context 패키지 — 언어와 스트림·취소 모델
• Go regexp 문서 — 정규식 문법·캡처·실행 시간의 성질
• Aho-Corasick 구현 · Cobra · Viper — 실제 의존성의 사용법
• git log 문서 · git diff 문서 — 이력·패치·스테이징의 차이
• SARIF 2.1.0 표준 — 정적 분석 결과의 교환 규격
• TruffleHog · detect-secrets — 탐지·검증·기준선 관리 접근 비교

현재 상태 (2026-10-23 확인)

줄 수는 해당 확장자의 추적 파일을 대상으로 빈 줄·주석을 포함해 센 물리적 줄 수이며, 끝에 개행이 없어도 마지막 행을 포함합니다. .git 내부 데이터는 제외하며, Go에는 생성기와 테스트데이터가 포함됩니다. 보고서 템플릿은 HTML·CSS 등의 혼합 내용이므로 순수 HTML 또는 JavaScript 줄 수로 분리하지 않았습니다. 전체 파일 수에는 위 표에서 따로 집계하지 않은 확장자의 파일도 포함됩니다.