Merge pull request #505 from Snozzberries/connecting

New Connecting Details Docs Page

build/commandDependencyFrequency.ps1

@@ -0,0 +1,24 @@
+$dependencies = @()
+$files = gci ..\powershell\public\ -File *.ps1 -Recurse
+foreach($file in $files){
+    $content  = gc $file -Raw
+    $parse    = [System.Management.Automation.Language.Parser]::ParseInput($content,[ref]$null,[ref]$null)
+    $commands = $parse.FindAll({
+        $args|?{$_ -is [System.Management.Automation.Language.CommandAst]}
+    },$true)|%{($_.CommandElements|Select -First 1).Value}`
+    |group|sort @{e={$_.Count};Descending=$true},Name
+
+    foreach($command in $commands){
+        $dependencies += @{
+            file    = $file
+            command = $command.Name
+            count   = $command.Count
+        }
+    }
+}
+
+$dependencies|group command|sort @{e={$_.Count};Descending=$true},Name|select count,name
+#Show modules
+#($dependencies.Name|%{Get-Command $_}).Source|sort -Unique
+#Show commands by modules filtering out a few
+#$dependencies|%{$n=$_.Name;$(Get-Command $_.Name).Source|?{$_ -notin @("Maester","Pester","PowerShellGet") -and $_ -notlike "Microsoft.PowerShell*"}|%{"$_;$n"}}|sort

powershell/public/Connect-Maester.ps1

@@ -1,6 +1,6 @@
 <#
 .SYNOPSIS
-   Helper method to connect to Microsoft Graph using Connect-MgGraph with the required scopes.
+   Helper method to connect to Microsoft Graph using Connect-MgGraph with the required permission scopes as well as other services such as Azure and Exchange Online.
 
 .DESCRIPTION
    Use this cmdlet to connect to Microsoft Graph using Connect-MgGraph.

website/docs/connect-maester/connect-maester-advanced.md

@@ -0,0 +1,117 @@
+---
+sidebar_label: Connect-Maester Advanced
+sidebar_position: 2
+title: Connect-Maester - Advanced
+---
+
+# Connect-Maester Advanced
+
+import CreateEntraApp from '../sections/create-entra-app.md';
+
+## Overview
+
+There are two main methods of authenticating sessions for use with Maester:
+
+* Within the Maester module
+* Within the respective modules for the tests
+
+### Within the Maester module
+
+:::tip
+Recommended for interactive use
+:::
+
+The Maester module includes [`Connect-Maester`](/docs/commands/Connect-Maester) to provide coverage for common scenarios. The parameter set options afford a user of the module the ability to test with common interactive methods. The Microsoft Graph API is the default authentication service, and more specifically the Microsoft Graph PowerShell SDK. Coverage for tests shipping with Maester have at least one option available in general.
+
+> The objective of the Maester module is not to replace or consolidate the authentication options across the many possible testing sources.
+
+### Within the respective modules for the tests
+
+**Recommended for automation use**
+
+The Maester module provides a framework for creating, executing, and reporting on configuration state using tests. Each test can rely on one or more sources to perform validation. Each source a test validates may be available without authentication (e.g., Domain Name System) or may require authentication to a sepcific environment (e.g., Microsoft Graph API).
+
+The recommendation for authenticating to modules necessary to support tests for the most extensibility is to authentcate within those source modules and running `Invoke-Maester` with the `-SkipGraphConnect` property.
+
+As an example, connecting to the Microsoft Graph PowerShell SDK module as a managed identity and then running Maester.
+
+> Running `Connect-Maester` is not required to use `Invoke-Maester`.
+
+```powershell
+Connect-MgGraph -Identity -NoWelcome
+Invoke-Maester -SkipGraphConnect -NonInteractive
+```
+
+The following diagram provides a general overview of command dependency relationships. You can extend Maester with your own tests that leverage other modules as may be beneficial. There is no dependency for your own tests to rely on the `Connect-Maester` capabilities.
+
+```mermaid
+graph TD;
+  Connect-Maester-->Microsoft.Graph.Authentication;
+  Connect-Maester-->Az.Accounts;
+  Connect-Maester-->ExchangeOnlineManagement;
+  Microsoft.Graph.Authentication-->Get-MgContext;
+  Microsoft.Graph.Authentication-->Get-MgEnvironment;
+  Microsoft.Graph.Authentication-->Invoke-MgGraphRequest;
+  Az.Accounts-->Get-AzContext;
+  Az.Accounts-->Invoke-AzRestMethod;
+  ExchangeOnlineManagement-->Get-ConnectionInformation;
+  ExchangeOnlineManagement-->Get-EXOMailbox;
+  ExchangeOnlineManagement-->Get-MtExo;
+  Get-MtExo-->Get-AcceptedDomain;
+  Get-MtExo-->o[Other Commands];
+```
+
+You can [write tests](/docs/writing-tests) that expand Maester to validate the configuration state of infrastructure in the cloud, on-premises, and entirely unrelated to Microsoft products.
+
+For use with the Maester tests the following provides an overview of creating the necessary service principal.
+
+<CreateEntraApp/>
+
+## Authenticating Across Tenants
+
+You may have a need to use Maester with multiple tenanats. The Maester tests enable you to accomplish this, but it is best to authenticate within the respective modules for the tests you wish to run.
+
+### Microsoft Graph PowerShell SDK Module
+
+The Microsoft Graph PowerShell SDK Module provides many [options for authenticating](https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands). Below is an example of using a X.509 Certificate private key file, `$cert`, to authenticate to `$tenantId` as the `$applicationId` service principal.
+
+```powershell
+#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
+#tenantId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
+#$b64 = Get-Content .\path\to\cert.pfx -Raw
+#$b64 = Get-AzKeyVaultSecret -VaultName $keyVaultName -Name $applicationDisplayName -AsPlainText
+#$bytes = [Convert]::FromBase64String($b64)
+#$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
+
+Connect-MgGraph -AppId $applicationId -Certificate $cert -TenantId $tenantId -NoWelcome
+```
+
+### Microsoft Azure Accounts PowerShell Module
+
+The Microsoft Azure Accounts PowerShell Module provides many [options for authenticating](https://learn.microsoft.com/en-us/powershell/azure/authenticate-noninteractive). Below is an example of using a X.509 Certificate private key file to authenticate to `$tenantId` as the `$applicationId` service principal.
+
+```powershell
+#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
+#tenantId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
+
+Connect-AzAccount -ServicePrincipal -ApplicationId $applicationId -TenantId $tenantId -CertificatePath /cert.pfx
+```
+
+### Microsoft Exchange Online and Security & Compliance PowerShell Modules
+
+The Microsoft Exchange Online and Security & Compliance PowerShell Modules provide many [options for authenticating](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2). Below is an example of using a X.509 Certificate private key file, `$cert`, to authenticate to `$tenantId` as the `$applicationId` service principal.
+
+> These modules don't reference the tenant ID GUID for authentication, they instead use the tenant's Microsoft Online Email Routing Address (MOERA).
+
+```powershell
+#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
+#$b64 = Get-Content .\path\to\cert.pfx -Raw
+#$b64 = Get-AzKeyVaultSecret -VaultName $keyVaultName -Name $applicationDisplayName -AsPlainText
+#$bytes = [Convert]::FromBase64String($b64)
+#$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
+#$domains = Invoke-MgGraphRequest -Uri https://graph.microsoft.com/v1.0/domains
+#$moera = ($domains.value|?{$_.isInitial}).id
+
+Connect-ExchangeOnline -Certificate $cert -AppID $applicationId -Organization $moera -ShowBanner:$false
+Connect-IPPSSession -Certificate $cert -AppID $applicationId -Organization $moera -ShowBanner:$false
+```

website/docs/connect-maester/readme.md

@@ -0,0 +1,95 @@
+---
+sidebar_label: Connect-Maester
+sidebar_position: 1
+title: Connect-Maester
+---
+
+# Connect-Maester
+
+## Overview
+
+`Connect-Maester` is a helper command that simplifies the process of authenticating to the services required to run Maester tests including Microsoft Graph PowerShell, Azure PowerShell and Exchange Online PowerShell.
+
+While `Connect-Maester` will handle the most common interactive authentication scenarios, it does not replicate all of the authentication options available in the respective modules.
+
+:::tip
+The `Connect-Maester` command is completely optional if your current PowerShell session is already connected to Microsoft Graph using Connect-MgGraph.
+:::
+
+Examining the code for `Connect-Maester` will reveal that it simply calls `Connect-MgGraph`.
+
+```mermaid
+graph TD;
+    Connect-Maester-->Connect-MgGraph;
+```
+
+What this means is that you can use `Connect-MgGraph` directly if you prefer to have more control over the authentication process. See the [Connect-MgGraph: Microsoft Graph authentication](https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands) documentation for more information on all the options available including the use of certificates, secrets, managed identities, different clouds and more.
+
+## Using Connect-Maester
+
+### Connect to Microsoft Graph
+
+To connect to Microsoft Graph, use the following command:
+
+```powershell
+Connect-Maester
+```
+
+Running `Connect-Maester` is the same as running the following:
+
+```powershell
+Connect-MgGraph -Scopes (Get-MtGraphScope)
+```
+
+#### Send Mail and Teams message
+
+Connects to Microsoft Graph with the Mail.Send scope in addition to the default Maester scopes. This allows you to use the required permission to send email when using the `Send-MtMail` command or when using `Invoke-Maester -MailRecipient [email protected]`
+
+```powershell
+Connect-Maester -SendMail
+```
+
+This is the same as running
+
+```powershell
+Connect-MgGraph -Scopes (Get-MtGraphScope -SendMail)
+```
+
+The same applies to the `-SendTeamsMessage` in `Connect-Maester`.
+
+#### Privileged scope
+
+Maester is designed to require read-only access to a tenant to run tests. Unfortunately, the Graph API command to query global admin roles in Microsoft Entra Privileged Identity Management requires the **RoleEligibilitySchedule.ReadWrite.Directory** command. For these tests to run accurately you will need to explicitly opt into using this additional privilege by connecting with
+
+```powershell
+Connect-Maester -Privileged
+```
+
+For technical details on this requirement see
+
+* [Graph API - List roleEligibilityScheduleRequests](https://learn.microsoft.com/en-us/graph/api/rbacapplication-list-roleeligibilityschedulerequests?view=graph-rest-1.0&tabs=http#permissions)
+* [Maester Issue #195](https://github.com/maester365/maester/issues/195#issuecomment-2170879665)
+
+#### Device code
+
+The `-DeviceCode` switch allows you to sign in using the device code flow. This will open a browser window to prompt for authentication and is useful on Windows when you want to avoid single signing on as the current user.
+
+```powershell
+Connect-Maester -UseDeviceCode
+```
+
+### Connect to Azure and Exchange Online
+
+`Connect-Maester` also provides options to connect to Azure and Exchange Online for running tests that use the Azure PowerShell and Exchange Online PowerShell modules.
+
+The `-All` switch can be used to connect to all the services used by the Maester tests. This includes Microsoft Graph, Azure, Exchange Online and Security Compliance.
+
+```powershell
+Connect-Maester -Service All
+```
+
+If you need to connect to just a subset of the services you can specifiy them using the `-Service` parameter.
+
+```powershell
+Connect-Maester -Service Azure,Graph
+```

website/docs/contributing.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 title: ✨ Contributing
 ---
 

website/docs/faq.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 title: ❓ FAQ
 ---
 

website/docs/installation.md

@@ -42,6 +42,8 @@ Install-Module ExchangeOnlineManagement -Scope CurrentUser
 
 In order to run all the CISA tests, you need to connect to the Azure, Exchange Online, and other modules.
 
+For a more detailed introduction to these concepts see the [Connect-Maester](/docs/connect-maester) documentation.
+
 Run the following command to interactively connect to the Azure, Exchange Online, and other modules. A sign in window will appear for each module.
 
 ```powershell
@@ -60,5 +62,7 @@ Exchange Online implements a [role-based access control model](https://learn.mic
 - Monitoring with Maester
   - [Set up Maester on GitHub](/docs/monitoring/github)
   - [Set up Maester on Azure DevOps](/docs/monitoring/azure-devops)
+  - [Set up Maester on Azure Container App Jobs](/docs/monitoring/azure-container-app-job)
   - [Set up Maester email alerts](/docs/monitoring/email)
+  - [Set up Maester Slack alerts](/docs/monitoring/slack)
 - [Writing Custom Tests](/docs/writing-tests)

website/docs/monitoring/readme.md

@@ -11,3 +11,4 @@ In this section we provide guidance for some popular services.
 - <IIcon icon="vscode-icons:file-type-azurepipelines" height="18" /> [Azure DevOps Pipeline](./azure-devops)
 - <IIcon icon="mdi:github" height="18" /> [GitHub Actions](./github)
 - <IIcon icon="devicon:azure" height="18" /> [Azure Automation](./azure-automation)
+- <IIcon icon="vscode-icons:file-type-docker2" height="18" /> [Azure Container App Job](./azure-container-app-job)

website/sidebars.js

@@ -15,6 +15,13 @@ const sidebars = {
     "writing-tests",
     "ca-what-if",
     "updating-tests",
+    {
+      type: "category",
+      label: "Connect-Maester",
+      collapsed: false,
+      collapsible: true,
+      items: [{ type: "autogenerated", dirName: "connect-maester" }],
+    },
     "watch",
     "contributing",
     "faq",