sharepoint-permissions-audit

Of course! Here is a detailed readme.md file generated from the provided PowerShell script.

---

SharePoint Permissions Audit Script

1. Overview

This PowerShell script provides a comprehensive audit of permissions for a SharePoint Online environment. It systematically crawls through a specified SharePoint site, including its subsites, to report on access rights at the library, folder, and individual item levels.

A key feature of this script is its ability to recursively expand both on-premises Active Directory (AD) and Azure AD (Entra ID) security groups to provide a complete picture of all users who have access, even through nested group memberships. The final reports are exported into organized CSV files, including valuable user details like Job Title and Department, making it an essential tool for security audits, compliance checks, and access reviews.

The script is interactive, prompting the user for the scope of the audit, such as whether to scan all libraries or filter by name, and whether to include the time-intensive operations of group member enumeration and item-level permission checks.

Author: Josh Lambert
Date: 2024-06-07
Version: 1.0

---

2. Features

• Comprehensive Auditing: Reports on permissions for lists, libraries, folders, and individual items.
• Recursive Group Expansion: Expands nested on-premises Active Directory and Azure AD security groups to identify all effective user permissions.
• Detailed User Information: Enriches reports with user data such as Title and Department.
• Flexible Scope: Allows auditing of all libraries or filtering by a specific name/substring.
• Granular Control: Provides options to include/exclude group member enumeration and item-level permissions to manage performance.
• Organized Output: Generates detailed reports in CSV format, stored in a timestamped folder with a logical subdirectory structure for easy analysis.
• Subsite Traversal: Automatically discovers and processes specified subsites within the target site collection.

---

3. Requirements

The script requires the following PowerShell modules to be installed on the machine where it is executed:

• PnP PowerShell: Used for interacting with SharePoint Online.
• Microsoft Graph PowerShell: Used for querying Azure Active Directory (Entra ID) groups.
• Active Directory PowerShell Module: Used for querying on-premises Active Directory groups. This module is typically installed as part of the Remote Server Administration Tools (RSAT).

---

4. Installation

Run the following commands in PowerShell to install the necessary modules for the current user:

# Install PnP PowerShell
Install-Module PnP.PowerShell -Scope CurrentUser

# Install Microsoft Graph PowerShell
Install-Module Microsoft.Graph -Scope CurrentUser

# Install the Active Directory module (requires administrator rights)
# This is part of Remote Server Administration Tools (RSAT)
# For Windows 10/11:
Add-WindowsCapability -Online -Name Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0

---

5. Configuration and Usage

Step 1: Configure the Script

Before running the script, you must edit it to provide connection details.

1. SharePoint Site URL: Locate the line Connect-PnPOnline -Url "" -Interactive -ClientId "" and replace the empty "" with the URL of the root SharePoint site you wish to audit.

   # Example
   Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/your-site" -Interactive -ClientId "your-client-id"

2. Client ID (Optional but Recommended): Using a specific Azure AD App Registration Client ID for PnP PowerShell is recommended for authentication. Replace your-client-id with your registered application's ID. If you leave it blank, a default PnP application will be used.

Step 2: Run the Script

1. Open a PowerShell terminal.
2. Ensure you are authenticated to both Azure (for Graph) and your on-premises Active Directory environment. The script will use your credentials to connect.
3. Navigate to the directory where you saved the script.
4. Execute the script:

   .\sharepoint-library-item-permission-audit.ps1

Step 3: Follow the Prompts

The script will prompt you for the following information:

1. Filter Libraries:

   Enter 1 for all lists and libraries, or a substring to filter by name:
   

   • Enter 1 to audit every list and library in the site.
   • Enter a name or partial name (e.g., "Finance") to only audit libraries whose titles contain that string.

2. Enumerate Group Members:

   Enumerate group members? (Y/N) This will significantly increase processing time:
   

   • Y: The script will expand all SharePoint, AD, and Azure AD groups to list individual users. Warning: This is very time-consuming for large sites with many groups.
   • N: The script will only report the group name that has been granted permission.

3. Include Item-Level Permissions:

   Include item-level permissions? (Y/N) This will significantly increase processing time:
   

   • Y: The script will check every single item and folder for unique permissions. Warning: This can dramatically increase execution time on libraries with thousands of items.
   • N: The script will only report permissions at the library and top-level folder level.

---

6. Output

The script generates all reports in a timestamped primary folder located at C:\Temp\SPOPermissions_<yyyy-MM-dd_hh-mm>\.

Inside this folder, you will find:

• Subfolders for each List/Library: A folder is created for each list or library that is processed.
• Permission Reports (CSV):
  • <ListName>_Permissions.csv: Contains the permissions for the root of the list or library.
  • <FolderName>_Permissions.csv: Contains permissions for folders that have unique permissions.
  • <ItemName>_Permissions.csv: (If item-level permissions are enabled) Contains permissions for individual files with unique access.
  • AllItems.csv: A master log of every file and folder processed, including metadata like size, modification date, and a summary of its permission status (inherits or unique).
  • UniquePermissionsReport.csv: A consolidated report that aggregates all unique item-level permission entries from across the entire site into a single file for easier analysis.

CSV Report Columns

Column	Description
Principal	The user or group that has permissions.
UserTitle	The job title of the user (if group members are enumerated).
UserDepartment	The department of the user (if group members are enumerated).
Type	The type of principal (e.g., User, SharePointGroup, SecurityGroup).
Permissions	The permission level assigned (e.g., Full Control, Edit, Read).
GrantedThrough	How the permission was granted (e.g., Direct Permissions, SharePoint Group: <GroupName>, AD Group: <GroupName>).
IsNestedGroup	True or False. Indicates if the permission comes from a nested group.
ObjectName	The name of the list, folder, or item.
ObjectUrl	The server-relative URL of the list, folder, or item.

---

7. Example

PS> .\sharepoint-library-item-permission-audit.ps1

# The script will first open browser windows to connect to SharePoint and Microsoft Graph.

# Next, it will display prompts in the console:
Enter 1 for all lists and libraries, or a substring to filter by name: 1
Enumerate group members? (Y/N) This will significantly increase processing time: N
Include item-level permissions? (Y/N) This will significantly increase processing time: Y

# The script will begin processing and show progress in the console.
# Once complete, the reports will be available in C:\Temp\SPOPermissions_2024-06-07_10-30\

This example will audit all libraries and lists, will not expand group members (it will just show the group name), and will include permissions for every item with unique access.