# compliantsec/m365sat architecture

> Architecture diagram of the GitHub repository compliantsec/m365sat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/compliantsec/m365sat
- Repository: https://github.com/compliantsec/m365sat

## Overview

##### Project Type and Purpose
- M365SAT is an open-source, modular PowerShell-based security assessment tool for Microsoft 365 and Azure.
- It exposes a CLI entrypoint (`M365SATTester.ps1` and `Get-M365SATReport`) that orchestrates authentication, module loading, inspections, and report generation across M365 workloads.

##### File Structure
- Top-level scripts & manifests:
- `M365SAT.psd1` / `.psm1` (PowerShell module definitions)
- `M365SATTester.ps1` (CLI orchestration)
- Core engine (`/core`):
- Core cmdlets (Connect, Invoke checks, logging, update modules, CSV/HTML report builders)
- Authentication Connectors (`/core/m365connectors`)
- Inspector modules (`/inspectors`):
- Organized by environment (AZURE, M365, CUSTOM) → product family → license level → L1/L2 checks
- Each `.ps1` implements a standard Audit-Build pattern returning PSCustomObject
- Support directories:
- `modules/welcome` (welcome banner)
- `log` (runtime logs)
- docs & metadata (README, LICENSE, SECURITY, TODO)

##### Extract Key Architecture Insights from README
- Modular/plugin architecture: new inspectors are simply new scripts under `/inspectors`
- Core engine orchestrates scanning, error handling (PoShLog), and report formatting (HTML/CSV)
- Connects to external services via PowerShell modules (Az, ExchangeOnlineManagement, Microsoft.Graph, PnP.PowerShell)

##### Components & Interactions
a. Main Components
- CLI Launcher: `M365SATTester.ps1` or `Get-M365SATReport`
- Core Orchestrator Module: loads configurations, update checks, duplicate checks
- Authentication Connectors: Azure, Exchange, Graph, Teams, SharePoint
- Inspector Plugin Layer: folder of PowerShell inspector scripts
- Reporting Engine: CSV/HTML builders
- Logging Service: PoShLog integration writing to `/log`
- Output: Report files on disk
- External Systems: Microsoft 365 Tenant, Azure APIs
b. Relationships & Data Flow
1. User invokes CLI → CLI Launcher
2. CLI Launcher calls Core Orchestrator
3. Core Orchestrator establishes connections via Authentication Connectors
4. Core Orchestrator loads Inspector Plugins dynamically
5. For each plugin: execute audit → return PSCustomObject
6. Core collects all results → Reporting Engine
7. Reporting Engine writes CSV/HTML; Logging Service writes logs
c. Architectural Patterns & Principles
- Plugin/Extension pattern: inspectors are discovered at runtime
- Single Responsibility: core handles orchestration, connectors handle auth, inspectors handle checks, reporting handles output
- Dependency on external PS modules abstracted via connectors
d. Key Technologies & Frameworks
- PowerShell 5.1 / 7
- PoShLog
- Az PowerShell modules
- ExchangeOnlineManagement, PnP.PowerShell, Microsoft.Graph, MicrosoftTeams

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Launcher
    CLI["CLI Launcher\n(M365SATTester.ps1)"]:::cli
    click CLI "https://github.com/compliantsec/m365sat/blob/production/M365SATTester.ps1"

    %% Welcome Banner
    WB["Welcome Banner\n(Invoke-M365SATBanner)"]:::welcome
    click WB "https://github.com/compliantsec/m365sat/blob/production/modules/welcome/Invoke-M365SATBanner.ps1"

    %% PowerShell Module Definitions
    PSD1["M365SAT.psd1"]:::definitions
    PSM1["M365SAT.psm1"]:::definitions

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Orchestrator["Core Orchestrator\n(Invoke-M365SATChecks)"]:::core
        ConnectCmd["Connect-M365SAT"]:::core
        ChecksCmd["Get-M365SATChecks"]:::core
        UpdateModules["Update Modules\n(Update-M365SATModules)"]:::core
        DupCheck["Check Duplicates\n(Check-M365SATModuleDuplicates)"]:::core
        UpdatesCheck["Check Updates\n(Check-M365SATUpdates)"]:::core

        Orchestrator --> ConnectCmd
        Orchestrator --> ChecksCmd
        Orchestrator --> UpdateModules
        Orchestrator --> DupCheck
        Orchestrator --> UpdatesCheck

        click Orchestrator "https://github.com/compliantsec/m365sat/blob/production/core/Invoke-M365SATChecks.ps1"
        click ConnectCmd "https://github.com/compliantsec/m365sat/blob/production/core/Connect-M365SAT.ps1"
        click ChecksCmd "https://github.com/compliantsec/m365sat/blob/production/core/Get-M365SATChecks.ps1"
        click UpdateModules "https://github.com/compliantsec/m365sat/blob/production/core/Update-M365SATModules.ps1"
        click DupCheck "https://github.com/compliantsec/m365sat/blob/production/core/Check-M365SATModuleDuplicates.ps1"
        click UpdatesCheck "https://github.com/compliantsec/m365sat/blob/production/core/Check-M365SATUpdates.ps1"
    end

    %% Authentication Connectors
    subgraph "Auth Connectors" 
        direction TB
        AZ["Azure Connector"]:::connector
        EX["Exchange Connector"]:::connector
        GR["Graph Connector"]:::connector
        SC["SecurityCompliance Connector"]:::connector
        SP["SharePoint Connector"]:::connector
        TM["Teams Connector"]:::connector

        AZ -->|"auth API calls"| EXT_AZ["Azure API"]:::external
        EX -->|"auth API calls"| EXT_EX["Exchange Online"]:::external
        GR -->|"auth API calls"| EXT_GR["Microsoft Graph"]:::external
        SC -->|"auth API calls"| EXT_SC["Security & Compliance"]:::external
        SP -->|"auth API calls"| EXT_SP["SharePoint"]:::external
        TM -->|"auth API calls"| EXT_TM["Teams"]:::external

        click AZ "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftAzure.ps1"
        click EX "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftExchange.ps1"
        click GR "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftGraph.ps1"
        click SC "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftSecurityCompliance.ps1"
        click SP "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftSharepoint.ps1"
        click TM "https://github.com/compliantsec/m365sat/blob/production/core/m365connectors/Connect-MicrosoftTeams.ps1"
    end

    %% Inspector Plugins
    subgraph "Inspector Plugins" 
        direction TB
        Inspectors["inspector scripts"]:::plugins
        click Inspectors "https://github.com/compliantsec/m365sat/tree/production/inspectors/"
    end

    %% Reporting Engine
    subgraph "Reporting Engine"
        direction TB
        CSV["CSV Report\n(Get-M365SATCSVReport)"]:::report
        HTML["HTML Report\n(Get-M365SATHTMLReport)"]:::report
        click CSV "https://github.com/compliantsec/m365sat/blob/production/core/Get-M365SATCSVReport.ps1"
        click HTML "https://github.com/compliantsec/m365sat/blob/production/core/Get-M365SATHTMLReport.ps1"
    end

    %% Logging Service
    subgraph "Logging Service"
        direction TB
        Logger["Invoke-M365SATLogger"]:::logging
        Logs["Log Files\n(log/)"]:::logdir
        click Logger "https://github.com/compliantsec/m365sat/blob/production/core/Invoke-M365SATLogger.ps1"
        click Logs "https://github.com/compliantsec/m365sat/tree/production/log/"
    end

    %% Output
    Output["Report Files (CSV/HTML)"]:::output

    %% External Systems
    subgraph "External Systems"
        direction TB
        EXT_AZ
        EXT_EX
        EXT_GR
        EXT_SC
        EXT_SP
        EXT_TM
    end

    %% Data Flows
    CLI -->|"invoke"| Orchestrator
    CLI --> WB
    Orchestrator --> AZ
    Orchestrator --> EX
    Orchestrator --> GR
    Orchestrator --> SC
    Orchestrator --> SP
    Orchestrator --> TM
    Orchestrator --> Inspectors
    Inspectors -->|"Audit Result Object"| Orchestrator
    Orchestrator --> CSV
    Orchestrator --> HTML
    Orchestrator --> Logger
    CSV --> Output
    HTML --> Output
    Logger --> Logs

    %% Styles
    classDef cli fill:#88C0D0,stroke:#2E3440,color:#2E3440;
    classDef welcome fill:#B48EAD,stroke:#2E3440,color:#2E3440;
    classDef definitions fill:#D08770,stroke:#2E3440,color:#2E3440;
    classDef core fill:#5E81AC,stroke:#2E3440,color:#ECEFF4;
    classDef connector fill:#A3BE8C,stroke:#2E3440,color:#2E3440;
    classDef plugins fill:#8FBCBB,stroke:#2E3440,color:#2E3440;
    classDef report fill:#EBCB8B,stroke:#2E3440,color:#2E3440;
    classDef logging fill:#81A1C1,stroke:#2E3440,color:#2E3440;
    classDef logdir fill:#4C566A,stroke:#2E3440,color:#ECEFF4;
    classDef output fill:#ECEFF4,stroke:#2E3440,color:#2E3440;
    classDef external fill:#D16D69,stroke:#2E3440,color:#2E3440;
```
