TruffleHog은 소스코드, git 히스토리, 클라우드 스토리지(S3, GCS 등), Slack, Jira, Docker 이미지 등 다양한 소스에서 유출된 자격증명(API 키, 토큰, 비밀번호 등)을 찾아내는 시크릿 스캐너입니다. 단순 패턴 탐지에 그치지 않고 발견된 시크릿을 실제 API에 대해 '검증(verify)'하여 살아있는 자격증명인지 확인하고, 검증된 키에 대해서는 권한/스코프까지 분석(analyze)해주는 것이 핵심 차별점입니다. Go로 작성된 단일 바이너리 CLI이며 Docker, 액션(action.yml), pre-commit 훅 형태로도 배포됩니다.
main.go의 kingpin 기반 CLI가 git/github/s3/docker 등 소스(pkg/sources)를 선택해 스캔을 시작하면, 각 소스는 데이터를 청크(chunk) 단위로 만들어 채널에 흘려보냅니다. pkg/decoders가 base64 등으로 인코딩된 내용을 디코딩하고, pkg/detectors 아래 수백 개의 개별 detector 패키지(정규식+키워드 기반)가 각 청크를 스캔해 detectors.Result(발견된 시크릿, SecretParts 등)를 생성합니다. no-verification이 아니면 각 detector가 실제 서비스 API에 요청을 보내 자격증명이 유효한지 검증하고(verificationcache로 중복 검증 방지), pkg/analyzer의 서비스별(analyzers/github, analyzers/anthropic 등) 분석기가 토큰의 권한/스코프를 조회해 보여줍니다. 결과는 pkg/output을 통해 텍스트/JSON/SARIF/GitHub Actions 포맷 등으로 출력됩니다. hack/checksecretparts 같은 정적분석 도구와 다양한 GitHub Actions 워크플로(.github/workflows)가 detector 품질과 회귀를 CI에서 검증합니다.
- STEP 01
go build 또는 Docker 이미지로 trufflehog 바이너리를 빌드/받아 `trufflehog git file://.` 같은 명령으로 로컬 저장소 히스토리를 스캔하면 콘솔에 진행 로그와 함께 발견된 시크릿 목록이 표시됩니다.
- STEP 02
기본 실행 시 발견된 각 시크릿에 대해 실제 API 호출로 검증을 시도하므로, 네트워크가 없거나 --no-verification을 안 주면 스캔이 느려지고 verified/unverified/unknown 상태가 각각 출력되는 것을 보게 됩니다.
- STEP 03
--json 옵션을 주면 사람이 읽기 좋은 텍스트 대신 라인 단위 JSON 결과가 나오고, 이를 파이프로 jq 등에 연결해 CI 파이프라인에 통합하는 흐름을 체험하게 됩니다.
- STEP 04
GitHub Actions로 action.yml을 사용하면 PR diff 범위만 스캔하도록 설정할 수 있고, 결과를 SARIF로 출력해 GitHub 코드 스캐닝 탭에 업로드하는 것도 시도해볼 수 있습니다.
- STEP 05
pre-commit 훅(.pre-commit-config.yaml)을 로컬 리포에 등록하면 커밋 시점에 스테이지된 변경분만 즉시 스캔되어, 실수로 시크릿을 커밋하기 전에 차단되는 경험을 하게 됩니다.
- STEP 06
analyze 서브커맨드로 발견된 특정 키 타입(github, stripe 등)을 넣으면 해당 키가 가진 스코프/권한 목록이 상세히 출력되는 것을 확인할 수 있습니다.
실행하고 나면 스캔 대상(git 저장소, S3 버킷, Slack 워크스페이스 등)에서 실제로 살아있는(verified) 자격증명 목록, 그 위치(파일/커밋/라인), 그리고 verified 키의 경우 어떤 권한 범위를 갖는지까지 담긴 리포트를 손에 넣게 됩니다. JSON/SARIF 출력을 택하면 이 결과를 그대로 CI/CD 파이프라인이나 보안 대시보드에 연결할 수 있습니다.
검증(verify) 단계는 대상 서비스에 실제 네트워크 요청을 보내므로, 스캔 대상이 크거나 detector가 많으면 시간이 오래 걸리고 대상 서비스의 API 레이트리밋에 걸릴 수 있습니다.
다수의 detector와 analyzer가 외부 서비스별 API 스펙에 의존하므로, 해당 서비스의 API가 변경되면 검증/분석 정확도가 영향을 받을 수 있습니다(파일 트리에 100개 이상의 개별 서비스 analyzer가 존재).
README 앞부분에 제공된 내용은 프로젝트 전체 설명이 아니라 `.github/workflows` 디렉터리의 PR 승인 체크 워크플로 문서였으며, 실제 사용법이나 CLI 옵션 전체는 이 자료만으로는 확인할 수 없습니다.
go.mod에 명시된 방대한 의존성(클라우드 SDK, DB 드라이버 등)으로 인해 소스 빌드 시 최초 빌드 시간과 바이너리 크기가 상당할 수 있습니다.
CI/CD 파이프라인이나 pre-commit 단계에서 '탐지+실증(verify)'까지 한 번에 처리하고 싶은 보안 엔지니어/DevSecOps 팀에게 적합한 도구로 보입니다. 코드 구조(pkg/detectors, pkg/analyzer, pkg/sources로 명확히 분리된 계층), 다양한 CI 워크플로(detector-tests, detector-corpora-test, smoke, secrets 등)와 정적분석 보조 도구(hack/checksecretparts)가 실제로 존재하는 것을 파일 트리와 대표 파일에서 직접 확인했으므로, 단순 데모 수준이 아니라 지속적으로 유지보수되는 실전 프로젝트라는 판단은 신뢰할 수 있습니다. 다만 본 검토는 제공된 파일 일부와 워크플로 문서 기반이며, 실제 CLI 사용성이나 전체 README의 사용법 설명은 직접 실행해봐야 완전히 확인할 수 있습니다.