Merge pull request #1382 from SamErde/docs-NavigationSidebar

Update docs navigation sidebar

Author: SamErde

website/docs/ca-what-if.md

@@ -60,8 +60,7 @@ Describe "Contoso.ConditionalAccess" {
         $userId = (Get-MgUser -UserId 'john@contoso.com').Id
         $sharePointAppId = '67ad5377-2d78-4ac2-a867-6300cda00e85'
 
-        $policiesEnforced = Test-MtConditionalAccessWhatIf -UserId $userId `
-            -IncludeApplications $sharePointAppId `
+        $policiesEnforced = Test-MtConditionalAccessWhatIf -UserId $userId -IncludeApplications $sharePointAppId
 
         $policiesEnforced.grantControls.builtInControls | Should -Contain "mfa"
     }
@@ -80,14 +79,14 @@ Describe "Contoso.ConditionalAccess" {
         $userId = (Get-MgUser -UserId 'adele@contoso.com').Id
         $azureAppId = 'c44b4083-3bb0-49c1-b47d-974e53cbdf3c'
 
-        $policiesEnforced = Test-MtConditionalAccessWhatIf -UserId $userId `
-            -IncludeApplications $azureAppId `
+        $policiesEnforced = Test-MtConditionalAccessWhatIf -UserId $userId -IncludeApplications $azureAppId
 
         $policiesEnforced.grantControls.builtInControls | Should -Contain "block"
     }
 }
 ```
+
 ## Next steps
 
-* To learn more about the **Test-MtConditionalAccessWhatIf** cmdlet, including the supported parameters and examples see [Test-MtConditionalAccessWhatIf | Maester Reference](https://maester.dev/docs/commands/Test-MtConditionalAccessWhatIf).
-* For a step by step guide on writing custom Maester tests and running them see [Writing Maester tests](/docs/writing-tests).
+- To learn more about the **Test-MtConditionalAccessWhatIf** cmdlet, including the supported parameters and examples see [Test-MtConditionalAccessWhatIf | Maester Reference](https://maester.dev/docs/commands/Test-MtConditionalAccessWhatIf).
+- For a step by step guide on writing custom Maester tests and running them see [Writing Maester tests](/docs/writing-tests).

website/docs/export-results.md

@@ -1,5 +1,5 @@
 ---
-title: Exporting results
+title: 📤 Exporting results
 ---
 
 Maester supports exporting test results to CSV and Excel files. This is useful for sharing test results with others or for further analysis in a spreadsheet program.
@@ -38,4 +38,3 @@ To export just the test results without the test suite hierarchy, use the `-Pass
 $results = Invoke-Maester -PassThru
 Convert-MtResultsToFlatObject -InputObject $results -PassThru
 ```
-

website/docs/intro.md

@@ -1,43 +1,71 @@
 ---
+title: 📦 Installation guide
 sidebar_position: 1
-title: Introduction
 ---
 
-## What is Maester?
+- Install the **Maester** PowerShell module, Pester, and the out of the box tests.
 
-Maester is a PowerShell based test automation framework to help you stay in control of your Microsoft security configuration.
+```powershell
+Install-Module Pester -SkipPublisherCheck -Force -Scope CurrentUser
+Install-Module Maester -Scope CurrentUser
 
-## Why Maester?
+md maester-tests
+cd maester-tests
+Install-MaesterTests
+```
 
-As business needs evolve, we often need to make changes to our tenant configuration. As employees come and go, new features are added, and existing features are updated. How do you ensure that a change in one area doesn't introduce a security vulnerability in another?
+- Sign into your Microsoft 365 tenant and run the tests.
 
-Take for example conditional access policies. You may have a policy that requires multi-factor authentication for a group of users. What if someone accidentally deletes the group or removes users from the group? **Your conditional access policy is now ineffective.**
+```powershell
+Connect-Maester
+Invoke-Maester
+```
 
-Let's take another scenario that is fairly common. What if the original author of the conditional access policy leaves the company and someone else makes a change to the policy without understanding the implications?
+## Invoke-Maester
 
-## How does Maester help?
+To learn more about the `Invoke-Maester` cmdlet including how to filter tests, and customize the run of the Pester Configuration see the [Invoke-Maester](commands/Invoke-Maester.mdx) documentation.
 
-What if we could run a set of tests to ensure that our configuration is in compliance with our security policies?
+## Optional modules and permissions
 
-That is exactly what Maester does.
+Maester includes optional [CISA](tests/cisa/) tests that require additional permissions and modules to run. These optional tests are skipped if the modules are not installed or there is no active connection.
 
-:::info[Why Maester?]
+### Installing Azure, Exchange Online and Teams modules
 
-Maester helps you monitor your Microsoft 365 tenant by running a set of tests to ensure your configuration is in compliance with your security policies.
+```powershell
+Install-Module Az.Accounts -Scope CurrentUser
+Install-Module ExchangeOnlineManagement -Scope CurrentUser
+Install-Module MicrosoftTeams -Scope CurrentUser
+```
 
-:::
+> The Security & Compliance PowerShell module is dependent on the ExchangeOnlineManagement `Connect-IPPSSession` cmdlet.
 
-Maester provides a framework for you to bring DevOps practices to managing your Microsoft security configuration.
+### Connecting to Azure, Exchange and other services
 
-* Define your security policies as code and store them in a version control system.
-* Continuously run tests that ensure your tenant configuration is complying with the defined policies.
-* Found an incorrect configuration? Create a new test to ensure it doesn't happen again.
-* Write tests using [Pester](https://pester.dev/), a popular testing framework for PowerShell.
-* Use the built-in tests to quickly get started with monitoring your tenant.
-* Write custom tests as you introduce new configuration and codify your intent for the configuration.
+In order to run all the CISA tests, you need to connect to the Azure, Exchange Online, and other modules.
 
-## Introducing Maester
+For a more detailed introduction to these concepts see the [Connect-Maester](connect-maester/readme.md) documentation.
 
-This introductory session on Maester is from the [PowerShell + DevOps Global Summit 2024](https://www.powershellsummit.org/) and provides an overview of the Maester framework.
+Run the following command to interactively connect to the Azure, Exchange Online, and other modules. A sign in window will appear for each module.
 
-<iframe width="640" height="360" src="https://www.youtube.com/embed/xfs02tjSU24" title="Introducing Maester: Your Microsoft 365 test automation framework by Merill Fernando" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+```powershell
+Connect-Maester -Service All
+```
+
+### Permissions
+
+Exchange Online implements a [role-based access control model](https://learn.microsoft.com/exchange/permissions-exo/permissions-exo). The controls these cmdlets test, require minimum roles of either of the following:
+
+- View-Only Configuration OR
+- O365SupportViewConfig
+
+## Next Steps
+
+- Monitoring with Maester
+  - [Set up Maester on GitHub](monitoring/github.md)
+  - [Set up Maester on Azure DevOps](monitoring/azure-devops.md)
+  - [Set up Maester on Azure Container App Jobs](monitoring/azure-container-app-job.md)
+- Alerting with Maester
+  - [Set up Maester email alerts](alerts/email.md)
+  - [Set up Maester Teams alerts](alerts/teams.md)
+  - [Set up Maester Slack alerts](alerts/slack.md)
+- [Writing Custom Tests](writing-tests/index.mdx)

website/docs/updating-tests.md

@@ -1,20 +1,20 @@
 ---
-title: Updating tests
+title: 🧪 Updating tests
 ---
 
 # Updating your Maester tests
 
 The Maester team will add new tests over time. To get the latest updates, use the commands below to update your GitHub repository with the latest tests.
 
-## Step 1: Change to the folder with your tests
+### Step 1: Change to the folder with your tests
 
 Open a command prompt and navigate to the folder where you have your Maester tests.
 
 ```powershell
 cd maester-tests
 ```
 
-## Step 2: Update the Maester module
+### Step 2: Update the Maester module
 
 Update the **Maester** PowerShell module to the latest version and load it.
 
@@ -23,7 +23,7 @@ Update-Module Maester -Force
 Import-Module Maester
 ```
 
-## Step 3: Update the tests folder
+### Step 3: Update the tests folder
 
 You will be prompted to confirm changes to the tests folder.
 

website/sidebars.js

@@ -4,45 +4,35 @@
 const sidebars = {
   siteSidebar: [
     "intro",
-    "installation",
     {
       type: "category",
-      label: "👁️‍🗨️ Monitoring with Maester",
-      collapsed: true,
-      collapsible: true,
-      items: [{ type: "autogenerated", dirName: "monitoring" }],
-    },
-        {
-      type: "category",
-      label: "📮 Maester Alerts",
+      label: "⚙️ Configure Maester",
       collapsed: true,
       collapsible: true,
-      items: [{ type: "autogenerated", dirName: "alerts" }],
+      link: {type: 'doc', id: 'configuration/overview'},
+      items: [{ type: "autogenerated", dirName: "configuration" }],
     },
     {
       type: "category",
-      label: "🛠️ Writing custom tests",
-      collapsed: false,
+      label: "🔗 Connect-Maester",
+      collapsed: true,
       collapsible: true,
-      items: [{ type: "autogenerated", dirName: "writing-tests" }],
+      items: [{ type: "autogenerated", dirName: "connect-maester" }],
     },
+    "export-results",
     {
       type: "category",
-      label: "⚙️ Configure Maester",
-      collapsed: false,
+      label: "👁️‍🗨️ Monitoring with Maester",
+      collapsed: true,
       collapsible: true,
-      link: {type: 'doc', id: 'configuration/overview'},
-      items: [{ type: "autogenerated", dirName: "configuration" }],
+      items: [{ type: "autogenerated", dirName: "monitoring" }],
     },
-    "ca-what-if",
-    "updating-tests",
-    "export-results",
     {
       type: "category",
-      label: "Connect-Maester",
-      collapsed: false,
+      label: "📮 Maester Alerts",
+      collapsed: true,
       collapsible: true,
-      items: [{ type: "autogenerated", dirName: "connect-maester" }],
+      items: [{ type: "autogenerated", dirName: "alerts" }],
     },
     "watch",
     "contributing",
@@ -86,6 +76,19 @@ const sidebars = {
           type: "html",
           value: '<span class="sidebar-divider" />',
         },
+        "ca-what-if",
+        {
+          type: "html",
+          value: '<span class="sidebar-divider" />',
+        },
+        "updating-tests",
+        {
+          type: "category",
+          label: "🛠️ Writing custom tests",
+          collapsed: true,
+          collapsible: true,
+          items: [{ type: "autogenerated", dirName: "writing-tests" }],
+        }
         "tests/tags/overview",
       ],
     },
@@ -97,6 +100,7 @@ const sidebars = {
       type: "category",
       label: "Command Reference",
       collapsed: true,
+      //className: "powershell",
       items: [{ type: "autogenerated", dirName: "commands" }],
     },
   ],