Đã đăng vào khoảng 5 giờ trước 4 phút đọc

libscan — CLI rà soát lỗ hổng dependency

MayFest2026

libscan — CLI rà soát lỗ hổng dependency và runtime EOL cho dự án PHP / JavaScript

Mở bài

Một web app bây giờ thường kéo theo vài trăm thư viện bên thứ ba qua Composer hoặc npm/yarn/pnpm. Trước mỗi lần release, dev và PM hay phải trả lời ba câu: dependency nào đang dính CVE nghiêm trọng, runtime (PHP, Node, Laravel, Vue...) còn được hỗ trợ không, và package nào đã quá cũ cần nâng cấp. Các SaaS thương mại làm được, nhưng đa phần bắt tạo tài khoản, gắn vào repo, và quá nặng nề cho team nhỏ hoặc các lần audit một lần để bàn giao cho khách.

libscan sinh ra để lấp khoảng đó: một CLI gọn, một binary tĩnh, không CGO, không tài khoản, không telemetry. Trỏ vào thư mục dự án, nó đọc lock file, hỏi các nguồn dữ liệu công khai, rồi xuất ra báo cáo dùng được luôn.

Cách hoạt động

Pipeline gồm 4 bước, mỗi bước đều có thể chạy độc lập nên dễ debug khi có gì đó sai:

Walk source tree, phát hiện các lock file đã biết: composer.lock, package-lock.json, yarn.lock, pnpm-lock.yaml. Đọc đúng version đang được resolve, không đoán từ semver range trong manifest.
Truy vấn dữ liệu công khai cho từng package, song song có rate-limit:
- OSV.dev — CVE advisories chuẩn hoá theo ecosystem
- Packagist / npm registry — version mới nhất để biết khoảng cách upgrade
- endoflife.date — trạng thái EOL của runtime và framework
- FIRST.org EPSS — xác suất CVE bị khai thác trong 30 ngày tới (best-effort)
- CISA KEV — danh sách lỗ hổng đã được xác nhận khai thác thực tế (best-effort)
Phân loại mỗi finding thành BLOCK / REVIEW / OK theo ngưỡng CVSS cấu hình được. Runtime gắn thêm nhóm Expired / Warn / Supported / Unknown với cửa sổ cảnh báo tuỳ chỉnh.
Render báo cáo ra một trong bốn format — text màu, json, docx, pdf — bằng tiếng Anh, tiếng Nhật hoặc tiếng Việt.

Cài đặt

Bản pre-built có sẵn cho macOS, Linux và Windows (cả x86_64 và arm64) ở mỗi tag release. Chọn cách nào tiện nhất với máy bạn.

macOS / Linux — Homebrew (khuyến nghị)

brew tap vocweb/tap
brew install libscan

Windows — Scoop (khuyến nghị)

scoop bucket add vocweb https://github.com/vocweb/scoop-bucket
scoop install libscan

Mọi OS — qua `go install`

Yêu cầu Go 1.23+ trên máy:

go install github.com/vocweb/libscan-cli/src/cmd/libscan@latest

Mọi OS — tải archive trực tiếp

Tải archive mới nhất từ trang Releases, giải nén rồi đưa binary vào PATH.

macOS / Linux (đổi Darwin_arm64 cho đúng platform: Darwin_x86_64, Linux_arm64, Linux_x86_64):

curl -sSL https://github.com/vocweb/libscan-cli/releases/latest/download/libscan-cli_<VERSION>_Darwin_arm64.tar.gz | tar xz
sudo mv libscan /usr/local/bin/

Windows PowerShell:

$ver = (Invoke-RestMethod https://api.github.com/repos/vocweb/libscan-cli/releases/latest).tag_name.TrimStart("v")
$url = "https://github.com/vocweb/libscan-cli/releases/latest/download/libscan-cli_${ver}_Windows_x86_64.zip"
Invoke-WebRequest $url -OutFile "$env:TEMP\libscan.zip"
Expand-Archive "$env:TEMP\libscan.zip" -DestinationPath "$env:USERPROFILE\bin" -Force
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")

Build từ source

Dùng khi muốn nghịch code hoặc cross-compile (cần Go 1.23+):

git clone https://github.com/vocweb/libscan-cli && cd libscan-cli
make build         # binary nằm ở ./bin/libscan

Kiểm tra cài đặt xong

libscan --version

Dùng nhanh

Scan thư mục hiện tại với cấu hình mặc định:

libscan

Scan một dự án cụ thể và xuất báo cáo PDF:

libscan --scan-path=/var/www/app --format=pdf --output=report.pdf

Tích hợp CI, fail job khi có finding mức BLOCK:

libscan --format=json --fail-on=BLOCK

Xuất báo cáo tiếng Việt dạng DOCX gửi khách:

libscan --lang=vi --format=docx --output=audit.docx

Các flag hay dùng

Flag	Ý nghĩa	Mặc định
`--scan-path`	Thư mục cần scan	`cwd`
`-f`, `--format`	`text` \| `json` \| `docx` \| `pdf`	`text`
`-o`, `--output`	Đường dẫn file output	stdout
`--lang`	`en` \| `ja` \| `vi`	`en`
`--workers`	Số worker truy vấn registry song song	`8`
`--timeout`	Timeout HTTP mỗi request (giây)	`10`
`--block-cvss`	Ngưỡng CVSS để xếp `BLOCK`	`9.0`
`--warn-cvss`	Ngưỡng CVSS để xếp `REVIEW`	`7.0`
`--fail-on`	`REVIEW` \| `BLOCK` — exit non-zero khi chạm mức này	(tắt)
`--offline-skip-epss`	Bỏ EPSS/KEV khi chạy ở môi trường air-gapped	`false`
`--no-low`	Ẩn finding `LOW` khỏi báo cáo	`false`

Mọi flag đều có khoá tương ứng trong libscan.ini, tiện để mỗi project commit kèm cấu hình mặc định. Flag CLI luôn ưu tiên hơn giá trị trong file.

Exit code thân thiện với CI

Code	Ý nghĩa
`0`	Scan xong, không vi phạm policy `--fail-on`
`2`	Lỗi người dùng (sai flag, config hỏng, path không tồn tại)
`3`	Lỗi runtime (mạng, render, walker)
`4+`	Exit theo policy khi `--fail-on=REVIEW` hoặc `--fail-on=BLOCK` kích hoạt

Mặc định, tìm thấy lỗ hổng KHÔNG làm vỡ build — chỉ --fail-on mới làm việc đó. Nhờ vậy bạn có thể drop libscan vào pipeline đang chạy mà không sợ release bị chặn bất ngờ.

Khi nào nên dùng

Audit nhanh một codebase trước khi nhận bàn giao, hoặc trước khi bàn giao cho khách
Gắn vào CI để gate release khi có CVE nghiêm trọng hoặc đã có exploit ngoài đời
Sinh PDF/DOCX cho engineering lead hoặc PM, khỏi phải copy-paste output terminal
Kiểm tra runtime (PHP, Node, Laravel, Vue, ...) còn được hỗ trợ hay đã EOL
Chạy ở môi trường air-gapped với --offline-skip-epss khi không có internet ra ngoài

Kết

libscan là một tool nhỏ, làm một việc và làm tới: cho bạn biết dependency và runtime nào đang là rủi ro, ở mức nào, và cái gì cần ưu tiên xử lý — chỉ bằng một câu lệnh, không cần dựng hạ tầng, không cần tài khoản. Hợp với dev cá nhân, team nhỏ, agency, và bất kỳ ai cần một bản audit dependency nhanh, sạch, và hành động được.

cli