DOCSEARCHbyAlgolia
Submit Docs

ScubaGear Documentation

repository·main·Indexed 25 days ago

https://github.com/cisagov/scubagear

An assessment tool for Microsoft 365 administrators to verify tenant configurations against CISA's Secure Cloud Business Applications (SCuBA) Secure Configuration Baselines. It features a PowerShell module for querying M365 APIs, comparing settings via Open Policy Agent (OPA) Rego policies, and generating reports in HTML, JSON, and CSV formats. Includes a configuration UI, machine-readable ScubaBaselines.json asset packages, and support for service principal authentication.

Tokens
65.1K
Snippets
125
Records
350
Agent score
80%

What's inside ScubaGear

  1. Overview of ScubaGear assessment process

    main

    ScubaGear follows a three-step assessment process:

    1. Query: PowerShell code queries M365 APIs for configuration settings.
    2. Compare: Calls Open Policy Agent (OPA) to compare settings against Rego security policies.
    3. Report: Generates results in HTML, JSON, and CSV formats.

  2. Understand CISA M365 Secure Configuration Baseline for Power Platform

    main

    The CISA M365 Secure Configuration Baseline (SCB) for Power Platform provides specific security policies to help secure Microsoft 365 Power Platform environments. These baselines are designed to help federal civilian executive branch (FCEB) agencies protect federal information, though they are also useful for non-federal organizations.

    Key components covered in this baseline include:

    • Power Apps: Canvas Apps, Model-Driven Apps, and Power Pages.
    • Power Automate: Automated workflows between apps and services.
    • Power Virtual Agents: Custom chat bots.
    • Connectors: API proxies for accessing services.
    • Microsoft Dataverse: Cloud database management system.

    Policies in this document are marked with indicators:

    • BOD 25-01 Requirement: Required under CISA BOD 25-01.
    • Automated Check: Can be automatically verified using ScubaGear.
    • Manual: Requires manual verification of settings.

  3. Understand the ScubaBaselines.json Asset Package Schema

    main

    The ScubaBaselines.json file is a machine-readable representation of the authoritative SCuBA (Secure Cloud Business Applications) security configuration baselines. It is used by tools, scripts, and applications to programmatically access security controls.

    Note: The markdown baseline files are the authoritative source; the JSON is an equivalent representation for machine consumption.

    Schema Version: 1.0.0 File Location: PowerShell/ScubaGear/schemas/ScubaBaselines.json

  4. Understand the CISA M365 Secure Configuration Baseline for Defender

    main

    The CISA M365 Secure Configuration Baseline (SCB) for Defender provides guidance for securing Microsoft 365 Defender and Defender for Office 365. This baseline is designed to help federal civilian executive branch (FCEB) agencies protect federal information assets through consistent and manageable security configurations.

    While primarily focused on Defender for Office 365, the baseline also includes settings configured in the Microsoft Purview portal. Agencies using Defender as their primary security tool should apply these settings, noting that some core M365 baselines (Exchange Online, Teams, etc.) may require a dedicated security tool comparable to Defender to achieve full compliance.

  5. Understand ScubaGear terminology and indicators

    main

    When reviewing ScubaGear baseline documents, several indicators describe how a policy is handled:

    • Automated Check: The policy can be automatically verified using ScubaGear.
    • Configurable: The policy can be customized via a configuration file.
    • Manual: The policy requires manual verification of settings.
    • BOD 25-01 Requirement: Indicates the policy is required under CISA BOD 25-01.
    • Resource Tenant & Home Tenant: In guest user scenarios, the resource tenant hosts the target resources, while the home tenant hosts the guest user's identity.
    • Microsoft Entra ID hybrid: A scenario where an on-premises Windows Server Active Directory federates access to a cloud M365 Microsoft Entra ID tenant.

  6. Understand the ScubaConfigApp Data Flow

    main

    The ScubaConfigApp follows a specific lifecycle from launch to YAML generation and execution.

    1. Initialization: The app loads a JSON control configuration and initializes a shared hashtable (syncHash). If the -Online switch is used, it connects to Microsoft Graph via Connect-MgGraph for user, group, and certificate lookups.
    2. Baseline Loading: Baselines are loaded either from a local ScubaBaselines.json file or downloaded from the OnlineBaselineSchemaURL based on the PullOnlineBaselines setting.
    3. Configuration (WPF UI): Users configure settings across several tabs:
      • Main: Organization, Products, and M365 Environment (syncHash.GeneralSettingsData).
      • Advanced: App auth, output paths, and OPA path (syncHash.AdvancedSettingsData).
      • Global Settings: DNS resolvers and DoH (syncHash.GlobalSettingsData).
      • Exclusions: Per-product policy exclusions (syncHash.ExclusionData).
      • Annotations: AnnotatePolicy entries (syncHash.AnnotationData).
      • Omissions: OmitPolicy entries (syncHash.OmissionData).
    4. Import & Migration: Users can import existing YAML. If legacy policy IDs are detected, the app performs a migration using a CSV cache (PolicyMigrationsCSVPath) and the Invoke-PolicyMigration function. Results are logged to syncHash.MigrationLog and displayed in a report popup.
    5. Generation & Execution: The app builds a YAML string using ConvertTo-Yaml, allows previewing, and then generates a temporary YAML file in the env:TEMP directory. This file is used to launch a PowerShell 5.1 process that runs Invoke-Scuba via the ScubaGear module.
    6. Results: ScubaGear writes results to the OutPath, which the app then reads and displays in the Results Reader tab.

  7. Understand CISA M365 Secure Configuration Baseline for Exchange Online

    main

    The CISA M365 Secure Configuration Baseline (SCB) for Exchange Online provides specific security policies designed to strengthen the security of Microsoft 365 Exchange Online environments. These baselines are tailored to federal government threat models and risk tolerances, though they are useful for non-federal organizations as well.

    Key Concepts:

    • BOD 25-01 Requirement: Indicates the policy is required under CISA Binding Operational Directive 25-01.
    • Automated Check: Indicates the policy can be automatically verified using ScubaGear.
    • Configurable: Indicates the policy can be customized via a ScubaGear configuration file.
    • Manual: Indicates the policy requires manual verification of settings.

    Prerequisites:

    • Many security functions (like Data Loss Prevention) require Defender for Office 365 Plan 1 or 2 (included in E5/G5, or available as add-ons for E3/G3).

  8. Verify M365 license requirements for ScubaGear policy checks

    main

    ScubaGear is tested against Microsoft 365 tenants with E3/G3 or E5/G5 license bundles.

    Certain policy checks in the baselines require specific licenses that are included by default in M365 E5 and G5, such as:

    • Microsoft Entra ID P2
    • Microsoft Defender for Office 365 Plan 1 or 2

    If you are using a tenant without these bundles, check the "License Requirements" section of the specific control to see if it requires additional licensing.

    Note on DOD endpoints: While DOD endpoints are included, they have not been formally tested. If you encounter bugs when using DOD endpoints, please open an issue in the repository.

  9. Access ScubaGear security baselines

    main

    Security baselines for various Microsoft services are distributed as part of the ScubaGear PowerShell module. You can access individual baseline documentation directly via the following paths within the repository:

    • Microsoft Entra ID: ../PowerShell/ScubaGear/baselines/aad.md
    • Exchange Online: ../PowerShell/ScubaGear/baselines/exo.md
    • Power BI: ../PowerShell/ScubaGear/baselines/powerbi.md
    • Power Platform: ../PowerShell/ScubaGear/baselines/powerplatform.md
    • Security Suite: ../PowerShell/ScubaGear/baselines/securitysuite.md
    • SharePoint & OneDrive: ../PowerShell/ScubaGear/baselines/sharepoint.md
    • Teams: ../PowerShell/ScubaGear/baselines/teams.md
    • Removed Policies: ../PowerShell/ScubaGear/baselines/removedpolicies.md

  10. Understand ScubaGear report behavior and execution

    main

    When using the ScubaConfigApp UI, keep the following behaviors in mind:

    • Execution Monitoring: ScubaGear runs as a background process. Do not close the UI during execution, or the assessment will be terminated.
    • Report Tabs: Tabs are generated dynamically. If no results are found for a specific product, no tab will be created for it.
    • Report Refresh: Changes to configurations do not automatically update existing reports. You must re-run the ScubaGear assessment to see updated results.
    • Native Viewer: The WPF report viewer may display content differently than the standard HTML reports generated by the CLI.

  11. Understand removed CISA M365 Secure Configuration Baseline Policies

    main

    This document tracks policies that have been removed from the CISA M365 Secure Configuration Baselines (SCBs).

    Important Note: The removal of a policy from the baselines does not necessarily mean the recommended configuration should not be used. Users should review the specific "Removal rationale" provided for each removed policy in the full documentation to determine the appropriate course of action.

    These baselines are designed to help secure federal civilian executive branch (FCEB) agencies' cloud business application environments, though they can serve as useful references for non-federal organizations.

  12. Understand the CISA M365 Secure Configuration Baseline for Teams

    main

    The CISA M365 Secure Configuration Baseline (SCB) for Teams provides specific policies to strengthen the security of Microsoft Teams environments. These baselines are tailored to federal government threats and risk tolerance, though they are useful for non-federal organizations as well.

    Key Implementation Details

    • Admin Controls: Most controls are managed via the Teams admin center.
    • Security Functions: Essential functions like Data Loss Prevention (DLP) require dedicated security tools. While M365 provides these via Defender for Office 365 (included in E5/G5 or available as add-ons for E3/G3), third-party solutions can be used instead.
    • License Assumptions: The baseline assumes a minimum of an M365 E3 or G3 license. Only features/settings requiring higher license levels are explicitly listed in the baseline documentation.