TECHDEV · Công cụ open-source
breakcheck
Dependency của bạn sẽ vỡ. CI của bạn sẽ rò rỉ. Có lẽ không phải hôm nay — nhưng vào ngày nền tảng gỡ API mà bạn phụ thuộc, hoặc cái tag bạn pin bị dời đi, là ngày bạn phát hiện ra. breakcheck quét project để tìm những thứ sẽ vỡ hoặc rò rỉ trước khi chúng xảy ra: dependency cũ, runtime hết hỗ trợ, CI action không pin, quyền workflow quá rộng, Docker base image không pin, và API mà các nền tảng đã gỡ bỏ:
node bin/breakcheck.js check --path .Không phụ thuộc thư viện, Node.js thuần, không mạng, không telemetry. Nó không sửa giùm bạn — nó chỉ cho bạn biết chính xác vấn đề nằm ở đâu, kèm cách sửa cho từng phát hiện, để lần vỡ tiếp theo là một migration có kế hoạch thay vì một cuộc chữa cháy.
Node.js 18+ · Không phụ thuộc thư viện · MIT
Demo: project mẫu cố tình lỗi
Repo đi kèm examples/broken/, cố tình lỗi — gần như mỗi loại một cái. Output thật của lệnh node bin/breakcheck.js check --path examples/broken:
[ERROR] broad-permissions: 'permissions: write-all' grants every permission to the workflow (.github/workflows/ci.yml:5)
fix: Grant only the permissions each job needs, e.g. 'permissions: { contents: read }'
[ERROR] unpinned-action: Action 'actions/checkout@v4' is pinned to mutable ref 'v4' — tags and branches can be moved (.github/workflows/ci.yml:11)
fix: Pin the action to a full commit SHA, e.g. 'owner/repo@<40-hex-sha>'
[ERROR] hardcoded-secret: Possible hardcoded AWS access key id in workflow file (.github/workflows/ci.yml:12)
fix: Move the secret to GitHub Secrets and reference it as ${{ secrets.NAME }}
[ERROR] unpinned-base: Docker base image 'node:latest' uses the mutable ':latest' tag (Dockerfile:1)
fix: Pin the base image, e.g. 'node:22-alpine'
[ERROR] removed-api: XSLT in the browser is being removed from Chrome and Edge — XSLTProcessor will stop working (app.js:2)
fix: Move the transform to the server, or pre-render the output at build time
[ERROR] removed-api: The 'imp' module was removed in Python 3.12 (legacy.py:3)
fix: Use 'importlib' instead
[WARN ] floating-version: Dependency 'foo' uses floating version '*' — installs are not reproducible (package.json:1)
fix: Pin to an exact version or a caret range, e.g. '^1.2.3'
[WARN ] deprecated-dep: 'moment' is in maintenance mode (no new features) (package.json:1)
fix: For new code consider day.js, date-fns, or Temporal
[ERROR] deprecated-dep: 'request' is deprecated since 2020 and unmaintained (package.json:1)
fix: Replace with node:http / undici, axios, or node-fetch
[ERROR] eol-runtime: engines.node '14' targets Node 14, which is end-of-life (Node 16 EOL Sep 2023, Node 14 EOL Apr 2023) (package.json:1)
fix: Move engines.node to '>=18' (20 LTS recommended) and test on it
[ERROR] eol-runtime: requires-python '>=3.8' allows Python 3.8, which is end-of-life (3.8 EOL Oct 2024) (pyproject.toml:1)
fix: Raise requires-python to '>=3.9' (3.11+ recommended)
[ERROR] deprecated-dep: 'pycrypto' is dead and unmaintained (last release 2013) (requirements.txt:1)
fix: Replace with 'pycryptodome'
[WARN ] unpinned-requirement: Requirement 'flask' is not pinned with '==' (requirements.txt:2)
fix: Pin to an exact version, e.g. 'flask==3.0.0'
Summary: 10 error(s), 3 warning(s), 7 file(s) scanned.
Scope: 7 files scanned (patterns v2026.10, scanned 2026-10-26).examples/clean/ qua sạch với:
Summary: 0 error(s), 0 warning(s), 6 file(s) scanned.
No known patterns in 6 files (patterns v2026.10, scanned 2026-10-26).Output demo sao chép đúng từ README của breakcheck (mục "Demo").
Kết quả sạch thực sự có nghĩa gì
- Không thấy pattern đã biết, không có nghĩa là không có vấn đề. Công cụ chỉ biết các pattern trong ruleset của nó; một lần quét sạch không nói gì về các vấn đề ngoài danh sách đó.
- N = số file công cụ đã kiểm tra, không phải mọi file trong thư mục. Các loại file không được quét không tính vào N.
- Phiên bản pattern là "đời" của ruleset — nó chỉ đổi khi một rule thay đổi, nên hai lần chạy cùng phiên bản là kiểm tra cùng một bộ rule.
- Ngày quét là thời điểm quét, một khẳng định tại một thời điểm. Nó không tự cập nhật khi repo phình ra, nên một bản paste cũ không mô tả repo hiện tại.
Công cụ quét cục bộ và không bao giờ gọi về nhà, nên nó không thể kiểm tra advisory trực tuyến — hãy dùng kèm audit của package manager để kiểm tra CVE.
Dịch từ README của breakcheck (mục "What a clean result means").
Bắt đầu nhanh
# cần Node.js 18+
git clone https://github.com/techdevfun/breakcheck.git
cd breakcheck
npm link # khiến `breakcheck` dùng được ở mọi nơiHoặc chạy luôn không cần cài: node bin/breakcheck.js --help
Lệnh sao chép đúng từ README của breakcheck (mục "Install").
Cách dùng
# Quét một project (exit 1 nếu có phát hiện mức error)
breakcheck check --path ./my-project
# Output JSON cho CI / script
breakcheck check --path ./my-project --format json
# Fail cả khi có warning (chế độ nghiêm)
breakcheck check --path ./my-project --fail-on warn| Tùy chọn | Mặc định | Tác dụng |
|---|---|---|
--path DIR | (bắt buộc) | Thư mục project cần quét |
--format text|json | text | Định dạng output |
--fail-on error|warn | error | Fail khi phát hiện đạt mức này |
--help, --version | Hiện trợ giúp / phiên bản |
Mã thoát: 0 = sạch (hoặc chỉ có phát hiện dưới ngưỡng) · 1 = có phát hiện đạt/vượt --fail-on · 2 = đối số sai / không đọc được thư mục.
Trong CI, warning không làm fail mặc định, nên bạn có thể áp dụng mà không vỡ build hiện tại — bật --fail-on warn khi warning đã về 0:
- name: Check for breakage risks
run: node bin/breakcheck.js check --path . --format textLệnh, bảng tùy chọn và mã thoát sao chép đúng từ README của breakcheck (mục "Usage", "In CI").
Nó kiểm tra gì
| File | Rule |
|---|---|
package.json | Dependency cũ (request, node-sass, tslint, babel-eslint, core-js 2.x, …), cảnh báo moment chỉ còn bảo trì, version trôi (*, latest, >=), engines.node trỏ Node hết hỗ trợ, thiếu engines.node |
requirements.txt | Gói Python cũ (pycrypto, nose), requirement không pin (không có ==) |
pyproject.toml | requires-python cho phép Python hết hỗ trợ, thiếu requires-python |
.github/workflows/*.yml | Action pin vào tag/branch có thể dời thay vì commit SHA đầy đủ, permissions: write-all, contents: write quá rộng, pull_request_target (chạy với secret — không chạy code PR không tin cậy dưới nó), secret dạng token bị hardcode. Action cục bộ (./.github/actions/…) thuộc repo nên không bị flag. Image docker:// được kiểm như base image của Dockerfile |
Dockerfile | Base image không tag hoặc :latest (error), tag chỉ có major (warning) |
Code (.js/.ts/.py) | API đã bị gỡ: XSLTProcessor trên trình duyệt, imp của Python, alias kiểu collections.Mapping, distutils |
Bảng dịch tóm tắt từ README của breakcheck (mục "What it checks").
Ghi chú trung thực
- Danh sách deprecation cố tình nhỏ. Mỗi mục đều là một removal hoặc deprecation công khai và đã ngã ngũ — không phải cuộc thi độ phổ biến.
- Chỉ chạy cục bộ, theo thiết kế. Công cụ quét cục bộ và không bao giờ gọi về nhà, nên không thể kiểm tra advisory trực tuyến — hãy dùng kèm
auditcủa package manager để kiểm tra CVE. - Thay đổi hành vi trong 0.2.0: tham chiếu
docker://trước đây bị bỏ qua lặng lẽ; nay được kiểm như base image của Dockerfile (không tag hoặc:latestlà error, tag chỉ có major là warning, tag khác và digest là sạch). Mỗi lần chạy cũng in thêm dòng scope sau dòng Summary.
Dịch từ README của breakcheck.
Roadmap — chưa ship
--fixcho các cách sửa cơ học an toàn (pin:latestthành tag cụ thể cố tình không tự sửa — chọn version là một quyết định).- Output SARIF cho GitHub code scanning.
- Thêm các mục removed-API, từ các báo cáo vỡ thật (mở issue khi một lần gỡ API của nền tảng làm bạn vỡ build).
Roadmap dịch từ README của breakcheck; chưa mục nào ship tính đến 2026-10-30.
Giấy phép
MIT — xem LICENSE trong repository.
Công cụ liên quan
Các công cụ mã nguồn mở khác của TECHDEV: sessguard, runverdict, gheist-guard, vetgate, context-diet, ci-failure-detective, agent-seatbelt, devsecops-os, env-doctor, skill-audit, logtrim, testguard, keymap, memgraph, ggufit, leaseguard, factfence, jsonfold
Đóng góp ý kiến
Bình chọn cho công cụ này, đề xuất tính năng, hoặc thảo luận với các vận hành khác trên bảng cộng đồng.