# Repo sạch ở HEAD vẫn có thể lộ key trong lịch sử Git

> Gitleaks tìm ra key bị lộ, nhưng việc đầu tiên là thu hồi key, chưa phải viết lại lịch sử.

Bản gốc: https://fdetimes.net/vi/cong-cu/gitleaks-quet-secret-truoc-khi-ban-giao-repo-cho-khach/

Một file `.env` bị xóa ở commit thứ 200 vẫn còn nguyên trong commit thứ 3. Đó là lý do một repo trông sạch sẽ khi bạn mở ra vẫn có thể chứa API key staging, token của một dịch vụ bên thứ ba, hay mật khẩu database mà ai đó đã dán vào lúc vội.

Với FDE, khoảnh khắc nguy hiểm nhất là lúc bàn giao. Bạn làm việc trong repo của khách hoặc repo riêng suốt nhiều tuần, rồi trao toàn bộ lịch sử cho đội kỹ sư của họ. Ai clone repo đó cũng đọc được mọi patch từng tồn tại.

Gitleaks sinh ra cho đúng việc này. Đây là công cụ mã nguồn mở, giấy phép MIT, chuyên tìm mật khẩu, API key và token trong repo Git, file và thư mục. Người tạo ra nó là Zach Rice, cũng là người bảo trì dự án.

## Vì sao phải quét lịch sử, không chỉ quét file?

Điểm mấu chốt nằm ở cách Gitleaks đọc repo. Lệnh `git` của nó quét repo cục bộ bằng cách chạy `git log -p` bên dưới, tức là duyệt từng patch trong lịch sử. Một key đã bị xóa khỏi file nhưng vẫn nằm trong diff cũ sẽ bị bắt.

Nếu chỉ cần quét một thư mục không phải repo Git, chẳng hạn bản export mã nguồn khách gửi qua file nén, bạn dùng lệnh `dir`. Hai lệnh này thay cho `detect` và `protect`, vốn đã bị đánh dấu deprecated từ phiên bản v8.19.0. Nếu bạn đọc một hướng dẫn cũ còn dùng `detect`, hãy hiểu đó là cú pháp đã lỗi thời.

**Điểm mấu chốt:** Xóa một dòng khỏi file không xóa được nó khỏi lịch sử Git.

## Thử hình dung một lần bàn giao

Giả sử bạn vừa xong ba tháng tích hợp hệ thống cho một khách hàng logistics. Tuần đầu, để demo nhanh, bạn hardcode API key của môi trường staging vào một file config, rồi hai ngày sau chuyển sang biến môi trường và xóa dòng đó. Ở HEAD, repo sạch hoàn toàn.

Trước khi đẩy repo sang tổ chức GitHub của khách, bạn mở terminal ở thư mục repo và chạy lệnh quét ở chế độ verbose để thấy chi tiết từng finding:

```bash
gitleaks git -v
```

Kết quả chỉ ra đúng commit tuần đầu, đúng file config, đúng chuỗi key. Đó là thứ một lần review code thông thường gần như chắc chắn bỏ qua, vì không ai đọc lại diff của ba tháng trước.

Phản xạ tự nhiên là đi xóa commit đó. Đừng làm thế trước tiên.

## Tìm thấy key rồi, làm gì trước?

Tài liệu của GitHub về xóa dữ liệu nhạy cảm nói rõ: việc đầu tiên là thu hồi secret đó, hoặc thay bằng một key mới. Lý do đơn giản. Key đã nằm trong lịch sử thì bạn phải giả định nó đã bị sao chép, và chỉ có vô hiệu hóa key mới thực sự cắt rủi ro.

Sau khi key cũ đã chết, mới đến câu hỏi có viết lại lịch sử bằng git-filter-repo hay không. GitHub cảnh báo rằng một khi đi tiếp sang bước kế, việc viết lại trở nên không thể đảo ngược, và cần phối hợp với mọi người đang cộng tác trên repo.

Ở site khách, việc phối hợp đó có nghĩa là báo cho đội của họ trước, vì mọi bản clone hiện có sẽ lệch với lịch sử mới.

Trong ví dụ trên, cách hợp lý là thay key staging bằng key mới, ghi lại trong tài liệu bàn giao rằng commit cũ chứa một key đã bị vô hiệu, rồi cùng khách quyết định có cần dọn lịch sử hay không. Quyết định đó thuộc về họ, không phải của riêng bạn.

## Ba sai lầm hay gặp trước buổi bàn giao

Phần lớn sự cố không đến từ việc thiếu công cụ mà từ làm sai thứ tự. Bảng dưới đây gom các lỗi suy ra trực tiếp từ cách Gitleaks và hướng dẫn của GitHub vận hành.

| Sai lầm | Vì sao nguy hiểm | Nên làm thay |
|---|---|---|
| Chỉ quét file ở HEAD | Key đã xóa vẫn nằm trong patch cũ, ai clone cũng đọc được | Chạy `gitleaks git` để duyệt toàn bộ lịch sử |
| Xóa commit trước khi thu hồi key | Key có thể đã bị sao chép, xóa commit không làm nó vô hiệu | Thu hồi hoặc thay key mới trước tiên |
| Viết lại lịch sử mà không báo đội khách | Việc viết lại không đảo ngược được, các bản clone sẽ lệch | Thống nhất với đội khách trước khi chạy git-filter-repo |

## Giữ repo sạch sau lần dọn dẹp

Khi các finding cũ đã được xử lý, bạn không muốn mỗi lần quét lại thấy chúng hiện lên. Baseline giải quyết chuyện này: Gitleaks bỏ qua những finding cũ đã có trong baseline, nên các lần quét sau chỉ báo leak mới.

Cách làm gồm hai bước. Lần quét đầu ghi kết quả ra file báo cáo, file này trở thành baseline. Những lần sau, bạn trỏ Gitleaks vào baseline đó và ghi finding mới ra một file khác:

```bash
# Lần đầu: lưu toàn bộ finding hiện có làm baseline
gitleaks git --report-path gitleaks-report.json

# Các lần sau: bỏ qua finding đã có, chỉ ghi leak mới
gitleaks git --baseline-path gitleaks-report.json --report-path findings.json
```

Điểm mạnh nhất của Gitleaks, theo chính Zach Rice, là hệ thống cấu hình cho phép viết rule riêng. Với FDE, điều này đáng giá khi khách có định dạng token nội bộ mà rule mặc định không nhận ra.

Thử hình dung khách dùng token dạng `acme_` theo sau là 32 ký tự; một file `.gitleaks.toml` tối thiểu sẽ giữ bộ rule mặc định và thêm đúng một rule:

```toml
[extend]
useDefault = true

[[rules]]
id = "acme-internal-token"
description = "Token nội bộ của khách"
regex = '''acme_[a-z0-9]{32}'''
keywords = ["acme_"]
```

Rồi chạy `gitleaks git -v --config .gitleaks.toml`. Hãy thử rule trên một repo nháp có cài sẵn một token giả trước khi dùng thật, để chắc regex bắt đúng thứ bạn muốn.

Để chặn leak từ gốc, Gitleaks chạy được như một pre-commit hook bằng cách chép script mẫu `pre-commit.py` vào thư mục `.git/hooks/`. Ở tầng team, dự án có GitHub Action quét pull request và commit. Pre-commit bảo vệ máy của bạn; Action bảo vệ cả những người khác trong repo.

Bộ ba này cũng là thứ đáng ghi vào CV. Một dòng như "dựng secret scanning pre-commit và CI, kèm rule riêng cho token nội bộ, trước khi bàn giao repo cho khách" cho nhà tuyển dụng thấy bạn coi repo bàn giao là tài sản có rủi ro, không chỉ là một đống code.

## Giới hạn cần biết trước khi chọn công cụ

README hiện tại của dự án tuyên bố Gitleaks đã feature complete: không nhận thêm tính năng mới, các bản phát hành sau chỉ là bản vá bảo mật. Tháng 3/2026, Rice ra mắt Betterleaks, một bản thay thế drop-in, nghĩa là flag CLI và file cấu hình hiện có dùng lại được mà không cần sửa.

Vì thế, công sức bạn bỏ ra hôm nay không phí. Lệnh quét, baseline và file rule ở trên đều mang thẳng sang Betterleaks được. Nếu khách đang bắt đầu từ con số không, đáng để hỏi họ muốn chuẩn hóa trên công cụ nào.

Bàn giao một repo là bàn giao cả quá khứ của nó, và một lần chạy `gitleaks git -v` trước buổi bàn giao rẻ hơn nhiều so với một cuộc gọi từ đội bảo mật của khách sau đó.

**Thử ngay tuần này:**

- Chạy gitleaks git -v trên repo bạn sắp bàn giao gần nhất và ghi lại từng finding cùng trạng thái xử lý
- Tạo baseline từ lần quét đầu, rồi chạy lại với --baseline-path để chắc chỉ còn leak mới hiện ra
- Chép script pre-commit.py mẫu của Gitleaks vào .git/hooks/ trong một repo bạn đang làm

## Nguồn

- [GitHub - gitleaks/gitleaks](https://github.com/gitleaks/gitleaks)

- [gitleaks README (master)](https://raw.githubusercontent.com/gitleaks/gitleaks/master/README.md)

- [Gitleaks](https://gitleaks.io)

- [Gitleaks: Open-source solution for detecting secrets in your code](https://www.helpnetsecurity.com/2024/06/27/gitleaks-open-source-solution-detecting-secrets-in-code/)

- [Betterleaks: Open-source secrets scanner](https://www.helpnetsecurity.com/2026/03/19/betterleaks-open-source-secrets-scanner/)

- [Removing sensitive data from a repository - GitHub Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
