Sharing Auditor

SharePoint/OneDrive External Sharing Auditor

Shared Workflow Routing

• Use the shared workflow spec for deterministic multi-plugin routing: workflows/multi-plugin-workflows.md.
• Apply the trigger phrases, handoff contracts, auth prerequisites, validation checkpoints, and stop conditions before escalating to the next plugin.

This skill provides comprehensive knowledge for auditing and managing external sharing across SharePoint and OneDrive via Graph API and SharePoint PowerShell, with a focus on safe remediation that avoids accidental data loss.

Integration Context Contract

• Canonical contract: docs/integration-context.md

* Use sovereign cloud values from the canonical contract when applicable.

Fail fast before Graph/SharePoint calls when required context is missing or invalid. Redact tenant/object identifiers in outputs.

Base URL

https://graph.microsoft.com/v1.0

All Graph API endpoints below are relative to this base URL.

API Endpoints

Drive Item Permissions

Guest User Management

Site Sharing Configuration

Access Reviews (Beta)

Sharing Link Types

Permission Link Response Example

{
  "id": "perm-id-abc123",
  "roles": ["read"],
  "link": {
    "scope": "anonymous",
    "type": "view",
    "webUrl": "https://contoso.sharepoint.com/:b:/s/project/abc123",
    "preventsDownload": false
  },
  "grantedToIdentitiesV2": [],
  "hasPassword": false,
  "expirationDateTime": null,
  "createdDateTime": "2025-11-15T08:30:00Z"
}

Key risk indicators in permission objects:

• link.scope = anonymous — anyone can access without sign-in
• expirationDateTime = null — link never expires
• hasPassword = false — no password protection
• roles includes write or owner — edit access to external parties

SharePoint Tenant Sharing Policies

SharingCapability Values

SharePoint PowerShell Commands

# Connect to SharePoint admin
Connect-SPOService -Url "https://contoso-admin.sharepoint.com"

# Get tenant-level sharing settings
Get-SPOTenant | Select-Object SharingCapability, DefaultSharingLinkType,
  DefaultLinkPermission, RequireAnonymousLinksExpireInDays,
  ExternalUserExpirationRequired, ExternalUserExpireInDays

# Get site-level sharing settings
Get-SPOSite -Identity "https://contoso.sharepoint.com/sites/project" |
  Select-Object SharingCapability, SharingAllowedDomainList,
  SharingBlockedDomainList, DefaultSharingLinkType

# List external users for a site
Get-SPOExternalUser -SiteUrl "https://contoso.sharepoint.com/sites/project"

Tenant Policy Enum Reference

Guest User Health Checks

Stale Guest Detection (90+ Days Inactive)

GET /users?$filter=userType eq 'Guest' and signInActivity/lastSignInDateTime le 2025-12-01T00:00:00Z
  &$select=displayName,mail,userPrincipalName,signInActivity,createdDateTime,externalUserState
  &$count=true
  &$orderby=signInActivity/lastSignInDateTime asc
Header: ConsistencyLevel: eventual

Guest Accounts Pending Redemption

GET /users?$filter=userType eq 'Guest' and externalUserState eq 'PendingAcceptance'
  &$select=displayName,mail,createdDateTime,externalUserState
  &$count=true
Header: ConsistencyLevel: eventual

External User State Values

Pagination Pattern

All list endpoints may return paginated results. Follow @odata.nextLink to fetch additional pages:

let allResults = [];
let url = "/users?$filter=userType eq 'Guest'&$top=100";

while (url) {
  const response = await client.api(url).get();
  allResults.push(...response.value);
  url = response["@odata.nextLink"] || null;
}

Important: Always paginate when scanning guest users or permissions — tenants may have thousands of guests.

Safe Remediation Principles

1. Never hard-delete sharing links without owner approval
2. Generate approval tasks instead of immediate revocation
3. Notify the file owner before any link is removed
4. Provide context — show what the link grants access to and who has used it
5. Batch by owner — group findings by file owner for efficient review
6. Snapshot before change — record the permission object before deletion

Revocation Patterns

Remove a Sharing Permission

DELETE /sites/{siteId}/drives/{driveId}/items/{itemId}/permissions/{permissionId}

Remove a Guest User

DELETE /users/{guestUserId}

Disable Anonymous Links at Site Level

Set-SPOSite -Identity "https://contoso.sharepoint.com/sites/project" -SharingCapability ExternalUserSharingOnly

Set Link Expiration Policy

Set-SPOTenant -RequireAnonymousLinksExpireInDays 30

Required Permissions

Error Handling

ConsistencyLevel Requirement

Queries using $count, $search, or advanced filters on signInActivity require:

Header: ConsistencyLevel: eventual

Without this header, the API returns 400 Bad Request.

Common Audit Patterns

Pattern 1: Full External Sharing Audit

1. Get-SPOTenant — check tenant-level sharing policy
2. Get-SPOSite -Limit All — list all sites with their sharing capability
3. For each site with ExternalUserAndGuestSharing: scan GET .../permissions for anonymous links
4. GET /users?$filter=userType eq 'Guest' — enumerate all guest accounts
5. Cross-reference guests with site permissions to identify orphaned access
6. Produce report grouped by risk level (High: anonymous, Medium: guest, Low: internal)

Pattern 2: Stale Guest Cleanup

1. GET /users?$filter=userType eq 'Guest' and signInActivity/lastSignInDateTime le {90daysAgo} — find stale guests
2. For each stale guest: GET /users/{id}/memberOf — list group memberships
3. Generate approval tasks for guest removal, grouped by the internal sponsor
4. After approval: DELETE /users/{guestId} — remove guest accounts
5. Verify removal: re-run guest query to confirm count reduction

Pattern 3: Anonymous Link Remediation

1. Identify sites with SharingCapability = ExternalUserAndGuestSharing
2. Scan all drive items for permissions where link.scope = 'anonymous'
3. Flag links with no expiration (expirationDateTime = null)
4. Generate owner notification with link details and access history
5. After owner review: DELETE .../permissions/{id} to remove approved links
6. Set-SPOSite -SharingCapability ExternalUserSharingOnly — downgrade site policy

Pattern 4: Tenant Sharing Policy Hardening

1. Audit current tenant settings: Get-SPOTenant
2. Set anonymous link expiration: Set-SPOTenant -RequireAnonymousLinksExpireInDays 30
3. Set guest expiration: Set-SPOTenant -ExternalUserExpirationRequired $true -ExternalUserExpireInDays 90
4. Set default link type to internal: Set-SPOTenant -DefaultSharingLinkType Internal
5. Block specific external domains: Set-SPOTenant -SharingBlockedDomainList "competitor.com"
6. Verify changes and document in change log

OData Filter Reference

Progressive Disclosure — Reference Files