Prerequisites

Requirements for deploying the Agent Knowledge Source Scanner solution.

PowerShell Requirements

Requirement	Version	Purpose
PowerShell	7.2+ (7.4+ for PnP 3.x)	Core runtime (#Requires -Version 7.2)
PnP.PowerShell	2.5.0+ or 3.x	SharePoint Online item enumeration, permission reads, sensitivity label retrieval

Installation

PnP.PowerShell 2.x

# Install PnP.PowerShell module (2.x — uses built-in multi-tenant app)
Install-Module -Name PnP.PowerShell -MinimumVersion 2.5.0 -Force -Scope CurrentUser

Note: PnP.PowerShell 2.5.0+ requires PowerShell 7.2 or later. Windows PowerShell 5.1 and PowerShell 7.0/7.1 are not supported.

PnP.PowerShell 3.x

PnP.PowerShell 3.x introduces breaking changes that affect authentication:

Change	Detail
PowerShell 7.4+ required	Minimum runtime raised from 7.0 to 7.4
.NET 8.0 required	Runtime dependency upgraded from .NET 6.0
Multi-tenant app removed	The PnP multi-tenant app registration (31359c7f-bd7e-475c-86db-fdb8c937548e) was removed in September 2024
-ClientId mandatory	Connect-PnPOnline now requires a tenant-specific Entra app registration
Cmdlet renames	Get-PnPAzureADGroupMember renamed to Get-PnPEntraIDGroupMember (this script handles both automatically)

# Install PnP.PowerShell 3.x
Install-Module -Name PnP.PowerShell -MinimumVersion 3.0.0 -Force -Scope CurrentUser

Register a Tenant-Specific Entra App

PnP.PowerShell 3.x requires a tenant-specific Entra app registration. Use the built-in registration command:

# Register the PnP app in your tenant (requires Entra Global Admin consent)
Register-PnPEntraIDApp -ApplicationName "PnP.PowerShell - AgentGov" `
    -Tenant "example.onmicrosoft.com" `
    -Interactive `
    -SharePointDelegatePermissions "AllSites.Read" `
    -GraphDelegatePermissions "Group.Read.All"

Record the Client ID from the output. Pass it to the scanner with -ClientId:

.\scripts\Get-KnowledgeSourceItemPermissions.ps1 `
    -SiteUrl "https://example.sharepoint.com/sites/AgentKB" `
    -LibraryName "Documents" `
    -AgentName "HR-Agent" `
    -AgentUserGroupId "00000000-0000-0000-0000-000000000001" `
    -ClientId "your-client-id-here"

Note: The script detects PnP.PowerShell 3.x at runtime and produces a clear error if -ClientId is not provided.

Permissions

SharePoint Online

The executing user must have permission to read item-level details and role assignments in each target library.

Role	Required For
Site Collection Admin or Site Member (with read access)	Enumerate items and read role assignments in knowledge source libraries

The script uses Connect-PnPOnline -Interactive which triggers a delegated (user) authentication flow. For PnP.PowerShell 3.x, the -ClientId parameter is also required (see PnP.PowerShell 3.x above). The signed-in user must have at least read access to the target SharePoint site and library.

Entra ID (Optional — Group Resolution)

When using the -AgentUserGroupId parameter to resolve agent user scope from a security group, the signed-in user needs permission to read group membership.

Permission	Type	Required For
GroupMember.Read.All or Group.Read.All	Delegated	Resolve security group members via Get-PnPEntraIDGroupMember (PnP 3.x) or Get-PnPAzureADGroupMember (PnP 2.x)
Entra ID Reader role	Directory	Alternative: read group membership via directory role

If group resolution fails, the script logs a warning and continues without agent user scope comparison.

Sensitivity Labels (Optional)

For sensitivity label cross-referencing, Microsoft Information Protection labels must be published to the target SharePoint sites. The scanner reads the _SensitivityLabel field on items, falling back to _ComplianceTag if unavailable.

Requirement	Purpose
Microsoft 365 E5 or E5 Compliance (recommended)	Sensitivity labels on SharePoint items
MIP labels published to target sites	_SensitivityLabel field populated on library items

Without sensitivity labels, risk scoring still functions but the CRITICAL tier (high-sensitivity + out-of-scope) cannot be evaluated.

Network Requirements

Endpoint	Protocol	Purpose
*.sharepoint.com	HTTPS	SharePoint Online site and item access via PnP PowerShell
login.microsoftonline.com	HTTPS	OAuth token acquisition (interactive authentication)
graph.microsoft.com	HTTPS	Entra ID group membership resolution (when using -AgentUserGroupId)

Configuration File

The scanner loads default settings from templates/item-scope-config.sample.json. Copy and customize for your environment:

Copy-Item .\templates\item-scope-config.sample.json .\templates\item-scope-config.json

Key configuration options:

Setting	Default	Description
maxItemsPerLibrary	10000	Maximum items scanned per library (override with -MaxItemsPerLibrary)
sensitivityLabelRiskTiers	See config file	Maps sensitivity label names to risk tiers (CRITICAL, HIGH, MEDIUM, LOW)
outputPath	./output/item-permissions-report.csv	Default report output location

Related Controls

This solution supports compliance with controls 4.3, 1.4, and 1.5. Organizations should verify that scanning coverage meets their specific regulatory obligations.