Hướng dẫn sử dụng

Từ lúc tạo tài khoản đến khi đưa kết quả vào CI/CD: từng bước, kèm mẹo để quét nhanh và ít báo nhầm.

1. Bắt đầu nhanh

Ba bước để có báo cáo đầu tiên, mất chừng một phút với dự án nhỏ:

  1. Tạo tài khoản tại trang đăng ký, hoặc bấm "Đăng nhập bằng Google" nếu không muốn nhớ thêm mật khẩu.
  2. Đưa mã nguồn vào ở trang chủ: kéo thả tệp ZIP, chọn cả thư mục, dán đường dẫn kho GitHub, hoặc dán thẳng một đoạn mã.
  3. Bấm quét rồi chờ. Trang quét chạy theo từng lô nhỏ nên không bị đứt giữa chừng dù dự án lớn; xong sẽ tự chuyển sang báo cáo.
Mã nguồn của bạn không rời khỏi máy chủ. Toàn bộ việc phân tích chạy cục bộ. Tính năng duy nhất gọi ra Internet là đối chiếu CVE, và nó chỉ gửi tên + phiên bản thư viện (ví dụ lodash@4.17.11) — không gửi mã. Chi tiết ở Chính sách bảo mật.

2. Các cách đưa mã vào quét

CáchHợp khi nàoLưu ý
Tệp nén Dự án đã đóng gói sẵn, hoặc tải từ máy khác về Nhận .zip. Dung lượng tối đa theo gói của bạn.
Cả thư mục Dự án đang nằm trên máy bạn Trình duyệt sẽ hỏi xác nhận trước khi tải lên nhiều tệp. Nên xoá node_modules, vendor trước cho nhanh.
Kho GitHub Dự án đã đẩy lên GitHub, kho công khai Dán đường dẫn dạng https://github.com/chu-kho/ten-kho. Tải về nhánh mặc định, giới hạn dung lượng riêng.
Dán mã Kiểm tra nhanh một tệp hoặc một hàm Nhớ chọn đúng ngôn ngữ để áp đúng bộ quy tắc.
Thư mục trên máy chủ Mã đã nằm sẵn trên chính máy chủ đặt công cụ Chỉ hiện khi quản trị viên bật; chỉ quét được thư mục nằm trong danh sách cho phép.

Tuỳ chọn "Giữ mã nguồn để tự sửa"

Mặc định mã nguồn tải lên bị xoá ngay sau khi quét xong, chỉ giữ lại kết quả. Nếu muốn dùng tính năng tự động sửa lỗi, hãy tích ô này trước khi quét — nếu không, tới lúc bấm sửa sẽ báo "Mã nguồn đã bị xoá sau khi quét" và bạn phải quét lại.

Nên loại bỏ gì trước khi quét

Thư viện bên thứ ba và tệp đã nén (minify) chiếm phần lớn thời gian quét nhưng gần như không có lỗi nào bạn sửa được. Bỏ chúng ra ngoài giúp báo cáo gọn và đúng trọng tâm hơn:

  • node_modules/, vendor/, bower_components/
  • Tệp *.min.js, *.bundle.js, bản dựng trong dist/, build/
  • Thư mục sao lưu (*-backup/, bản chép cũ của dự án) — nếu không sẽ đếm lỗi hai lần

3. Đọc kết quả

Báo cáo mở đầu bằng điểm rủi ro (thang A–F) và năm ô đếm theo mức nghiêm trọng. Điểm này chỉ là cái nhìn tổng quát — hãy nhìn vào số lỗi Nghiêm trọng và Cao để quyết định làm gì trước.

MứcNghĩa là gìXử lý
Nghiêm trọngCho phép đọc cơ sở dữ liệu, chạy lệnh trên máy chủ hoặc chiếm tài khoản người dùngSửa trước khi lên môi trường thật
CaoLỗ hổng khai thác được nhưng cần thêm điều kiệnSửa trong đợt phát hành gần nhất
Trung bìnhLàm yếu phòng thủ, thường cần kết hợp lỗi khácĐưa vào danh sách việc
ThấpSai thói quen tốt, rủi ro nhỏSửa khi tiện tay
Thông tinGhi nhận để bạn biết, không phải lỗiĐọc rồi bỏ qua

Hai bảng phía dưới — tệp có nhiều lỗi nhất và nhóm lỗ hổng phổ biến (theo mã CWE) — cho biết nên bắt đầu từ đâu. Nếu một nhóm CWE chiếm vài nghìn lỗi thì thường chỉ là một kiểu sai lặp lại: sửa đúng chỗ đó là giảm được hàng loạt.

4. Xử lý từng phát hiện

Mỗi phát hiện đều có tệp, số dòng, đoạn mã trích dẫn, mô tả và gợi ý cách sửa. Bạn đánh dấu được ba trạng thái:

  • Cần xử lý — trạng thái mặc định.
  • Đã sửa — dùng sau khi bạn tự sửa trong mã, để lần đọc sau khỏi rà lại.
  • Bỏ qua — dành cho báo nhầm hoặc trường hợp bạn chấp nhận rủi ro. Nên ghi chú lý do trong mã bằng một dòng bình luận để người sau hiểu.
Không có bộ quét nào đúng 100%. Công cụ đọc mã theo mẫu, nên có thể báo nhầm chỗ bạn đã xử lý bằng cách nó không nhận ra, và ngược lại cũng có lỗi nó không thấy. Hãy xem kết quả là danh sách chỗ cần xem lại, không phải bản án. Điểm đối chiếu với bộ đo OWASP Benchmark được công bố tại trang Benchmark.

5. Tự động sửa lỗi

Với những lỗi có cách sửa máy móc rõ ràng (ví dụ thêm hàm escape khi in ra HTML, thay hàm băm yếu), nút "Sửa tất cả & tải về" sẽ vá và trả lại mã cho bạn. Quy trình:

  1. Quét với ô "Giữ mã nguồn để tự sửa" đã tích.
  2. Mở báo cáo, bấm Sửa tất cả. Trang xem trước cho bạn đối chiếu từng dòng trước/sau.
  3. Chọn kiểu tải về: toàn bộ dự án (chép đè lên thư mục cũ) hoặc chỉ các tệp đã vá (gọn, hợp khi bạn muốn tự xem lại từng tệp).
  4. Giải nén, chạy lại bộ kiểm thử của bạn, rồi mới commit.
Khi quét thư mục trực tiếp trên máy chủ, bản sửa ghi đè thẳng lên tệp gốc. Hãy commit hoặc sao lưu trước khi bấm sửa. Bản vá do máy sinh ra là gợi ý — bạn vẫn phải xem lại và kiểm thử.

Những lỗi cần hiểu ngữ cảnh (thiết kế phân quyền sai, dùng sai thư viện mã hoá…) sẽ không nằm trong danh sách tự sửa; phần mô tả sẽ nói rõ hướng xử lý để bạn tự làm.

6. Xuất báo cáo & CI/CD

Từ trang báo cáo có hai kiểu tệp tải về:

  • JSON — toàn bộ phát hiện kèm điểm rủi ro, dùng để lưu trữ hoặc tự xử lý bằng script.
  • SARIF — định dạng chuẩn cho GitHub / GitLab Code Scanning. Nạp lên là lỗi hiện ngay trong tab Security và trên từng pull request.

Ví dụ đưa kết quả vào GitHub Actions:

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vinbs-scan.sarif

Báo cáo quá lớn thì làm sao?

Dự án lớn có thể ra vài nghìn phát hiện — tệp JSON gộp khi đó rất nặng, mở bằng tay không xuể và thường vượt giới hạn đầu vào của các công cụ khác. Dùng ô "Tải JSON chia nhỏ" ngay trên trang báo cáo: chọn số lỗi mỗi tệp rồi tải về một ZIP gồm

  • …-00-doc-truoc.txt — vài dòng giải thích cách dùng bộ tệp;
  • …-00-tom-tat.json — số lỗi theo mức và theo từng quy tắc, đọc tệp này trước để chọn việc;
  • …-phan-01-tren-05.json, -phan-02-… — các phần đã sắp theo mức nghiêm trọng, nên phần 01 luôn là phần đáng xử lý nhất.

Khi báo cáo vượt khoảng 800 lỗi, trang sẽ tự gợi ý kiểu tải này thay vì tệp gộp.

Nếu bạn tự triển khai công cụ trên máy chủ riêng, mã nguồn còn kèm tools/slice-report.php để làm việc tương tự từ dòng lệnh — đọc tệp theo luồng, in bảng tóm tắt theo nhóm quy tắc và cắt ra từng lô:

php tools/slice-report.php bao-cao.json
php tools/slice-report.php bao-cao.json --rule=php.sqli --dedupe --limit=20 --out=storage/slices

7. Đối chiếu CVE thư viện

Ngoài việc đọc mã bạn viết, công cụ còn đọc các tệp khoá phụ thuộc để tìm thư viện cũ đã có lỗ hổng công bố: composer.lock, package-lock.json, yarn.lock, requirements.txt, go.sum, Cargo.lock…

  • Nguồn dữ liệu là OSV.dev của Google.
  • Chỉ tên và phiên bản gói được gửi đi, không bao giờ gửi mã nguồn.
  • Cách sửa gần như luôn là nâng phiên bản thư viện lên bản đã vá — phần kết quả ghi rõ nâng lên mức nào.
Tính năng này nằm trong gói Pro trở lên, và quản trị viên phải bật ở cấu hình máy chủ (SCANNER_SCA_ENABLED) vì nó là đường gọi ra Internet duy nhất.

8. Giám sát máy chủ

Trang Giám sát máy chủ đọc tiến trình đang chạy và các kết nối mạng của chính máy chủ đặt công cụ, rồi làm nổi những kết nối đi ra địa chỉ bên ngoài — dấu hiệu thường thấy khi máy bị cài mã độc đào tiền ảo hoặc bị tuồn dữ liệu ra ngoài.

  • Trên Linux đọc trực tiếp từ /proc, không cần quyền đặc biệt.
  • Trên Windows cần bật hàm exec() để gọi netstat và tasklist.
  • Mặc định tắt; quản trị viên bật bằng SCANNER_HOST_MONITOR_ENABLED. Đây là thông tin nhạy cảm — chỉ bật trên máy bạn tự quản.

Cần gói Business.

9. Quét máy khác (collector)

Muốn kiểm tra một máy không phải máy chủ đặt công cụ — máy tính cá nhân, một VPS khác — thì dùng bản thu thập:

  1. Vào trang Giám sát máy chủ → Bản thu thập, tải collect.sh (Linux/macOS) hoặc collect.ps1 (Windows).
  2. Chạy script trên máy cần kiểm tra. Nó thu tiến trình, kết nối mạng và danh sách phần mềm đã cài.
  3. Kết quả là một tệp JSON: tải lên trang này để xem báo cáo, hoặc để script tự gửi về nếu quản trị viên đã đặt SCANNER_HOST_REPORT_TOKEN.

Phần mềm đã cài được đối chiếu CVE theo hai nguồn, hiển thị thành hai mục riêng: OSV cho thư viện lập trình, và NVD cho phần mềm hệ điều hành / ứng dụng desktop (7-Zip, Tomcat, .NET…) mà OSV không phủ. Phần NVD chạy nền theo lô, nên cứ để trang mở vài chục giây cho nó đếm xong.

Chỉ chạy bản thu thập trên máy bạn quản trị. Chạy trên máy người khác khi chưa được phép là vi phạm pháp luật.

Cần gói Business.

10. Quét mạng

Chế độ quét mạng rà cổng đang mở, dịch vụ tương ứng, cấu hình TLS và các tiêu đề bảo mật HTTP của một máy hoặc một dải địa chỉ.

  • Nhập địa chỉ IP, tên miền hoặc dải CIDR (ví dụ 192.168.1.0/24).
  • Mặc định chỉ quét được dải mạng nội bộ. Quét địa chỉ công khai cần quản trị viên bật riêng và bạn phải tự tích ô xác nhận được uỷ quyền.
  • Có giới hạn số máy mỗi lần quét để không làm nghẽn mạng.
Quét cổng hệ thống của người khác khi chưa được phép là hành vi bất hợp pháp theo pháp luật Việt Nam và hầu hết các quốc gia. Ô xác nhận uỷ quyền là cam kết có giá trị ràng buộc — xem Điều khoản sử dụng.

Cần gói Business.

11. Gói & hạn mức

Gói Dung lượng tải lên Lượt quét mỗi ngày Tính năng mở thêm
Free
Quét mã nguồn cơ bản
20 MB 5 Quét mã nguồn, tự sửa lỗi, xuất JSON
Pro
Đối chiếu CVE + xuất CI
200 MB 50 Đối chiếu CVE (SCA/NVD), Xuất SARIF cho CI
Business
Toàn bộ tính năng nâng cao
500 MB 500 Quét mạng (Nessus-lite), Giám sát máy chủ, Bản thu thập máy khác, Quét mục tiêu công khai, Đối chiếu CVE (SCA/NVD), Xuất SARIF cho CI

Mọi gói đều quét mã nguồn không giới hạn số lỗi và dùng được tính năng tự sửa. Gói chỉ khác nhau ở hạn mức và các tính năng nâng cao. Xem thêm tại trang Gói sử dụng; nâng gói bằng cách liên hệ quản trị viên.

12. Mẹo & câu hỏi thường gặp

Quét ra hàng nghìn lỗi, bắt đầu từ đâu?

Gần như chắc chắn là do quét cả thư viện bên thứ ba hoặc thư mục sao lưu. Loại chúng ra rồi quét lại, con số sẽ giảm mạnh. Sau đó lọc theo mức Nghiêm trọng, và sửa theo nhóm CWE chứ đừng sửa theo từng dòng — một kiểu sai thường lặp ở hàng trăm chỗ.

Quét bị dừng giữa chừng?

Trang quét chia việc thành từng lô nhỏ nên hiếm khi quá hạn. Nếu vẫn dừng, thường là dự án vượt giới hạn số tệp hoặc dung lượng của gói — hãy quét từng phần (ví dụ chỉ thư mục app/, rồi tới public/).

Có lỗi tôi chắc chắn là báo nhầm

Đánh dấu Bỏ qua để nó không làm nhiễu báo cáo. Trạng thái này được nhớ theo từng lần quét.

Mã nguồn của tôi có bị giữ lại không?

Không, trừ khi bạn tự tích "Giữ mã nguồn để tự sửa" — và khi đó mã cũng chỉ nằm lại cho tới khi bạn xoá lần quét đó. Bấm xoá lần quét là gỡ cả kết quả lẫn mã nguồn còn lưu.

Quét được ngôn ngữ nào?

Tập trung vào PHP, JavaScript/TypeScript, Python, Java, C#, Go, Ruby, cùng các tệp cấu hình và hạ tầng (.env, Dockerfile, YAML). Ngoài ra còn các kiểm tra chung như lộ khoá bí mật, quyền tệp và cấu hình sai — những thứ này áp dụng cho mọi dự án.

Vẫn cần hỗ trợ?

Liên hệ qua vi-sos.com. Khi báo lỗi, gửi kèm mã lần quét trên thanh địa chỉ sẽ giúp tra cứu nhanh hơn.