cv4pve-diag

Corsinvest Srl · Corsinvest.cv4pve.diag

Diagnostic Tool for Proxmox VE

cv4pve-diag is a comprehensive diagnostic tool for Proxmox VE that performs health checks and system analysis on your virtualization infrastructure. Features: - Node health and status monitoring - VM/Container diagnostics and configuration validation - Storage capacity and performance checks - Replication and backup status verification - Snapshot age monitoring - Multiple output formats (Text, HTML, JSON, Markdown) - Customizable severity thresholds - Support for ignore patterns

winget install --id Corsinvest.cv4pve.diag --exact --source winget

Latest 2.4.0

Release Notes

Compliance reporting cv4pve-diag can now produce compliance-aware reports alongside the usual diagnostic output. Diagnostic findings are tagged with the normative controls they satisfy — so when an admin user has no two-factor authentication, the same finding doubles as evidence of a gap against ISO 27001 A.5.17, NIS2 Art. 21(j), DORA Art. 9 and PCI DSS 8.4.2.

  • 40+ diagnostic checks are mapped to compliance controls across 14 frameworks: ISO 27001:2022, NIS2, DORA, PCI DSS v4.0, GDPR, AgID (Italian PA), ENS (Spanish PA, RD 311/2022), BSI C5:2020 (German cloud baseline), SOC 2 (AICPA Trust Services Criteria), NIST SP 800-53 rev.5 (Moderate baseline subset), ISO/IEC 27017 (cloud), ISO/IEC 27018 (PII in cloud), CIS Controls v8 and NIST CSF 2.0. Each finding can carry several control ids — for example, the "admin user without two-factor authentication" finding now references controls across most frameworks at once.
  • New --compliance= command-line option. When passed, the report is filtered to keep only the findings mapped to that standard, and a ControlId column is added so each finding shows the specific control identifier (e.g. A.5.17, Art.21(j)).
  • Works with every output format: Text, Markdown, HTML, JSON, Excel. The Excel header carries the selected standard so the file is self-describing.
  • New IncludeOkResult setting (top-level): when enabled, passing checks are also written to the report (as Ok results). Useful for full audit-style reports that need to prove a control was verified, not only that it was violated.
  • Full explanation, list of standards, control catalog and disclaimer in the new docs/compliance.md.

Important: the compliance mapping is technical and informative only — it covers the subset of each standard that can be verified from the Proxmox VE state. It does not replace a formal audit. See the disclaimer in docs/compliance.md for full scope and limits. New diagnostic checks Two new observability checks fill a gap on long-term monitoring evidence:

  • IC0018 — No external metric server configured on the cluster. Without an InfluxDB / Graphite metric server, long-term monitoring relies only on the volatile per-node RRD, which is reset on reboot — auditors typically require persistent historical data for incident investigation.
  • IC0019 — Metric servers exist but every one of them is disabled — same effect as IC0018, but worth surfacing separately because the fix is just toggling the existing configuration on.
  • IG0016 — VM has a machine type pinned to an old version while the node already offers a newer one (e.g. pc-i440fx-6.2 while pc-i440fx-9.2 is available). Pinning is correct for stability, but old machine versions accumulate deprecated CPU / microcode behaviour and miss QEMU bug-fixes; tagged against the patch-management controls. Upgrade requires a VM stop/start.
  • IC0020 — Pool with members but no ACL entry at /pool/. The pool exists as an organisational tag but is not used as a privilege boundary, which is the point of pools.
  • IC0021 — API token without a comment. Without a comment the token's purpose / owner cannot be attributed at audit time, making safe revocation impossible.
  • WC0019 — Two or more enabled backup jobs run on the same storage at the same systemd-calendar schedule, causing I/O contention and longer overall runtime.
  • WN0045 — Node clock drifts more than 5 seconds from another cluster node. Even when each node looks fine vs NTP, mutual drift is a frequent silent cause of corosync token retransmits, HA fencing instability and broken log correlation. In addition, a wider set of pre-existing checks now also carries compliance tags (TFA on transitive admins, account lifecycle, firewall logging, certificate management, PVE patch level, container privileged-access checks, …) — the diagnostic logic and codes are unchanged, but findings now reference the relevant ISO 27001 / NIS2 / DORA / PCI DSS controls. The full mapping per area is in docs/compliance.md; the full list of checks is in docs/checks.md. Reporting & output
  • --compliance= (see above) adds the ControlId column to every report format.
  • Output format inferred from --output-file extension: passing --output-file=report.xlsx (or .html / .json / .md) now produces the matching format automatically, even without an explicit --output. Previously the file would be saved with the wrong content for the extension.
  • Excel report header now includes the selected compliance standard, when applicable. Documentation The README has been restructured around the most common reading paths. Long content has moved into dedicated docs so the README stays scannable:
  • New docs/checks.md — full catalog of every diagnostic check with code, description and severity.
  • New docs/settings.md — full settings.json reference with field-by-field defaults, performance tuning recipes and CVE scanning configuration.
  • New docs/compliance.md — what the compliance mapping is, list of standards and controls, --compliance CLI usage, and the audit disclaimer.
  • New docs/ignored-issues.md — full guide to suppressing accepted findings. Fixes
  • Error code collision fixed (WG0025): the code was incorrectly used both for the per-VM/CT CPU threshold check and for "HA guest has no replication job". The HA replication check now has its own code (WG0043). Ignore rules referencing WG0025 for HA replication need to be updated — WG0025 from now on means only CPU threshold breach.
  • Error code collision fixed (WN0023): the code was used both for "TLS certificate expires within 30 days" and for "ZFS pool disk usage above threshold". The ZFS pool usage check now uses the new WN0044 code. Ignore rules referencing WN0023 for ZFS pool usage need to be updated — WN0023 from now on means only certificate expiration warning.
  • Cross-node checks skipped on single-node setups (CN0001, CN0002, WN0005, WN0006, WN0007, WN0008, WN0009): these checks compare a node against its peers. On a host with no peers they are now skipped entirely instead of emitting empty / vacuously-true results. Single-node compliance gaps are already surfaced by IC0017, IC0002, IC0003.
  • All remaining cluster fetches are now resilient: a failing call (access, HA, replication, firewall options/rules, pools, status, log, tasks, RRD) no longer aborts the analysis. The affected check is skipped and a WG0042 Warning is recorded, consistently with what was already in place for per-node and per-guest fetches. New checks Access:
  • WC0013 — User holds Administrator role transitively via a group but has no TFA.
  • WC0014 — Disabled user still has Administrator role on /.
  • WC0015 — root@pam has API tokens with no privilege separation (token holds full root rights).
  • WC0016 — User is still enabled past its expiration date.
  • IC0010 — Administrator ACL on / with Propagate disabled — children resources do not inherit.
  • IC0011 — External realm (LDAP / AD / OpenID) does not enforce TFA at realm level. Backup:
  • WC0017 — Enabled backup job has no schedule — it will never run automatically.
  • WC0018 — Recent backup task ended with a non-OK status.
  • IC0012 — Backup job is currently disabled. Firewall:
  • IC0013 — Cluster firewall has enabled rules but none configure logging — no audit trail.
  • IC0014 — Cluster firewall has 10+ disabled rules — stale configuration. Cluster:
  • IC0015 — 10+ error-level entries in the recent cluster journal.
  • IC0016 — 10%+ of recent cluster tasks failed — investigate recurring errors.
  • IC0017 — Cluster has a single node — HA, quorum and replication provide no real protection. Per guest:
  • IG0015 — Running guest is not covered by any HA resource.
  • WG0043 — HA guest has no enabled replication job — on non-shared storage the failover target will have no recent data. (Originally landed as WG0025; reassigned to fix a code collision — see Fixes above.) CVE checks
  • Removed the Debian Security Tracker check (CN0014 / WN0041) and the Cve.DebianTrackerEnabled setting. PVE's /apt/versions API only exposes a curated list of Proxmox-distributed packages (proxmox-ve, pve-manager, kernel, qemu-server, …), which is not what the Debian Security Tracker indexes. The two sets do not overlap, so the check was producing zero findings by design. For a Debian-wide audit run debsecan directly on each node.
  • CN0015 / WN0042 (NVD) — the NVD query now uses virtualMatchString (instead of cpeName with a * version wildcard, which NVD rejects with 404), so the check actually runs and returns Proxmox VE CVEs across all versions.
  • NVD fetch failures now emit a WG0042 warning instead of leaving the check silently empty.
  • NVD CVE entries with no CVSS score or no description are skipped.

Migration: if your settings.json contains "DebianTrackerEnabled": true, just remove that line. The rest of the Cve section keeps working as before. What's Changed

  • feat: tighter CVE checks + xUnit test project by @franklupo in #46
  • feat: 16 new diagnostic checks derived from cv4pve-report compliance by @franklupo in #47
  • feat(resilience): wrap remaining cluster fetches with ToSafe* by @franklupo in #48
  • fix(cve): NVD query + remove Debian Tracker (zero-match by design) by @franklupo in #49
  • feat(compliance): v2.4.0 — full compliance reporting, 14 frameworks, 5 new checks by @franklupo in #50 Full Changelog: v2.3.0...v2.4.0

Installer type: zip

Architecture Scope Download SHA256
x86 Download F435A14CAFD5EFE1E0371A8A8CE511CEC31C7F871FE170A00AD9B3FCA65AC330
x64 Download 0CB6069C0B3220BC300635AB5D3FD70612A70F16A16F7B26DE77DAE79EF28E04
arm64 Download 1A19E84D1B9F51905A1BD43FEDCCCFB57BAF9FBB71AF889DA93210FD2AA25F1B

Details

Homepage
https://github.com/Corsinvest/cv4pve-diag
License
GPL-3.0
Publisher
Corsinvest Srl
Support
https://www.corsinvest.it/cv4pve
Privacy Policy
https://www.corsinvest.it/privacy
Copyright
Copyright (c) 2019-2025 Corsinvest Srl
Moniker
cv4pve-diag

Tags

corsinvestdiagnostichealth-checkmonitoringproxmoxproxmoxvevirtualizationvm

Older versions (10)

2.2.4
Architecture Scope Download SHA256
x86 Download 089D21474F68ED1BA09C10EABB1952A159ED1E4BB1BF7F4461CEEFA75ABFCFFB
x64 Download 9FD22016A5B2895F3920FFC60AABCEF6BAC7878DF708870CF431EF56A36346CA
arm64 Download 8A279D36461FC484547105C6DFF34D1405F3B91EB1B156BCFACE683D0F8676FC
2.2.3
Architecture Scope Download SHA256
x86 Download 02BEDDA5E83114C6AF662B7E0CDD135F60D0533205286621709802A185965E0D
x64 Download 68173250EF81304D1CA97AF6320CC67E18FD24E88EFA60C8CCA398F1D6641A77
arm64 Download 249C16669B724666488D23345695CADC974D689B77780E113F75842CA51F6B26
2.2.2
Architecture Scope Download SHA256
x86 Download 0A158233B1FB0FB2817BC6A61022E1A83B55AAF13B5F38033979F8A3EFF4490F
x64 Download 31D6C2038E6E6DA86071193331859273419706967BC37F4667F69640473E4EF2
arm64 Download 1C78E1889D2144D76FEDAA3BF0BB9D03EBCA01C4A25D62AA7A2FD236B764C028
2.2.1
Architecture Scope Download SHA256
x86 Download 2D34BA2377FB14A78C9894A25B8E846F2745C5E0732A9150DDAF6DDEF2F7C19F
x64 Download 7B35B13ED3BA7505234BAFA75571C02A94E8E3A52654A59921000E8705DB7F89
arm64 Download CE30179752B6370AFA188BE6954B7A0E7B16510CB7954E0A526E6552B13850D6
2.2.0
Architecture Scope Download SHA256
x86 Download A4A48517DCC95C09B59048CE8D4C20C3B5589243D393BE57B5CE9D3EF7896829
x64 Download 0B963C6262134D010619FE524A297E8B36FDE971E3B9BA5E9D686739F63BD416
arm64 Download 5817A7733DFAEA02AE7BAC320E67392330642667F81C02E738097061F99DD621
2.1.0
Architecture Scope Download SHA256
x86 Download 7165C03B6C16786233DEDECA044CF5728143815824A518889681CED2C42F6332
x64 Download 24775262C8529CAF076E3945F7313D1D28C28904A8B6E92797E2C0BC465E295E
arm64 Download 754EBDA11D2E4423214D1F75F7C0C11A8992049450E9ACC76D1DC3CA5EBC457B
2.0.3
Architecture Scope Download SHA256
x86 Download 0BC802EF54EF955B666A70625BE6F08C91B00B4BFE97A68FC6F33B6994D1163C
x64 Download 74BA91212010F15561474A1288FF2DD53B4282BB6E168C379BCBD3E6EDE89A3E
arm64 Download 016407AC5E6A867C97D7DEF7ECE1D40E14EF4C9D85F5FC6F8697F0D1D6E85754
2.0.2
Architecture Scope Download SHA256
x86 Download 98280E1F39837C69BD6C7E5027E29119A6B38D6CC0F4245D3C8FF8D3745B4CED
x64 Download BF3832F5EB5E3071C19F686298F852FE9588CA198349947EEFF7FED1F75BEF68
arm64 Download 7E0129E62F5EAF56CDD6AEDEB0E24AF17EF38FB6B05905027C4F68DF416D4A8A
2.0.1
Architecture Scope Download SHA256
x86 Download 529A57440CC04FCF2633BB523125F78813B7B7C7FF785E61BA98823B32234CB4
x64 Download 763257DFBE3C6741E306FBE9DA75183156053D59CA4BFB06A4C25A0118A61C7C
arm64 Download F0C4F101D5CECE31DECADCECEC04DC4B514B1E59C656BB37F68E5ABD73AE3642
1.9.0
Architecture Scope Download SHA256
x64 Download 2A143004B834B07CB6CF51653029B6E2B9B002F66FBC5D0311B9BC37133BF5F5
x86 Download 739FB4E55FEAC8B825794A5A85DD1B5516DB9C61ADB7CBFE3FDDC7B146E6C4FA
arm64 Download A1D68D3533808811FA17E3B69461D18F7D3363738E65E7F1601824A84351F3A5