Permissions Auditor

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/:

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:

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.

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.