Skip to content

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 ​

bash
# 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 json

Exit 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 ​

CheckChức năng
lintPhân tích tĩnh qua backend native (phpcs + phpstan + media guard).
integrityMagento 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.
profilerCapture 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).
  • --url tuyệt đối http(s):// ở lần chạy đầu (freeze trong run và được rerun dùng lại).
  • Đã govard env up vớ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.

ModeKhi nàoPhạm vi phân tích
projectThư mục chứa root Magento (bin/magento + Composer requirement Magento) và không nằm trong moduleToàn project
module_in_projectThư mục là module (etc/module.xml hoặc Composer type magento2-module) trong project MagentoChỉ module đó (toàn project mount read-only)
standaloneThư mục là module không có project Magento ở trênChỉ 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 --php chỉ 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ận 8.1–8.5 (mặc định cả năm). 7.4/8.0 bị 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.lock hoặc ruleset (phpcs.xml, phpstan.neon, *.dist) loại bỏ analyzer state nhưng giữ Composer download cache.
  • --no-lint-result-cache báo bypassed và 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:

bash
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 pull

Cá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ẫnNội dung
~/.govard/audit/<project-id>/sessions/<session-id>/manifest.jsonSession manifest
.../runs/<run-id>/audit-result.jsonEvidence từng run (ghi atomically)
.../runs/<run-id>/report.jsonReport native của provider
.../runs/<run-id>/artifacts/profiler/profile.csvCSV profiler (khi bật)
~/.govard/cache/audit/lint/<target-id>/Cache lint tái sử dụng

→ Tham khảo: Lệnh CLI · Cấu hình

Phát hành theo giấy phép MIT.