AuditSphere - User Guide

Table of Contents

1. Introduction
2. Getting Started
3. Initial Setup
4. Dashboard Overview
5. Connecting Microsoft 365
6. Monitoring Activity
7. Anomaly Detection
8. Compliance Monitoring
9. Managing Alerts
10. Access Reviews
11. Reports
12. Settings & Configuration
13. Troubleshooting

Introduction

AuditSphere is a comprehensive security and compliance monitoring platform for Microsoft 365 SharePoint and OneDrive environments. It helps organizations:

• Monitor user activity and file access in real-time
• Detect anomalous behavior using machine learning
• Assess compliance against industry standards (CIS Benchmarks)
• Review and manage access permissions systematically
• Generate reports for auditing and compliance evidence

Getting Started

System Requirements

• Modern web browser (Chrome, Firefox, Edge, Safari)
• Microsoft 365 tenant with appropriate admin permissions
• Valid user account with assigned role (Admin, Analyst, or Viewer)

Accessing AuditSphere

1. Navigate to your organization's AuditSphere URL
2. Click Sign In to authenticate
3. You will be redirected to your identity provider
4. Enter your credentials and complete authentication
5. Upon successful login, you'll be directed to the Dashboard

Initial Setup

First-Time Administrator Setup

If you're setting up AuditSphere for your organization for the first time:

Step 1: Environment Configuration

The following environment variables must be configured by your administrator:

Step 2: Microsoft App Registration

1. Go to Azure Portal > App Registrations
2. Create a new registration for AuditSphere
3. Configure the redirect URI to: {YOUR_APP_URL}/api/microsoft/callback

Required API Permissions

Configure the following permissions in your app registration:

Microsoft Graph Permissions:

Office 365 Management APIs Permissions:

SharePoint Permissions:

4. Grant admin consent for all permissions in your organization

Expose an API Configuration

1. Navigate to Expose an API in your app registration
2. Set the Application ID URI (e.g., api://{your-client-id})
3. Add a scope with the following settings:
   • Scope name: access_as_user
   • Who can consent: Admins and users
   • Admin consent display name: Access AuditSphere API
   • User consent display name: Access AuditSphere
   • State: Enabled
4. If using a separate frontend client, add it under Authorized client applications with the scope selected

Authentication Configuration

1. Go to Authentication in your app registration
2. Add platform configuration for Web
3. Add redirect URI: {YOUR_APP_URL}/api/microsoft/callback
4. Enable Access tokens and ID tokens under Implicit grant

Create Client Secret

1. Go to Certificates & secrets
2. Create a new client secret
3. Copy the secret value immediately (it won't be shown again)
4. Add the secret to your environment configuration as MICROSOFT_CLIENT_SECRET

Step 3: Database Setup

Run the database migration to create required tables:

npm run db:generate
npx prisma migrate deploy

Step 4: Start the Application

# Development mode
npm run dev
 
# Production mode
npm run build
npm start

Dashboard Overview

The Dashboard is your central hub for monitoring security status.

Dashboard Components

Quick Stats Cards

• Total Events (24h): Number of audit events in the last 24 hours
• Anomalies Detected: Open anomalies requiring attention
• Active Alerts: Security alerts requiring action
• Compliance Score: Overall compliance percentage

Connection Status

The Microsoft 365 connection indicator shows:

• Connected (green): Successfully connected to your tenant
• Disconnected (red): No active connection - action required

Activity Overview

Visual charts showing:

• Event trends over time
• Event distribution by type
• User activity patterns

Navigation Menu

Connecting Microsoft 365

Initial Connection

1. Navigate to Settings > Connections
2. Click Connect Microsoft 365
3. You'll be redirected to Microsoft's authentication page
4. Sign in with an account that has admin permissions
5. Review and accept the requested permissions
6. Upon success, you'll be redirected back to AuditSphere

Connection Status

After connecting, the system will:

• Begin syncing audit events (every 15 minutes)
• Display your connected account information
• Show connection health status

Disconnecting

If you need to disconnect:

1. Go to Settings > Connections
2. Click Disconnect next to your Microsoft 365 connection
3. Confirm the disconnection

Note: Disconnecting will stop event collection but will not delete historical data.

Monitoring Activity

Viewing Audit Events

Navigate to Activity to see all collected audit events.

Event Information

Each event displays:

• Timestamp: When the event occurred
• Operation: Type of action (e.g., FileAccessed, FileShared)
• User: Who performed the action
• Resource: File or site affected
• IP Address: Source IP of the action
• User Agent: Client application used

Filtering Events

Use the filter panel to narrow results:

Searching Events

Use the search bar to find events by:

• File name
• User email
• Site URL
• Operation type

Exporting Events

Click Export to download filtered events as CSV.

Anomaly Detection

How Anomaly Detection Works

AuditSphere uses machine learning to identify unusual patterns:

• Access Patterns: Unusual file access behavior
• Timing Anomalies: Activity at unusual times
• Volume Anomalies: Unusually high activity levels
• External Sharing: Suspicious sharing with external users

Viewing Anomalies

Navigate to Anomalies to see detected issues.

Anomaly Details

Each anomaly shows:

• Type: Category of anomaly
• Severity: CRITICAL, HIGH, MEDIUM, LOW
• Confidence: ML model confidence score (0-100%)
• Status: NEW, INVESTIGATING, RESOLVED, FALSE_POSITIVE
• Related Event: The audit event that triggered detection

Managing Anomalies

Update Status

1. Click on an anomaly to view details
2. Select new status from dropdown
3. Add notes if needed
4. Click Update

Bulk Actions

1. Select multiple anomalies using checkboxes
2. Choose action from bulk menu
3. Confirm the action

Status Workflow

Compliance Monitoring

Supported Standards

AuditSphere includes built-in checks for:

• CIS Microsoft 365 Foundations Benchmark

Viewing Compliance Status

Navigate to Compliance to see your compliance posture.

Compliance Dashboard

• Overall Score: Percentage of passing checks
• By Category: Breakdown by compliance area
• Check Results: Individual check pass/fail status

Compliance Categories

Check Severity Levels

Running Compliance Checks

1. Click Run Compliance Check
2. Select the compliance standard
3. Wait for checks to complete
4. Review results and recommendations

Viewing Check Details

Click any check to see:

• Check description
• Current status
• Evidence collected
• Remediation recommendations

Managing Alerts

Alert Types

Alert Severity

• CRITICAL: Immediate action required
• HIGH: Urgent attention needed
• MEDIUM: Should be reviewed soon
• LOW: Informational

Alert Status

Managing Alerts

Acknowledge an Alert

1. Click on the alert
2. Click Acknowledge
3. Add investigation notes
4. Alert moves to ACKNOWLEDGED status

Resolve an Alert

1. Open an acknowledged alert
2. Click Resolve
3. Document the resolution
4. Alert moves to RESOLVED status

Dismiss an Alert

1. Click Dismiss for false positives
2. Provide reason for dismissal
3. Alert is removed from active view

Alert Configuration

Navigate to Settings > Alert Configuration to:

• Create custom alert rules
• Set notification preferences
• Configure severity thresholds

Access Reviews

Access Reviews help you systematically review and clean up permissions.

Creating a Review Campaign

1. Navigate to Access Review > Campaigns

2. Click Create Campaign

3. Configure the campaign:

   • Name: Descriptive campaign name
   • Description: Purpose of the review
   • Scope: Select sites to include
   • Reviewers: Assign reviewers
   • Due Date: Review deadline

4. Click Create

Campaign Workflow

Reviewing Permissions

As a Reviewer

1. Navigate to Access Review > My Reviews
2. See your pending review items
3. For each permission, choose:
   • Retain: Keep the access
   • Remove: Revoke the access
4. Provide justification for your decision
5. Submit decisions

Bulk Decisions

1. Select multiple items
2. Choose bulk action (Retain All / Remove All)
3. Provide common justification
4. Submit

Designated Owners

Assign resource owners who are responsible for reviewing their resources:

1. Go to Access Review > Designated Owners
2. Click Add Owner
3. Select the resource (site/drive)
4. Assign the owner
5. Optionally mark as primary owner

Scheduled Reviews

Set up recurring reviews:

1. Go to Access Review > Schedules
2. Click Create Schedule
3. Configure:
   • Frequency: Weekly, Monthly, Quarterly, Yearly
   • Review Period: Days for completion
   • Auto-execute: Automatically remove access on completion
   • Notifications: Email reminders
4. Save the schedule

Reports

Available Report Types

Generating a Report

1. Navigate to Reports
2. Click Generate Report
3. Select report type
4. Configure parameters:
   • Date range
   • Filters
   • Include options
5. Choose format: PDF, XLSX, or CSV
6. Click Generate

Downloading Reports

1. Wait for report generation to complete
2. Click Download next to the report
3. Report downloads in selected format

Scheduled Reports

Set up automatic report generation:

1. Click Schedule Report
2. Configure frequency
3. Select recipients
4. Reports will be emailed automatically

Settings & Configuration

Profile Settings

Navigate to Settings > Profile to:

• Update display name
• View account email
• See assigned role

Notification Preferences

Configure how you receive alerts:

Microsoft Connection

Manage your Microsoft 365 integration:

• View connection status
• Reconnect if needed
• Disconnect account

Alert Configuration

Create custom alert rules:

1. Go to Settings > Alert Configuration
2. Click Add Rule
3. Configure:
   • Name: Rule identifier
   • Condition: When to trigger
   • Severity: Alert priority
   • Notification: How to notify

Troubleshooting

Common Issues

"Microsoft 365 Not Connected"

Problem: Dashboard shows disconnected status.

Solution:

1. Go to Settings > Connections
2. Click Connect Microsoft 365
3. Re-authenticate with admin credentials
4. Ensure permissions are granted

"No Events Appearing"

Problem: Activity page shows no events.

Solutions:

1. Verify Microsoft 365 is connected
2. Check that audit logging is enabled in your Microsoft 365 tenant:
   • Go to Microsoft 365 Admin Center
   • Navigate to Compliance > Audit
   • Ensure auditing is turned on
3. Wait 15-30 minutes for initial sync
4. Verify the connected account has AuditLog.Read.All and ActivityFeed.Read permissions

"Compliance Checks Failing"

Problem: All compliance checks show errors.

Solution:

1. Ensure Microsoft connection is active
2. Verify admin permissions in Microsoft 365
3. Check that the app has SharePointTenantSettings.ReadWrite.All permission
4. Verify the connected account can access admin settings

"Access Review Not Collecting Permissions"

Problem: Campaign stuck in "Collecting" state.

Solutions:

1. Verify Sites.FullControl.All permission is granted
2. Check that selected sites are accessible
3. Review error logs in campaign details

"Permission Removal Not Working"

Problem: Access review decisions to remove permissions are not being executed.

Solutions:

1. Verify Sites.FullControl.All and Sites.Manage.All permissions are granted
2. Check that GroupMember.ReadWrite.All is granted for group permission removals
3. Ensure the app has write access to the affected sites

Getting Help

If you encounter issues not covered here:

1. Check the Help section in the application
2. Contact your system administrator
3. Review application logs for error details

Glossary

Document Information