SharePoint Audit Tool

A SharePoint permissions auditing application for analyzing site permissions, sharing links, and security risks.

Development Status

Early development - Not recommended for production use. Breaking changes expected.

Features

The tool collects and displays:

• Sharing Links - Anonymous, organization-wide, and specific-people links with metadata (expiration, password protection, download restrictions, member lists)
• Permission Assignments - Direct role assignments on sites, lists, and items
• Broken Inheritance - Items with unique permissions that differ from their parent
• Sensitivity Labels - Microsoft Information Protection labels applied to content
• Site Structure - Webs, lists, libraries, folders, and files
• Principals - Users, groups, and security principals with access

Each audit creates a snapshot (audit run) that can be compared over time.

Azure Setup

The tool requires an Entra ID (Azure AD) app registration with certificate authentication.

1. Create App Registration

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click New registration
3. Name: spaudit (or your preference)
4. Supported account types: Accounts in this organizational directory only
5. Click Register
6. Copy the Application (client) ID and Directory (tenant) ID

2. Configure API Permissions

1. Go to API permissions > Add a permission
2. Select SharePoint > Application permissions
3. Add these permissions:
   • Sites.FullControl.All (required for sharing link enumeration)
4. Click Grant admin consent

3. Create Certificate

Generate a self-signed certificate:

# PowerShell - create certificate
$cert = New-SelfSignedCertificate -Subject "CN=spaudit" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -NotAfter (Get-Date).AddYears(2)

# Export PFX (with private key)
$pwd = ConvertTo-SecureString -String "your-password" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath "spaudit.pfx" -Password $pwd

# Export CER (public key only, for Azure upload)
Export-Certificate -Cert $cert -FilePath "spaudit.cer"

4. Upload Certificate to Azure

1. Go to your app registration > Certificates & secrets
2. Click Upload certificate
3. Upload the .cer file (public key)

5. Configure Environment

Copy the .pfx file to your server and configure the environment variables (see Configuration below).

Quick Start

Prerequisites

• Go 1.25+
• Mage (go install github.com/magefile/mage@latest)
• Entra ID app registration with SharePoint permissions (see Azure Setup)
• Certificate (.pfx file)

Setup

# Clone and bootstrap
git clone https://github.com/f0oster/spaudit && cd spaudit
mage bootstrap

# Configure environment
cd cmd/server
cp ../../.env.example .env
# Edit .env with your SharePoint credentials

# Build and run
mage build
./server.exe

Open http://localhost:8080

How It Works

1. Add Site - Enter a SharePoint site URL in the web interface
2. Start Audit - The tool queues a background job to audit the site
3. Data Collection - The job connects to SharePoint and collects:
   • Site structure (webs, lists, items)
   • Permission role assignments
   • Sharing links and their members
   • Sensitivity labels
4. Progress Updates - Real-time progress via Server-Sent Events
5. View Results - Browse collected data organized by site, list, and item

Each audit creates a new "audit run" - a point-in-time snapshot. You can switch between audit runs to compare changes.

Jobs can be cancelled from the web interface. The audit supports configurable batch sizes, retry logic, and parallel item scanning.

Configuration

Required Variables

Variable	Description
SP_TENANT_ID	Azure tenant ID (GUID)
SP_CLIENT_ID	App registration client ID (GUID)
SP_CERT_PATH	Path to .pfx certificate file
SP_CERT_PASSWORD	Certificate password (empty if none)

Server

Variable	Default	Description
HTTP_ADDR	:8080	Server listen address
HTTP_LOG_PATH	(none)	Path for HTTP request logging (JSON format)

Database

Variable	Default	Description
DB_PATH	./spaudit.db	SQLite database file path
DB_MAX_OPEN_CONNS	25	Maximum open connections
DB_MAX_IDLE_CONNS	5	Maximum idle connections
DB_CONN_MAX_LIFETIME	1h	Connection max lifetime
DB_CONN_MAX_IDLE_TIME	15m	Idle connection timeout
DB_BUSY_TIMEOUT_MS	5000	SQLite busy timeout (ms)
DB_ENABLE_WAL	true	Enable Write-Ahead Logging

Logging

Variable	Default	Description
LOG_LEVEL	info	Log level: debug, info, warn, error
LOG_FORMAT	json	Log format: json or text
LOG_OUTPUT	stdout	Output: stdout, stderr, or file path

Development Commands

mage bootstrap   # Install tools and run generators
mage build       # Build server binary
mage test        # Run tests
mage gen         # Regenerate database and template code
mage verify      # Run formatting, linting, tests, and build

Project Structure

spaudit/
├── cmd/server/       # Entry point
├── domain/           # Entities, contracts, events
├── application/      # Services
├── infrastructure/   # Repositories, SharePoint client
├── interfaces/web/   # HTTP handlers, templates, presenters
├── platform/         # Job executors, workflows
├── database/         # Migrations and queries
└── gen/db/           # SQLC generated code

Dependencies

• SQLite (modernc.org/sqlite)
• SQLC - SQL code generation
• Chi - HTTP router
• Gosip - SharePoint client
• Templ - HTML templates
• HTMX - Frontend interactivity

License

MIT License - see LICENSE

---

For architecture details, see docs/ARCHITECTURE.md.