Audit
Govard lưu mỗi lần audit như một session bất biến tại ~/.govard/audit/<project-id>/sessions/<session-id>/. Dùng để lint code Magento, bắt webshell và capture CSV profiler stock của Magento mà không sửa env.php.
Bắt đầu nhanh
# Lint toàn project (tự dò mode)
govard audit run
# Phân tích không cần container (Magento 2 / Mage-OS) — chạy trên host, không cần Docker
govard audit run --checks integrity
# Lint + profiler trên một URL (lần đầu cần --url)
govard audit run --checks lint,profiler --url 'https://shop.test/category.html?product_list_limit=48'
# Chỉ profiler
govard audit run --checks profiler --url 'https://shop.test/'
# Chạy lại đúng bộ check cũ (dùng lại URL profiler đã freeze)
govard audit rerun --session 20260816T010203Z-a1b2c3d4
# Kiểm tra
govard audit status --session 20260816T010203Z-a1b2c3d4
govard audit result --session 20260816T010203Z-a1b2c3d4 --run run-0001
govard audit diff --base origin/master
# Machine-readable
govard audit run --format jsonExit code: 0 khi mọi check pass, khác 0 sau summary khi có check fail/cancel — dùng được cho CI.
Các check
| Check | Chức năng |
|---|---|
lint | Phân tích tĩnh qua backend native (phpcs + phpstan + media guard). |
integrity | Magento 2 / Mage-OS: phân tích không cần container, đọc trực tiếp checkout — Composer manifest/lock có khớp nhau (kể cả composer.lock có được sinh từ đúng composer.json bên cạnh hay không, so bằng chính content-hash của Composer), tính nhất quán module/DI/sequence, và tính hợp lệ của các định nghĩa route mà module mang theo (webapi.xml, routes.xml). Chạy trên host nên dùng được cả khi máy không có Docker. |
profiler | Capture MAGE_PROFILER=csvfile stock của Magento qua include web-server có lease, một GET có giới hạn tới --url, rồi khôi phục. |
profiler yêu cầu:
- Target là whole Govard project (standalone/module-only bị từ chối trước khi mutate).
--urltuyệt đốihttp(s)://ở lần chạy đầu (freeze trong run và đượcrerundùng lại).- Đã
govard env upvới bản Govard hiện tại (để mount custom config tồn tại).
Artifact: runs/<run-id>/artifacts/profiler/profile.csv + digest SHA-256.
Chế độ target (--mode)
auto (mặc định) tự phân loại thư mục mà target được phân giải từ đó: thư mục làm việc hiện tại, hoặc --path <dir> nếu được truyền.
| Mode | Khi nào | Phạm vi phân tích |
|---|---|---|
project | Thư mục chứa root Magento (bin/magento + Composer requirement Magento) và không nằm trong module | Toàn project |
module_in_project | Thư mục là module (etc/module.xml hoặc Composer type magento2-module) trong project Magento | Chỉ module đó (toàn project mount read-only) |
standalone | Thư mục là module không có project Magento ở trên | Chỉ module đó (deps cài vào worktree tạm) |
Ép buộc với --mode project|module_in_project|standalone — lỗi nếu thư mục không thỏa. audit run và audit diff nhận --path <dir> để phân giải target ở nơi khác thư mục làm việc hiện tại (đường dẫn tương đối được tính theo thư mục đó; thư mục phải tồn tại), nhờ vậy có thể audit một module mà không cần đổi thư mục trước. Chi tiết xem docs/reference/cli-commands.md.
Trạng thái phase: failed và error
Mỗi phase công cụ (phpcs, compat, phpstan) báo failed khi công cụ chạy xong và tìm thấy lỗi, và error khi chính công cụ bị lỗi. Phase error mang exit_code và stderr_tail (50 dòng cuối của stderr, tối đa 8 KiB) trong report JSON, và thông báo lỗi audit có dạng PHP <version> phpstan: error (exit 255): <dòng stderr cuối>. Phase phpstan mà finding duy nhất là lỗi crash của analyzer (Internal error: ..., được tách riêng thành giới hạn công cụ) cũng hiển thị là error, trong khi outcome của kết quả PHP vẫn do các finding còn lại quyết định.
Phiên bản PHP (--php)
Lint image cung cấp 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5.
project/module_in_project: đúng một version —stack.php_versionđang active. Truyền--phpchỉ chấp nhận khi trùng version đó; từ chối nếu container đang chạy báo PHP khác config.standalone: nhận8.1–8.5(mặc định cả năm).7.4/8.0bị từ chối trước khi làm gì (unsupported_php:).
Đường dẫn quét & Media guard
Analyzer bỏ qua vendor/, generated/, var/, pub/static/, pub/media/ (không phải shipped code). Vì pub/media là nơi webshell được upload, mỗi PHP version còn chạy media guard: quét theo tên trong pub/media tìm .php/.phtml/.pht. Mỗi hit là M2-LINT-MEDIA (tiền tố theo framework: M2-LINT-* cho Magento, LARAVEL-LINT-*, SYMFONY-LINT-*, WP-LINT-*) và fail run — chỉ mili giây, chỉ tên file.
Provider (--lint-provider)
| Giá trị | Backend |
|---|---|
govard (mặc định) | Native: context build nhúng, ghim theo digest. Nếu image đã ghim không pull được hoặc label lệch, Govard build local và tiếp tục. |
<external> | Phải trùng key trong audit.lint.external_providers ở .govard.yml (Cấu hình). Không bao giờ là fallback; tên lạ = lỗi. |
Module standalone không có project config nên chỉ dùng được govard.
Cache
State tái sử dụng: ~/.govard/cache/audit/lint/<target-id>/ (sống sót sau audit cleanup). Một generation cho mỗi toolchain identity (image, runner, PHP matrix, analyzer policy).
- Đổi
composer.json/composer.lockhoặc ruleset (phpcs.xml,phpstan.neon,*.dist) loại bỏ analyzer state nhưng giữ Composer download cache. --no-lint-result-cachebáobypassedvà giữ download cache.
Evidence ghi cache state (cold/warm/bypassed) + lý do theo từng PHP, image digest, toolchain digest, timing từng phase.
Credential: ~/.composer/auth.json mount read-only khi tồn tại. SSH_AUTH_SOCK chỉ forward với --allow-lint-ssh-agent. Source tree luôn read-only.
Toolchain
Image lint dùng chung cả máy — không cần project, không gọi external provider:
govard audit toolchain status # chỉ local — nên chạy gì tiếp
govard audit toolchain pull # chỉ image official đã ghim, không build
govard audit toolchain build # chỉ context nhúng, không pullCác lệnh này cần container runtime: status kiểm tra image local, pull tải một image, build build một image. Trên host không có Docker, chúng thoát với mã 3 kèm CAPABILITY_MISSING trước khi chạm vào bất cứ thứ gì, giống mọi lệnh cần Docker khác (Runs Without Docker). Phân tích không cần container không bị ảnh hưởng — govard audit run --checks integrity không hề chạm tới container.
File
| Đường dẫn | Nội dung |
|---|---|
~/.govard/audit/<project-id>/sessions/<session-id>/manifest.json | Session manifest |
.../runs/<run-id>/audit-result.json | Evidence từng run (ghi atomically) |
.../runs/<run-id>/report.json | Report native của provider |
.../runs/<run-id>/artifacts/profiler/profile.csv | CSV profiler (khi bật) |
~/.govard/cache/audit/lint/<target-id>/ | Cache lint tái sử dụng |