### Install OPA for ScubaGear

Source: https://github.com/cisagov/scubagear/blob/main/docs/prerequisites/dependencies.md

Attempts to download and install the OPA executable if the initial setup failed or was skipped.

```powershell
# Download OPA
Install-OPAforSCuBA
```

--------------------------------

### ScubaGear Configuration Example (scuba_config.yaml)

Source: https://context7.com/cisagov/scubagear/llms.txt

This is a complete example of the scuba_config.yaml file, demonstrating various settings for a production tenant security assessment. It includes product selection, environment details, organization metadata, authentication methods, output settings, policy exclusions, annotation configurations, and specific settings for Entra ID, Defender, and Exchange Online.

```yaml
# scuba_config.yaml - Complete configuration example
Description: "Production tenant security assessment configuration"

# Products to assess
ProductNames:
  - aad
  - defender
  - exo
  - sharepoint
  - teams
  - powerplatform

# Environment type
M365Environment: commercial

# Organization metadata (required for BOD compliance)
OrgName: "Contoso Corporation"
OrgUnitName: "IT Security Division"

# Service principal authentication (optional)
Organization: "contoso.onmicrosoft.com"
AppID: "12345678-1234-1234-1234-123456789012"
CertificateThumbprint: "ABCD1234567890ABCD1234567890ABCD12345678"

# Output settings
OutPath: "C:\\ScubaReports"
OutFolderName: "M365Assessment"

# Omit policies from assessment
OmitPolicy:
  MS.EXO.4.3v1:
    Rationale: "Policy only applies to federal executive branch agencies"
    Expiration: 2025-12-31
  MS.AAD.1.2v1:
    Rationale: "Third-party MFA solution in use"

# Annotate policy results
AnnotatePolicy:
  MS.AAD.2.1v1:
    IncorrectResult: false
    Comment: "Remediation scheduled for Q2 2025"
    RemediationDate: 2025-06-30
  MS.EXO.3.1v1:
    IncorrectResult: true
    Comment: "False positive - DMARC configured via third-party"

# Entra ID (AAD) specific configuration
Aad:
  MS.AAD.1.1v1: &CapExclusions
    CapExclusions:
      Users:
        - "12345678-1234-1234-1234-123456789012"  # Emergency access account
      Groups:
        - "87654321-4321-4321-4321-210987654321"  # Break glass admin group
  MS.AAD.2.1v1: *CapExclusions
  MS.AAD.3.1v1: *CapExclusions
  MS.AAD.7.4v1:
    RoleExclusions:
      Users:
        - "abcdef01-2345-6789-abcd-ef0123456789"
      Groups: []

# Defender specific configuration
Defender:
  MS.DEFENDER.1.4v1: &SensitiveAccountFilter
    SensitiveAccounts:
      IncludedUsers:
        - "ceo@contoso.com"
        - "cfo@contoso.com"
      IncludedGroups:
        - "C-Suite Executives"
      IncludedDomains:
        - "contoso.com"
      ExcludedUsers: []
      ExcludedGroups: []
      ExcludedDomains: []
  MS.DEFENDER.1.5v1: *SensitiveAccountFilter
  MS.DEFENDER.2.1v1:
    SensitiveUsers:
      - "John Doe;jdoe@contoso.com"
      - "Jane Smith;jsmith@contoso.com"
  MS.DEFENDER.2.2v1:
    AgencyDomains:
      - "contoso.gov"
  MS.DEFENDER.2.3v1:
    PartnerDomains:
      - "trustedpartner.com"

# Exchange Online specific configuration
Exo:
  MS.EXO.1.1v2:
    AllowedForwardingDomains:
      - "subsidiary.contoso.com"

```

--------------------------------

### Install and Import ScubaGear

Source: https://context7.com/cisagov/scubagear/llms.txt

Commands to install the module from the PowerShell Gallery, verify the installation, and load it into the current session.

```powershell
# Install ScubaGear from PSGallery
Install-Module -Name ScubaGear

# Verify installation
Get-Module -ListAvailable -Name ScubaGear

# Import the module
Import-Module ScubaGear
```

--------------------------------

### Basic Configuration Example

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/configuration.md

Specify only essential parameters like ProductNames and M365Environment for a basic ScubaGear configuration.

```yaml
ProductNames: ['aad', 'defender', 'exo']
M365Environment: commercial
```

--------------------------------

### Start ScubaConfigApp Basic Usage

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

Launches the ScubaGear Configuration UI for creating and managing configuration files.

```powershell
Start-SCuBAConfigApp
```

--------------------------------

### Initialize ScubaGear Dependencies

Source: https://context7.com/cisagov/scubagear/llms.txt

Commands to install required PowerShell modules and the OPA executable. Use flags to manage scope, updates, and OPA installation.

```powershell
# Install all dependencies with default settings
Initialize-SCuBA

# Install for all users (requires admin privileges)
Initialize-SCuBA -Scope AllUsers

# Skip OPA download if already installed
Initialize-SCuBA -NoOPA

# Force reinstall of all dependencies
Initialize-SCuBA -Force

# Skip automatic updates to existing modules
Initialize-SCuBA -SkipUpdate
```

--------------------------------

### Install OPA for SCuBA

Source: https://context7.com/cisagov/scubagear/llms.txt

Downloads and installs the Open Policy Agent (OPA) executable. Supports default installation, specific versions, different operating systems, and custom installation directories.

```powershell
# Install OPA with defaults
Install-OPAforSCuBA
```

```powershell
# Install specific version
Install-OPAforSCuBA -ExpectedVersion "0.68.0"
```

```powershell
# Install for different OS
Install-OPAforSCuBA -OperatingSystem MacOS
```

```powershell
# Install to custom directory
Install-OPAforSCuBA -ScubaParentDirectory "C:\Tools"
```

--------------------------------

### Start ScubaConfigApp with Configuration Import

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

Launches the configuration UI and imports an existing YAML configuration file from the specified path.

```powershell
Start-SCuBAConfigApp -ConfigFilePath "C:\configs\myconfig.yaml"
```

--------------------------------

### Initialize ScubaGear Dependencies

Source: https://github.com/cisagov/scubagear/blob/main/README.md

Installs the minimum required dependencies for ScubaGear. This command should be run after installing the module.

```powershell
# Install the minimum required dependencies
Initialize-SCuBA
```

--------------------------------

### Install Pester Module

Source: https://github.com/cisagov/scubagear/blob/main/Testing/Readme.md

Installs the Pester testing framework module on a Windows development system.

```powershell
Install-Module -Name Pester -Force -SkipPublisherCheck
```

--------------------------------

### Brace Style Example

Source: https://github.com/cisagov/scubagear/blob/main/CONTENTSTYLEGUIDE.md

Demonstrates the One True Brace style requirement.

```Rego
test_Example_Correct if {
    Output := <Product>.tests with input as {
        "example_tag" : {
            "ExampleVar" : false
        }
    }

    TestResult("MS.<Product>.<Policy Group #>.<Policy #>v<Version #>", Output, "ReportDetailString", true) == true
}
```

--------------------------------

### Initialize ScubaGear Module

Source: https://github.com/cisagov/scubagear/blob/main/docs/prerequisites/serviceprincipal-troubleshooting.md

Run this command to install the required module for Power Platform registration. Ensure you have the necessary administrative permissions.

```powershell
Initialize-SCuBA
```

--------------------------------

### Initialize Report Page

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/EXOReport.html

Main entry point for report page initialization, including data retrieval and UI setup.

```javascript
window.addEventListener('DOMContentLoaded', () => { const MAX_DNS_ENTRIES = 20; const darkMode = getJsonData('dark-mode-flag') === "true"; const caps = getJsonData('cap-json'); const riskyApps = getJsonData('risky-apps-json'); const riskyThirdPartySPs = getJsonData('risky-third-party-sp-json'); buildExpandableTable(caps, "caps"); buildExpandableTable(riskyApps, "riskyApps"); buildExpandableTable(riskyThirdPartySPs, "riskyThirdPartySPs"); colorRows(); applyScopeAttributes(); truncateSPFList(MAX_DNS_ENTRIES); truncateDNSTables(MAX_DNS_ENTRIES); mountDarkMode(darkMode, "Individual Report"); });
```

--------------------------------

### Launch Configuration UI and Check Errors

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

Starts the configuration UI and retrieves error information if the application fails to launch.

```powershell
# Basic usage - Launch the configuration UI
$SCuBAUI = Start-SCuBAConfigApp -Passthru
$SCuBAUI.error
```

--------------------------------

### Install-OPAforSCuBA

Source: https://context7.com/cisagov/scubagear/llms.txt

Downloads and installs the Open Policy Agent (OPA) executable.

```APIDOC
## Install-OPAforSCuBA

### Description
Downloads and installs the Open Policy Agent (OPA) executable required for policy evaluation.

### Method
Not Applicable (PowerShell Cmdlet)

### Endpoint
Not Applicable (PowerShell Cmdlet)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **ExpectedVersion** (string) - Optional - Specifies the exact version of OPA to install.
- **OperatingSystem** (string) - Optional - Specifies the target operating system (e.g., 'MacOS', 'Linux', 'Windows').
- **ScubaParentDirectory** (string) - Optional - Specifies a custom parent directory where OPA will be installed.

### Request Example
```powershell
# Install OPA with defaults
Install-OPAforSCuBA

# Install specific version
Install-OPAforSCuBA -ExpectedVersion "0.68.0"

# Install for different OS
Install-OPAforSCuBA -OperatingSystem MacOS

# Install to custom directory
Install-OPAforSCuBA -ScubaParentDirectory "C:\Tools"
```

### Response
#### Success Response (200)
None (Cmdlet execution)

#### Response Example
None
```

--------------------------------

### Error: Test-ScubaGearVersion not recognized

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/update.md

This error indicates that ScubaGear is not installed or the module is not loaded. Install ScubaGear using the provided installation links or run `Import-Module ScubaGear`.

```powershell
PS C:\Users\ScubaGear> Test-ScubaGearVersion
Test-ScubaGearVersion : The term 'Test-ScubaGearVersion' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ Test-ScubaGearVersion
+ ~~~~~~~~~~~~~~~~~~~~~
   + CategoryInfo          : ObjectNotFound: (test-ScubaGearVersion:String) [], CommandNotFoundException
   + FullyQualifiedErrorId : CommandNotFoundException
```

--------------------------------

### Install and Update Selenium

Source: https://github.com/cisagov/scubagear/blob/main/Testing/Readme.md

Installs the Selenium module and updates the Chrome driver for browser automation.

```powershell
Install-Module Selenium
```

```powershell
./Testing/Functional/SmokeTest/UpdateSelenium.ps1
```

--------------------------------

### Install ScubaGear Dependencies

Source: https://github.com/cisagov/scubagear/blob/main/docs/execution/execution.md

Install the minimum required dependencies for ScubaGear to function. Run this command before invoking ScubaGear.

```powershell
# Install the minimum required dependencies
Initialize-SCuBA 
```

--------------------------------

### Verify OPA Installation

Source: https://github.com/cisagov/scubagear/blob/main/docs/prerequisites/dependencies.md

Checks the installed OPA version to ensure the executable is correctly placed and functional.

```powershell
# Navigate to the Tools folder.
# Check the OPA version
.\opa_windows_amd64.exe version
```

--------------------------------

### Verify ScubaGear Installation

Source: https://github.com/cisagov/scubagear/blob/main/README.md

Checks the installed version of ScubaGear to verify the installation. Use this command to confirm ScubaGear is ready.

```powershell
# Check the version
Invoke-SCuBA -Version
```

--------------------------------

### Install ScubaGear Module

Source: https://github.com/cisagov/scubagear/blob/main/README.md

Installs the ScubaGear module from the PowerShell Gallery. Run this in a PowerShell 5 terminal.

```powershell
# Install ScubaGear
Install-Module -Name ScubaGear
```

--------------------------------

### Initialize ScubaGear Dependencies

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/update.md

Installs missing dependencies and updates existing ones without removing modules.

```powershell
PS C:\Users\ScubaGear> Initialize-SCuBA -Scope CurrentUser
```

--------------------------------

### Simulate Migration State in JSON

Source: https://github.com/cisagov/scubagear/blob/main/docs/execution/scubacached.md

Example of modifying authentication method policy JSON to simulate different tenant migration states.

```json
"authentication_method_policy":  {
    "AuthenticationMethodConfigurations@odata.context": "https://graph.microsoft.com/beta/$metadata#policies/authenticationMethodsPolicy/authenticationMethodConfigurations%22",
    "PolicyVersion":  "1.5",
    "PolicyMigrationState":  "migrationComplete",
    "DisplayName":  null
}
```

```json
"authentication_method_policy":  {
    "AuthenticationMethodConfigurations@odata.context": "https://graph.microsoft.com/beta/$metadata#policies/authenticationMethodsPolicy/authenticationMethodConfigurations%22",
    "PolicyVersion":  "1.5",
    "PolicyMigrationState":  null,
    "DisplayName":  "Authentication Methods Policy"
}
```

```powershell
Invoke-SCuBACached -ProductNames aad -ExportProvider $false -OutPath "C:\ScubaResults\AAD_Policy_Test"
```

--------------------------------

### Start ScubaConfigApp with Graph for GCC High

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

Launches the configuration UI, enables Microsoft Graph connectivity, and targets the GCC High M365 environment.

```powershell
Start-SCuBAConfigApp -Online -M365Environment gcchigh
```

--------------------------------

### Start ScubaConfigApp with Graph Connectivity

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

Launches the configuration UI with Microsoft Graph connectivity enabled for the commercial environment. This is an interactive usage.

```powershell
Start-SCuBAConfigApp -Online
```

--------------------------------

### Invoke-SCuBACached Optional Examples

Source: https://github.com/cisagov/scubagear/blob/main/docs/execution/scubacached.md

Demonstrates re-running analysis with different report settings in cached mode, including dark mode and quiet mode for report generation.

```powershell
Invoke-SCuBACached -ProductNames * -ExportProvider $false -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24" -DarkMode
```

```powershell
Invoke-SCuBACached -ProductNames * -ExportProvider $false -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24" -Quiet
```

--------------------------------

### Invoke-SCuBACached Full Mode Example

Source: https://github.com/cisagov/scubagear/blob/main/docs/execution/scubacached.md

Runs Invoke-SCuBACached in full mode, which authenticates and exports fresh data. This is the default behavior when -ExportProvider is not explicitly set to $false.

```powershell
# Runs exactly like Invoke-SCuBA - authenticates and exports fresh data
Invoke-SCuBACached -ProductNames teams, aad -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24"
```

```powershell
# Explicitly set ExportProvider to true (same as default)
Invoke-SCuBACached -ProductNames * -ExportProvider $true -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24"
```

--------------------------------

### Copy-SCuBASampleConfigFile PowerShell Cmdlet

Source: https://context7.com/cisagov/scubagear/llms.txt

Copies sample configuration files to assist users in getting started with ScubaGear configuration. This function helps in setting up initial configuration files.

```powershell
# Copy sample configuration file
Copy-SCuBASampleConfigFile
```

--------------------------------

### ScubaGear Log Folder Path Example

Source: https://github.com/cisagov/scubagear/blob/main/docs/troubleshooting/debuglogging.md

ScubaGear indicates the location of the debug log folder at the start of a run. Debug and verbose output are written exclusively to the log file to prevent console clutter.

```text
ScubaGear logging enabled
Log folder: C:\ScubaResults\M365BaselineConformance_2026_03_11_11_18_27\DebugLogs
```

--------------------------------

### Full Configuration Reference Example

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/configuration.md

Invoke ScubaGear using a full configuration file that includes all available parameters. Unspecified or commented-out parameters will use default values, except for authentication parameters.

```powershell
# Invoke with full configuration reference
Invoke-SCuBA -ConfigFilePath full_config.yaml
```

--------------------------------

### Copy Sample Configuration Files

Source: https://context7.com/cisagov/scubagear/llms.txt

Copies sample configuration files to the default location or a specified directory.

```powershell
Copy-SCuBASampleConfigFile
```

```powershell
Copy-SCuBASampleConfigFile -DestinationDirectory "C:\MyConfigs"
```

--------------------------------

### Start-SCuBAConfigApp

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/scubaconfigapp.md

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

```APIDOC
## Start-SCuBAConfigApp

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

### Method
Cmdlet

### Endpoint
N/A (PowerShell Cmdlet)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **ConfigFilePath** (String) - Optional - Path to existing YAML configuration file to import
- **Language** (String) - Optional - UI language (localization). Default: "en-US"
- **Online** (Switch) - Optional - Enable Microsoft Graph connectivity. Default: False
- **M365Environment** (String) - Optional - Target M365 environment (commercial, gcc, gcchigh, dod). Default: "commercial"
- **Passthru** (Switch) - Optional - Return the configuration objects. Default: False

### Request Example
```powershell
# 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
```

### Response
#### Success Response (Object)
- **GeneralSettings** (Object) - General configuration settings.
- **AdvancedSettings** (Object) - Advanced configuration settings.
- **GlobalSettings** (Object) - Global configuration settings.
- **Exclusions** (Array) - List of policy exclusions.
- **Annotations** (Array) - List of annotations.
- **Omissions** (Array) - List of policy omissions.

#### Response Example
```json
{
  "GeneralSettings": {
    "TenantId": "your-tenant-id",
    "DisplayName": "Your Display Name",
    "Description": "Your Description"
  },
  "AdvancedSettings": {
    "OutputPath": "C:\\ScubaGearOutput",
    "AuthenticationType": "OAuth2"
  },
  "GlobalSettings": {
    "Products": ["Exchange Online", "SharePoint Online"]
  },
  "Exclusions": [],
  "Annotations": [],
  "Omissions": []
}
```
```

--------------------------------

### Generate ScubaGear Configuration with Pre-set Values

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/configuration.md

Generates a sample configuration file with pre-populated organization and product name values. This cmdlet allows for initial setup of specific parameters.

```powershell
# Create config with pre-set values
New-SCuBAConfig -Organization "example.onmicrosoft.com" -ProductNames "aad,defender"
```

--------------------------------

### Preview Service Principal Creation

Source: https://github.com/cisagov/scubagear/blob/main/docs/prerequisites/serviceprincipal-workflows.md

Use the WhatIf parameter to test the creation of a new service principal without making actual changes. This helps in reviewing the intended app registration, permissions, role assignments, and certificate details.

```powershell
New-ScubaGearServicePrincipal `
    -M365Environment commercial `
    -ProductNames 'aad', 'exo', 'sharepoint', 'teams', 'defender', 'powerplatform' `
    -WhatIf
```

--------------------------------

### Test Product Combinations with Cached Data

Source: https://github.com/cisagov/scubagear/blob/main/docs/execution/scubacached.md

Demonstrates exporting full data and running analysis on specific product subsets.

```powershell
Invoke-SCuBACached -ProductNames * -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24"
```

```powershell
Invoke-SCuBACached -ProductNames teams, aad -ExportProvider $false -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24"
```

```powershell
Invoke-SCuBACached -ProductNames exo, defender -ExportProvider $false -OutPath "C:\ScubaResults\M365BaselineConformance_2025_09_22_10_19_24"
```

--------------------------------

### Locate Pester Installation

Source: https://github.com/cisagov/scubagear/blob/main/Testing/Readme.md

Run this command to identify the file system path of the currently installed Pester module for manual removal.

```PowerShell
(GetInstalledModule -Name Pester).InstalledLocation
```

--------------------------------

### Manage Frontend Initialization and Utilities

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/BaselineReports.html

JavaScript functions for DOM interaction, data parsing, and session-based dark mode management.

```javascript
window.addEventListener('DOMContentLoaded', () => {
	const darkMode = getJsonData('dark-mode-flag') === "true";
	applyScopeAttributes();
	mountDarkMode(darkMode, "Parent Report");
});

/**
 * Retrieves JSON data derived from the text content of a <script> element with the specified ID.
 *
 * @param {string} id The ID of the <script> element.
 * @returns {any} The parsed JSON data.
 * @throws {Error} If the element with the specified ID is not found or if the JSON parsing fails.
 */
const getJsonData = (id) => {
	const el = document.getElementById(id);
	if (!el) throw new Error(`Element with id "${id} not found`);
	try {
		return JSON.parse(el.textContent);
	} catch (error) {
		throw new Error(`Failed to parse JSON from element with id "${id}": ${error.message}`);
	}
}

/**
 * Ensures the input value is returned as an array.
 *
 * @param {any} val The value to normalize.
 * @returns {Array} The normalized array.
 */
const normalizeToArray = (val) => Array.isArray(val) ? val : (val ? [val] : []);

/**
 * Parse .NET JSON date: /Date(1675800895000)/ -> Date
 *
 * @param {string} val
 * @returns {Date|null} The parsed date or null if parsing fails.
 */
const parseDotNetDate = (val) => {
	if (typeof val !== "string") return null;
	const match = val.match(/^\/Date\((-?\d+)(?:\[+-\]\d{4})?\)\/$/);
	if (!match) return null;
	const date = new Date(parseInt(match[1], 10));
	return isNaN(date) ? null : date;
};

/**
 * Checks if Dark Mode session storage variable exists. Creates one if it does not exist.
 * Sets the report's default Dark Mode state using the $DarkMode (JavaScript darkMode) PowerShell variable.
 * @param {boolean} darkMode The default dark mode state.
 * @param {string} pageLocation The page where this function is called.
 */
const mountDarkMode = (darkMode, pageLocation) => {
	try {
		let darkModeCookie = sessionStorage.getItem("darkMode");
		if (darkModeCookie === undefined || darkModeCookie === null) {
			if (darkMode) {
				sessionStorage.setItem("darkMode", 'true');
			} else {
				sessionStorage.setItem("darkMode", 'false');
			}
			darkModeCookie = sessionStorage.getItem("darkMode");
		}
		setDarkMode(darkModeCookie);
		document.getElementById('toggle').checked = (darkModeCookie === 'true');
	} catch (error) {
		console.error("Error applying dark mode to the " + pageLo
```

--------------------------------

### Install Specific ScubaGear Version

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/psgallery.md

Install a particular version of ScubaGear by specifying the version number with the -RequiredVersion parameter. Ensure you are using PowerShell 5.

```powershell
# Install ScubaGear 1.7.1
Install-Module -Name ScubaGear \
  -RequiredVersion 1.7.1
```

--------------------------------

### Example DMARC Record Response

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/baselines/exo.md

This is an example of a DMARC TXT record response, indicating the policy for handling emails that fail SPF/DKIM checks and where to send aggregate and failure reports.

```text
v=DMARC1; p=reject; pct=100; rua=mailto:reports@dmarc.cyber.dhs.gov, mailto:reports@example.com; ruf=mailto:reports@example.com
```

--------------------------------

### OPA Rego Test Case Example

Source: https://github.com/cisagov/scubagear/blob/main/CONTENTSTYLEGUIDE.md

Example of an OPA Rego test case following the `test_mainVar_In/correct_*V#` naming convention. Use this structure for defining tests that verify policy logic.

```rego
test_ExampleVar_Correct_V1 if {
    Output := <Product>.tests with input as {
        "example_policies" : [
            {
                "Example3" : "ExampleString",
                "Example2" : false
            }
        ]
    }

    TestResult("MS.<Product>.<Policy Group #>.<Policy #>v<Version #>", Output, "ReportDetailString", true) == true
}
```

```rego
test_ExampleVar_Correct_V2 if {
    ...
}
```

```rego
test_ExampleVar_Incorrect if {
    Output := <Product>.tests with input as {
        "example_policies" : [
            {
                "Example3" : "ExampleString",
                "Example2" : true
            }
        ]
    }

    TestResult("MS.<Product>.<Policy Group #>.<Policy #>v<Version #>", Output, "ReportDetailString", false) == true
}
```

```rego
test_ExampleVar_UnknownReportString_Incorrect if {
    Output := <Product>.tests with input as {
        "example_policies" : [
            {
                "Example3" : "ExampleString",
                "Example2" : true
            }
        ]
    }

    ReportDetailArrayStrs := [
        "Part of string",
        "Second part",
        "Third part"
    ]
    TestResultContains("MS.<Product>.<Policy Group #>.<Policy #>v<Version #>", Output, ReportDetailArrayStrs, false) == true
}
```

--------------------------------

### Update-ScubaGear

Source: https://context7.com/cisagov/scubagear/llms.txt

Updates ScubaGear to the latest version, removing old versions and cleaning up installations.

```APIDOC
## Update-ScubaGear

### Description
Updates ScubaGear to the latest version, removing old versions and cleaning up installations.

### Parameters
#### Query Parameters
- **Source** (string) - Optional - The source to update from (e.g., GitHub).
- **Scope** (string) - Optional - The installation scope (e.g., AllUsers).
```

--------------------------------

### Initialize UI and Load Data

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/SharePointReport.html

Sets up the UI by building expandable tables for various data types and applying scope attributes. It also truncates DNS entries and tables to a maximum limit. This function is typically called after the DOM is fully loaded.

```javascript
window.addEventListener('DOMContentLoaded', () => {
    const MAX_DNS_ENTRIES = 20;
    const darkMode = getJsonData('dark-mode-flag') === "true";
    const caps = getJsonData('cap-json');
    const riskyApps = getJsonData('risky-apps-json');
    const riskyThirdPartySPs = getJsonData('risky-third-party-sp-json');
    buildExpandableTable(caps, "caps");
    buildExpandableTable(riskyApps, "riskyApps");
    buildExpandableTable(riskyThirdPartySPs, "riskyThirdPartySPs");
    colorRows();
    applyScopeAttributes();
    truncateSPFList(MAX_DNS_ENTRIES);
    truncateDNSTables(MAX_DNS_ENTRIES);
    mountDarkMode(darkMode, "Individual Report");
});
```

--------------------------------

### Test-ScubaGearVersion

Source: https://context7.com/cisagov/scubagear/llms.txt

Checks the installed ScubaGear version against the latest available version and validates dependency status.

```APIDOC
## Test-ScubaGearVersion

### Description
Checks the installed ScubaGear version against the latest available version and validates dependency status.

### Parameters
#### Query Parameters
- **CheckGitHub** (switch) - Optional - If set, checks GitHub releases for the latest version.
```

--------------------------------

### Render Advanced Key-Value List

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/SharePointReport.html

Initializes the UI wrapper, search controls, and grouping options for displaying metadata.

```javascript
const renderAdvancedKeyValueList = (listItems, dataType) => { const wrapper = document.createElement("div"); wrapper.classList.add("kv-advanced"); const controls = document.createElement("div"); controls.classList.add("kv-controls"); wrapper.appendChild(controls); const searchInput = document.createElement("input"); searchInput.type = "search"; searchInput.id = "modal-search"; searchInput.placeholder = "Search..."; controls.appendChild(searchInput); // The option to group by is only present for permissions. Credentials only has "active"/"expired" fields. let groupSelect = null; if (dataType === "Permissions") { const selectLabel = document.createElement("label"); selectLabel.htmlFor = "modal-group-by"; selectLabel.textContent = " Group by"; controls.appendChild(selectLabel); groupSelect = document.createElement("select"); groupSelect.id = "modal-group-by"; const groupOptions = [ { value: "none", label: "None" }, { value: "RoleType", label: "Role type" }, { value: "IsAdminConsented", label: "Admin consent" }, { value: "IsRisky", label: "Risk" } ]; groupOptions.forEach(o => { const option = document.createElement("option"); option.value = o.value; option.textContent = o.label; groupSelect.appendChild(option); }); controls.appendChild(groupSelect); } const state = { search: "", groupBy: "none", dataType: dataType, }; const resultList = document.createElement("div"); resultList.classList.add("kv-results"); wrapper.appendChild(resultList); searchInput.addEventListener("input", e => { state.search = e.target.
```

--------------------------------

### Update ScubaGear via GitHub

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/update.md

Downloads and installs the latest ScubaGear release directly from GitHub.

```powershell
PS C:\Users\ScubaGear> Update-ScubaGear -Source GitHub
```

```powershell
PS C:\Users\ScubaGear> Update-ScubaGear -Source GitHub
Updating ScubaGear from GitHub...
Removing all existing ScubaGear versions...
Downloading ScubaGear 1.6.0 from GitHub...
Installing ScubaGear 1.6.0...
ScubaGear 1.6.0 installed successfully from GitHub
```

--------------------------------

### Determine Credential State

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/DefenderReport.html

Calculates the status of a credential based on its start and end date-time properties.

```javascript
const getCredentialState = (cred) => { if (!cred || typeof cred !== "object") return "Unknown"; const start = parseDotNetDate(cred.StartDateTime); const end = parseDotNetDate(cred.EndDateTime); const now = new Date(); if (start && end) { if (now < start) return "Inactive"; if (now > end) return "Expired"; return "Active"; } if (end && now > end) return "Expired"; return "Active"; };
```

--------------------------------

### Render Summary List

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/AADReport.html

Builds an unordered list summarizing data, such as credentials or permissions counts. It creates a list with labels and their corresponding values. This function is intended for specific columns like 'KeyCredentials' and 'Permissions'.

```javascript
const renderSummaryList = (colName, items) => {
  const count = items.length;
  const makeUl = () => {
    const ul = document.createElement("ul");
    ul.className = "summary-list";
    return ul;
  };
  const addItem = (ul, label, value) => {
    const li = document.createElement("li");
    const strong = document.createElement("strong");
    strong.textContent = `${label}`;
    li.appendChild(strong);
    li.appendChild(document.createTextNode(` ${String(value)}`));
    ul.appendChild(li);
  };
  if (colName === "KeyCredentials" || c
```

--------------------------------

### Update ScubaGear via PSGallery

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/update.md

Removes existing versions and installs the latest ScubaGear module from PSGallery.

```powershell
PS C:\Users\ScubaGear> Update-ScubaGear
Updating ScubaGear from PSGallery...
Removing all existing ScubaGear versions...
Installing latest ScubaGear from PSGallery...
ScubaGear updated to version 1.6.0
```

--------------------------------

### Launch ScubaGear Configuration UI

Source: https://github.com/cisagov/scubagear/blob/main/docs/configuration/configuration.md

Use this command to launch the graphical Configuration UI for creating and managing ScubaGear configuration files. This is the recommended method for users preferring a visual interface.

```powershell
# Launch the Configuration UI
Start-SCuBAConfigApp
```

--------------------------------

### Run UninstallModules.ps1 Script

Source: https://github.com/cisagov/scubagear/blob/main/docs/installation/uninstall.md

Execute this PowerShell script located in the 'utils' folder to remove installed modules.

```powershell
# Uninstall modules
.\UninstallModules.ps1
```

--------------------------------

### Render Advanced Key-Value List

Source: https://github.com/cisagov/scubagear/blob/main/PowerShell/ScubaGear/Sample-Reports/IndividualReports/EXOReport.html

Initializes the UI wrapper, search controls, and grouping options for displaying complex metadata lists.

```javascript
const renderAdvancedKeyValueList = (listItems, dataType) => { const wrapper = document.createElement("div"); wrapper.classList.add("kv-advanced"); const controls = document.createElement("div"); controls.classList.add("kv-controls"); wrapper.appendChild(controls); const searchInput = document.createElement("input"); searchInput.type = "search"; searchInput.id = "modal-search"; searchInput.placeholder = "Search..."; controls.appendChild(searchInput); // The option to group by is only present for permissions. Credentials only has "active"/"expired" fields. let groupSelect = null; if (dataType === "Permissions") { const selectLabel = document.createElement("label"); selectLabel.htmlFor = "modal-group-by"; selectLabel.textContent = " Group by"; controls.appendChild(selectLabel); groupSelect = document.createElement("select"); groupSelect.id = "modal-group-by"; const groupOptions = [ { value: "none", label: "None" }, { value: "RoleType", label: "Role type" }, { value: "IsAdminConsented", label: "Admin consent" }, { value: "IsRisky", label: "Risk" } ]; groupOptions.forEach(o => { const option = document.createElement("option"); option.value = o.value; option.textContent = o.label; groupSelect.appendChild(option); }); controls.appendChild(groupSelect); } const state = { search: "", groupBy: "none", dataType: dataType, }; const resultList = document.createElement("div"); resultList.classList.add("kv-results"); wrapper.appendChild(resultList); searchInput.addEventListener("input", e => { state.search = e.target.va
```

--------------------------------

### Reset-ScubaGearDependencies

Source: https://context7.com/cisagov/scubagear/llms.txt

Manages ScubaGear dependencies by installing missing modules, updating outdated modules, and cleaning up multiple versions.

```APIDOC
## Reset-ScubaGearDependencies

### Description
Manages ScubaGear dependencies by installing missing modules, updating outdated modules, and cleaning up multiple versions.

### Parameters
#### Query Parameters
- **Scope** (string) - Optional - The installation scope (e.g., AllUsers).
- **WhatIf** (switch) - Optional - Preview changes without making them.
- **Confirm** (switch) - Optional - Confirm each action.
```

--------------------------------

### Uninstall Pester Module

Source: https://github.com/cisagov/scubagear/blob/main/Testing/Readme.md

Use this command to remove all existing versions of the Pester module when encountering installation conflicts.

```PowerShell
Uninstall-Module -Name Pester -Force -AllVersions
```

--------------------------------

### Manage ScubaGear Application Permissions

Source: https://github.com/cisagov/scubagear/blob/main/docs/prerequisites/serviceprincipal-troubleshooting.md

This example demonstrates how to set specific application permissions for ScubaGear, enforcing least privilege by only including permissions for the 'aad' product. Permissions for other products like SharePoint or Exchange will be removed.

```powershell
# Example: You originally set up for all products
New-ScubaGearServicePrincipal -ProductNames '*'

# Now you only need AAD - extra permissions will be removed (SharePoint, Exchange, etc.)
Get-ScubaGearAppPermission -AppID $AppID -ProductNames 'aad' | Set-ScubaGearAppPermission
```

--------------------------------

### OPA: Correctly assign `ActualValue`

Source: https://github.com/cisagov/scubagear/blob/main/CONTENTSTYLEGUIDE.md

For consistency and best practice, assign `ExampleVar.ExampleSetting` to `ActualValue` instead of a status variable when a boolean is anticipated.

```rego
tests contains {
    "PolicyId" : "MS.<Product>.<Policy Group #>.<Policy #>v<Version #>",,
    "Criticality" : "Should",
    "Commandlet" : "Example-Command",
    "ActualValue" : ExampleVar.ExampleSetting,
    "ReportDetails" : ReportDetailsBoolean(Status),
    "RequirementMet" : Status
} if {
    ExampleVar := input.example_var
    Status := ExampleVar == true
}
```