ADR 0010Đề xuất
ADR 0010. Bộ máy phát hiện bí mật và dữ liệu cá nhân: tự viết, quy tắc biên dịch sẵn, chỉ xác thực ngoại tuyến
- Trạng thái: Đề xuất
- Ngày: 2026-10-02
- Liên quan: ADR 0003, ADR 0007, ADR 0009, ADR 0011. Câu hỏi Q34, Q36
Bối cảnh
Cần phát hiện trên máy: khóa riêng, token API, khóa cloud, mật khẩu trong tệp cấu hình, .env, lịch sử shell (bí mật), và dữ liệu cá nhân Việt Nam như số CCCD, CMND, số điện thoại, email, số thẻ ngân hàng. Ràng buộc: binary Go tĩnh không CGO, không mạng, giá trị không rời máy (ADR 0011), không thực thi từ xa (ADR 0003), gói Dedicated phân phối on-prem cho khách hàng (giấy phép phải cho phép phân phối kèm sản phẩm thương mại).
Các công cụ mã nguồn mở đã biết (giấy phép cần xác nhận lại ở S7):
| Công cụ | Ngôn ngữ, giấy phép | Cách phát hiện | Đánh giá |
|---|---|---|---|
| gitleaks | Go, MIT | Regex (RE2 của Go) kèm từ khóa lọc trước, entropy, allowlist; bộ quy tắc TOML khoảng 150 đến 200 mục; có chế độ quét thư mục | Bộ quy tắc tốt, giấy phép dễ dãi. Thiết kế quanh git và xuất báo cáo; kiểu Finding mang nguyên giá trị (Secret, Match); kéo nhiều phụ thuộc CLI; API thư viện không cam kết ổn định |
| trufflehog (v3) | Go, AGPL-3.0 | Hơn 700 detector, xác thực sống bằng cách gọi API của nhà cung cấp | AGPL kéo nghĩa vụ mở mã khi phân phối hoặc cung cấp qua mạng; xác thực sống cần mạng và gửi bí mật tới bên thứ ba: trái hai yêu cầu cứng |
| Nosey Parker | Rust, Apache-2.0 | Regex (Hyperscan), bộ quy tắc YAML | Không nhúng được vào Go không CGO; bộ quy tắc dùng tham khảo được (giữ ghi công) |
| detect-secrets | Python, Apache-2.0 | Plugin regex và entropy | Không nhúng được; tham khảo ý tưởng baseline |
| GitGuardian ggshield | Python, MIT (client) | Phát hiện ở SaaS | Gửi nội dung ra ngoài: loại |
| Microsoft Presidio | Python, MIT | Nhận dạng dữ liệu cá nhân (regex, NER) | Không nhúng được; không có bộ nhận dạng cho giấy tờ Việt Nam; chỉ tham khảo |
Không có công cụ mã nguồn mở nào có sẵn bộ nhận dạng CCCD, CMND, đầu số di động Việt Nam đáng tin cậy.
Quyết định
- Tự viết bộ máy trong repo này (
internal/detect), Go thuần. Đường ống cho mỗi khối văn bản:- Sinh ứng viên: bí mật dùng lọc trước bằng từ khóa (Aho-Corasick trên tập từ khóa của mọi quy tắc đang bật, chỉ chạy regex của quy tắc có từ khóa xuất hiện); dữ liệu cá nhân dùng bộ tách token viết tay (dãy chữ số có dấu phân cách, ứng viên email) thay cho regex để đạt thông lượng.
- Regex bằng
regexpcủa Go (RE2, thời gian tuyến tính, không quay lui, không ReDoS). - Entropy Shannon theo bảng ký tự của quy tắc, ngưỡng theo quy tắc.
- Bộ xác thực ngoại tuyến: Luhn và dải IIN cho số thẻ; cấu trúc CCCD (mã tỉnh, mã thế kỷ và giới tính, năm sinh hợp lý); đầu số di động và cố định Việt Nam; checksum CRC32 của token GitHub kiểu mới, token npm; phân tích PEM và khóa OpenSSH để biết loại khóa và có mã hóa passphrase hay không; cấu trúc JWT (chỉ header, không giữ claim); giải base64 của
authstrong cấu hình Docker để kiểm tra dạnguser:pass. - Allowlist: giá trị giữ chỗ (
changeme,xxx,<password>,${VAR},%(var)s,null), giá trị ví dụ công khai (khóa mẫu trong tài liệu AWS, số thẻ thử nghiệm), đường dẫn tài liệu và fixture đã biết. - Ngữ cảnh: từ khóa gần vị trí khớp (cùng dòng, hoặc tên cột CSV, khóa JSON, YAML) nâng độ tin cậy; vị trí và quyền tệp xác định mức phơi nhiễm (
14mục 2). - Kết quả đi qua ranh giới che giấu ngay trong hàm detector: hàm trả về vị trí, preview đã che, fingerprint; kiểu dữ liệu kết quả không có trường chứa giá trị (ADR 0011).
- Không xác thực sống. Không gọi API của nhà cung cấp để kiểm tra bí mật còn hiệu lực: scanner không có mạng, và gửi bí mật đi kiểm tra chính là làm lộ nó. Độ tin cậy chỉ đến từ bộ xác thực ngoại tuyến.
- Quy tắc biên dịch sẵn trong binary (mã Go cộng dữ liệu nhúng), mã ổn định
AHK-<NHÓM>-<SỐ>cho bí mật,AHP-<NHÓM>-<SỐ>cho dữ liệu cá nhân, kèmdetector_version. Cấu hình trung tâm chỉ bật, tắt theo mã và chỉnh tham số số học trong miền (ngưỡng entropy, ngưỡng số bản ghi). Không nhận regex, từ khóa, hay đường dẫn allowlist từ trung tâm. Cập nhật quy tắc đi theo bản phát hành scanner đã ký. - Bộ quy tắc bí mật khởi đầu từ cấu hình mặc định của gitleaks (MIT) qua một bộ chuyển đổi chạy lúc dựng, kết quả là tệp dữ liệu được commit và review như mã; ghi công trong
NOTICE. Mỗi quy tắc đưa vào phải có ca dương và ca âm trong bộ kiểm thử. Đồng bộ với upstream bằng rà soát định kỳ (mỗi quý), không tự động. Bổ sung quy tắc riêng cho bối cảnh máy chủ và Việt Nam: lịch sử shell và client CSDL,.envcủa Laravel,wp-config.php, cấu hình cổng thanh toán (VNPay, MoMo, ZaloPay: định dạng xác minh ở S7), token bot Telegram. - Dữ liệu cá nhân Việt Nam: quy tắc riêng (
14mục 5). Phiên bản đầu không dùng học máy, không nhận dạng tên người (NER quá nhiễu và tốn tài nguyên). - Công cụ bên thứ ba chỉ làm chuẩn đối chiếu trong phòng thí nghiệm (gitleaks, trufflehog ở chế độ không xác thực, Nosey Parker), giống cách ADR 0007 dùng Trivy, Grype. Không nhúng, không phân phối trufflehog.
- Đích độ chính xác (chốt sau S7, S8, đo trên bộ mẫu ở
11): quy tắc bí mật độ tin cậy cao có precision không dưới 90% và recall không dưới 90% trên bộ mẫu định dạng đã biết; quy tắc chung (gán mật khẩu) báo riêng ở mức độ tin cậy thấp, mặc định ẩn khỏi danh sách chính; CCCD có ngữ cảnh precision không dưới 95%. - Thông lượng (đích, S6): không dưới 30 MiB/s mỗi lõi cho bộ quy tắc bí mật đầy đủ có lọc trước, không dưới 60 MiB/s mỗi lõi cho bộ tách token dữ liệu cá nhân.
Hệ quả
- Nắm hoàn toàn bất biến "giá trị không rời máy" ở tầng kiểu dữ liệu, không phải dựa vào việc nhớ xóa trường của thư viện bên thứ ba.
- Một binary, không phụ thuộc lớn mới; quy tắc phát hành cùng nhịp scanner, có
rules_versiontrong báo cáo. - Phải tự duy trì bộ quy tắc (định dạng token mới xuất hiện liên tục: R23); chi phí đã tính trong
12(SCN-12, SCN-13, rà soát định kỳ). - Không biết bí mật còn hiệu lực hay đã thu hồi. Khuyến nghị khắc phục luôn là "xoay vòng bí mật" (rotate), không chỉ xóa tệp.
- Không thấy bí mật đã mã hóa, đã nén, hay nằm trong định dạng nhị phân ngoài danh sách
AHK-FILE-*.
Phương án đã cân nhắc
| Phương án | Lý do không chọn |
|---|---|
| Nhúng gitleaks làm thư viện | Giấy phép dùng được, nhưng kiểu kết quả mang nguyên giá trị, kéo phụ thuộc CLI, API không ổn định, khó áp ngân sách và chỉ mục tăng dần của ADR 0009. Dùng bộ quy tắc của nó thay vì mã |
| Nhúng trufflehog | AGPL-3.0 với gói Dedicated phân phối on-prem; xác thực sống cần mạng và gửi bí mật ra ngoài |
| Gọi binary gitleaks có sẵn trên máy | Thực thi chương trình ngoài, phiên bản không kiểm soát, kết quả chứa giá trị đi qua stdout |
| Quét tập trung trên bản sao tệp | Trái ADR 0011 |
| Học máy để giảm dương tính giả | Tốn tài nguyên trên máy, khó giải thích; xem lại sau khi có số liệu dương tính giả thật (chỉ thống kê ẩn danh) |