Tôi từng commit một file hướng dẫn vận hành cho khách hàng — thông tin đăng nhập server, URL trang quản trị, cấu hình mail — thẳng vào GitHub. Repo private, nhưng vẫn là GitHub. Và tôi tiếp tục làm việc mà không để ý. Đến khi phát hiện ra, đã có 14 commit chồng lên trên.
Sau đó là một buổi chiều với git filter-repo, force push, và rotate toàn bộ password, API key, token có trong file đó. Phần tệ nhất: tôi đang dùng Claude để viết cái tài liệu đó. AI viết nhanh, deadline đang đến gần, và bandwidth review của tôi không theo kịp tốc độ output.
Bài viết này về những gì tôi thay đổi sau sự cố đó. Không phải thói quen — mà là hệ thống.
Vấn đề Cốt Lõi: Sự Chú Ý Là Tài Nguyên Có Hạn
Khi code cùng Claude, Cursor, hay bất kỳ AI assistant nào, tốc độ output tăng đột biến. Bản nháp tài liệu từng mất 2 tiếng nay chỉ cần 10 phút. Đó là giá trị. Nhưng bandwidth review của bạn không thay đổi — thậm chí còn giảm đi, vì nhịp làm việc của AI-driven workflow không cho phép bạn dừng lại.
Trong môi trường này, "tôi sẽ cẩn thận hơn" không phải là chiến lược. Sự cẩn thận là tài nguyên sẽ cạn kiệt. Deadline, mệt mỏi, cái momentum của một session Claude đang chạy tốt — đó chính xác là những lúc secret lọt qua.
Thứ thực sự hiệu quả là làm cho việc lộ secret trở nên bất khả thi về mặt cấu trúc, hoặc nếu không được, để máy móc quyết định luận bắt những thứ con người bỏ sót.
Đây là framework 4 lớp chúng tôi đang dùng tại VAON.
Framework 4 Lớp
| Lớp | Vai trò | Công cụ | Strength |
| 1. Design Architecture | Cấu trúc ngăn secret lọt vào file được track | Quy ước .gitignore | ◎ Primary |
| 2. git pre-commit | Scan quyết định luận trên mỗi commit | gitleaks + lefthook | ◎ Core |
| 3. GitHub Push Protection | Cửa chặn phía server | GitHub Advanced Security | ○ Failsafe |
| 4. Claude Code Hook | Bắt secret ngay khi AI viết | PreToolUse hook | △ Auxiliary |
Thứ tự quan trọng. Phần lớn developer theo bản năng với tới Layer 4 — "thêm Claude hook vào". Đó là ngược. Claude hook chỉ kích hoạt khi Claude viết. Mọi con đường khác — bạn gõ trực tiếp, tool AI khác, paste từ shell — đều bypass hoàn toàn.
Bắt đầu từ Layer 1 và mở rộng ra ngoài.
Layer 1 — Design Architecture: Làm Cho Việc Lộ Secret Bất Khả Thi
Đây là lớp rẻ nhất và mạnh nhất. Nguyên tắc: đặt nội dung nhạy cảm vào những vị trí mà git không bao giờ track.
Tạo thư mục _credentials/ (hoặc tên bất kỳ) và thêm vào .gitignore:
# .gitignore
_credentials/
*.local.md
*.secret.md
credentials*.md
**/draft/
Bây giờ viết manual vận hành, runbook, tài liệu bàn giao cho khách hàng vào _credentials/ thoải mái. Password thật, token thật, ở dạng văn bản người đọc được. File đó không bao giờ chạm vào git history. Không tricks, không template, không placeholder — chỉ là cấu trúc.
Mất gì: Version history qua git cho các file này.
Được gì: Zero cognitive overhead. Cấu trúc không thể bị lộ, dù Claude viết nhanh đến đâu.
Với credential cần versioning, dùng 1Password Shared Vault, Bitwarden, hoặc Notion page có ACL. Git không phải công cụ đúng cho secret.
Layer 2 — git pre-commit / gitleaks: Cửa Chặn Quyết Định Luận
Đây là lớp tự động hóa cốt lõi. Cài hai công cụ:
- gitleaks — phát hiện secret qua regex pattern matching trên các file staged. Go binary, nhanh, bao phủ AWS keys, GitHub tokens, Stripe secrets, OpenAI keys và hàng trăm pattern khác.
- lefthook — quản lý git hooks theo kiểu declarative bằng YAML. Một file, chạy song song, dễ chia sẻ trong team.
brew install gitleaks lefthook
Tạo lefthook.yml tại root repo:
pre-commit:
commands:
gitleaks:
run: gitleaks git --staged --redact --verbose
Cài hooks:
lefthook install
Mỗi lần commit bây giờ đều chạy scan quyết định luận. Nếu file staged match một secret pattern — format AWS key, prefix GitHub token, bearer token, v.v. — commit bị block. Không cảnh báo. Block.
Thêm rule cho dự án cụ thể trong .gitleaks.toml:
# Project-specific detection
[[rules]]
id = "japanese-password-field"
description = "Detect passwords in Japanese-language documentation"
regex = '''(?i)(パスワード|password|pw|pass)\s*[:：=]\s*["']?[A-Za-z0-9!@#$%^&*\-_=+]{6,}["']?'''
tags = ["password"][[rules]]
id = "internal-api-key"
description = "Company-specific API key format"
regex = '''mycompany_(live|test)_[A-Za-z0-9]{24,}'''
tags = ["api-key"]# Suppress false positives from templates
[[allowlists]]
paths = ['''docs/.*\.template\.md''']
regexes = ['''DUMMY_|<placeholder>|xxxxxxxx''']
Điểm mấu chốt: pattern tổng quát (hình dạng API key) + pattern riêng của dự án (tên field trong tài liệu). Tài liệu vận hành tiếng Nhật hay dùng cú pháp パスワード: — pattern tổng quát sẽ không bắt được nếu không có custom entry.
Layer 3 — GitHub Push Protection: Cửa Chặn Phía Server
Dù có pre-commit hook, developer vẫn có thể bypass:
git commit --no-verify -m “quick fix”
Layer 3 là failsafe phía server. Push Protection của GitHub scan mọi push để tìm secret pattern trước khi chấp nhận, bất kể trạng thái hook local.
Bật tại: Settings → Advanced Security → Secret Protection → Push protectio
Lưu ý quan trọng: Public repo được bật miễn phí và tự động. Private repo cần GitHub Team trở lên + Secret Protection được bật (một phần của GitHub Advanced Security, có tính phí). Nếu muốn dùng cho private repo của client, kiểm tra billing plan của org trước.
Khi push bị block, GitHub hiển thị chính xác vị trí match và yêu cầu override rõ ràng kèm lý do — tạo audit trail.
Layer 4 — Claude Code Hook: Chỉ Là Bổ Trợ
Chỉ đến giờ mới nói về tooling riêng của Claude. Đây là có chủ ý.
Thêm vào ~/.claude/settings.json:
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/secret-guard.sh" }
]
}
]
}
}
Tạo ~/.claude/hooks/secret-guard.sh:
#!/usr/bin/env bash
set -euo pipefailPAYLOAD=$(cat)
CONTENT=$(printf '%s' "$PAYLOAD" | jq -r '
.tool_input.content //
.tool_input.new_string //
empty
')[[ -z "$CONTENT" ]] && exit 0
TMP=$(mktemp -t secret-guard.XXXXXX)
trap 'rm -f "$TMP"' EXIT
printf '%s' "$CONTENT" > "$TMP"if gitleaks dir "$TMP" --no-banner --redact >/dev/null 2>&1; then
exit 0
ficat >&2 <<'EOF'
secret-guard: Potential secret detected. Write/Edit blocked.
→ Move credentials to _credentials/ (gitignored)
→ Use <PLACEHOLDER> in templates
→ Add false positives to .gitleaks.toml [[allowlists]]
EOF
exit 2
chmod +x ~/.claude/hooks/secret-guard.sh
Nếu Bạn Đã Lỡ Lộ Rồi
1. Xóa khỏi history:
# Dùng git filter-repo (không dùng filter-branch đã deprecated)
git filter-repo --path path/to/secret-file.md --invert-paths
git push origin --force --all
2. Rotate tất cả. Không có ngoại lệ.
Một khi secret đã được push — dù là private repo — hãy coi như đã bị lộ. Xóa history không phải là "hoàn tác" sự cố; đó là hạn chế exposure thêm. Bản thân credential phải được thay thế.
3. Hiểu vấn đề cache:
GitHub giữ data một thời gian sau force push. Fork giữ vĩnh viễn. Với public repo, liên hệ GitHub Support để xóa cache. Xem hướng dẫn xóa sensitive data của GitHub.
Kỷ Nguyên AI Đòi Hỏi Tư Duy Cấp Hệ Thống
Khi công cụ AI tăng tốc output của chúng ta, chúng tạo ra một loại rủi ro mà ý chí không thể xử lý được. Khoảng cách giữa "tốc độ viết" và "bandwidth review" chỉ ngày càng rộng hơn. Phản ứng hợp lý duy nhất là loại bỏ sự phụ thuộc vào sự chú ý của con người đối với các failure mode mà máy móc có thể bắt được một cách quyết định luận.
Layer 1 (kiến trúc) + Layer 2 (gitleaks) xử lý hơn 95% các kịch bản lộ secret thực tế. Layer 3 bao phủ edge case và bypass. Layer 4 bắt vấn đề sớm trong vòng lặp AI.
Setup một lần. Chạy mãi mãi.
Tại VAON, chúng tôi chạy stack này trên mọi dự án client. Một tiếng bỏ ra để setup đã ngăn được ít nhất 3 sự cố trong năm vừa qua — và có lẽ còn nhiều hơn mà chúng tôi không bao giờ biết.
Tham khảo: https://zenn.dev/takna/articles/secret-leak-prevention-4-layer