TruffleHog là gì? Cách phát hiện API Key, Token và Secret bị lộ trong Git

Trong quá trình phát triển phần mềm, việc vô tình commit các thông tin nhạy cảm như API Key, Access Token, mật khẩu database hoặc Private Key là một lỗi khá phổ biến.

Ví dụ:

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxxxx
DATABASE_PASSWORD=123456
STRIPE_SECRET_KEY=sk_live_xxxxx

Nếu những giá trị này bị push lên GitHub, GitLab hoặc xuất hiện trong file build frontend, chúng có thể bị người khác lấy được và sử dụng trái phép.

Một công cụ rất hữu ích để phát hiện vấn đề này là TruffleHog.

TruffleHog là gì?

TruffleHog là công cụ chuyên dùng để tìm kiếm các secret bị lộ trong:

Git repository
Git history
File và thư mục local
Docker image
GitHub hoặc GitLab repository
Cloud storage
Build output như dist/, .next/
Log hoặc dữ liệu truyền qua stdin

TruffleHog có thể phát hiện nhiều loại secret phổ biến như:

AWS Access Key
GitHub Token
Stripe Secret Key
OpenAI API Key
Database credentials
Private Key
JWT Secret
PostgreSQL connection string

Điểm đặc biệt của TruffleHog là nó không chỉ tìm các chuỗi trông giống secret mà còn có khả năng xác minh xem secret đó còn hoạt động hay không.

TruffleHog hoạt động như thế nào?

Quá trình đơn giản có thể hiểu như sau:

Source Code / Git History
        ↓
TruffleHog Scanner
        ↓
Tìm chuỗi giống Secret
        ↓
Nhận diện loại Secret
        ↓
Xác minh Secret
        ↓
Hiển thị kết quả

Ví dụ TruffleHog phát hiện một GitHub Token:

Detector Type: Github
File: src/config.ts
Line: 15
Commit: a82fc93

Tùy từng trường hợp, kết quả thường được phân thành ba trạng thái.

Verified

Secret đã được xác minh và vẫn có khả năng sử dụng được.

Đây là trường hợp nguy hiểm nhất.

verified 🔴

Nếu gặp trường hợp này, cần revoke hoặc rotate secret ngay lập tức.

Unknown

TruffleHog nhận diện được secret nhưng không thể xác minh.

Nguyên nhân có thể là:

Network error
API provider không phản hồi
Rate limit
Firewall

Nên coi secret này là nguy hiểm cho tới khi kiểm tra xong.

Unverified

Chuỗi dữ liệu trông giống secret nhưng TruffleHog không xác nhận được nó còn hợp lệ.

Ví dụ có thể là:

Key test
Key đã hết hạn
Key đã bị revoke
False positive

Cài đặt TruffleHog

Trên macOS có thể cài nhanh bằng Homebrew:

brew install trufflehog

Sau đó kiểm tra:

trufflehog --version

Nếu command hiển thị version thì TruffleHog đã được cài thành công.

Quét toàn bộ Git History

Đây là một trong những chức năng hữu ích nhất của TruffleHog.

Trong thư mục repository:

trufflehog git file://. --results=verified,unknown

Lệnh này sẽ kiểm tra lịch sử Git để tìm các secret từng được commit.

Điều này rất quan trọng vì đôi khi developer đã xóa secret khỏi code hiện tại nhưng secret vẫn còn trong Git history.

Ví dụ:

Commit A
.env chứa AWS key

Commit B
xóa AWS key

Code hiện tại không còn AWS key nhưng commit A vẫn lưu nó.

TruffleHog có thể phát hiện trường hợp này.

Quét các file hiện tại

Nếu muốn kiểm tra các file trong project, kể cả file chưa được commit:

trufflehog filesystem .

Tuy nhiên project Node.js thường có thư mục rất lớn như:

node_modules
dist
.git

Vì vậy nên tạo file exclude:

node_modules/
\.git/

Ví dụ lưu thành:

.trufflehog-exclude

Sau đó chạy:

trufflehog filesystem . \
  -x .trufflehog-exclude \
  --results=verified,unknown

Việc này giúp giảm đáng kể số lượng file không cần thiết phải quét.

Kiểm tra Angular hoặc React build

Đây là một trường hợp rất quan trọng đối với frontend developer.

Ví dụ trong Angular:

export const environment = {
  apiSecret: 'sk_live_xxxxx',
};

Khi chạy:

npm run build

giá trị này có thể bị đưa trực tiếp vào:

dist/main.xxxxx.js

File JavaScript này được tải xuống trình duyệt của người dùng.

Điều đó có nghĩa là secret không còn là secret nữa.

Có thể dùng TruffleHog kiểm tra build output:

npm run build

trufflehog filesystem dist \
  --results=verified,unknown \
  --fail

Nếu tìm thấy secret, command sẽ trả về lỗi và có thể ngăn quá trình deploy.

Đối với Next.js có thể kiểm tra:

trufflehog filesystem .next \
  --results=verified,unknown \
  --fail

Kiểm tra Docker Image

Secret đôi khi không nằm trong source code nhưng lại bị copy vào Docker image.

Ví dụ:

COPY .env /app/.env

Đây là một lỗi khá nguy hiểm.

Có thể kiểm tra Docker image bằng:

trufflehog docker \
  --image docker://myapp:latest \
  --results=verified,unknown

Trước khi push image lên registry, việc scan image là một bước khá hữu ích.

Dùng TruffleHog trong CI/CD

Thay vì chờ đến lúc secret bị lộ mới kiểm tra, tốt hơn nên chạy TruffleHog tự động mỗi khi có Pull Request.

Quy trình có thể như sau:

Developer Push Code
       ↓
GitHub Actions
       ↓
TruffleHog Scan
       ↓
Không có Secret
       ↓
Cho phép Merge

Nếu phát hiện secret:

Developer Push Code
       ↓
GitHub Actions
       ↓
TruffleHog phát hiện Secret
       ↓
CI Failed
       ↓
Không cho Merge

Một command thường dùng trong CI:

trufflehog git file://. \
  --results=verified,unknown \
  --fail

Trong đó:

--results=verified,unknown

chỉ tập trung vào những kết quả đáng quan tâm hơn.

Còn:

--fail

sẽ làm pipeline thất bại khi phát hiện secret.

Nếu đã commit nhầm Secret thì phải làm gì?

Một sai lầm phổ biến là nghĩ rằng chỉ cần xóa secret rồi commit lại là đủ.

Ví dụ:

git commit -m "remove api key"

Điều này không giải quyết hoàn toàn vấn đề.

Secret vẫn có thể tồn tại trong:

Git history
Fork
Clone của developer khác
CI logs
Docker image
Cache

Quy trình đúng nên là:

1. Revoke hoặc Rotate Secret
2. Tạo Secret mới
3. Đưa Secret mới vào Environment Variable hoặc Secret Manager
4. Xóa Secret khỏi Source Code
5. Nếu cần, dọn Git History
6. Scan lại bằng TruffleHog

Điểm quan trọng nhất là:

Rotate secret trước, dọn Git history sau.

Ví dụ nếu AWS Access Key bị lộ, hãy vô hiệu hóa key đó từ AWS trước.

Việc git reset, git revert hoặc force push không làm cho key cũ mất hiệu lực.

Không nên đưa Secret vào Frontend

Một nguyên tắc quan trọng khác:

Frontend không nên chứa secret.

Ví dụ các biến:

NEXT_PUBLIC_
VITE_
REACT_APP_

thường được đưa vào JavaScript chạy trên trình duyệt.

Nếu bạn đặt:

VITE_STRIPE_SECRET_KEY=sk_live_xxxxx

thì key đó có khả năng bị bundle vào frontend.

Người dùng có thể mở DevTools hoặc tải JavaScript về và xem được.

Frontend chỉ nên sử dụng các giá trị được thiết kế để public.

Secret thật phải nằm ở backend.

Workflow TruffleHog đơn giản cho Developer

Một workflow khá thực tế có thể là:

# Kiểm tra Git history
trufflehog git file://. \
  --results=verified,unknown

Sau đó kiểm tra project local:

trufflehog filesystem . \
  -x .trufflehog-exclude \
  --results=verified,unknown

Nếu là frontend:

npm run build

trufflehog filesystem dist \
  --results=verified,unknown \
  --fail

Cuối cùng, thêm bước scan vào CI/CD để tự động kiểm tra mỗi lần push code hoặc tạo Pull Request.

Kết luận

TruffleHog là một công cụ rất hữu ích để giảm nguy cơ lộ secret trong quá trình phát triển phần mềm.

Nó giúp developer phát hiện các thông tin nhạy cảm như:

API Key
Access Token
Database Password
Private Key
Cloud Credentials

không chỉ trong code hiện tại mà còn trong Git history, Docker image và build output.

Đối với các project web hiện đại sử dụng Angular, React, NestJS, Node.js hoặc Docker, việc thêm secret scanning vào quy trình phát triển là một bước tương đối đơn giản nhưng có thể ngăn chặn những sự cố bảo mật nghiêm trọng.

Một quy tắc đáng nhớ là:

Secret đã bị commit thì hãy coi như đã bị lộ. Rotate trước, xóa sau.

TruffleHog là gì? Cách phát hiện API Key, Token và Secret bị lộ trong Git

TruffleHog là gì?

TruffleHog hoạt động như thế nào?

Verified

Unknown

Unverified

Cài đặt TruffleHog

Quét toàn bộ Git History

Quét các file hiện tại

Kiểm tra Angular hoặc React build

Kiểm tra Docker Image

Dùng TruffleHog trong CI/CD

Nếu đã commit nhầm Secret thì phải làm gì?

Không nên đưa Secret vào Frontend

Workflow TruffleHog đơn giản cho Developer

Kết luận

Đăng nhận xét