Phát hiện và xóa secret bị lộ trong Git bằng TruffleHog và Gitleaks

Bối cảnh & Tại sao lại quan trọng

Lộ secret vào Git diễn ra nhanh hơn hầu hết các đội ngũ có thể hình dung. Một lập trình viên kiểm thử Stripe webhook hoặc instance RDS PostgreSQL ở môi trường local, dán API token vào file config chỉ để debug trong năm phút, chạy git commit -am "kiểm tra nhanh" rồi push lên remote repository. Các bot tự động và công cụ cào dữ liệu công khai trên GitHub thường xuyên quét và thu thập các AWS key, Slack webhook cùng chứng chỉ riêng tư bị lộ chỉ trong chưa đầy 60 giây.

Git không bao giờ quên. Việc chạy git rm credentials.env rồi tạo một commit mới chẳng giải quyết được vấn đề gì. Vì Git hoạt động như một cơ sở dữ liệu bất biến, định danh theo nội dung (content-addressable), mỗi snapshot commit sẽ đóng băng trạng thái repository của bạn tại đúng thời điểm đó. Bất kỳ ai clone repo của bạn cũng đều có thể chạy git log -p hoặc xem lại các snapshot cũ để đào bới những khóa bí mật mà bạn ngỡ rằng đã xóa từ nhiều tháng trước.

Sở hữu mật khẩu mạnh mới chỉ giải quyết được một nửa vấn đề. Các công cụ như trình tạo mật khẩu trên trình duyệt tại toolcraft.app/vi/tools/security/password-generator giúp việc tạo token 64 ký tự với độ hỗn loạn (entropy) cao trở nên vô cùng dễ dàng mà không cần gửi chuỗi thô qua mạng. Tuy nhiên, độ entropy cao đến mấy cũng không thể cứu bạn nếu token đó nằm chình ình trong lịch sử commit công khai.

Một hệ thống phòng thủ vững chắc đòi hỏi hai lớp bảo vệ chuyên biệt:

  • TruffleHog: Đào sâu vào lịch sử và xác thực trực tiếp. Với hơn 800 detector, công cụ này không chỉ so khớp pattern regex—nó còn gửi request đến API của các nhà cung cấp (AWS STS, Stripe, Slack, GitHub) để kiểm tra xem thông tin xác thực bị lộ có còn hoạt động ngay tại thời điểm đó hay không.
  • Gitleaks: Công cụ phân tích tĩnh cực nhanh được viết bằng Go. Nó quét các quy tắc regex và độ hỗn loạn Shannon entropy qua hàng trăm dòng code đã staged trong chưa đầy 10 mili-giây, biến nó thành người gác cổng lý tưởng cho các pre-commit hook ở máy local và pipeline PR.

Cài đặt

Việc trang bị cả hai công cụ này cho máy làm việc của bạn chỉ mất chưa đầy ba phút.

1. Cài đặt Gitleaks

Gitleaks được phát hành dưới dạng binary độc lập không phụ thuộc thư viện bên ngoài (zero-dependency) trên macOS, Linux và Windows. Bạn có thể tải trực tiếp bản release trên Linux:

# Tải xuống và giải nén Gitleaks (x86_64 Linux)
curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz | tar -xz gitleaks
sudo mv gitleaks /usr/local/bin/

# Kiểm tra phiên bản
gitleaks version

Trên macOS, Homebrew sẽ xử lý mọi thứ nhanh gọn:

brew install gitleaks

2. Cài đặt TruffleHog

TruffleHog v3 cung cấp một script cài đặt chính thức tự động lấy binary phù hợp với kiến trúc máy của bạn:

# Cài đặt binary TruffleHog trực tiếp vào /usr/local/bin
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sudo sh -s -- -b /usr/local/bin

# Kiểm tra phiên bản
trufflehog --version

3. Cài đặt Pre-Commit Framework

Để ngăn chặn các commit nguy hiểm ngay trước khi chúng rời khỏi bàn phím của bạn, hãy kết hợp Gitleaks với package pre-commit:

# Cài đặt qua pip hoặc trình quản lý package của hệ thống
pip install pre-commit

# Kiểm tra phiên bản
pre-commit --version

Cấu hình

1. Cấu hình Gitleaks để chặn rò rỉ qua Local Hook

Tạo file .pre-commit-config.yaml ở thư mục gốc của repository để Gitleaks tự động kiểm tra các diff đã staged:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.2
    hooks:
      - id: gitleaks

Kích hoạt hook vào thư mục .git/hooks ở máy local:

pre-commit install

Kể từ lúc này, mỗi lệnh git commit sẽ kích hoạt quá trình quét diff ngay lập tức. Nếu có private key hoặc API token lọt vào index, commit sẽ bị chặn lại ngay lập tức.

2. Tùy chỉnh quy tắc cho Gitleaks (.gitleaks.toml)

Dữ liệu mẫu trong test fixture và các chuỗi hash giả lập chắc chắn sẽ kích hoạt cảnh báo của các detector. Để bỏ qua các cảnh báo giả mà không cần tắt scanner, hãy tạo file .gitleaks.toml trong thư mục gốc của bạn:

title = "Cấu hình danh sách cho phép (allowlist) Gitleaks cho dự án"

[allowlist]
description = "Bỏ qua dữ liệu mock và các ví dụ trong tài liệu"
paths = [
  '''tests/mocks/''',
  '''fixtures/dummy_keys.json'''
]
regexes = [
  '''EXAMPLE_KEY_[a-zA-Z0-9]{16,32}''',
  '''AKIAIOSFODNN7EXAMPLE'''
]

3. Dọn sạch Secret bị lộ khỏi lịch sử Git

Bạn phát hiện một khóa đang hoạt động trong commit log? Trước hết, hãy thu hồi và cấp lại (rotate) thông tin xác thực đó ngay tại nhà cung cấp. Luôn giả định rằng bất kỳ khóa nào bị lộ đều đã bị các công cụ thu thập dữ liệu tự động chiếm đoạt.

Tiếp theo, hãy xóa sạch dấu vết khỏi Git. Các lệnh Git tiêu chuẩn không thể viết lại commit tree trên tất cả các nhánh một cách đáng tin cậy. Tiêu chuẩn chính thức được cộng đồng khuyên dùng là git-filter-repo.

Khai báo chính xác các chuỗi nhạy cảm cần thay thế trong file replace-secrets.txt:

sk_live_51AbCdEfGhIjKlMnOpQrSt==>REMOVED_SECRET
AKIAIOSFODNN7EXAMPLE_SECRET_STRING==>REMOVED_SECRET

Bây giờ hãy sao lưu repository và viết lại toàn bộ commit tree trực tiếp:

# Sao lưu bản clone repository của bạn trước
cp -r my-repo my-repo-backup
cd my-repo

# Cài đặt git-filter-repo
pip install git-filter-repo

# Xóa chuỗi nhạy cảm trên toàn bộ lịch sử commit, tag và branch
git filter-repo --replace-text replace-secrets.txt --force

Sau khi quá trình viết lại lịch sử hoàn tất, hãy force-push các ref commit đã viết lại lên origin:

git push origin --force --all
git push origin --force --tags

Hãy thông báo cho các thành viên trong nhóm ngay lập tức. Bản clone local của họ sẽ bị xung đột với commit tree đã được viết lại, vì vậy họ cần phải clone lại hoặc hard-reset về các branch mới được push.

Xác minh & Giám sát

1. Kiểm tra cơ chế bảo vệ của Local Pre-Commit

Kiểm tra hook ở máy local bằng một token giả lập có định dạng tương tự Personal Access Token thật của GitHub:

# Đưa mẫu token thử nghiệm vào staging
echo 'GITHUB_TOKEN=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' > test_leak.py
git add test_leak.py
git commit -m "Kiểm tra cơ chế bảo vệ secret"

Gitleaks sẽ chặn commit chỉ trong vài mili-giây và dừng thực thi:

[INFO] Khởi tạo môi trường cho https://github.com/gitleaks/gitleaks.
Đang phát hiện secret...

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

Finding:     ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
Secret:      ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
RuleID:      github-pat
Entropy:     3.854
File:        test_leak.py
Line:        1

ERR phát hiện secret trong các thay đổi đã staged! Commit bị chặn.

Bỏ stage và xóa file tạm thời để khôi phục branch của bạn:

git reset HEAD test_leak.py
rm test_leak.py

2. Rà soát toàn bộ lịch sử Repository với TruffleHog

Quét toàn bộ đồ thị commit trong lịch sử bằng TruffleHog. Việc thêm cờ --only-verified sẽ lọc bỏ các kết quả không còn hoạt động, chỉ hiển thị những khóa còn hiệu lực và xác thực thành công với API từ xa:

# Quét lịch sử commit của repository hiện tại để tìm các key còn hoạt động
trufflehog git file://$(pwd) --only-verified

Bạn cũng có thể rà soát trực tiếp các remote repository mà không cần clone về máy:

trufflehog git https://github.com/your-org/target-repo.git --only-verified

3. Giám sát liên tục qua GitHub Actions

Local hook cung cấp một rào chắn bước đầu rất tốt, nhưng một lập trình viên đang vội vẫn có thể bỏ qua chúng bằng lệnh git commit --no-verify. Hãy thực thi việc quét tập trung bằng cách chạy Gitleaks trên mọi lượt push và pull request. Lưu pipeline sau vào .github/workflows/secret-scan.yml:

name: Quét Secret

on:
  pull_request:
  push:
    branches: [main, develop]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Chạy Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Thiết lập fetch-depth: 0 sẽ lấy toàn bộ đồ thị commit thay vì chỉ lấy một snapshot commit đơn lẻ (shallow clone). Điều này giúp ngăn chặn các khóa bị ẩn trong những commit trung gian hoặc commit đã bị squash của PR không bị lọt vào các branch production mà không hay biết.

Share: