PermiX
Why PermiX Exists
SharePoint permissions are notoriously hard to understand — even for the people who set them up.
When something goes wrong (“why can’t I see this site?”, “who gave that external user access?”, “did I accidentally share that folder with everyone?”), the usual answer is: ask your admin. The admin then has to stop what they’re doing, dig through the SharePoint admin center, click through multiple nested permission levels, and try to explain what they found in a way that actually makes sense to the person asking.
The goal
Give site owners, project managers, and security-conscious users the ability to investigate their own environment confidently — spot a potential issue, understand what they’re looking at, and either fix it themselves or bring a clear, specific question to IT instead of a vague concern.
Less guesswork. Fewer support tickets. More ownership.
That loop is slow, frustrating for everyone, and doesn’t scale.
What PermiX Is Not
PermiX is a read-only analysis tool. It makes no changes to your SharePoint environment. It has no backend, stores nothing externally, and runs entirely within your own infrastructure — locally or in a container you control.
Quick Start
Option A: Local Web Server ✅ recommended
Best authentication experience — uses browser popups for seamless re-authentication.
Windows:
git clone https://github.com/CreativeAcer/PermiX.git
cd PermiX
.\Install-Prerequisites.ps1
.\Start-SPOTool-Web.ps1 # opens http://localhost:8080
Linux/macOS:
# Install PowerShell 7+ first (if not already installed)
# Ubuntu/Debian: wget -q https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
# sudo dpkg -i packages-microsoft-prod.deb && sudo apt update && sudo apt install -y powershell
# Fedora: sudo dnf install -y powershell
# macOS: brew install powershell
git clone https://github.com/CreativeAcer/PermiX.git
cd PermiX
pwsh ./Install-Prerequisites.ps1
pwsh ./Start-SPOTool-Web.ps1 # opens http://localhost:8080
Why local mode is preferred:
- One-click authentication — browser popups handle all auth flows automatically
- No re-authentication needed — analyze any site without additional device codes
- Seamless UX — MSAL token cache handles everything in the background
- Works on Windows, Linux, and macOS — PowerShell 7+ is cross-platform
Requires PowerShell 7+ and PnP.PowerShell 3.x (installer handles this).
Option B: Container
Zero local dependencies — just Podman or Docker.
git clone https://github.com/CreativeAcer/PermiX.git
cd PermiX
podman compose up # or: docker compose up
Open http://localhost:8080 and you’re in.
Container mode limitations:
- Device code authentication — requires terminal access to see device codes
- Re-authentication per site — analyzing different sites requires entering a new device code each time
- Why? SharePoint access tokens are scoped per site, and container mode can’t use browser popups
Use container mode for: server deployments, CI/CD pipelines, or Linux-only environments.
Not ready to connect yet?
Hit Demo Mode on the Connection tab — it loads realistic sample data so you can explore every feature without a SharePoint connection.
Platform Support
| Mode | Windows | Linux | macOS |
|---|---|---|---|
| Local Web Server | ✅ | ✅ | ✅ |
| Container | ✅ | ✅ | ✅ |
Local mode uses PowerShell 7+ (cross-platform) with Interactive authentication (browser popups). Container mode uses device code flow in all environments.
Container Deployment
Prerequisites
Commands
| Command | Description |
|---|---|
podman compose up |
Web UI at localhost:8080 (default) |
podman compose down |
Stop the container |
podman build -t spo-analyzer . |
Build image only |
podman run -p 8080:8080 spo-analyzer |
Run without compose |
Live SharePoint Connection
The container uses device code flow for authentication (no browser popup available in headless environments).
Auto-connect on startup — uncomment and set env vars in compose.yaml:
environment:
- SPO_TENANT_URL=https://yourtenant.sharepoint.com
- SPO_CLIENT_ID=your-app-registration-guid
The device code appears in the container terminal. Open https://microsoft.com/devicelogin, enter the code, and the web server starts already connected.
Connect via the UI — click “Connect to SharePoint” in the browser. The device code appears in the container terminal (podman logs <container>). Authenticate at the device login URL; the UI updates when complete.
⚠️ Authentication Requirements:
- Initial connection: Device code required (appears in terminal)
- Analyzing different sites: New device code required for each unique site URL
- Why multiple authentications? SharePoint access tokens are scoped per site collection. Container mode cannot use Interactive auth (browser popups), so it must request new device codes when switching sites.
- Workaround: Analyze the same site you connected to initially, or use local mode for seamless multi-site analysis.
Features
🔐 Permission Analysis
- Site-level permissions with inheritance detection
- User enumeration with internal/external classification
- Group analysis with member counts
- Role assignment mapping across all resources
- Permission inheritance tree with broken inheritance detection
- Sharing link audit (anonymous, company-wide, specific-people)
⚠️ Risk Assessment
- 11 security rules across Critical, High, Medium, and Low severity levels
- Overall risk score (0-100) with a color-coded dashboard banner — you’ll know immediately if something’s wrong
- Catches: external admins, anonymous edit links, excessive permissions, broken inheritance, stale accounts, empty groups
- Filterable findings by severity with detailed remediation guidance
👥 External User Enrichment
- Microsoft Graph integration — enriches external users with live account status
- Stale account detection — flags accounts inactive for 90+ days
- Account status tracking — Active, Disabled, or Never signed in
- Domain analysis — aggregates external users by organization so you can see who’s really in your tenant
🔎 Deep Dive Views
- Sites — storage analysis, health scoring, filterable grid
- Users — permission breakdown, internal vs external classification
- Groups — membership analysis, empty group detection
- External Users — domain analysis, access audit, enrichment with stale warnings
- Role Assignments — principal-to-permission mapping with security review
- Inheritance — broken inheritance overview with percentage scoring + interactive tree view showing the full parent-child hierarchy
- Sharing Links — link type distribution, anonymous edit detection
🖱️ Interactive UI
- Global search — Omnibox (Ctrl+K / Cmd+K) searches across sites, users, and groups instantly
- Clickable charts — click any bar or segment to drill straight into the underlying data
- Tree visualizations — collapsible hierarchical view of permission inheritance
- Export anywhere — CSV or JSON with a format chooser modal on every table
- Sortable/filterable tables with real-time search
- Responsive design for desktop and mobile
🔑 Capability Awareness
- Proactive permission checking — After connecting to SharePoint, PermiX tests what data you can access and shows you upfront
- Transparent capability status — Clear indicators show whether you can enumerate sites, read users, access storage data, and query external users
- Smart button states — Operations requiring admin permissions (like “Get All Sites”) are automatically disabled for non-admin users with helpful tooltips explaining why
- Graceful degradation — The tool works with limited permissions and tells you exactly what features are available to you
Security Rules
11 rules evaluate your environment across five categories: External Access, Sharing Links, Permissions, Inheritance, and Groups.
| Severity | What it catches |
|---|---|
| 🔴 Critical | External site admins, anonymous edit links |
| 🟠 High | External users with elevated permissions, anonymous links, excessive Full Control, broken inheritance |
| 🟡 Medium | Multiple external domains, excessive org-wide links, direct user assignments |
| 🔵 Low | Empty groups |
Risk score (0–100) is calculated from the top 5 findings. Levels: Critical 80+, High 60–79, Medium 30–59, Low 1–29, None 0.
Screenshots
App Registration
You need an Azure AD App Registration to connect to SharePoint Online.
1. Create the registration
- Azure Portal > App registrations > New registration
- Name:
PermiX - Account types: Single tenant
- Authentication > Allow public lcient flows >
Yes - Redirect URI: Public client/native (Web) >
http://localhostandhttps://login.microsoftonline.com/common/oauth2/nativeclient
2. Add API permissions
| API | Permission | Type |
|---|---|---|
| Microsoft Graph | Sites.FullControl.All | Delegated |
| Microsoft Graph | User.Read.All | Delegated |
| Microsoft Graph | GroupMember.Read.All | Delegated |
| SharePoint | AllSites.FullControl | Delegated |
Why FullControl? This is a read-only tool, but SharePoint treats reading RoleAssignments and RoleDefinitionBindings as a privileged operation.
Sites.Read.All/AllSites.Readis insufficient.SharePoint Administrator role: Tenant-wide site enumeration and storage data require this role. PermiX automatically detects your permissions on connection and shows you a capability status display indicating exactly what data you can access. Non-admin users can still analyze individual sites — the tool gracefully adapts to your permission level.
Click Grant admin consent after adding all permissions.
3. Enable public client
Authentication > Allow public client flows > Yes > Save
Project Structure
PermiX/
├── Start-SPOTool-Web.ps1 # 🚀 Web UI entry point (local mode)
├── Dockerfile # 🐳 Container image definition
├── compose.yaml # 📦 Podman/Docker Compose config
├── docker-entrypoint.ps1 # ⚙️ Container startup script
├── Install-Prerequisites.ps1 # 📥 Module installer for local mode
│
├── Functions/
│ ├── Core/ # 🧠 Core infrastructure & utilities
│ │ ├── AuditLog.ps1 # Audit trail logging
│ │ ├── Checkpoint.ps1 # Analysis checkpoint/resume support
│ │ ├── Logging.ps1 # General logging helpers
│ │ ├── OutputAdapter.ps1 # Output formatting adapter
│ │ ├── Settings.ps1 # Configuration management
│ │ ├── SharePointDataManager.ps1 # Central data store & caching
│ │ └── ThrottleProtection.ps1 # API throttle/rate-limit handling
│ │
│ ├── Analysis/ # 🔍 Data analysis & enrichment
│ │ ├── GraphEnrichment.ps1 # Microsoft Graph user enrichment
│ │ ├── JsonExport.ps1 # JSON export formatting
│ │ └── RiskScoring.ps1 # Security risk scoring engine
│ │
│ ├── SharePoint/ # 🏢 SharePoint data collection
│ │ ├── PermissionsCollector.ps1 # Collects all permission assignments
│ │ ├── PermissionsMatrix.ps1 # Builds permission matrix view
│ │ ├── SiteCollector.ps1 # Site enumeration & metadata
│ │ └── SPOConnection.ps1 # Authentication & connection handling
│ │
│ ├── Server/ # 🌐 Web server & API backend
│ │ ├── ApiHandlers.ps1 # REST API route handlers
│ │ ├── BackgroundJobManager.ps1 # Background analysis job runner
│ │ └── WebServer.ps1 # HTTP server (PowerShell HttpListener)
│ │
│ └── Demo/ # 🎭 Demo mode
│ └── DemoDataGenerator.ps1 # Generates realistic sample data
│
├── Web/ # 🖥️ Browser-based frontend
│ ├── index.html # Single-page app shell
│ ├── Assets/
│ │ ├── permix-icon.svg # Icon for Project
│ │ ├── permix-logo-light.svg # Light social image
│ │ └── permix-logo-dark.svg # Dark social image
│ ├── css/
│ │ ├── app.css # Core styles & layout
│ │ └── enhancements.css # Extended components & animations
│ └── js/
│ ├── app.js # App bootstrap & tab routing
│ ├── app-state.js # Shared application state
│ ├── api.js # Backend API client
│ ├── analytics.js # Analytics tab logic
│ ├── charts.js # Chart rendering (Chart.js)
│ ├── connection.js # Connection tab & auth flow
│ ├── deep-dives.js # Deep dive modal views
│ ├── export.js # CSV/JSON export logic
│ ├── operations.js # Operations tab logic
│ ├── permissions-matrix.js # Permissions matrix view
│ ├── search.js # Global omnibox search (Ctrl+K)
│ └── ui-helpers.js # Shared UI utilities
│
├── Images/ # 📸 Screenshots for documentation
└── Logs/ # 📋 Runtime logs (auto-created)
Troubleshooting
| Problem | Solution |
|---|---|
| “Access is denied” | Verify app registration permissions and admin consent |
| “PnP PowerShell module not found” | Run Install-Prerequisites.ps1 or Install-Module PnP.PowerShell -Force |
| “Connection timeout” | Check network; ensure redirect URI is http://localhost |
| Execution policy error | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| Container auth not working | Check the container terminal for the device code; ensure SPO_HEADLESS=true is set |
Detailed logs live in ./Logs/. When in doubt, Demo Mode is a great way to confirm whether the issue is connection-related or not.
Contributing
Contributions are welcome! Fork the repo, create a feature branch, and open a pull request. Bug reports, ideas, and feedback via Issues are equally appreciated.
License
MIT — see LICENSE.