AuditSphere - User Guide

Table of Contents

1. Introduction
2. Getting Started
3. Initial Setup
4. Dashboard Overview
5. Connecting Cloud Providers
6. Repositories
7. Monitoring Activity
8. Anomaly Detection
9. Compliance Monitoring
10. Data Classification
11. Data Retention
12. Managing Alerts
13. Access Reviews
14. Reports
15. Settings & Configuration
16. Troubleshooting

Introduction

AuditSphere is a multi-cloud metadata aggregation and compliance platform that provides unified security monitoring across Microsoft 365, Google Workspace, Box, Dropbox, and other enterprise data repositories. It helps organizations:

• Aggregate metadata across all cloud storage providers (never stores document content)
• Monitor user activity and file access in real-time across all providers
• Detect anomalous behavior using per-provider ML models
• Assess compliance against 8 frameworks (GDPR, HIPAA, SOX, NIST, ISO 27001, SOC 2, CCPA, CIS MS365)
• Classify data with a unified taxonomy mapped to provider-native labels
• Enforce retention policies and detect violations
• 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 admin user account

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 Cloud Providers

AuditSphere supports connecting multiple cloud storage providers. Each connection uses OAuth to securely access metadata without storing document content.

Supported Providers

Connecting a Provider

1. Navigate to Settings > Connections
2. Find the provider you want to connect in the Cloud Connections card
3. Click Connect
4. You’ll be redirected to the provider’s authentication page
5. Grant the requested permissions (metadata read-only)
6. You’ll be redirected back to AuditSphere

Connection Status

• Active — Connected and tokens are valid
• Expired — Token has expired, click Reconnect to re-authenticate
• Revoked — Connection was disconnected by the user

Microsoft 365 Connection

1. Navigate to Settings > Connections
2. Click Connect next to 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 Frameworks

AuditSphere includes 8 built-in compliance frameworks, all provider-agnostic:

Running Compliance Checks

1. Navigate to Compliance
2. In the Quick Actions panel, click the framework you want to run (e.g., Run HIPAA Checks)
3. Wait for checks to complete
4. Results appear in the main panel with pass/fail status per rule

Rule Types

The compliance engine uses 4 types of declarative rules:

Compliance Dashboard

• Overall Score: Percentage of passing checks across all frameworks
• By Category: Breakdown by compliance area (access_control, data_retention, etc.)
• By Severity: Breakdown by critical/high/medium/low
• Check Results: Individual rule pass/fail with evidence and remediation

Check Severity Levels

Filtering Results

Use the Standard dropdown to filter by framework (e.g., show only GDPR results) and the Category dropdown to filter by area (e.g., data_retention only).

Data Classification

Taxonomy

AuditSphere uses a four-level classification taxonomy:

Label Mapping

Provider-native labels are mapped to the unified taxonomy:

• Microsoft Sensitivity Labels → unified levels
• Google Drive Labels → unified levels
• Box Classifications → unified levels

Navigate to Classification > Label Mappings to manage mappings.

Coverage

The Classification page shows how many files fall into each level across all providers, and what percentage remain unclassified.

Data Retention

Retention Policies

Define how long data should be retained based on classification:

1. Navigate to Retention > Policies
2. Create a policy with retention days, action (delete/archive/review), and applicable classification levels

Violation Detection

AuditSphere automatically detects retention violations:

Retention Dashboard

Navigate to Retention to see:

• Active policies and their configuration
• Violation list with file details, provider, and overdue days
• Per-provider compliance rate

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