Add Start-FinOpsMultitool — cross-platform terminal UI for FinOps scanning

[Zac larsen (z-larsen)]

🛠️ 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?

• 🧹 Lint tests
• 👍 PS -WhatIf / az validate
• 🔌 Manually deployed + verified
• 🧪 Unit tests
• 👀 Integration tests

🐳 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)

[Zac larsen (z-larsen)]

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

[Michael Flanakin (flanakin)]

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)]

Thanks, Michael! Would love to join.

[Zac larsen (z-larsen)]

Thanks Brett - all three are fixed in b336ab0c.

1. TUI data-source selection fails before scans start
Select-DataSource's return value now lands in $sourceChoice, so it no longer collides with the [ValidateSet] $DataSource parameter. Added an AST regression test in Start-FinOpsMultitool.Tests.ps1 that fails if any ValidateSet parameter is assigned to anywhere in Invoke-FinOpsMultitool - it guards the class of bug rather than this one instance.

2. MACC results are not bounded by the selected scope
Get-MaccCommitment now correlates billing accounts to the selected subscriptions through a shared Get-FinOpsBillingScope helper instead of ignoring $Subscriptions.

3. Billing Structure drops a readable EA enrollment
Dropped the billingInfo/default dependency. It is not a valid resource type and 404s on every api-version, which is what left the account set empty. Get-BillingStructure now lists billing accounts and correlates them through the same Get-FinOpsBillingScope helper Get-ContractInfo uses, and warns when correlation fails.

Unit suite: 2433 passed / 0 failed / 7 skipped.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] PR Review

Summary: Solid architecture and consistently read-only (no destructive Az cmdlets or write REST calls found anywhere across ~15,900 new lines of PowerShell). The main gaps are: agent-skill docs routing to a deleted skill, a cluster of "silent failure looks identical to clean scan" bugs across several scanner modules (a pattern this repo has been burned by before), a few standalone data-correctness bugs, and near-zero test coverage for the 30 scanner modules that are the actual feature being shipped.

🚫 Blockers (1)

1. Eight agent-skill files route an AI agent to an azure-cost-management skill that a dedicated Pester test (AgentPlugins.Tests.ps1) confirms no longer ships — a dead end for any agent following the routing tables.

⚠️ Should fix (20)

1. Get-SavingsRealized.ps1 — the per-subscription fallback path computes RI/SP savings with a different, incorrect formula than the rest of the file.
2. Get-ContractInfo.ps1 — the Currency field is populated with a country code, not a currency code.
3. Get-LegacyResources.ps1 — sort order puts low-impact findings before high-impact ones.
4. Get-PolicyRecommendations.ps1 — two differently-named catalog entries share the same policy definition ID, double-counting one policy.
5. Get-CarbonMetrics.ps1 — the window-probe can lock onto an empty-data month and never try older windows.
6. Get-IdleVMs.ps1 — per-VM metrics failures are silently swallowed.
7. Get-StorageTierAdvice.ps1 — capacity/transaction metric failures are silently swallowed or defaulted to zero.
8. Get-BudgetStatus.ps1 — large-tenant sampling checks only the first 10 subscriptions (not random) and silently skips the rest if that sample is empty.
9. Get-BudgetStatus.ps1 — reusing a partial CostTrend result can zero-fill months it doesn't actually cover.
10. Get-CommitmentUtilization.ps1 — per-reservation utilization fetch failures are silently swallowed, understating counts with no caveat.
11. Get-AIWorkloadMetrics.ps1 — AI-detection query failures are reported identically to "no AI workloads found."
12. Get-PolicyInventory.ps1 — an exception partway through the subscription loop aborts the rest of the tenant silently, and the per-subscription fallback strategy never triggers to fill the gap.
13. Get-CostTrend.ps1 — multi-subscription cost aggregation sums cost across subscriptions without checking or converting currency.
14. Get-AIWorkloadMetrics.ps1 — AI cost aggregation has the same cross-currency summation issue.
15. Get-UnitEconomics.ps1 — compute/storage cost aggregation has the same cross-currency summation issue.
16. Get-SharedCostAllocation.ps1 — the cost-by-resource query never follows nextLink, understating allocations for subscriptions with many billed resources.
17. Get-CostByTag.ps1 — the same missing-pagination gap in its core cost-by-tag query.
18. Get-OrphanedResources.ps1 — the same missing-pagination gap in its cost-enrichment query.
19. Get-FOHubProvider.ps1 — a KQL comparison wraps a column in tolower(), which the project's own coding guidelines explicitly forbid (the operator used is already case-insensitive).
20. Start-FinOpsMultitool.ps1 — comment-based help claims export options for Excel, JSON, and Power BI; the code only ever produces CSV, HTML, and a text summary.

Test coverage: the 4 new Pester test files (559 lines) cover only shared plumbing (hub provider resolution, hub size classification, policy-effect string parsing, cmdlet parameter shape). None of the 30 scanner modules' actual domain logic (Get-IdleVMs, Get-OrphanedResources, Get-CostByTag, etc. — roughly 8,000+ lines) has a single test exercising it. Given "Include Pester tests for all functions" is a stated convention, this is worth closing before or shortly after merge — even a handful of mocked tests for the highest-risk scanners (idle VMs, orphaned resources, cost by tag) would materially reduce risk.

💡 Suggestions (6)

1. Get-TagRecommendations.ps1 — every catalog entry is Priority = 'Required', so the MissingRecommended filter can never match anything.
2. Get-VmCostBreakdown.ps1 — the VM-lookup query has no order by, so which VM is picked when a name is ambiguous isn't deterministic across runs.
3. Get-SharedCostAllocation.ps1 — $Spokes isn't deduplicated before allocation, so a caller-supplied duplicate subscription ID dilutes and double-counts.
4. src/powershell/Private/FinOpsMultitool/README.md — lists Az.Resources as a required module; nothing in the multitool actually calls an Az.Resources cmdlet (all reads go through raw REST or Resource Graph).
5. Naming: the "AHB" acronym is cased inconsistently — Get-AhbVmSavingsRatio.ps1/Get-AhbVmRates use Ahb, Get-AHBOpportunities.ps1 uses AHB.
6. Invoke-AzRestMethodWithRetry.ps1 — exponential backoff has no jitter; low risk for the interactive CLI, but worth adding if -NonInteractive is ever run as a fleet of concurrent scheduled jobs against the same tenant.

---

Not all 90+ files in this PR were reviewed at the same depth — review focused on the PowerShell scanner modules, helpers, entry points, tests, and docs/agent-skills, which make up the vast majority of the new code.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 🚫 Blocker

This routing table (and lines 62, 66, 110 in this same file) points to an azure-cost-management skill that no longer ships — src/powershell/Tests/Unit/AgentPlugins.Tests.ps1 (lines 142-151) explicitly asserts skills/azure-cost-management doesn't exist. That test only scans plugin manifests, not skill body text, so these references slipped through. An agent following "How is our MACC tracking?" or "Advisor cost recommendations" hits a dead end. The same dangling reference also appears in finops-multitool/references/allocation.md, waste-detection.md, cost-analysis.md, commitments.md, anomaly-investigation/SKILL.md, azure-workbooks-finops/SKILL.md, and rate-optimization-portfolio/SKILL.md — recommend either restoring the referenced content inline/into an existing skill, or removing these pointers tenant-wide.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] ⚠️ Should fix

This per-subscription fallback path computes $riSavings += $cost * 0.4 and $spSavings += $cost * 0.25 directly. That contradicts the formula this same file documents and uses everywhere else: lines 39-43 explain that for a discount rate d, savings = paid * d / (1-d), not paid * d — "At a 40% discount, $100 paid implies $66.67 saved, not $40." The primary MG-scope path (lines 141, 146) correctly applies $script:FinOpsRiSavingsFactor/FinOpsSpSavingsFactor (d/(1-d)), but this fallback — which runs whenever MG-scope Cost Management access is unavailable — reverts to the naive cost * d. For the same stated 40%/25% discount assumption (see the EstimateBasis message at line 392), this understates RI savings by ~40% and SP savings by ~25% relative to what the primary path would report for identical costs. Suggest reusing $script:FinOpsRiSavingsFactor/FinOpsSpSavingsFactor here too.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] ⚠️ Should fix

Currency = if ($props.soldTo) { $props.soldTo.country } else { 'Unknown' } — soldTo is a billing mailing address, not a currency source, so this puts a country code (e.g. "US") into a field named Currency. Any downstream consumer reading this field gets a country code mislabeled as a currency code.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] ⚠️ Should fix

Sort-Object @{ Expression = 'Impact'; Descending = $true }, Category sorts on the string value of Impact, and the only values used elsewhere in this file are 'High' and 'Low'. Alphabetically 'H' < 'L', so a descending sort puts 'Low' before 'High' — the opposite of the intended remediation priority. A caller reading LegacyResources top-to-bottom sees the least-important finding first.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] ⚠️ Should fix

This entry ("Storage accounts should be limited by allowed SKUs") uses the same PolicyDefId (.../policyDefinitions/7433c107-6db4-4ad1-b57a-a76dce0154a1) as the "Allowed storage account SKUs" entry above at line 125. Looks like a copy-paste duplicate — the same built-in policy is presented twice under different display names, double-counting it across Analysis/Missing/Assigned.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 💡 Suggestion

Resolve-VmAssociation's ARG query has no order by, so when multiple VMs match an ambiguous name, which one becomes "the" VM ($rows[0]) isn't deterministic across calls. The Ambiguous/Note caveat already surfaced elsewhere is a nice touch, but consider adding e.g. order by id asc so repeat runs against the same tenant pick the same VM.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 💡 Suggestion

$Spokes is never deduplicated before allocation (only $costSubs gets Select-Object -Unique, for cost querying). A caller-supplied duplicate subscription ID inflates $nSpokes — diluting every other spoke's fixed-cost share — and emits two allocation rows for that spoke. Low likelihood since it requires bad caller input, but a Select-Object -Unique on $Spokes up front would close it.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 💡 Suggestion

Az.Resources is listed as a required module, but nothing in the multitool actually calls an Az.Resources cmdlet (grepped for Get-AzResource, Get-AzPolicyAssignment, Get-AzRoleAssignment, etc. across all modules — zero hits; everything goes through raw REST calls or Search-AzGraphSafe). Worth double-checking whether it's still needed, or dropping it from the install instructions here and at line 31.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 💡 Suggestion

Minor naming inconsistency: this file/function use all-caps AHB (Get-AHBOpportunities), while Get-AhbVmSavingsRatio.ps1/Get-AhbVmRates use Pascal-case Ahb. PowerShell/.NET naming guidance favors Pascal-case for multi-letter acronyms (Ahb) — worth picking one convention.

[Michael Flanakin (flanakin)]

This is a nit and valid to skip. We need to rename all of these when we move them to public funcs. They'll all become {verb}-FinOps{noun} anyway, so we can deliberate naming conventions later. Tho I would suggest we align with whatever Microsoft defines as standard conventions.

[Michael Flanakin (flanakin)]

🤖 [AI][Claude] 💡 Suggestion

Backoff here (and in Search-AzGraphSafe.ps1) is pure exponential with no jitter. Low risk for a single-process interactive CLI, but if -NonInteractive is run as a scheduled job across multiple tenants/machines that happen to hit the same throttle window, all instances retry on the identical schedule. Adding a small random jitter (e.g. Get-Random -Minimum 0.8 -Maximum 1.2) would spread that out.