AzureLocalRanger

Author(s)

• Azure Local Cloud

Tags

AzureLocal AzureStackHCI HCI Arc ArcEnabledInfrastructure PowerShell Documentation Inventory Audit AsBuilt Report Discovery HealthCheck Cluster FailoverClustering Windows WindowsServer Hyper-V StorageSpacesDirect S2D

Functions

Invoke-AzureLocalRanger New-AzureLocalRangerConfig Export-AzureLocalRangerReport Test-AzureLocalRangerPrerequisites Test-RangerPermissions Invoke-RangerWizard Export-RangerWafConfig Import-RangerWafConfig Get-RangerRemediation Publish-RangerRun

PSEditions

Core

Dependencies

This module has no dependencies.

Release Notes

## v2.3.0 — Cloud Publishing

Push Ranger run packages to Azure Blob and stream telemetry to Log Analytics
Workspace after every run — with no code changes required if the cluster is
already Arc-enrolled and the runner has Storage Blob Data Contributor.

### Added
- **Azure Blob publisher (#244)** — `Publish-RangerRun` uploads the run package
 (manifest, evidence, package-index, log, reports, powerbi) to Azure Blob with
 SHA-256 idempotency. Auth chain: Managed Identity → Entra RBAC → SAS from Key Vault.
 `Invoke-AzureLocalRanger -PublishToStorage` triggers automatically post-run.
- **Catalog + latest-pointer blobs (#245)** — after each publish, writes
 `_catalog/{cluster}/latest.json` and merges `_catalog/_index.json` so
 downstream consumers find the latest run without listing.
- **Log Analytics Workspace sink (#247)** — `Invoke-AzureLocalRanger -PublishToLogAnalytics`
 posts `RangerRun_CL` (scores, counts, AHB, cloud-publish status) and
 `RangerFinding_CL` (one row per failing WAF rule) to a DCE/DCR pair via
 the Logs Ingestion API.
- **Cloud Publishing guide (#246)** — `docs/operator/cloud-publishing.md` with
 step-by-step RBAC setup, config examples, and troubleshooting.
## v2.2.0 — WAF Compliance Guidance

Turn the WAF score from a static grade into an actionable roadmap: every rule
now carries a structured remediation block, and the report ranks fixes by
priority, projects your post-fix score, and can emit a copy-pasteable script.

### Added
- **Structured remediation block per WAF rule (#236)** — every rule in
 `config/waf-rules.json` now carries `remediation.{rationale, steps,
 samplePowerShell, estimatedEffort, estimatedImpact, dependencies, docsUrl}`.
 Reports surface a new "Next Step" column in Findings and a full Remediation
 Detail section per failing rule.
- **WAF Compliance Roadmap (#241)** — failing rules are bucketed into
 Now/Next/Later tiers by `priorityScore = (weight * severity * impact) / effort`.
 Rendered as a ranked table in the technical tier; exported as
 `powerbi/waf-roadmap.csv`.
- **Gap-to-Goal projection (#242)** — greedy fix-plan: *"Current 67%. Closing
 these 3 findings raises you to 82% (Excellent)."* Honours rule dependencies
 so prerequisites fix first. Exported as `powerbi/waf-gap-to-goal.csv`.
- **Per-pillar WAF Compliance Checklist (#238)** — one subsection per pillar
 with every rule, status, weight, effort, next step, and a Signed Off column
 for handoff / sprint artefact use. Exported as `powerbi/waf-checklist.csv`.
- **Get-RangerRemediation (#243)** — new public command emits a copy-pasteable
 remediation script from an existing manifest. Supports `-Format ps1|md|checklist`,
 `-Commit` for live cmdlets (dry-run by default), `-IncludeDependencies` to
 expand prerequisites, `-FindingId` to target specific rules.

### Changed
- `config/waf-rules.json` schema version bumped to `2.2.0` with a new
 `prioritization` block defining severity / impact / effort factors.
- Invoke-RangerWafRuleEvaluation now returns `roadmap` and `gapToGoal`
 alongside the existing `pillarScores` / `ruleResults`.

## v2.1.0 — Preflight Hardening

Close the three auth/preflight gaps identified against v2.0.0 so RBAC and
credential problems surface up-front instead of mid-run.

### Added
- **Per-resource-type ARM probe (#235)** — pre-run permission audit now issues a
 `Get-AzResource` against each v2.0.0 collector surface
 (`logicalNetworks`, `storageContainers`, `customLocations`, `appliances`,
 `gateways`, `marketplaceGalleryImages`, `galleryImages`). `Partial` overall
 when some surfaces 403, `Fail` when all do. Skipped in fixture mode.
- **Deep WinRM CIM probe (#234)** — `Invoke-RangerCimDepthProbe` runs after the
 shallow WinRM preflight and issues a representative `Get-CimInstance`
 against `root/MSCluster`, `root/virtualization/v2`, and
 `root/Microsoft/Windows/Storage`. Non-blocking warning on `partial` /
 `denied`; result captured in `manifest.run.remoteExecution.cimDepth`.
- **Azure Advisor read probe (#233)** — pre-check calls
 `Get-AzAdvisorRecommendation`. Denied 403 downgrades overall readiness to
 `Partial` and emits an actionable finding. Absent `Az.Advisor` is a `Skip`
 with an install hint, not a failure.

### Changed
- Overall readiness thresholds unchanged: `Insufficient` throws,
 `Partial` warns and continues, `Full` proceeds silently.

## v2.0.0 — Extended Collectors & WAF Intelligence

### Added — Collectors
- **Arc machine extensions per node (#215)** — AMA / Defender for Servers / Guest Configuration inventory per Arc-enrolled node with provisioning state; XLSX Extensions tab; Power BI `arc-extensions.csv`.
- **Logical networks + subnets (#216)** — Microsoft.AzureStackHCI/logicalNetworks with subnet, VLAN, IP pool, DHCP detail; cross-reference against host vSwitch; new Logical Networks / Subnets XLSX tabs.
- **Storage paths (#217)** — Microsoft.AzureStackHCI/storageContainers with CSV cross-reference; StoragePaths XLSX tab + Power BI CSV.
- **Custom locations (#218)** — Microsoft.ExtendedLocation/customLocations inventory linked to Resource Bridge host resource IDs.
- **Arc Resource Bridge (#219)** — bridge version / distro / status collection + Arc VM `vmProvisioningModel` classification (hyper-v-native / arc-vm-resource-bridge).
- **Arc Gateway (#220)** — Microsoft.HybridCompute/gateways with per-node routing detection.
- **Marketplace + custom images (#221)** — Microsoft.AzureStackHCI/marketplaceGalleryImages + galleryImages with storage-path cross-reference.

### Added — Intelligence
- **Azure Hybrid Benefit + cost analysis (#222)** — softwareAssuranceProperties-based AHB detection, per-core $10/month cost calculation, potential monthly savings, pricing reference footer. New Cost & Licensing HTML/Markdown/DOCX/PDF section + CostLicensing XLSX tab + cost-licensing Power BI CSV.
- **VM distribution balance (#223)** — coefficient-of-variation analysis across nodes; warning/fail thresholds; per-node distribution table in management + technical tiers.
- **Agent version grouping (#224)** — Arc agent + OS version grouped by node with drift detection (latestVersion, maxBehind, status).
- **Weighted WAF scoring (#225)** — per-rule weight 1-3, warnings award 0.5x weight, graduated threshold bands, score thresholds (Excellent/Good/Fair/Needs Improvement) exposed on the result.

### Added — Commands & UX
- **Export-RangerWafConfig / Import-RangerWafConfig (#226)** — hot-swap WAF rule config with schema validation, -Validate dry-run, -Default restore.
- **json-evidence export format (#229)** — raw resource-only JSON payload with minimal `_metadata` envelope, no scoring/run metadata; accepted via `Invoke-AzureLocalRanger -OutputFormats json-evidence` and `Export-AzureLocalRangerReport -Formats json-evidence`.
- **-SkipModuleUpdate (#231)** — opt-out of automatic Az.* module install/update on startup for air-gapped environments.

### Added — Reliability
- **Concurrent collection guard (#230)** — second `Invoke-AzureLocalRanger` call in the same session warns and returns rather than racing shared state.
- **Empty-data safeguard (#230)** — collection with zero nodes throws an actionable error instead of rendering empty tables.
- **Module auto-install/update on startup (#231)** — required modules (Az.Accounts, Az.Resources, Az.ConnectedMachine, Az.KeyVault) are installed or updated if missing/below minimum version.

### Added — Output
- **Portrait/landscape page switching (#227)** — `@page landscape-pg` rule applied to wide tables (Arc extensions, logical network subnets).
- **Conditional status-cell coloring (#227)** — Healthy / Warning / Failed cells are auto-colored in HTML/PDF.
- **Pricing footer with dated reference (#228)** — every cost section lists the pricing as-of date and official pricing URL.

## v1.6.0 — Platform Intelligence

### Added — Auth & Discovery
- **Auto-discover resource group (#196)** — subscription-wide ARM search by cluster name when resourceGroup is absent.
- **Auto-discover cluster FQDN (#197)** — pulled from Azure Arc; fallback to TrustedHosts + DNS on-prem chain.
- **Multi-method Azure auth (#200)** — service-principal-cert (thumbprint / PFX), tenant-matching context reuse, sovereign-cloud environment.
- **Save-AzContext handoff (#201)** — Export/Import-RangerAzureContext helpers for background runspaces.
- **Resource Graph single-query (#205)** — Search-AzGraph fast path for Arc machine discovery; Get-AzResource fallback.

### Added — Connectivity
- **WinRM TrustedHosts + DNS fallback (#203)** — on-prem FQDN resolution when Arc is unavailable.
- **Cross-RG node fallback (#204)** — Arc machines query with subscription-wide fallback; warning per cross-RG node.

### Added — Commands & UX
- **Invoke-AzureLocalRanger -Wizard (#211)** — inline wizard parameter; prompt text surfaces wizard as recommended alternative.
- **Test-RangerPermissions (#202)** — dedicated RBAC + provider registration audit; console/JSON/Markdown output.
- **-SkipPreCheck (#212)** — pre-run permission audit runs by default; opt-out flag and behavior.skipPreCheck config.
- **File-based progress IPC (#213)** — Write/Read/Remove-RangerProgressState for background runspace progress.

### Added — Resilience
- **Graceful degradation (#206)** — ARM error classifier + skipped-resources tracker; manifest.run.skippedResources; behavior.failOnPartialDiscovery gate.

### Added — Output
- **Headless-browser PDF (#207)** — msedge --headless=new --print-to-pdf renders the HTML report; plain-text fallback when no browser.
- **DOCX OOXML tables (#208)** — section.type='table'/'kv'/'sign-off' render as real Word tables.
- **XLSX formula-injection safety (#209)** — cells beginning with =, +, -, @ are apostrophe-prefixed.
- **Power BI export (#210)** — new `powerbi` format; nodes/volumes/storage-pools/health-checks/network-adapters CSVs + _relationships.json star-schema + _metadata.json.
- **Graduated WAF scoring (#214)** — threshold bands with partial point awards; named aggregate calculations; {value} message substitution.

Full history: https://github.com/AzureLocal/azurelocal-ranger/blob/main/CHANGELOG.md