permissions-auditor

name	permissions-auditor
description	Audit PnP PowerShell permission attributes against the APIs a cmdlet actually calls and against its documentation. Use when a change adds or alters an API call or a RequiredApi* attribute, when a user reports a 401/403 or a consent problem, or to sweep a folder under src/Commands/ for wrong or over-declared permissions.

Playbook: permissions-auditor

Verify that a cmdlet's declared API permissions match the APIs it actually calls, and that its documentation says the same thing.

Why this matters more than it looks

Wrong permission metadata fails silently at runtime, in someone else's tenant. Nothing in the build catches it, no test covers it, and the user finds out through a 401 in an unattended script or by granting an app far more access than the cmdlet needs. It is the highest-value static check in this repository.

There are three independent statements of the same fact, and all three can be compared without running anything:

1. the attributes on the cmdlet class
2. the API calls in the method body
3. the Required Permissions block in documentation/<Cmdlet>.md

Any disagreement between them is a finding.

Report findings in the session. Never open an issue or PR for one — see Human in the loop. A permission finding is security-adjacent; a maintainer decides whether it goes on a public tracker.

The attributes

Declared in src/Commands/Attributes/:

Attribute	Meaning
RequiredApiDelegatedPermissions	Needed when connected with delegated permissions.
RequiredApiApplicationPermissions	Needed when connected with application permissions.
RequiredApiDelegatedOrApplicationPermissions	Same scope satisfies either flavour.
ApiNotAvailableUnderDelegatedPermissions	Cmdlet cannot work delegated at all.
ApiNotAvailableUnderApplicationPermissions	Cmdlet cannot work app-only at all.
ApiPermissionsNotRequired	Needs nothing on the app registration. Informational.
ApiPermissionsDependOnResource	Requirement follows from the resource or invocation. Informational.

Semantics, from RequiredApiPermissionsBase:

• Multiple attributes on one class are ORed. Any one of them being satisfied is enough.
• Multiple scopes inside one attribute are ANDed. All of them are required.

Scope format is <resource>/<scope>, optionally https://-prefixed:

[RequiredApiDelegatedPermissions("sharepoint/AllSites.FullControl", "sharepoint/User.ReadWrite.All")]
[RequiredApiApplicationPermissions("sharepoint/Sites.FullControl.All", "sharepoint/User.ReadWrite.All")]

The failure mode to hunt for first

RequiredApiPermissionsBase parses each string with the regex (?:https://)?(?<resource>[^/]*?)/(?<scope>.*) and maps the resource through TokenHandler.DefineResourceTypeFromAudience. That method returns Unknown only for blank input; every other unrecognised audience falls through to _ => Enums.ResourceTypeName.SharePoint (src/Commands/Base/TokenHandler.cs), because vanity domains give SharePoint audiences no fixed shape.

So there are two distinct defects, and the common one is not what it looks like:

Written	Result
"garph/Group.Read.All"	Silently becomes a SharePoint scope Group.Read.All. The cmdlet declares a permission that does not exist on SharePoint, and its real Graph requirement is undeclared.
"Group.Read.All" (no /)	Regex fails, null, scope dropped entirely — the cmdlet declares nothing.
"/Group.Read.All" (blank resource)	Unknown → null → dropped.

Hunt for the first one primarily: a scope whose resource segment is not one of the audiences listed in DefineResourceTypeFromAudience, and any SharePoint-classified scope whose name looks like a Graph permission (*.Read.All, Group.*, User.*, Directory.*) on a cmdlet whose code calls Graph. Then check for null slots in PermissionScopes for the slashless cases.

Second failure mode: an attribute array with a single scope where the code demonstrably needs two (e.g. reads a user and writes a site), or the reverse — an AND list that over-declares and forces users to grant more than the cmdlet uses. Over-declaration is a real finding here, not a nitpick; least privilege is the point of the attribute.

Establishing what the code actually calls

Work out the resource from the base class, then confirm against the call sites.

Base class	Resource
PnPGraphCmdlet	Microsoft Graph
PnPWebCmdlet, PnPSharePointCmdlet, PnPWebRetrievalsCmdlet<T>	SharePoint (CSOM, site scope)
PnPSharePointOnlineAdminCmdlet	SharePoint (CSOM, tenant admin scope)
PnPAzureManagementApiCmdlet	Azure Management
PnPOfficeManagementApiCmdlet	Office 365 Management
PnPGcsCmdlet	Graph consumer / cloud storage
PnPTasksCmdlet	Planner / Tasks

Call sites to read:

• GraphRequestHelper.Get / GetResultCollection / Post / PostHttpContent / Patch / Delete — the URL literal names the Graph endpoint. Look it up rather than guessing its scopes.
• RequestHelper.* — same shape, non-Graph resource.
• CSOM: Tenant.<Method>, CurrentWeb.<...>, ClientContext.Load + ExecuteQueryRetry().
• A cmdlet may call more than one resource. Every one of them needs covering.

Do not infer a scope from the cmdlet name. Get- prefixed cmdlets routinely need write scopes because the underlying admin API is a POST, and several Set- cmdlets need only a read scope on a second resource they look something up in.

Use the Microsoft Learn MCP server to resolve a Graph endpoint to its documented least-privilege permission set. Do not answer from memory — Graph permission requirements change, and a confidently wrong scope here is worse than an admitted gap.

Cross-checking against the documentation

documentation/<Verb-PnPNoun>.md states the same requirement in prose under ## SYNOPSIS:

## SYNOPSIS

**Required Permissions**

Access to SharePoint admin site

* SharePoint: AllSites.FullControl and User.ReadWrite.All when using delegated permissions
* SharePoint: Sites.FullControl.All and User.ReadWrite.All when using application permissions

Check that every scope in the attributes appears here with the right delegated/application flavour, and that nothing appears here that the attributes do not declare. ANDed scopes read as "X and Y"; ORed alternatives read as separate bullets. A cmdlet carrying ApiPermissionsNotRequired should not have a Required Permissions block at all.

Existing tooling to lean on

The repository already ships two cmdlets that read this metadata. Read their implementations to match their interpretation exactly rather than inventing your own:

• Get-PnPCommandPermission (src/Commands/Base/GetCommandPermission.cs) — returns the declared and derived permissions for a cmdlet.
• Test-PnPConnectionPermission — compares a token's claims against that metadata.

If your reading of an attribute disagrees with what these cmdlets do, they are the authority.

Procedure

1. Scope the run: a folder under src/Commands/, a changed file set, or one cmdlet. State the scope in the report — a partial audit reported as complete is worse than no audit.
2. For each cmdlet class, collect: base class, permission attributes, every API call site.
3. Resolve each call site to its documented least-privilege permissions (Microsoft Learn MCP).
4. Compare attributes ↔ code. Then attributes ↔ documentation synopsis.
5. Discard anything you cannot substantiate. An unverified scope claim is worse than a gap.

Reporting

One row per finding, ordered by consequence:

Field	Content
Cmdlet	Verb-PnPNoun and file.cs:line
Kind	missing / over-declared / wrong-flavour / silently-dropped / doc-mismatch
Declared	What the attributes say
Required	What the API actually needs, with the Learn URL you got it from
Consequence	The concrete failure — "app-only connection gets 403 on /users/{id}/drive"

Say plainly which cmdlets you checked and which you could not resolve. Confidence: high only when you have a Microsoft source for the scope; otherwise say what would settle it.