Add Start-FinOpsMultitool — cross-platform terminal UI for FinOps scanning by z-larsen · Pull Request #2155 · microsoft/finops-toolkit

Zac Larsen (z-larsen) · 2026-05-19T20:24:30Z

🛠️ Description

Adds the FinOps multitool to the FinOps toolkit. Discussed with Brett Wilson (@MSBrett), who suggested contributing the tool into the official toolkit.

The multitool scans an Azure environment for cost optimization, governance, and FinOps insights — cost trends, orphaned resources, idle VMs, tag hygiene, reservation and savings plan utilization, Azure Hybrid Benefit opportunities, budgets, anomaly alerts, and policy compliance — and grounds its findings in live resource state.

Everything in this PR is read-only. It needs Reader or Cost Management Reader on the target scope and never creates, changes, or deletes a resource. Remediation and the MCP server were split out to a separate branch and will follow as their own PR.

One scanner engine, two consumers:

Interface	Entry point	Best for
Terminal UI	`Start-FinOpsMultitool`	A person who wants a full assessment
Agent skills	`src/templates/agent-skills/`	AI agents answering a single question through `az` or an Azure MCP server

A separate WPF GUI is maintained outside this repo. This PR contributes the terminal UI and the agent skills.

Running it

The terminal UI uses arrow-key menus when the console supports them. Consoles that can't render those menus — PowerShell remoting sessions, some editor terminals — fall back to numbered prompts, which is also what a screen reader can follow. Both paths run the same scans and produce the same results.

For automation, -NonInteractive with -Scans, -DataSource, -SubscriptionId, and -OutputPath supplies every choice, so the tool runs from a pipeline or a scheduled job:

Start-FinOpsMultitool -NonInteractive `
    -SubscriptionId '00000000-0000-0000-0000-000000000000' `
    -Scans Get-OrphanedResources, Get-IdleVMs `
    -DataSource API `
    -OutputPath './results'

FinOps hub data paths

This addresses Brett Wilson (@MSBrett)'s scaling review. When a FinOps hub is present, cost scans prefer the hub's Kusto database — an Azure Data Explorer or Fabric cluster, auto-discovered through Resource Graph, or a local ftklocal emulator via FINOPS_HUB_KUSTO_URI — and push aggregation into the engine, returning only summarized result sets. Raw cost rows are never materialized in PowerShell on that path.

The storage-export reader remains as a small-dataset fallback rather than the scalable path, and the terminal UI warns before using it on a hub with no reachable cluster, offering the live Cost Management API instead.

Scans

30 scan modules across optimization, governance, cost analysis, commitments, monitoring, Advisor, account, AI and ML, and sustainability. The terminal UI surfaces 26 of them. Results render in the terminal and export to one CSV per scan, a FinOpsReport.html summary, and a ScanSummary.txt file.

📦 Files added / changed

Path	Purpose
`Public/Start-FinOpsMultitool.ps1`	Public cmdlet — launches the cross-platform terminal UI
`Invoke-FinOpsMultitool.ps1` + `FinOpsMultitool.psm1`	Terminal UI + module loader
`modules/`	30 read-only scanner modules
`helpers/Get-FOHubProvider.ps1` + `Invoke-FOHubKustoQuery.ps1`	Scalable FinOps hub Kusto data path (ADX / Fabric / ftklocal)
`agent-skills/finops-multitool/` + `references/`	Routing hub skill and its investigation references
`agent-skills/cost-data-source/`	Cost data-source routing skill (Kusto vs storage vs API)
`agent-skills/{power-bi-finops, cost-allocation, …}/`	11 FinOps-adjacent skills
`Tests/Unit/Start-FinOpsMultitool.Tests.ps1` + `FOHubProvider.Tests.ps1`	Pester unit tests
`docs-mslearn/.../powershell/multitool/` + `docs/multitool.md`	Documentation (command reference, landing page, TOC, changelog)

📸 Screenshots

Screenshots are in the public repo README.

📋 Checklist

🧪 How did you test this change?

🐳 Deploy to test?

N/A — standalone PowerShell tooling, not a template deployment.

🏷️ Do any of the following that apply?

🚨 This is a breaking change.
🐣 The change is less than 20 lines of code.

📄 Did you update `docs/changelog.md`?

✅ Updated changelog
❌ Log not needed (small/internal change)

📖 Did you update documentation?

✅ Documentation updated — FinOps multitool reference under docs-mslearn/.../powershell/multitool/, a Jekyll landing page, overview/TOC/changelog entries, and the module README plus the finops-multitool and cost-data-source skills.
❌ Docs not needed (small/internal change)

… GUI Adds the Azure FinOps Multitool as a new PowerShell cmdlet in the FinOps toolkit. The Multitool is a WPF-based GUI that scans an Azure tenant for cost optimization, governance, and FinOps insights including cost trends, orphaned resources, idle VMs, tag hygiene, reservation/savings plan utilization, AHB opportunities, budgets, anomaly alerts, and policy compliance. - Public/Start-FinOpsMultitool.ps1: thin launcher cmdlet with comment-based help - Private/FinOpsMultitool/: full implementation (24 scanner modules, WPF GUI, Power BI template) - Tests/Unit/Start-FinOpsMultitool.Tests.ps1: Pester unit tests Windows-only (requires WPF support).

Zac Larsen (z-larsen) · 2026-05-19T20:29:14Z

@microsoft-github-policy-service agree company="Microsoft"

Michael Flanakin (flanakin) · 2026-05-20T19:53:36Z

Zac Larsen (@z-larsen) This is exciting! I don't know much about the tool, but would love to learn more. Can you join us at the contributor sync next Wednesday to share?

https://aka.ms/ftk/contrib-sync

Zac Larsen (z-larsen) · 2026-05-21T16:51:49Z

Thanks, Michael! Would love to join.

…info - Add contract-aware cost access warning banner (EA/MCA/CSP) on Overview tab - Add contract-specific billing tab messages when billing access unavailable - Add MG hierarchy unavailable info node in tree view with role guidance - Fix tag cost queries: use TagKey grouping type (not Tag/Dimension) - Add batched TagKey+TagValue query attempt with per-tag fallback - Clear skipSubs between batched and per-tag strategies - Add throttle pacing (2s every 2 queries) to avoid 429s - Add EA/MCA cost access detection in Get-CostData - Add runspace pool for API call parallelization

…ge tags

- A budget query that returned a non-200 or threw was counted as a subscription without a budget, so missing access produced an exact-looking coverage percentage. Unreadable subscriptions are now tracked separately, excluded from the without-budget count, and suppress the percentage. - Coverage wording now covers both an unqueried sample and an unreadable subscription.

- The variance analysis section did not point at the budget history scan, which is the one purpose-built for month-by-month budget vs actual. Added it there and to the hand-offs list.

- Budget history reused cached Cost Trend data whenever the subscription was present, so requesting more months than the cache held reported the uncovered months as zero spend and under budget. Coverage is now checked and uncovered windows fall back to a live query. - Cursor repositioning now goes through a guarded helper so a buffer resize mid-render cannot surface a .NET stack trace. - Corrected the sustainability skill data source table for the Emissions Impact Dashboard retirement and marked Azure carbon optimization as preview.

- Shared cost allocation called ConvertTo-AllocationPercentages, which an earlier cleanup commit deleted along with the write path, so any scan that found a positive pool threw CommandNotFoundException. Reimplemented the normalization for the single input shape this caller builds. - Export amounts parsed under the operator's culture, reading 123.45 as 12345 wherever '.' is the thousands separator. They now parse invariantly. - The telemetry dimension name reached KQL unescaped, so a caller could terminate the string literal and append query operators. - Region, SKU, and location reached OData filters without their single quotes doubled, allowing the filter predicate to be rewritten. - Added a guard that fails on any call to a command the module never defines, plus coverage for the parsing and escaping fixes.

- Fix null comparison ordering, $matches shadowing an automatic variable, and four variables that were assigned but never read. - Rename Parse-* helpers to approved verbs. Two were both named Parse-CostRows with different signatures and collided in module scope. - Suppress console output, helper shape, and signature parity rules with justifications, matching the existing pattern in the repository. - Test.PowerShell.Lint now passes 7144 of 7144.

- Use interval=FULL for the Idle VMs and Storage Tier metric queries. P14D and P30D are not published timegrains, so Azure Monitor rejected both with HTTP 400 and the scans returned zero on every tenant. - Count a failed blob capacity read as a metric failure. Every tier recommendation requires a capacity reading, so the previous silent failure suppressed the recommendation instead of reporting the account as unevaluated.

- Fail closed when an explicitly requested subscription cannot be resolved and the host cannot prompt. The unanswered picker read a blank answer as "scan everything", so an automated run with a stale -SubscriptionId exported every subscription in the tenant. - URI-encode the OData location value. Doubling the quotes alone left a percent-encoded quote to decode back into a literal one and rewrite the filter predicate.

- Prefix exported cells that open with =, +, - , @, tab, or CR so a resource name or tag cannot execute as a spreadsheet formula. Numbers are left alone so a negative cost stays a number. - Parse hub subscription ids as GUIDs and fail on an unparseable one. The character-class check passed 36 hyphens, and an all-invalid list dropped the scope filter and returned every subscription in the hub. - Cap gzip expansion when reading export parts, so a highly compressed blob in the container cannot exhaust memory. - Flag commitment figures that came from the tenant-wide reservation order endpoint, which cannot be filtered to the scanned subscriptions.

- Document that -SubscriptionId returns an error when the subscription cannot be resolved and nothing can answer a prompt, rather than scanning every subscription. - Refresh ms.date on the six pages this pull request changes. The update workflow is skipped for fork pull requests.

- Correct full-month forecast windows, column matching, and row totals. - Flag actual-only forecast fallbacks. - Keep measured zero utilization without counting absent commitments. - Restrict export totals to selected subscriptions.

- Reject incomplete pages, required-query failures, and invalid costs. - Preserve POST bodies and discard failed attempts before retries. - Calculate hourly vCPU cost from the captured UTC reporting window.

- Separate billed and amortized costs; reject invalid amounts and incomplete coverage. - Preserve subscription scope, currencies, credits, and observed periods. - Keep unknown budget forecasts and unsupported history unavailable. - Surface hub source failures and unverified financial KPIs.

- Respect explicit data-source selection and retain Kusto provenance. - Validate savings currencies and exclude non-usage charges. - Separate month-to-date commitment estimates from the AHB estimate. - Export nested CSV summaries once and use invariant amounts and ISO dates. - Align public help and documentation with the Microsoft style guide. - Add source, savings, export, and pagination regression coverage. Validation: 2812 unit tests passed (7 skipped), 7144 lint checks passed, and no ScriptAnalyzer findings. Two independent reviews approved the batch. Successful online Hub validation remains blocked by a 403 response.

Michael Flanakin (flanakin)

🤖 [AI][Claude Code] PR Review

Summary: Ambitious, well-organized addition (108 files, 30 read-only scanner modules, terminal UI, 12 new agent skills). Read-only guarantee holds everywhere it was checked — no mutating Azure calls found in any reviewed file. The dominant issue is a systemic pattern: several modules sum Azure Cost Management amounts across subscriptions without checking currency consistency first, unlike the project's own Get-SavingsRealized.ps1/Get-CostTrend.ps1/Get-CostData.ps1, which correctly throw or track per-currency. In an EA/MCA tenant with subscriptions billed in different currencies, this silently produces wrong dollar totals. There's also one execution-verified macOS bug (8 failing Pester tests) and a fail-fast bug that discards an entire scan's results on the first subscription access error.

Pester run on this branch: 526 passed, 8 failed, 7 skipped — all 8 failures trace to two root causes documented below.

Three smaller, non-blocking polish items were split out to #2335 (v16 milestone) rather than posted inline, since they're real but not urgent: a misattributed diagnostic message, a missing static test-guard for the read-only invariant, and missing comment-based help on the primary TUI entry point.

🚫 Blockers (6)

Get-CostByTag.ps1 — a single failed subscription throws and discards the entire scan's results.
Get-CostByTag.ps1 — sums cost across subscriptions/currencies, labels the total with whichever currency was seen last.
Get-AIWorkloadMetrics.ps1 — same cross-currency summing bug in AI cost-per-token/request metrics.
Get-SharedCostAllocation.ps1 — the FinOps Hub data path has no currency-mismatch check (the Live API path in the same function does).
Get-UnitEconomics.ps1 — currency is correctly flagged "Mixed", but the cost/unit-economics numbers next to it aren't gated on that flag.
Read-FinOpsHubData.ps1 — macOS stat -f '%Lp' drops the sticky bit, breaking private-directory validation for any path under a sticky world-writable ancestor (e.g. /tmp). Execution-verified via the failing Pester run above.

⚠️ Should fix (15)

7-8. Same cross-currency summing pattern in Get-OptimizationAdvice.ps1 and Get-ReservationAdvice.ps1 (Advisor savings estimates).
9-12. Missing nextLink pagination: Get-BillingStructure.ps1 (5 calls), Get-MaccCommitment.ps1 (2 calls), Get-BillingAccount.ps1, MgCostScope.ps1.
13-15. Weak/silent failure logging: Get-TagInventory.ps1, Get-PolicyInventory.ps1, Get-ContractInfo.ps1.
16-17. Invoke-FinOpsMultitool.ps1 — silent Hub-detection failure swallowing, and a shared catch that mislabels an untried scan as failed.
18. MultitoolSafety.Tests.ps1 — the "no undefined commands" self-test false-fails on non-Windows (one of the 8 real Pester failures above).
19. Test coverage: 16 of 30 scanner modules have no test exercising their own domain logic, despite the PR checklist marking unit tests as done.
20. finops-reporting/SKILL.md references a content-humanizer skill that doesn't exist anywhere in the repo.
21. finops-multitool-commands.md's scan-coverage table doesn't disclose that 4 of the 30 modules aren't reachable through the documented menu or -Scans parameter.

💡 Suggestions (8)

Minor: stale .gitignore entry, a malformed survey URL, changelog tense inconsistency, a duplicated bullet, an unjustified tolower(), a USD-only savings figure with no currency label, dead code, and the same hub-path currency pattern as the blockers (lower risk here, but worth the same fix while touching this code).

Michael Flanakin (flanakin) · 2026-09-23T18:34:27Z

+                    if (-not $subResp -or $subResp.StatusCode -ne 200) {
+                        throw "Cost-by-tag query failed for $($pj.Call.SubName) (HTTP $($subResp.StatusCode)); results are incomplete."
+                    }


🤖 [AI][Claude Code] 🚫 Blocker

Any non-200 response from any subscription's cost query throws immediately, aborting the whole scan and discarding all tag aggregation already collected for prior subscriptions. In a tenant of 50 subscriptions, one 403 (missing Cost Management Reader on a single sub) on subscription #3 discards results for subs 1-2 and never processes subs 4-50. This also makes the $subsFailed bookkeeping and the "N subscription(s) returned data, M skipped" summary message unreachable — the partial-failure design those imply can never actually run.

Suggest catching the per-subscription failure, incrementing $subsFailed/$script:costAccessIssue as already coded, and continue-ing to the next subscription instead of throwing — consistent with how Get-CostData.ps1/Get-CostTrend.ps1 handle partial subscription failures.

🤖 [AI][Claude Code] Taking this — fix incoming in a stacked PR.