PSProxmoxVE/docs/review/REVIEW_REPORT.md

PSProxmoxVE Module Review Report — Scan 7

Scan date:           2026-03-23
Prior report date:   2026-03-23 (scan-6)
PVE API spec date:   2026-03-21T15:04:50.641Z
PVE API spec SHA256: 4af79be30166209a4714b771f65e1e9540c5b738f414ff30c98454402e29d030
PVE version hint:    N/A (not set in spec)
Total API endpoints: 646
Findings DB:         docs/review/findings.json (F001–F083)
Open findings:       12 (before scan) → 11 open + 1 regressed (after scan)
New this scan:       0  Resolved this scan: 1 (F082)  Regressed: 1 (F050)
Last CI run:         integration-tests.yml | success | 2026-03-23T21:42:02Z | https://github.com/goodolclint/PSProxmoxVE/actions/runs/23461565300

Executive Summary

• Delta: 1 resolved (F082) | 0 new | 1 regressed (F050) | 11 open + 1 regressed
• API drift: 0 breaking changes in implemented endpoints | 42 PVE 9.0 endpoints unimplemented (F061)
• CI: Last integration run: PASSED | 0 test failures (both PVE 8 and PVE 9)
• Code quality: 11 of 12 DECISIONS.md entries upheld — 1 regression (D003: URL encoding in 5 service files)
• Module has 169 cmdlets, ~170 markdown docs, netstandard2.0 targeting, 1,749 total tests (374 xUnit + 1,268 Pester + 107 integration)
• PSGallery manifest complete except IconUri (F021)
• All community/repo standards pass (issue templates, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CODEOWNERS, etc.)

---

Phase 1 — Repository Inventory & Structure

Project Layout

Item	Present	Path/Notes
Solution file	Yes	PSProxmoxVE.sln
Cmdlet project	Yes	src/PSProxmoxVE/ (netstandard2.0)
Core library	Yes	src/PSProxmoxVE.Core/ (netstandard2.0)
xUnit tests	Yes	tests/PSProxmoxVE.Core.Tests/ (net10.0;net48)
Pester tests	Yes	tests/PSProxmoxVE.Tests/
Module manifest	Yes	src/PSProxmoxVE/PSProxmoxVE.psd1
MAML help	Yes	src/PSProxmoxVE/PSProxmoxVE.dll-Help.xml
Format file	Yes	src/PSProxmoxVE/PSProxmoxVE.format.ps1xml
README.md	Yes	With badges (Build, Unit Tests, License, PSGallery)
CHANGELOG.md	Yes	Keep a Changelog format, 0.1.0-preview entry
CONTRIBUTING.md	Yes	Dev setup, coding standards, PR process
LICENSE	Yes	MIT
CODE_OF_CONDUCT.md	Yes	Contributor Covenant 2.1
SECURITY.md	Yes	Vulnerability disclosure policy
DECISIONS.md	Yes	12 active decisions (D001–D012)
.editorconfig	Yes	Root config with per-filetype overrides
.gitignore	Yes	Comprehensive
.gitattributes	Yes	LF enforcement, binary handling, diff drivers
CODEOWNERS	Yes	* @goodolclint
dependabot.yml	Yes	Automated dependency updates
Issue templates	Yes	Bug report + feature request (YAML forms) + config.yml
PR template	Yes	Summary, type, checklist, API endpoints, testing
CI workflows	Yes	build.yml, unit-tests.yml, integration-tests.yml, publish.yml
Review system	Yes	docs/review/findings.json, docs/review/REVIEW_REPORT.md
Cmdlet docs	Yes	~170 markdown files in docs/cmdlets/

Missing Items

Finding ID	Item	Notes
F021	IconUri in manifest PSData	PSGallery listings display placeholder without it

---

Phase 2 — PVE API Coverage Audit

Coverage by Functional Area

Area	Spec Endpoints	Covered	%	Notes
VMs (qemu)	97	~30	31%	Core CRUD, lifecycle, guest agent, disk ops, config
Containers (lxc)	62	~18	29%	CRUD, lifecycle, snapshots, config, interfaces
Nodes	77	~10	13%	List, status, config, DNS, startall/stopall
Firewall	40	~22	55%	Rules, groups, aliases, IP sets, options, refs
Cluster	79	~3	4%	Resources and status only
SDN	60	~16	27%	Zones, VNets, subnets, IPAM, DNS, controllers
Storage	24	~14	58%	CRUD, content, upload, download, allocate
Backup	6	6	100%	Full coverage
Access/Users	45	~22	49%	Users, groups, roles, domains, tokens, ACL, permissions
Tasks	5	~4	80%	List, status, log, stop
Pools	7	~5	71%	CRUD + list
HA	21	0	0%	F053 — 🆕 Rules subsystem new in PVE 9.0
Ceph	40	0	0%	F054
Notifications	25+	0	0%	F068 — New in PVE 8.1+
ACME/Certs	23	0	0%	F069
Disks	18	0	0%	F067
Replication	5	0	0%
Services	7	0	0%
Total	646	~120	~18.6%

API Drift Table

No breaking changes detected in endpoints the module currently implements. All changes are additive (new optional parameters).

Finding ID	Area	Change	PVE Version	Risk
F061	HA rules	New /cluster/ha/rules subsystem	9.0	Additive
F061	Bulk actions	New /cluster/bulk-action	9.0	Additive
F061	SDN fabrics	New /cluster/sdn/fabrics	9.0	Additive
—	Various	77 additive parameter changes across implemented endpoints	8.x–9.x	Additive

High-Value Uncovered Endpoints

Priority 1 — Commonly needed:

• GET /access/acl — List ACLs (only PUT covered)
• GET /cluster/nextid — Get next free VM ID
• GET /cluster/ha/resources — HA resource management
• VNC/SPICE console proxy endpoints
• GET /nodes/{node}/subscription — Subscription status

Priority 2 — Frequently useful:

• GET /nodes/{node}/syslog / journal — Log access
• GET /nodes/{node}/hardware — PCI passthrough info
• GET /nodes/{node}/scan/* — Storage discovery
• POST /access/domains/{realm}/sync — LDAP/AD sync
• APT package management

---

Phase 3 — Code Quality & Best Practices

DECISIONS.md Compliance

Decision	Status	Notes
D001 — TaskService.WaitForTask	✅ Compliant	No inline polling loops in cmdlets
D002 — SecureString passwords	✅ Compliant	All 6 password params use SecureString
D003 — URL encoding	❌ REGRESSED (F050)	20 instances in 5 service files
D004 — No bare catch blocks	✅ Compliant	All catches are specific or filtered
D005 — OutputType on all cmdlets	✅ Compliant	All 169 cmdlets have OutputType
D006 — ConfirmImpact.High	✅ Compliant	All destructive cmdlets confirmed
D007 — Sealed cmdlet classes	✅ Compliant	All 169 cmdlets sealed
D008 — Newtonsoft.Json only	✅ Compliant	No System.Text.Json attributes
D009 — Framework targets	✅ Compliant	netstandard2.0 / net10.0;net48
D010 — VmId ValidateRange	✅ Compliant	All VmId params validated
D011 — Verb class constants	✅ Compliant	No string literals
D012 — Magic string constants	✅ Compliant	Auth headers extracted

D003 Regression Detail (F050)

20 instances of missing Uri.EscapeDataString() across 5 service files:

File	Methods Affected	Unescaped Params
NodeService.cs	7 (GetNodeStatus, GetNodeConfig, SetNodeConfig, GetDns, SetDns, StartAll, StopAll)	node
NetworkService.cs	5 node-network (GetNetworks, CreateNetwork, SetNetwork, RemoveNetwork, ApplyNetworkConfig)	node, iface
NetworkService.cs	2 SDN (RemoveSdnZone, RemoveSdnVnet)	zone, vnet
CloudInitService.cs	3 (GetCloudInitConfig, SetCloudInitConfig, RegenerateCloudInitImage)	node
TaskService.cs	2 (GetTask, GetTaskLog)	node
TemplateService.cs	1 (CreateTemplate)	node

Properly escaped services (no issues): VmService, ContainerService, SnapshotService, FirewallService, PoolService, UserService, StorageService.

Other Code Quality Findings

• No TODO/FIXME/HACK comments
• No commented-out code
• No unused using directives detected
• HttpClient lifecycle is well-managed (1:1 ownership, proper disposal)
• PveCmdletBase.WaitForStatusTransition power-state polling loop is distinct from task polling (D001 compliant)

---

Phase 4 — Testing Coverage Analysis

Test Summary

Category	Files	Tests
xUnit (C# unit)	25	374
Pester (PS unit)	48	1,268
Pester (integration)	1	107
Total	74	1,749

Coverage Highlights

• 100% cmdlet unit test coverage — all 169 cmdlets have Pester parameter/metadata tests
• xUnit service tests: UserService (78), StorageService (40), FirewallModel (24), BackupService (23), SdnModel (21)
• 32 JSON fixture files from real PVE 8/9 API responses for model deserialization tests
• Integration tests: 107 tests across connection, nodes, VMs, containers, snapshots, storage, users, firewall, SDN, backup, templates, cloud-init, guest agent

Coverage Gaps (F046)

Gap	Severity	Detail
No VmService xUnit tests	Medium	VM ops (clone, migrate, import) have complex logic untested at service layer
No ContainerService xUnit tests	Medium	Similar complexity to VmService
No NetworkService xUnit tests	Low	Thin CRUD wrappers
No FirewallService xUnit tests	Low	Thin CRUD wrappers
Pool/Cluster cmdlets lack integration tests	Low	Simple read-only operations

---

Phase 4b — CI Integration Test Results

Last CI Run

Field	Value
Run ID	23461565300
Conclusion	SUCCESS
Date	2026-03-23T21:42:02Z
SHA	1faaba0
Branch	main

All 7 jobs passed: container-image, build, provision, test(8), test(9), cleanup, cleanup-images.

CI Findings

Finding ID	Test / Cmdlet	Status	Notes
F080	Restart-PveContainer	Resolved (scan-6)	ConfirmImpact.High fix applied
F081	Copy-PveContainer	Resolved (scan-6)	Cascade from F080
F082	PVE 8 Docker image	Resolved (this scan)	Container-image job now succeeds

---

Phase 5 — Security Review

Finding ID	Area	File(s)	Severity	Status	Description
F050	URL encoding	5 service files	Medium	Regressed	20 instances of unescaped path params (see Phase 3)
F031	Secrets	terraform.tfvars, CI	Low	Open	Lab IPs in terraform.tfvars (gitignored); CI uses ${{ secrets.* }} properly
—	Credential handling	All password cmdlets	Pass	—	SecureString with Marshal try/finally throughout
—	TLS/HTTPS	PveHttpClient.cs	Pass	—	HTTPS-only, SkipCertificateCheck opt-in with warning
—	CSRF	PveHttpClient.cs	Pass	—	CSRFPreventionToken on all mutating requests
—	Bare catches	All .cs files	Pass	—	No D004 violations
—	Boundary generation	PveHttpClient.cs	Pass	—	Uses RandomNumberGenerator (CSPRNG)
—	Dependencies	Both .csproj	Pass	—	Newtonsoft.Json 13.0.3, SharpCompress 0.47.3 (current)

---

Phase 6 — PSGallery Publication Readiness

Finding ID	Check	Pass/Fail	Notes
—	ModuleVersion	Pass	0.1.0, dynamically set from git tag
—	GUID	Pass	Present and unique
—	Author/CompanyName	Pass	goodolclint / Worklab
—	Description	Pass	Descriptive, mentions PVE 8.x/9.x
—	PowerShellVersion	Pass	5.1 minimum
—	CompatiblePSEditions	Pass	Desktop + Core
—	CmdletsToExport	Pass	Explicit list of 169 cmdlets
—	Tags	Pass	8 tags for discoverability
—	LicenseUri/ProjectUri	Pass	GitHub links
F021	IconUri	Fail	Not set — PSGallery shows placeholder
—	ReleaseNotes	Pass	Present in PSData
—	Framework targets	Pass	netstandard2.0 for both publishable projects
—	Publish workflow	Pass	Tag-triggered, 3-job pipeline with PS 5.1 smoke test
—	CHANGELOG	Pass	Keep a Changelog format

---

Phase 7 — Community & Repo Maintenance Standards

Finding ID	Check	Pass/Fail	Notes
—	Bug report template	Pass	YAML form with version fields
—	Feature request template	Pass	YAML form with use case
—	Issue template config	Pass	Disables blank issues, links to Discussions
—	PR template	Pass	Checklist with build, tests, psd1, changelog
—	CONTRIBUTING.md	Pass	Complete dev setup and coding standards
—	CODE_OF_CONDUCT.md	Pass	Contributor Covenant 2.1
—	SECURITY.md	Pass	Responsible disclosure instructions
—	DECISIONS.md	Pass	12 decisions, linked from CLAUDE.md
—	CODEOWNERS	Pass	* @goodolclint
—	.editorconfig	Pass	Per-filetype overrides
—	.gitattributes	Pass	LF enforcement, binary handling
—	Commit conventions	Pass	Conventional Commits consistently used
—	Release process	Pass	Tag-based publish with GitHub Release
—	Dependabot	Pass	Automated dependency PRs

---

Phase 9 — Prioritized Recommendations

🔴 Critical

No critical findings.

🟠 High

No high findings.

🟡 Medium

Finding ID	What	Where	Why	Fix
F050	Uri.EscapeDataString missing (REGRESSED)	NodeService, NetworkService, CloudInitService, TaskService, TemplateService	D003 violation — defense-in-depth URL encoding missing on 20 path parameter interpolations	Add Uri.EscapeDataString() to all node, iface, zone, vnet params in URL paths
F046	Integration test coverage gaps	tests/	VmService, ContainerService lack xUnit service-layer tests; Pools/Cluster lack integration tests	Add xUnit tests for VmService and ContainerService
F059	VM/CT-level firewall 0% coverage	—	Firewall endpoints exist for VMs and containers but no cmdlets implemented	Add VM/CT-scoped firewall cmdlets
F060	Cluster config 0% coverage	—	Cluster options, join/create, notifications, metrics uncovered	Add cluster config cmdlets
F061	PVE 9.0 endpoints 0% coverage	—	42 new endpoints (HA rules, bulk actions, SDN fabrics) not implemented	Prioritize HA rules and bulk actions

🟢 Low

Finding ID	What	Where	Why	Fix
F021	No IconUri in manifest	PSProxmoxVE.psd1	PSGallery listing looks less professional	Add 128x128 PNG icon and set IconUri
F031	Hardcoded test IPs	terraform.tfvars, CI	Lab IPs committed (gitignored locally)	Verify tfvars not tracked in git
F053	HA subsystem 0% coverage	—	No HA cmdlets	Implement when HA rules (PVE 9.0) are prioritized
F054	Ceph subsystem 0% coverage	—	Large specialized surface	Low priority unless Ceph users identified
F067	Disk management 0% coverage	—	Node disk ops (LVM, ZFS, init)	Useful for provisioning workflows
F068	Notifications 0% coverage	—	25+ endpoints (PVE 8.1+)	Medium-value for operational users
F069	ACME/Certificates 0% coverage	—	Certificate management	Low priority