Posted inGit

Cài đặt Gitleaks: Chặn lộ lọt API Key và Password từ Git Hook đến CI/CD Pipeline

Git tutorial - IT technology blog
Git tutorial - IT technology blog

Vấn đề: Một cú Enter bất cẩn, token AWS bay thẳng lên GitHub

Chắc hẳn không ít anh em từng giật thót tim khi lỡ tay gõ git push một commit sót OpenAI API key hay AWS secret access key. Chỉ mất chừng 2 đến 5 phút là các bot tự động trên Internet đã quét sạch token vừa lộ. Sáng hôm sau thức dậy, hóa đơn AWS nhảy vọt lên 5.000 USD vì bị kẻ gian thuê đào coin, hay database khách hàng bị dump sạch lúc nào không hay.

Nguyên nhân thường rất ngớ ngẩn: bạn gán cứng credential vào code để test nhanh vài phút rồi quên xóa, hoặc tiện tay gõ git add . gom luôn cả file .env vào commit. Trông chờ vào sự tỉnh táo của con người không bao giờ là chiến lược an toàn. Ta cần một cơ chế secret scanning tự động ở cả hai chốt chặn: ngay trên máy dev (Git hooks) và trên pipeline kiểm thử (CI/CD). Đó chính là lúc Gitleaks phát huy tác dụng.

1. Quick start: Cài đặt và quét commit đầu tiên sau 3 phút

Gitleaks là một binary Go độc lập, khởi động chỉ tốn vài chục mili-giây. Nó kết hợp regex và thuật toán Shannon Entropy để rà soát credential của hơn 160 dịch vụ phổ biến.

Bước 1: Cài đặt Gitleaks

Với macOS, cách nhanh nhất là dùng Homebrew:

brew install gitleaks

Trên Linux, tải trực tiếp pre-built binary:

wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz
tar -zxvf gitleaks_8.18.2_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

Kiểm tra binary đã nhận diện hay chưa:

gitleaks version

Bước 2: Quét thử nghiệm repository

Đứng tại thư mục gốc của project, quét lại toàn bộ lịch sử commit từ trước đến nay:

gitleaks detect --verbose

Nếu chỉ muốn kiểm tra những file bạn vừa git add vào staging area:

gitleaks protect --staged --verbose

Nếu dính secret, terminal sẽ lập tức in đỏ tên file, số dòng, fingerprint và loại khóa (ví dụ: Stripe Secret Key, AWS Access Key) kèm mã thoát exit code 1 để chặn đứng quy trình.

2. Đi sâu vào cơ chế và thiết lập 2 tầng bảo vệ

Gitleaks phân tích mã nguồn ra sao?

File cấu hình TOML của Gitleaks vận hành dựa trên hai cơ chế chính:

  • Regex Pattern: Bắt các chuỗi có format nhận diện rõ ràng. Ví dụ, AWS Access Key ID luôn bắt đầu bằng tiền tố AKIA[0-9A-Z]{16}, còn GitHub token luôn có dạng ghp_[a-zA-Z0-9]{36}.
  • Shannon Entropy: Tính toán độ hỗn loạn của chuỗi. Một password ngẫu nhiên 32 ký tự như xK9#mQ2$vL8!zP1@ có entropy rất cao, khác hẳn biến thông thường như user_display_name.

Chốt chặn 1: Git pre-commit hook trên máy dev

Hãy ngăn chặn secret ngay tại máy cá nhân trước khi nó biến thành một commit hash. Nếu phát hiện token, commit sẽ bị hủy lập tức.

Dùng framework pre-commit là giải pháp nhàn nhất. Bạn tạo file .pre-commit-config.yaml ở thư mục gốc repo:

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

Cài đặt hook vào thư mục .git/hooks của dự án:

pip install pre-commit
pre-commit install

Xong bước này, mỗi lần bạn gõ git commit, hook sẽ tự động soi các file staged. Có secret là lệnh commit bị dừng ngay.

Chốt chặn 2: CI/CD Pipeline gác cổng

Tại sao cần thêm CI/CD? Vì dev hoàn toàn có thể lách qua hook cục bộ bằng lệnh git commit --no-verify. Server CI/CD đóng vai trò thẩm phán tối cao: pass scan thì mới cho merge code.

File workflow mẫu cho GitHub Actions (.github/workflows/gitleaks.yml):

name: gitleaks-security-scan

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

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Điểm cần nhớ: Bắt buộc phải khai báo fetch-depth: 0. Mặc định GitHub Actions chỉ clone 1 commit mới nhất, khiến runner bỏ lọt toàn bộ commit trung gian trong Pull Request.

3. Nâng cao: Tùy biến Rules và Xử lý báo động giả (False Positive)

Tùy biến với file .gitleaks.toml

Dự án thường có mock data hoặc token nội bộ khiến Gitleaks báo động giả. Hãy tạo file .gitleaks.toml tại thư mục gốc để nới lỏng đường dẫn kiểm tra:

title = "Custom Gitleaks Config"

[extend]
useDefault = true

[allowlist]
description = "Bo qua fixtures va lockfiles"
paths = [
  '''tests/fixtures/.*''',
  '''go\.sum''',
  '''package-lock\.json'''
]
regexes = [
  '''fake_dummy_secret_for_unit_tests'''
]

Whistelist nhanh bằng inline comment

Khi viết unit test cho cổng thanh toán, bạn buộc phải để mock key trong file test. Thay vì sửa rule chung phức tạp, chỉ cần gắn comment inline này ở cuối dòng:

stripe_test_key = "pk_test_51NzABC1234567890dummy"  # gitleaks:allow

Trình quét sẽ lờ dòng code này đi.

4. Kinh nghiệm thực chiến khi triển khai cho team

Thiết lập tool chỉ mất 15 phút, nhưng đưa vào vận hành thực tế sẽ phát sinh vấn đề văn hóa làm việc. Dưới đây là 3 bài học mình rút ra khi triển khai cho team:

  • Xóa secret rồi commit đè không có tác dụng: Secret vẫn nằm nguyên trong lịch sử git log. Bước 1: vào console nhà cung cấp thu hồi (revoke/rotate) key ngay lập tức. Bước 2: dùng git-filter-repo hoặc BFG Repo-Cleaner để purge sạch commit đó khỏi lịch sử git.
  • Quét baseline nếu repo đã có tuổi đời nhiều năm: Một repo 5 năm tuổi bật Gitleaks lên có thể nổ đỏ lòm vài trăm cảnh báo cũ. Hãy dùng lệnh gitleaks detect --report-path baseline.json để lưu lại các cảnh báo quá khứ. Sau đó cấu hình cờ --baseline-path để CI/CD chỉ chặn những commit mới phát sinh từ hôm nay.
  • Quy ước an toàn cho file .env.example: Tuyệt đối không để chuỗi ngẫu nhiên dài trong file mẫu. Hãy dùng placeholder rõ ràng như STRIPE_KEY=your_stripe_key_here để tránh kích hoạt bộ đo entropy.
Share:
Tags: