AuditSphere Pro (SPFx) - User Guide

Table of Contents

1. Introduction
2. Prerequisites
3. Installation & Deployment
4. Initial Configuration
5. Using the Dashboard
6. Overview Page
7. Activity Log
8. Anomaly Detection
9. Compliance Monitoring
10. Alerts Management
11. Access Reviews
12. Sites Management
13. Reports
14. Settings
15. Troubleshooting

Introduction

AuditSphere Pro is a SharePoint Framework (SPFx) web part that brings comprehensive security and compliance monitoring directly into your SharePoint environment. It provides:

• Real-time Dashboard - Monitor security metrics at a glance
• Activity Monitoring - Browse and search audit events from Microsoft 365
• Anomaly Detection - AI-powered detection of unusual user behavior
• Compliance Checks - CIS Microsoft 365 benchmark assessments
• Access Reviews - Systematic permission review campaigns
• Alerting - Security notifications and alert management
• Reports - Generate compliance and activity reports

The web part connects to the AuditSphere API backend service, which handles all data processing, Microsoft Graph integration, and anomaly detection.

Prerequisites

System Requirements

• SharePoint Online tenant (Microsoft 365)
• SharePoint Administrator access (for initial deployment)
• Modern web browser (Edge, Chrome, Firefox, Safari)

Backend Requirements

• AuditSphere API deployed and accessible
• Azure AD app registration configured
• API permissions granted and admin consented

Azure AD App Registration

Your Azure AD app registration must have the following configured:

Application ID URI:

• Format: api://{your-client-id}
• Example: api://eca12ded-8416-41fd-ac0a-ffaccb1ecb04

Exposed API Scope:

• Scope name: access_as_user
• Who can consent: Admins and users
• Admin consent display name: Access AuditSphere API
• State: Enabled

Required API Permissions (on backend app):

Office 365 Management APIs:

Installation & Deployment

Step 1: Build the Package

If building from source:

# Navigate to project directory
cd auditsphere-spfx
 
# Install dependencies
npm install
 
# Build the solution package
npm run build

This creates auditsphere-pro.sppkg in the sharepoint/solution/ folder.

Step 2: Upload to App Catalog

1. Go to your SharePoint Admin Center
2. Navigate to More features > Apps > Open
3. Click App Catalog (create one if it doesn't exist)
4. Select Apps for SharePoint
5. Click Upload and select auditsphere-pro.sppkg
6. In the deployment dialog:
   • Check "Make this solution available to all sites in the organization" for tenant-wide deployment
   • Click Deploy

Step 3: Approve API Permissions

1. Go to SharePoint Admin Center
2. Navigate to Advanced > API access
3. You'll see pending permission requests for AuditSphere Pro
4. Select each permission and click Approve
5. The web part needs access to your Azure AD app registration

Step 4: Add to a Page

1. Navigate to any SharePoint modern page
2. Click Edit
3. Click + to add a new web part
4. Search for "AuditSphere" or find it under your organization's apps
5. Click to add the web part to the page
6. Configure the web part properties (see Initial Configuration)
7. Click Publish

Initial Configuration

After adding the web part to a page, configure it using the property pane.

Opening the Property Pane

1. Click the web part to select it
2. Click the pencil icon (Edit) on the web part toolbar
3. The property pane opens on the right side

Configuration Options

Available Themes

The web part also automatically detects and applies dark/light mode based on your SharePoint site theme.

Using the Dashboard

Navigation

The dashboard uses a tab-based navigation at the top:

Common Actions

• Refresh: Click the refresh button in the header to reload data
• Auto-refresh: Configure in Settings to automatically refresh at intervals
• Theme: Change visual theme in Settings

Overview Page

The Overview page provides a dashboard summary of your security posture.

Statistics Cards

• Total Events (24h): Audit events collected in the last 24 hours
• Anomalies: Number of detected anomalies requiring attention
• Active Alerts: Security alerts that need action
• Compliance Score: Overall compliance percentage

Activity Trends

A 7-day chart showing event volume trends over time.

Recent Activity Feed

A combined feed showing:

• Recent audit events
• Recent anomaly detections
• Timestamps and severity indicators

Activity Log

Browse and search all collected audit events from Microsoft 365.

Filtering Events

Use the filter bar to narrow results:

Event Details

Each event displays:

• Timestamp: When the event occurred
• Operation: Type of action performed
• User: Who performed the action
• Site URL: Where the action occurred
• IP Address: Source IP address
• User Agent: Client application used

Pagination

Events are displayed 50 per page. Use the pagination controls at the bottom to navigate.

Exporting

Click Export to download the current filtered view as CSV.

Anomaly Detection

View AI-detected unusual behavior patterns.

Anomaly Types

Severity Levels

Managing Anomalies

Filter by Severity

Use the severity filter dropdown to show only specific severity levels.

Filter by Status

Filter by status: NEW, INVESTIGATING, RESOLVED, FALSE_POSITIVE

Update Status

1. Click on an anomaly row
2. Select new status from the dropdown
3. Status updates immediately

AI Explanations

Each anomaly includes an AI-generated explanation describing:

• What was detected
• Why it's unusual
• Recommended actions

Compliance Monitoring

Run and view CIS Microsoft 365 benchmark compliance checks.

Running Checks

1. Click Run Compliance Check
2. Select the compliance standard (CIS MS365 Benchmark)
3. Wait for checks to complete
4. Review results

Understanding Results

Compliance Score

A percentage showing how many checks passed vs. total checks.

Check Status

Severity Levels

Viewing Check Details

Click on any check to see:

• Full check description
• Current configuration evidence
• Remediation steps

Clear Data

Click Clear Data to remove all compliance check history and start fresh.

Alerts Management

View and manage security alerts generated by the system.

Alert Types

Alert Status Workflow

Managing Alerts

Mark as Read

Click the checkbox to mark an alert as read.

Change Status

1. Click on an alert to expand details
2. Select new status from dropdown:
   • ACKNOWLEDGED: Being investigated
   • RESOLVED: Issue addressed
   • DISMISSED: False positive or no action needed

Alert Statistics

The header shows counts by status:

• New alerts
• Acknowledged
• Resolved

Access Reviews

Create and manage systematic permission review campaigns.

Access Review Tabs

Creating a Campaign

1. Go to Access Review > Campaigns

2. Click Create Campaign

3. Fill in campaign details:

   • Name: Descriptive campaign name
   • Description: Purpose of the review
   • Scope: Select sites/resources to review
   • Due Date: Deadline for completion

4. Click Create

Campaign Lifecycle

Reviewing Permissions (My Reviews)

1. Go to Access Review > My Reviews
2. See all permissions assigned to you for review
3. For each item, decide:
   • Retain: Keep the permission
   • Remove: Revoke the permission
4. Enter justification (required for remove decisions)
5. Click Submit Decision

Bulk Decisions

1. Select multiple items using checkboxes
2. Click Bulk Retain or Bulk Remove
3. Enter common justification
4. Click Submit

Scheduled Reviews

Set up recurring automatic reviews:

1. Go to Access Review > Schedules

2. Click Create Schedule

3. Configure:

   • Name: Schedule name
   • Frequency: Weekly, Monthly, Quarterly, or Yearly
   • Review Period: Days allowed for completion
   • Scope: Sites/resources to include
   • Auto-execute: Automatically remove access on completion
   • Notifications: Enable email reminders

4. Click Save

Designated Owners

Assign users responsible for reviewing specific resources:

1. Go to Access Review > Designated Owners
2. Click Add Owner
3. Select the resource (site or drive)
4. Select the owner (user)
5. Optionally mark as Primary Owner
6. Click Save

Sites Management

View and manage SharePoint sites being monitored.

Site List

Displays all SharePoint sites with:

• Site name and URL
• Last activity date
• Security status
• Monitoring status

Site Statistics

Header cards show:

• Total Sites: Number of sites
• External Sharing: Sites with external sharing enabled
• Recently Active: Sites with recent activity

Syncing Sites

Click Sync Sites to refresh the site list from Microsoft 365.

Site Details

Click on a site to see additional details and configuration options.

Reports

Generate and download compliance and activity reports.

Available Report Types

Generating a Report

1. Click Generate Report
2. Select report type
3. Configure parameters:
   • Date range
   • Filters (if applicable)
4. Click Generate
5. Wait for processing to complete

Downloading Reports

1. Find the report in the list
2. Click the Download button
3. Report downloads as CSV file

Managing Reports

• View: See report details and parameters
• Download: Download the generated file
• Delete: Remove the report

Settings

Configure the web part and manage connections.

API Configuration

• API URL: The AuditSphere API backend URL
• Azure AD Client ID: Your app registration client ID

Click Test Connection to verify the API is accessible.

Microsoft Connection Status

Shows whether the backend is connected to Microsoft 365:

• Connected: Green indicator, connection active
• Disconnected: Red indicator, action needed

Theme Settings

Select from available color themes:

• Default (Blue)
• Indigo
• Light Blue
• Navy
• Violet
• Sky Blue

Dark/light mode is automatically detected from your SharePoint site theme.

Auto-Refresh

Configure automatic data refresh:

• Set interval in seconds
• Set to 0 to disable

Troubleshooting

Common Issues

"Failed to connect to API"

Problem: Web part cannot reach the AuditSphere API.

Solutions:

1. Verify the API URL in Settings is correct
2. Check that the API service is running
3. Verify network connectivity
4. Check browser console for CORS errors

"Authentication failed"

Problem: Azure AD token acquisition failed.

Solutions:

1. Verify the Azure AD Client ID is correct
2. Check that API permissions are approved in SharePoint Admin Center
3. Ensure the app registration has the correct scopes configured
4. Clear browser cache and try again

"No data appearing"

Problem: Dashboard shows empty or no events.

Solutions:

1. Verify Microsoft 365 connection is active (check Settings)
2. Ensure audit logging is enabled in your Microsoft 365 tenant
3. Wait for the sync interval (events sync every 15 minutes)
4. Check that the connected account has proper permissions

"Compliance checks failing"

Problem: All compliance checks show errors.

Solutions:

1. Verify the API service has proper Microsoft Graph permissions
2. Check that the service account has admin access
3. Review API logs for specific error messages

"Access review not collecting"

Problem: Campaign stuck in "Collecting" status.

Solutions:

1. Verify Sites.FullControl.All permission is granted
2. Check that selected sites are accessible
3. Review API service logs

"Permission changes not executing"

Problem: Access review remove decisions not being applied.

Solutions:

1. Verify Sites.FullControl.All and Sites.Manage.All permissions
2. Check GroupMember.ReadWrite.All for group permissions
3. Ensure the API service has write access

Getting Help

For additional support:

1. Check the Help page within the application
2. Contact your SharePoint administrator
3. Review browser developer console for error details
4. Check API service logs for backend errors

Browser Developer Console

To view detailed error messages:

1. Press F12 to open Developer Tools
2. Go to the Console tab
3. Look for red error messages
4. Network tab shows API request/response details

Glossary

Document Information