Skip to content

fix(connect): request cloud-aware Graph permissions for preview checks - #2706

Draft
Cloud-Architekt wants to merge 2 commits into
maester365:mainfrom
Cloud-Architekt:tnh-PreviewCheckNonComercialClouds
Draft

Cloud-Architekt wants to merge 2 commits into
maester365:mainfrom
Cloud-Architekt:tnh-PreviewCheckNonComercialClouds

Conversation

@Cloud-Architekt

@Cloud-Architekt Cloud-Architekt commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Important

Code freeze for Maester 3.0: from 7 November 2026 we will only merge bug fixes while we get ready to release Maester 3.0 next week. New features and new tests opened after that will be reviewed after the release.

Note

Stacked on #2705. This branch is based on tnh-EntraGovernanceChecks, so until #2705 merges the "Files changed" tab also shows that PR's changes. Review only commit 2af8b8fae (8 files). Merge #2705 first; this PR then reduces to that single commit. Not intended to merge before #2705.

📑 Description

Make Get-MtGraphScope -IncludePreview request the Graph permissions that the new preview checks of #2705 need, and stop requesting them in national clouds where Microsoft Graph does not offer these APIs. This is a draft for review, a fix to the connection flow, not a new check. No tests are added or changed under tests/.

Without it, #2705 documents permissions that the standard preview connection never requests (ConfigurationMonitoring.Read.All, RemoteTenantGroups.Read.All, TenantGovernance-*), so MT.1254 and MT.1258 are skipped or unreadable for anyone using Connect-Maester -IncludePreview.

No issue is closed by this PR.

What changes

Area Change
Get-MtGraphScope (public) New -Environment parameter (China, Germany, Global, USGov, USGovDoD; default Global). With -IncludePreview and Global, five scopes are added: ConfigurationMonitoring.Read.All, CrossTenantInformation.ReadBasic.All, RemoteTenantGroups.Read.All, TenantGovernance-RelatedTenant.Read.All, TenantGovernance-Relationship.Read.All. Any other cloud leaves them out. A help example is added.
Connect-Maester Passes -Environment through to Get-MtGraphScope, so the sign-in request matches the cloud.
Test-MtContext Compares the granted scopes with the cloud-aware list, so a national-cloud session is not reported as missing scopes it can never have. An unset environment is treated as Global; an environment Maester does not know is treated as national (USGov).
Write-MtGraphConsentHelp The suggested Get-MtGraphScope command includes -Environment <cloud> when preview scopes are requested in a non-Global cloud, so the printed remedy is runnable.
Documentation website/docs/sections/permissions.md replaces the two per-test permission sections of #2705 with one list of the Global-only preview scopes and explains the cloud behavior.
Tests New cases for Get-MtGraphScope (Global, national clouds, no preview), Test-MtContext (per-cloud scope selection including unknown and unset environments) and Write-MtGraphConsentHelp.

Behavior is unchanged for existing callers: the default is Global, and nothing changes unless -IncludePreview is used. Commercial and GCC tenants use the Global cloud and receive the new scopes.

✅ Checks

  • My pull request adheres to the code style of this project.
  • My code requires changes to the documentation.
  • I have updated the documentation as required.
  • The build and unit tests pass after running /powershell/tests/pester.ps1 locally.

Validation evidence

The full unfiltered unit suite and module build have not been run, so the last box is intentionally unchecked. No live sign-in was attempted in any cloud.

Run on a clean checkout of branch commit 2af8b8fae:

pwsh -NoLogo -NoProfile -Command '& ./powershell/tests/pester.ps1 -Include @("Get-MtGraphScope*", "Test-MtContext*", "Write-MtGraphConsentHelp*", "Connect-Maester*", "PSScriptAnalyzer*", "Help*", "RepositoryLayout*") -Output Normal'

Passed: 1,090 tests across 7 files (Get-MtGraphScope 9, Test-MtContext 13, Write-MtGraphConsentHelp 14, Connect-Maester 32, PSScriptAnalyzer 534, Help 474, RepositoryLayout 14).

Dependencies


How to Contribute

🏗️ Read our full contributing guide for the Maester project.
🧪 We also have additional instructions and a checklist for creating tests.

Join us at the Maester repository discussions or Entra Discord for more help and conversations!
While you wait for a review, why not spread some Maester love on social media? Thank you! 💖

- Add MT.1253 for risk remediation and skip MT.1013 when satisfied
- Add preview checks for tenant configuration and access package drift
- Add preview GDAP and Tenant Governance allowlist assessment
- Extend affected-object reporting and portal links
- Document delegated admin settings and required permissions
- Add unit tests and update golden fixtures
- Add missing monitoring and Tenant Governance preview scopes
- Exclude Global-only preview scopes from national cloud connections
- Pass the Graph environment through connection, validation, and consent help
- Add regression tests and update permission documentation
@coderabbitai

coderabbitai Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

This pull request changes files that a website explainer describes:

  • How Maester works (website/public/explainers/how-it-works/) describes powershell/public/connect/Connect-Maester.ps1, report/src/lib/affectedObjectTypes.ts

If the change alters what the explainer shows (a gate, a reason code, a command, a count), update its composition and its chapters in website/src/data/explainers.json. If it doesn't, no action is needed.

@{ Status = 403 }, @{ Status = 503 }
) {
InModuleScope Maester -Parameters @{ Status = $Status } {
param($Status)
@{ Condition = 'the runs cannot be read'; Note = '*runs could not be read*' }
) {
InModuleScope Maester -Parameters @{ Condition = $Condition; Note = $Note } {
param($Condition, $Note)
@{ Code = 401 }, @{ Code = 403 }
) {
InModuleScope Maester -Parameters @{ Code = $Code } {
param($Code)

# Longest number of characters shown for a current or desired property value in the result.
[ValidateRange(20, 1000)]
[int] $MaximumValueLength = 80,

# Maximum number of drifted properties listed for each resource; the others are counted.
[ValidateRange(1, 100)]
[int] $MaxPropertiesPerResource = 5
@codacy-production

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity

Metric Results
Complexity 0

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@SamErde

SamErde commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

The latest #2705 changes how this follow-up needs to be integrated. I reviewed #2705 at 6f4ce5cb10a28e28110507b0e76e37ca180d1f30 and this PR at 2af8b8faef4b0158572195e1aa72bcda203f8c31.

[P2] The automatic merge retains Global-only scopes in national clouds.

#2705 now adds all five scopes to the unconditional $previewScopes array. This commit adds the same scopes to $globalOnlyPreviewScopes and conditionally appends that array, but does not remove the entries introduced by the newer #2705 changes.

A local git merge-tree --write-tree simulation reports a conflict in website/docs/sections/permissions.md, while automatically merging Get-MtGraphScope.ps1. The automatically merged function has both sets of entries:

Function tested Global USGov / USGovDoD / China / Germany
This PR's current function Global-only scopes included once Global-only scopes omitted
Automatically merged with current #2705 Global-only scopes included twice Global-only scopes still included

I ran this PR's 14 existing Get-MtGraphScope tests against the automatically merged function in isolation, replacing only the test setup's module import with dot-sourcing that function: 10 passed, 4 failed. All four national-cloud exclusion cases failed because ConfigurationMonitoring.Read.All was still present. Direct calls also confirmed the retained RemoteTenantGroups.Read.All scope and the duplicate Global entries. No live sign-in was attempted.

Please update this branch against the latest #2705, remove the five scopes from the unconditional preview array so they exist only in the Global-only array, resolve the permissions-documentation conflict, and rerun the connection, context-validation, consent-help and scope tests on the combined head. Add an assertion that the returned scopes contain no duplicates.

Resolving only the visible Markdown conflict will leave the cloud-filtering fix ineffective.

AI-assisted review: GPT-6 (Codex), final-review lane.

@earbona23 earbona23 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scope logic is right, and I checked it rather than skimmed it: Get-MtGraphScope adds $globalOnlyPreviewScopes when $Environment -eq 'Global' and only writes a verbose line otherwise, and Test-MtContext maps an unknown or custom Graph environment to the conservative side. Four things from reading around it.

1. This PR contains #2705 entirely

Measured on the two file lists: #2705 touches 48 files, this one 50, and 45 are the same. The five that are only here are the connect ones — Connect-Maester.ps1, Test-MtContext.ps1, Write-MtGraphConsentHelp.ps1 and their two test files.

It is not just an overlap, it is a dependency: this PR calls Get-MtGraphScope -Environment, and that parameter does not exist in main — it is added in Get-MtGraphScope.ps1, one of the 45 shared files. So merging this merges #2705's governance checks too, and reviewing the diff GitHub shows here means reviewing both. Pointing the base of this PR at #2705's branch, or saying in the body that they land together, would save the next reviewer from working that out from the file list.

2. Two of the five Global-only scopes are not declared by any check

Searching the whole diff for Graph:Scope:<name> in a Permission attribute:

scope declared by a check
ConfigurationMonitoring.Read.All 1 (MT.1254)
RemoteTenantGroups.Read.All 1 (MT.1258)
TenantGovernance-Relationship.Read.All 1 (MT.1258)
CrossTenantInformation.ReadBasic.All 0
TenantGovernance-RelatedTenant.Read.All 0

The comment says CrossTenantInformation.ReadBasic.All is "only used with the Tenant Governance checks", but no check names it, so every Global-cloud user consents to a scope Maester does not declare a use for. TenantGovernance-RelatedTenant.Read.All looks like the opposite case: something reads directory/tenantGovernance/relatedTenants — Test-MtCrossTenantAdministrationRelationship.Tests.ps1 mocks that URI — so the scope is used and the Permission attribute is missing it. One to drop, one to declare, if I have read it right.

3. MT.1258 reads the cross-tenant access policy without declaring a permission for it

Test.MT.1258.ps1:147 calls policies/crossTenantAccessPolicy/partners. List partners gives the least privileged permission as Policy.Read.All, with Policy.ReadWrite.CrossTenantAccess as the higher one; Directory.Read.All is not listed for it. The attribute declares Directory.Read.All, TenantGovernance-Relationship.Read.All and RemoteTenantGroups.Read.All.

This is also the only one of these endpoints that is documented as available in every national cloud (Global, US Gov L4, L5, China all ✅ on that page), so it is not part of the Global-only story — it just needs its permission named.

4. The follow-on: in a national cloud the checks still run, now without their scopes

I went looking for what stops MT.1253/1254/1258 from running once their scopes are deliberately left out, and I do not think anything does yet:

  • Resolve-MtNativePlan.ps1:38 sets $enforce = @{ Service = $true; License = $true; TenantType = $false; Cloud = $false }, so the CloudMismatch skip at :313 is off by default. Cloud = ('Commercial', 'GCC') on the new checks is therefore correct and currently inert.
  • I found no comparison of a test's declared Permission against the granted scopes anywhere in the planner, so there is no missing-permission skip either.

If that is right, this PR turns "Connect-MgGraph fails in USGov" into "Connect-MgGraph succeeds and three checks return a 403 in USGov", which is a clear improvement but not the whole way. The complete version is for those checks to skip by Cloud, which needs the enforcement flag, or for the planner to skip a check whose declared scope was not granted — and the second would pay for itself far beyond this PR, since it is what turns every "403 from Graph" into a clean missing permission row.

Which raises the thing I would most like your view on: $globalOnlyPreviewScopes is a hand-kept list that has to agree with the Cloud attribute of the checks that need those scopes. Two places to remember. Could the Global-only set be derived from the checks themselves — the scopes declared only by checks whose Cloud excludes the national clouds — so the list cannot drift from the attributes? The inventory the engine already builds has both halves.

Not a blocker on any of this. Point 3 is the only one I would fix before merge, since it is a permission the check needs and a reader of the attribute would not know to grant.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants