View on GitHub

ScubaGear

Automation to assess the state of your M365 tenant against CISA's baselines

ScubaConfigApp Module

The ScubaConfigApp is a PowerShell-driven UI built with Windows Presentation Framework. It’s not an executable—it’s lightweight, portable, and supports any Microsoft OS with graphical UI.

Overview

ScubaConfigApp module contains these elements:

ScubaGear Assessment Process Diagram

Main Function

Start-SCuBAConfigApp

Opens the ScubaGear Configuration UI for creating and managing configuration files, executing ScubaGear assessments, and viewing results with native report viewers.

Syntax

Start-SCuBAConfigApp [[-ConfigFilePath] <String>] [[-Language] <String>] [-Online] [[-M365Environment] <String>] [-Passthru]

Parameters

Parameter Type Description Default
ConfigFilePath String Path to existing YAML configuration file to import None
Language String UI language (localization) “en-US”
Online Switch Enable Microsoft Graph connectivity False
M365Environment String Target M365 environment (commercial, gcc, gcchigh, dod) “commercial”
Passthru Switch Return the configuration objects False

Examples:

# Basic usage - Launch the configuration UI
Start-SCuBAConfigApp

# Launch with Graph connectivity for commercial environment (Interactive)
Start-SCuBAConfigApp -Online

# Import existing configuration
Start-SCuBAConfigApp -ConfigFilePath "C:\configs\myconfig.yaml"

# Launch and connect to graph for GCC High environment
Start-SCuBAConfigApp -Online -M365Environment gcchigh

#Use Passthru with a variable to retrieve all configurations in hashtables
$SCuBAUI = Start-SCuBAConfigApp -Passthru
#retrieving data
$SCuBAUI.GeneralSettings | ConvertTo-Json
$SCuBAUI.AdvancedSettings | ConvertTo-Json
$SCuBAUI.GlobalSettings | ConvertTo-Json
$SCuBAUI.Exclusions | ConvertTo-Json -Depth 4
$SCuBAUI.Annotations | ConvertTo-Json -Depth 4
$SCuBAUI.Omissions | ConvertTo-Json -Depth 4

Features

Configuration Management

User Interface

File Operations

ScubaGear Execution

Report Summary

Usage Workflow

Follow this step-by-step guide to use the ScubaConfigApp for configuration creation, ScubaGear execution, and report review:

Step 1. Launch the Application

Start-SCuBAConfigApp

Step 2. Configure Organization Information

Step 3. Select Products for Assessment

Navigate to the “Products” tab:

Step 4. Configure Exclusions

In the “Exclusions” tab:

Step 5. Add Annotations

In the “Annotations” tab:

Step 6. Add Omissions

In the “Omissions” tab:

Step 7. Set Advanced Settings

In the “Advanced” tab:

Step 8. Review Configuration Preview

Click “Preview & Generate” to enable the preview tab and generate the YAML file. This should automatically navigate to the “Preview” tab:

[!IMPORTANT] Be sure to click the “Preview & Generate” when done making updates to pull those changed into yaml output. Clicking on the Preview tab won’t show the update

Step 9. Save Configuration

Click “Save YAML”:

Step 10. Execute ScubaGear Assessment

Step 11. Monitor Execution Progress

While ScubaGear runs:

Step 12. Review Report Summary

Once execution completes:

Step 13. Analyze Results and Take Action

For each product report:

ScubaGear Assessment Process Diagram

Run ScubaGear Feature

The integrated ScubaGear execution feature allows you to run assessments directly from the UI without manual command-line operations.

Execution Process

  1. Pre-Execution Validation: The UI validates your configuration before starting
  2. ScubaGear Invocation: Automatically calls Invoke-SCuBA with your settings
  3. Progress Tracking: Real-time output display with status updates
  4. Completion Handling: Automatic report loading and tab generation
  5. Error Management: Clear error messages and troubleshooting guidance

Requirements for Execution

Output Monitoring

During execution, you’ll see:

Report Summary Feature

The native WPF report viewer provides a modern, integrated experience for reviewing ScubaGear assessment results.

Status Badge System

Each policy displays a colored status badge indicating compliance level:

Badge Color Status Meaning
Green Pass Policy meets compliance requirements
Yellow Warning Policy needs attention or has minor issues
Red Failure Policy fails compliance requirements
Blue Manual Policy requires manual review or verification
Gray Error/N/A Policy has errors or is not implemented

Report Navigation

Integration with ScubaGear

The configurations created by this UI are fully compatible with the main ScubaGear assessment tool:

# Use the generated configuration
Invoke-SCuBA -ConfigFilePath "path\to\generated\example.onmicrosoft.com.yaml"

Module Files

Core Files

Configuration Files

Requirements

Troubleshooting

Debug Configuration

Use debug window to get detailed information about:

Enabling Debug Mode

This is enabled by default. However if your not seeing the debug button, follow these steps:

  1. Edit ScubaConfigApp\ScubaConfigApp_Control_en-US.json in the module directory.
  2. Change "DebugMode": true to enable.
  3. Restart the UI application. There will be a debug button in the bottom right corner.

Example:

{
  "DebugMode": true,
  ...
}

The Debug Window displays detailed diagnostic information, but it is not intended for end users to troubleshoot issues on their own. Instead, it is recommended to:

[!IMPORTANT] A Sanitize option is available to replace sensitive data with placeholder values.

ScubaGear Debug Window

Common Issues

Issues / Troubleshooting / Workarounds

Run ScubaGear and Report Summary Notes

Development

Adding Localization

  1. Create new configuration file following naming pattern: ScubaConfigApp_Control_<locale>.json
  2. Translate all text elements in the localeContext section
  3. Create new baseline configuration file following naming pattern: ScubaBaselines_<locale>.json
  4. Translate text elements: name, rationale for each baseline item
  5. Set PullOnlineBaselines:false within the ScubaConfigApp_Control_en-US.json app configuration file
  6. Update root module (ScubaConfigApp.psm1) to support new locale.