From 5e311f8abb979a006762499e8162c1e49dd86f7d Mon Sep 17 00:00:00 2001 From: jtdauria-shi Date: Thu, 20 Aug 2026 22:11:52 -0400 Subject: [PATCH 1/3] Installation improvements, Microsoft Insights addition, & deadlink updates --- docs/Microsoft-Insights/Usage-Guide.md | 230 ++++++++++++++++++ docs/SHIELD/Defend/Deployment.md | 2 +- docs/SHIELD/Defend/Reference/index.md | 2 +- docs/SHIELD/Deploy/Deployment/index.md | 2 +- docs/SHIELD/Deploy/Usage-Guide.md | 2 +- docs/SHIELD/Deploy/index.md | 6 +- docs/SHIELD/Prerequisites/Installation.md | 140 ++++++++--- docs/SHIELD/Prerequisites/index.md | 52 ++-- docs/SHIELD/Usage-Guide.md | 2 +- .../Images/Screenshots/MI-columns-dark.png | Bin 0 -> 193149 bytes .../Images/Screenshots/MI-columns-light.png | Bin 0 -> 191698 bytes .../Images/Screenshots/MI-filter-dark.png | Bin 0 -> 104627 bytes .../Images/Screenshots/MI-filter-light.png | Bin 0 -> 103378 bytes .../Screenshots/MI-license-type-dark.png | Bin 0 -> 52372 bytes .../Screenshots/MI-license-type-light.png | Bin 0 -> 51875 bytes .../Images/Screenshots/MI-overview-dark.png | Bin 0 -> 212476 bytes .../Images/Screenshots/MI-overview-light.png | Bin 0 -> 211837 bytes .../Screenshots/MI-system-user-admin-dark.png | Bin 0 -> 6383 bytes .../MI-system-user-admin-light.png | Bin 0 -> 6326 bytes .../Screenshots/MI-top-level-metrics-dark.png | Bin 0 -> 35395 bytes .../MI-top-level-metrics-light.png | Bin 0 -> 35250 bytes .../Images/Screenshots/MI-warning-dark.png | Bin 0 -> 58177 bytes .../Images/Screenshots/MI-warning-light.png | Bin 0 -> 58480 bytes zensical.toml | 4 + 24 files changed, 375 insertions(+), 67 deletions(-) create mode 100644 docs/Microsoft-Insights/Usage-Guide.md create mode 100644 docs/assets/Images/Screenshots/MI-columns-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-columns-light.png create mode 100644 docs/assets/Images/Screenshots/MI-filter-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-filter-light.png create mode 100644 docs/assets/Images/Screenshots/MI-license-type-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-license-type-light.png create mode 100644 docs/assets/Images/Screenshots/MI-overview-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-overview-light.png create mode 100644 docs/assets/Images/Screenshots/MI-system-user-admin-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-system-user-admin-light.png create mode 100644 docs/assets/Images/Screenshots/MI-top-level-metrics-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-top-level-metrics-light.png create mode 100644 docs/assets/Images/Screenshots/MI-warning-dark.png create mode 100644 docs/assets/Images/Screenshots/MI-warning-light.png diff --git a/docs/Microsoft-Insights/Usage-Guide.md b/docs/Microsoft-Insights/Usage-Guide.md new file mode 100644 index 0000000..ffa0c26 --- /dev/null +++ b/docs/Microsoft-Insights/Usage-Guide.md @@ -0,0 +1,230 @@ +# Microsoft Insights Usage Guide + +!!! note + This article has recently been published and is subject to change. + +## Overview + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-overview-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-overview-dark.png#only-dark){ loading=lazy } + +The integration between SHI One and Microsoft gives you incredible visibility into your tenant. The platform displays numerous metrics and advanced insights, all in one place. The insights tell you what users are actively using, what is being consumed, and what service plans are enabled in your environment. To put it simply, this report is designed to guide you in answering: + +- **What do I own?** +- **What are users consuming?** +- **What do I do with this information?** + +!!! info + The data found in this report is populated from SHIELD. Data will not be available unless you have deployed SHIELD into your environment. For instructions on how to install SHIELD, see [Overview and Installation Requirements](/SHIELD/Prerequisites/Installation). For more information about SHIELD, see [SHI Environment Lockdown and Defense (SHIELD)](https://www.shi.com/it-lifecycle-services/software-lifecycle-management/shield){:target="_blank"}. + +--- + +## Benefits + +- **Complete Visibility and Control** - Gain a comprehensive view of which features are being used by users, administrators and systems. Instantly identify what licenses and capabilities your organization owns and see exactly how they are being consumed. +- **Proactive Compliance and Risk Management** - Easily sport discrepancies between assigned, consumed, and purchased licenses. Microsoft Insights helps you quickly detect over-consumption, reducing compliance and financial risks by revealing when usage exceeds entitlements. +- **Actionable Usage Intelligence** - Track user assignments, monitor feature adoption, and unlock detailed consumption patterns. This gives you the ability to optimize license allocation, address gaps, and make informed decisions to maximize your Microsoft investment. + +--- + +## Sign In + +1. Go to SHI One: [https://one.shi.com/](https://one.shi.com/){:target="_blank"} +2. Sign into SHI One using one of the available options and complete the login. +3. Once you are signed in, click **Assessments** in the left navigation. +4. Click **Microsoft Insights**. + +--- + +## Top Level Metrics + +![Top Level Metrics - Light](../.../../assets/Images/Screenshots/MI-top-level-metrics-light.png#only-light){ loading=lazy } +![Top Level Metrics - Dark](../.../../assets/Images/Screenshots/MI-top-level-metrics-dark.png#only-dark){ loading=lazy } + +The featured metrics at the top display common subscriptions along with the monthly active users (MAU), assigned licenses, and purchase licenses. The top-level metrics give you immediate insights into the most common Microsoft service plans. By comparing the number of monthly active users and assigned licenses to the number of purchased licenses, you can easily see if your organization is compliant or not. + +- **Subscription Type** - The specific Microsoft subscription plan that is being used (e.g., Microsoft 365 E3). +- **Monthly Active Users (MAU)** - Users who actively use the service within the monthly period. +- **Assigned** - The number of licenses that have been assigned to an endpoint. Endpoints are physical devices such as desktop computers, virtual machines, mobile phones, embedded devices, and servers that connect and exchange information with a computer network. +- **Purchased** - The number of licenses that have been purchased by your organization, typically through an agreement + +**Example** + +In the screenshot above, Microsoft 365 E5 has **341** monthly active users, is assigned to **348** endpoints, and there are **350** licenses purchased. In this situation, the organization is in good shape because there are **350** purchased licenses, and only **348** have been assigned. It's also important to note that of the **348** assigned licenses, only **341** have been used during the reporting period, which means there are **7** licenses underutilized. + +--- + +## Individual Usage Reports + +### Filters + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-filter-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-filter-dark.png#only-dark){ loading=lazy } + +The filters at the top of the individual reports allow you to filter users by license. By default, the report will be filtered to **All Users**, but you can click on the drop-down menu and select any service plan that appears, even **Unassigned** users. +Filters can help you quickly answer questions like: + +- **Are users with E3 licenses using E5 capabilities?** +- **Are users with E3 licenses in scope for E3 features?** + +### Columns + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-columns-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-columns-dark.png#only-dark){ loading=lazy } + +The reports section breaks down each capability tier into a single column. Each column has its own set of feature groups, along with the associated features. Some examples include: + +- **Identity & Access** - Conditional Access (Risk-Based), Identity Protection (Risk Policies), Privileged Identity Management +- **Threat Protection** - Endpoint Detection & Response, Identity Theft Protection, Cloud App Discovery & Session Control +- **Core Apps** - Microsoft Teams, Exchange Online, OneDrive for Business, Microsoft 365 Apps for Enterprise +- **Security & Compliance** - Safe Links / Attachments / Anti-phishing, Sensitivity Labels (Manual) +- **Device Management** - Device Compliance, Device Management & Configuration Profiles, App Protection Policies + +### Feature Numbers + +Next to each feature you will see summary of the feature in your environment. The structure is **MAU** / **In Scope** / **Purchased**. + +- **MAU (Monthly Active Users)** - Users who actively use the service within the monthly period. +- **In Scope** - Users who have the service plan enabled in their license profile. +- **Purchased** - The number of licenses that have been purchased by your organization. +To understand this information, consider the following two examples: + +**Example 1: Endpoint Detection & Response Feature Usage** + +- Endpoint Detection & Response + - MAU: **134** + - IN SCOPE: **152** + - PURCHASED: **210** + +- **Purchased Licenses**: The organization owns **210** licenses for the **Endpoint Detection & Response** feature. +- **Endpoints Enabled**: This feature has been enabled on **152** devices or endpoints. +- **Monthly Active Users**: There are **134** people actively using the feature each month. + +In this example, the organization is not overconsuming the **Endpoint Detection & Response** feature, since active usage (**134**) and enabled endpoints (**152**) are both below the number of purchased licenses (**210**). However, this organization may have more licenses than needed. Ideally, the number of purchased licenses should closely match the number of endpoints enabled and users actively using the feature. It's also important to note that having too many unused licenses may lead to unnecessary costs. + +**Example 2: Identity Theft Protection Feature Usage** + +- Identity Theft Protection + - MAU: **220** + - IN SCOPE: **275** + - PURCHASED: **210** + +- **Purchased Licenses**: The organization owns **210** licenses for the **Identity Theft Protection** feature. +- **Endpoints Enabled**: The feature has been enabled on **275** devices or endpoints. +- **Monthly Active Users**: There are **220** people actively using the feature each month. + +In this example, the organization is overconsuming the **Identity Theft Protection** feature, since active usage (**220**) and enabled endpoints (**275**) are both greater than the number of purchased licenses (**210**). In other words, this organization is using more licenses than it has purchased and may face issues down the road. + +### Warnings + +A warning appears when you have more users using a feature than the number of licenses you have purchased. In these situations, we recommend reaching out to your SHI representative, who will be able to assist you. + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-warning-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-warning-dark.png#only-dark){ loading=lazy } + +!!! info + Sometimes, you might notice that the number of monthly active users is higher than the number of users "in scope." This is not an error; it's simply a result of how Microsoft calculates and reports these metrics. + +### License Types + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-license-type-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-license-type-dark.png#only-dark){ loading=lazy } + +You can drill further into each feature to see the associated license type by clicking on the feature. This section shows you what license type is consuming the feature. + +**Example** + +In the above screenshot, we are viewing usage for **All Users**, and want to take a closer look at the **Identity Protection (Risk Policies)** feature, since the bar is red. When we click on the feature, we can see it is associated with the following license types in the environment: + +- **M365 E5** +- **M365 E3 - EMS E5 / Entra P2 Add-ons** +- **M365 E3** +- **M365 F3** +- **Unassigned** + +For the first two license types (**M365 E5** & **M365 E3 - EMS E5 / Entra P2 Add-ons**), feature usage is less than or equal to the number of licenses purchased. In this case we can see the following breakdown: + +- **M365 E5 - 320 in scope** - 350 purchased ✅ +- **M365 E3 - EMS E5 / Entra P2 Add-ons - 270 in scope** - 270 purchased ✅ + +However, for the other three license types (**M365 E3**, **M365 F3**, **Unassigned**), feature usage is greater than the number of licenses purchased. In this case, we can see the following breakdown: + +- **M365 E3 - 480 in scope** - 0 purchased ❌ +- **M365 F3 - 100 in scope** - 0 purchased ❌ +- **Unassigned - 10 in scope** - 0 purchased ❌ + +In total, the feature is being used on **1,180** devices, but the organization has only purchased **620** licenses. To resolve this, there are two options: + +1. **Purchase more licenses** to cover all usage +2. **Reduce the number of devices** using the feature to match the number of licenses owned + +!!! note + Not every feature displays the associated license type. However, you will still be able to see monthly active users (**MAU**), the number of endpoints with the feature enabled (**In scope**), the number of licenses owned (**Purchased**). + +### Activity + +Microsoft Insights considers a feature in use when a qualifying activity is detected within the selected reporting period. Activity is categorized into one of three usage types; **System**, **User**, and **Admin**: + +![Microsoft Insights Overview - Light](../.../../assets/Images/Screenshots/MI-system-user-admin-light.png#only-light){ loading=lazy } +![Microsoft Insights Overview - Dark](../.../../assets/Images/Screenshots/MI-system-user-admin-dark.png#only-dark){ loading=lazy } + +1. **System (S)** - Automatically generated by Microsoft. + - **Examples**: Policy Checks, Compliance, Security Monitoring, etc. +2. **User (U)** - Activity created by users interacting with Microsoft features. + - **Examples**: Sending emails, joining meetings, opening files, applying sensitivity labels, etc. +3. **Admin (A)** - Activity performed by administrators managing or reviewing Microsoft features. + - **Examples**: Role activations, audit searches, policy changes, investigations, etc. + +Every feature will have an associated activity. Some features only have one activity, while others may have more than one. + +**Note**: A feature is considered "active" even if its activity is background or administrative in nature, if qualifying telemetry exists during the reporting period. Some products are measured primarily through user-driven actions. Others reflect value through system-driven and admin-driven activity. Some examples include: + +- **User Driven** + - Teams + - Exchange + - SharePoint +- **System & Admin** + - Defender for Identity + - Conditional Access + - Intune + - Data Loss Prevention (DLP) + +--- + +## Data Unavailable + +The first phase of Microsoft Insights is pulling in data. If you have successfully installed SHIELD, you should see data for the following sections: + +- **Entra ID P1** +- **Entra ID P2** +- **Defender for Identity** + +If data is not available in the platform or certain columns are grayed out, it is likely due to one of the following reasons: + +- **SHIELD Not Installed** + - If SHIELD is not installed in your environment, the system will not be able to display any insights in the report. For steps to install SHIELD, see [Overview and Installation Requirements](/SHIELD/Prerequisites/Installation). +- **Permissions Not Granted** + - The Microsoft Graph Reports API requires the `Reports.Read.All` permission to be granted for the workload. To resolve this issue, make sure the required API permissions have been consented to the Entra ID or reach out to the user who oversees granting permissions. +- **API Access Not Available or Enabled** + - This may be because the API has not been turned on yet or does not exist (such as a non-public API access). +- **Organization Does Not Have Service Plan or License** + - If a service plan or license is not active for the relevant Microsoft products, the system cannot retrieve or display usage information in the report. In this situation, you should check to confirm your organization's current service plans and licenses. + +--- + +## Glossary + +- **Monthly Active Users (MAU)** - Users who actively used or benefited from the service during this period. +- **Return on Investment (ROI)** - A performance metric used to evaluate an investment. +- **In Scope** - Users who have the service plan enabled in their license profile. +- **Assigned** - The number of licenses that are assigned to an endpoint. +- **Purchased** - The number of licenses owned. +- **The number of licenses that have been purchased by your organization.** +- **In Use** - Qualifying activities are detected within the selected reporting period. +- **System-Driven** - Automatically generated by Microsoft. +- **User-Driven** - Activity created by users interactive with Microsoft features. +- **Admin-Driven** - Activity performed by administrators managing or reviewing Microsoft features. +- **Service Plans** - Bundles of features and capabilities grouped together under a single license or subscription. Service plans define what functionalities are available to users in the organization. +- **Feature Sets** - Collections of related features that work together to deliver specific functionality or address a particular business needed. Feature sets typically focus on a core area, such as security, collaboration, or device management. +- **Consumption** - The actual usage of features or services by users, devices, or systems in an environment. It measures how much of the licensed capabilities are being actively used. +- **Capability Tiers** - Different levels or categories of features, often organized by complexity or value. Higher tiers generally include all features from lower tiers, plus additional advanced capabilities. diff --git a/docs/SHIELD/Defend/Deployment.md b/docs/SHIELD/Defend/Deployment.md index a5f4470..163fa34 100644 --- a/docs/SHIELD/Defend/Deployment.md +++ b/docs/SHIELD/Defend/Deployment.md @@ -56,4 +56,4 @@ To use Defend, the following must already be deployed: - [Defend Usage Guide](Usage-Guide/) - [Defend Reference](Reference/) - [Troubleshooting](Troubleshooting) -- [SHIELD Platform Deployment](../Getting-Started) +- [Overview and Installation Requirements](../Prerequisites/Installation) diff --git a/docs/SHIELD/Defend/Reference/index.md b/docs/SHIELD/Defend/Reference/index.md index 502755b..76ebea2 100644 --- a/docs/SHIELD/Defend/Reference/index.md +++ b/docs/SHIELD/Defend/Reference/index.md @@ -82,7 +82,7 @@ Each SHIELD lifecycle action is mapped to a standardized backend workflow. The f A dedicated section for advanced Privileged workflows, including intermediary logic and RBAC extensions, will be added in a future release. -📄 Placeholder: [Privileged Device Workflows](./Lifecycle/Privileged Device Workflows) +📄 Placeholder: Privileged Device Workflows (coming soon) --- diff --git a/docs/SHIELD/Deploy/Deployment/index.md b/docs/SHIELD/Deploy/Deployment/index.md index 6b35bed..c3df0e6 100644 --- a/docs/SHIELD/Deploy/Deployment/index.md +++ b/docs/SHIELD/Deploy/Deployment/index.md @@ -74,4 +74,4 @@ These cannot be renamed or deleted through the SHIELD UI. - [Deploy Usage Guide](../Usage-Guide) - [Reference Docs](../Reference/) - [Troubleshooting](../Troubleshooting) -- [Full SHIELD Deployment](../../Getting-Started) +- [Overview and Installation Requirements](../../Prerequisites/Installation/) diff --git a/docs/SHIELD/Deploy/Usage-Guide.md b/docs/SHIELD/Deploy/Usage-Guide.md index d1abedd..5b8e1e7 100644 --- a/docs/SHIELD/Deploy/Usage-Guide.md +++ b/docs/SHIELD/Deploy/Usage-Guide.md @@ -81,6 +81,6 @@ Once core deployment is complete, your SHIELD UI will provide management cards f - [Architectural Analysis Overview](../../SHIELD/Reference/Architecture/Architectural-Analysis-Overview) - [Deploy Overview](/SHIELD/Deploy/) -- [Deployment Guide](../Getting-Started) +- [Overview and Installation Requirements](../Prerequisites/Installation/) - [Reference Docs](Reference/) - [Troubleshooting](Troubleshooting) diff --git a/docs/SHIELD/Deploy/index.md b/docs/SHIELD/Deploy/index.md index b81141e..783880a 100644 --- a/docs/SHIELD/Deploy/index.md +++ b/docs/SHIELD/Deploy/index.md @@ -29,9 +29,7 @@ flowchart TD

-SHIELD's Deploy module provides the foundation for a secure environment using Microsoft's **Securing Privileged Access (SPA)** architecture. This module automates the provisioning of security-critical components such as identity boundaries, privileged access zones, Conditional Access policies, and more. - - +SHIELD's Deploy module provides the foundation for a secure environment using Microsoft's **Securing Privileged Access (SPA)** architecture. This module automates the provisioning of security-critical components such as identity boundaries, privileged access zones, Conditional Access policies, and more. ## What Is SPA? @@ -103,7 +101,7 @@ By centralizing and automating the deployment of SPA, the Deploy module: ## Related Pages -- [Deployment Guide](../Getting-Started) +- [Overview and Installation Requirements](../Prerequisites/Installation) - [Deploy Usage Guide](Usage-Guide) - [Deploy Reference](Reference/) - [Troubleshooting Deploy Module](Troubleshooting) diff --git a/docs/SHIELD/Prerequisites/Installation.md b/docs/SHIELD/Prerequisites/Installation.md index ee83417..dc0b33f 100644 --- a/docs/SHIELD/Prerequisites/Installation.md +++ b/docs/SHIELD/Prerequisites/Installation.md @@ -6,51 +6,116 @@ SHIELD is a self-hosted application deployed in a customer’s Azure App Service !!! info "Security Considerations" While this application requires sensitive permissions to conduct the automated scan, by self-hosting the application, SHI does not represent a supply chain risk or path to compromise a customer environment via the SHIELD platform, as there is no control maintained beyond the initial point of installation. All code being run to conduct the automated discovery is available for code and security reviews prior to engagement upon request. Permissions exist for both the user initiating the report and the application itself. Code review is available upon request. + --- -## Networking Requirements +## Installation Prerequisites + +### Disable Network Traffic Inspection + +Network traffic inspection must be turned off for SHIELD and Microsoft endpoints on the device installing SHIELD. Major cloud service providers do not allow network traffic inspection of their services and SHIELD relies on Microsoft Azure networking. If inspection is not disabled, SHIELD will not install or function properly. -For a smooth installation, network traffic inspection must be disabled on the device installing SHIELD. If inspection is enabled, Microsoft will drop the traffic, and SHIELD will not function properly. This includes tools like Palo, Zscaler, or nginx (caching). Traffic inspection must be excluded from network inspection according to Microsoft's terms and conditions. For more information, see [Microsoft Documentation](http://aka.ms/pnc){:target="_blank"}. +Every organization uses different equipment and processes, so the steps to disable inspection will vary. -If you require assistance, please reach out to your networking team, security team, or the person in charge of information technology at your organization. For more information about traffic inspection, see [Network Traffic Inspection](./Network-Traffic-Inspection). +**How to Proceed**: -- Add the following network endpoints to the inspection exclusion list: +- If you’re not sure how to disable network traffic inspection, please contact your networking team, security team, or the person in charge of information technology at your organization. +- You can also share the following network endpoints with your networking team to have the addresses excluded from inspection: +Add the following network endpoints to the inspection exclusion list - `https://api.shilab.com` - `https://url.shilab.com` - `https://*.azurewebsites.net` - *Your specific deployment URL (generated after deployment)* +**Common Network Traffic Inspection Technologies** + +- **Firewalls** (Palo Alto, Fortinet, Cisco) +- **Secure Web Gateways (SWG) & Proxies** (Zscaler, ProxySG) +- **Cloud Access Security Brokers** (Netskope, Microsoft Defender for Cloud Apps) +- **Data Loss Prevention (DLP)** (Microsoft Purview DLP, Symantec DLP) +- **WAN Acceleration and Optimization** (Riverbed, Cisco WAAS, nginx caching) +- **VPN & Traffic Redirection** (VPN gateways, SASE platforms) + +For more information about traffic inspection, see [Network Traffic Inspection](./Network-Traffic-Inspection). + --- -## Installation Instructions +### Create a Dedicated Azure Subscription -!!! info "SHIELD Installation Has Changed" - The **SHIELD - Desktop** application is now the preferred method, for faster and easier installation.

- **Why?** The desktop application automates most steps, making setup much simpler.

- **Manual Installation**: If you prefer the manual method, please reach out to an SHI employee for guidance and support +1. Sign in to your Azure portal. + - **Enterprise**: [https://portal.azure.com/](https://portal.azure.com/){:target="_blank"} + - **Government**: [https://portal.azure.us/](https://portal.azure.us/){:target="_blank"} +2. Navigate to **Subscriptions** and click **+ Add**. +3. If applicable, choose an offer type from the options provided. **Enterprise Agreement (EA) customers** typically do not have to select an offer type. +4. Enter a name for the subscription (e.g., "SHIELD – Production") or similar. +5. **Enterprise Agreement (EA) customers**: Assign a billing account and confirm creation. +--- -### SHIELD - Desktop's Installer Module +### Global Administrator + +The user installing SHIELD must be a **Global Administrator** in order to grant Microsoft Graph application permissions via admin consent. For more information about permissions, see [Application Permissions](./Application-Permissions). + +1. Sign in to your Entra ID admin center. + - **Enterprise**: [https://entra.microsoft.com/](https://entra.microsoft.com/){:target="_blank"} + - **Government**: [https://entra.microsoft.us/](https://entra.microsoft.us/){:target="_blank"} +2. Navigate to **Roles & admins**. +3. Search for and click on the **Global Administrator** role. +4. If the user deploying SHIELD is already assigned the **Global Administrator** role, no additional action is required. If a user needs to be assigned the **Global Administrator** role, follow the steps below: + 1. At the top, click **+ Add Assignments**. + 2. Click the link under **Select member(s)**. + 3. Check the box next to the desired user and click **Select**. You can also use the search bar if needed. + 4. Select your desired settings. We recommend the following: + - Assignment type: **Active** + - Permanently eligible: Uncheck + - Assignment duration: 24-48 hours + 5. Click **Assign**. -1. Create a new Azure subscription dedicated to SHIELD (recommended for isolation). -2. You must have: - - **Global Administrator** or **Privileged Role Administrator** (to grant Microsoft Graph application permissions via admin consent). For more information about permissions, see [Application Permissions](./Application-Permissions). - - `Owner` on the Azure subscription (to deploy resources) -3. If you haven't already done so, turn off network traffic inspection on the device installing SHIELD, so there are no interruptions during installation. If you require assistance with this step, please see [Networking Requirements](#networking-requirements) above. -4. Run the installer to set up SHIELD automatically using the following link: [https://url.shilab.com/shield-install](https://url.shilab.com/shield-install) - - **Note**: The download will not work if network traffic inspection is enabled, especially in Microsoft/Azure environments. +--- + +### Azure Subscription Owner + +Make sure the user installing SHIELD is the the **Owner** on the Azure subscription in order to deploy resources. + +1. Sign in to your Azure portal. + - **Enterprise**: [https://portal.azure.com/](https://portal.azure.com/){:target="_blank"} + - **Government**: [https://portal.azure.us/](https://portal.azure.us/){:target="_blank"} +2. Navigate to **Subscriptions** and select the subscription to be used with SHIELD. +3. Click **Access control (IAM)** in the left navigation bar. +4. Click on the **Role assignments** tab. +5. If the user deploying SHIELD is already assigned the **Owner** role of the subscription, no additional action is required. If a user needs to be assigned the **Owner** role, follow the steps below: + 1. At the top, click **+ Add** and click **Add role assignment** in the drop-down menu. + 2. Click on the **Privileged administrator** roles tab. + 3. Click on the **Owner** role so it is highlighted and click **Next**. + 4. Click **+ Select members**, click on the desired user account, and click **Select**. + 5. Click **Next**. + 6. Select **Allow user to assign all roles (highly privileged)**. + 7. Click **Next**. + 8. If applicable, select your desired Assignment type settings. We recommend the following: + - Assignment type: **Active** + - Assignment duration: **Permanent** + 9. Once finalized, click **Review + assign**. + 10. (Optional) Confirm the role appears in the **Role assignments** tab. -### Install and Deploy SHIELD Discover +--- +## Install and Deploy SHIELD Discover -1. After installation, launch the SHIELD - Desktop application. -2. Log in using the account manager in the top right corner. Be sure to log in with the account that has the necessary `Owner` and `Global Admin` permissions in Azure. These are required to grant the necessary permissions for deployment. +!!! info "SHIELD Installation Has Changed" + The **SHIELD - Desktop** application is now the preferred method, for faster and easier installation.

+ **Why?** The desktop application automates most steps, making setup much simpler.

+ **Manual Installation**: If you prefer the manual method, please reach out to an SHI employee for guidance and support. + +0. Run the installer to set up SHIELD automatically using the following link: [https://url.shilab.com/shield-install](https://url.shilab.com/shield-install) + - **Note**: The download will not work if network traffic inspection is enabled, especially in Microsoft/Azure environments. +1. After installation, launch the SHIELD - Desktop application. +2. Log in using the account manager in the top right corner. Be sure to log in with the account that has the necessary **Owner** and **Global Administrator** permissions in Azure. These are required to grant the necessary permissions for deployment. 3. After you are successfully logged in, click on the **Installer** module. - **Note**: An additional tab may open, and another log in may be required. -4. Select the **Azure Subscription** that is dedicated for SHIELD. -5. Select your desired **Azure Region** from the drop-down menu. **West US 3** is recommended, but other regions can be selected depending on company policy. +4. Select the **Azure Subscription** that is dedicated for SHIELD. +5. Select your desired **Azure Region** from the drop-down menu. **West US 3** is recommended, but other regions can be selected depending on company policy. 6. Click on the toggle switch to display **Advanced Options**. -7. For **Operation Mode**, select **Discover** from the drop-down menu. -8. Click on the **Deploy** button for the SHIELD installer to begin the installation process. +7. For **Operation Mode**, select **Discover** from the drop-down menu. +8. Click on the **Deploy** button for the SHIELD installer to begin the installation process. - **Note**: An additional tab may open, and another log in may be required. 9. The installer will do the following: - Download the SHIELD Deploy ZIP file @@ -60,19 +125,30 @@ If you require assistance, please reach out to your networking team, security te - `Application.ReadWrite.All` - `AppRoleAssignment.ReadWrite.All` 11. Lastly, assign the Read and Write Everything role to the user who will run SHIELD scans via the "SHIELD End User Login" enterprise app in Entra. - - -### Running the SHIELD Web Instance - + 1. Sign in to your Entra ID admin center. + - **Enterprise**: [https://entra.microsoft.com/](https://entra.microsoft.com/){:target="_blank"} + - **Government**: [https://entra.microsoft.us/](https://entra.microsoft.us/){:target="_blank"} + 2. Navigate to **Enterprise apps** in the navigation bar. + 3. Clear out the **Enterprise Applications** filter. + 4. Search for 'SHIELD End User Login' and click on the name of the application. + 5. Click **Users and groups** in the left navigation bar. + 6. Click **+ Add user/group**. + 7. Click the link under **Users and groups**. + 8. Check the box next to the desired user and click **Select**. You can also use the search bar if needed. + 9. Click on the link under **Select a role**. + 10. Search for 'Read and Write Everything', click on the name of the role, and click **Select**. + 11. Click **Assign**. + +## Running the SHIELD Web Instance 1. Navigate to your SHIELD web instance in your browser: [https://portal.azure.com/](https://portal.azure.com/){:target="_blank"} 2. Click **Resource groups**. 3. Click **SHIELD**. 4. Click on the App Service that starts with "shield-xxxxxxxxx" (the x's are a random set of lower-case letters and numbers). 5. In the top right corner, click on the **Default domain** link. **Example**: shield-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.eastus-01.azurewebsites.net -6. Log in to the SHIELD web instance with the account that has the necessary Azure permissions. +6. Log in to the SHIELD web instance with the account that has the necessary Azure permissions. 7. Click on **Discover Module**. -8. Click **Start Authentication Sync**. Then click **Start Report Collection** to start scanning the tenant environment. +8. Click **Start Authentication Sync**. Then click **Start Report Collection** to start scanning the tenant environment. 9. During the first scan, SHIELD - Desktop will open and request account credentials multiple times. Log in each time as required. You will also need to accept each set of permissions. -10. Once the scan is complete, reports are available on the SHIELD web instance. - 1. Click **Discover** in the left navigation pane and click **Overview**. \ No newline at end of file +10. Once the scan is complete, reports are available on the SHIELD web instance. + 1. Click **Discover** in the left navigation pane and click **Overview**. diff --git a/docs/SHIELD/Prerequisites/index.md b/docs/SHIELD/Prerequisites/index.md index c1339f4..32ceccc 100644 --- a/docs/SHIELD/Prerequisites/index.md +++ b/docs/SHIELD/Prerequisites/index.md @@ -6,7 +6,7 @@ Before deploying SHIELD or using Discover, ensure your environment meets all lic ## Pricing -### Azure Cost Estimate Associated (as of 7/28/2026): +### Azure Cost Estimate Associated (as of 7/28/2026) | User Count | Premium v4 Service Plan | vCPU(s) | RAM | Storage | Pay as you go | 1 year savings plan | 3 year savings plan | 1 year reserved | 3 year reserved | | -------------- | ----------------------- | ------- | ---- | ------- | ----------------- | ------------------------------- | ------------------------------- | ------------------------------- | ------------------------------- | @@ -38,22 +38,22 @@ SHIELD automates secure deployment and lifecycle management using Microsoft 365 #### SHI Lab Azure Architecture -- Regulatory compliance standards: [https://servicetrust.microsoft.com/](https://servicetrust.microsoft.com/){:target="_blank"} -- Encryption at rest (mandatory) -- Encryption in transit (mandatory) +- Regulatory compliance standards: [https://servicetrust.microsoft.com/](https://servicetrust.microsoft.com/){:target="_blank"} +- Encryption at rest (mandatory) +- Encryption in transit (mandatory) - Quantum resistant algorithms only - Latest TLS version for resource only -- CRUD Audit +- CRUD Audit - SQL Audit is enabled too -- Access Audit (Mandatory) -- Full micro-segmentation (address/port enforcement for all resources) -- Data-store behind API, no internet access -- SSO Access Only (no cred vaulting workarounds, pure modern SSO, credential-less only) -- MFA for all authentication is mandatory -- Human-free production-only design +- Access Audit (Mandatory) +- Full micro-segmentation (address/port enforcement for all resources) +- Data-store behind API, no internet access +- SSO Access Only (no cred vaulting workarounds, pure modern SSO, credential-less only) +- MFA for all authentication is mandatory +- Human-free production-only design - Access to the Production environment is limited to only highly critical incidents. -- Debug access is severely limited -- No Operating Systems +- Debug access is severely limited +- No Operating Systems - Pure Serverless - Always up to date - No custom execution except for designed workload (no viruses possible) @@ -63,16 +63,16 @@ SHIELD automates secure deployment and lifecycle management using Microsoft 365 #### Miscellaneous Considerations -- No customer data is used in any environment except for production -- Environment is only production only, reducing surface area of attack +- No customer data is used in any environment except for production +- Environment is only production only, reducing surface area of attack - No dev or test environments - Prod only via ring deployment and feature flags -- All tooling can run locally so that no production access is required for testing, development and debugging -- No on-premise systems, all resources are cloud only including end user compute/systems -- Hardware supply chain is strictly enforced -- Surface devices are only allowed at all levels of end user compute -- Firmware credentials are set to cert auth on all endpoints -- Device source code available for review: [https://microsoft.github.io/mu/](https://microsoft.github.io/mu/){:target="_blank"} +- All tooling can run locally so that no production access is required for testing, development and debugging +- No on-premise systems, all resources are cloud only including end user compute/systems +- Hardware supply chain is strictly enforced +- Surface devices are only allowed at all levels of end user compute +- Firmware credentials are set to cert auth on all endpoints +- Device source code available for review: [https://microsoft.github.io/mu/](https://microsoft.github.io/mu/){:target="_blank"} --- @@ -105,10 +105,10 @@ serviceConfiguration-->|Object IDs with associated Scopes reported to Data Gatew SHIELD Discover collects the following data: -- Tenant ID -- Principal ID that saved the report -- Principal ID that ran the report -- Principal Object ID +- Tenant ID +- Principal ID that saved the report +- Principal ID that ran the report +- Principal Object ID - Assigned License – The Service Plan IDs of the license(s) that are assigned (direct or indirect) to the specific principal - Assigned Services – The service configuration assignment determining 'benefitting' from a service. This includes the service configuration type if possible (feature, such as 'Conditional Access,' a service within the Entra ID license) - Consumed Services – Usage telemetry retrieved to indicate if the specific principal is consuming/using the service, regardless of license status @@ -164,4 +164,4 @@ docs\SHIELD\Reference\Plugins\DefenderEndpoint ## Related Pages - 📄 [Hardware Requirements](../Defend/Reference/Hardware-Selection) -- 📄 [Deployment Guide](../Getting-Started) +- 📄 [Overview and Installation Requirements]v diff --git a/docs/SHIELD/Usage-Guide.md b/docs/SHIELD/Usage-Guide.md index 4ec7e91..39781c7 100644 --- a/docs/SHIELD/Usage-Guide.md +++ b/docs/SHIELD/Usage-Guide.md @@ -19,7 +19,7 @@ These are deployed via the SHIELD UI at `{your-subdomain}.azurewebsites.net` usi !!! note "Immutable Components" Security groups, scope tags, and admin units cannot be changed after deployment. All other settings can be modified afterward. -📖 For step-by-step deployment instructions, see the [Deployment Guide](./Getting-Started) +📖 For step-by-step deployment instructions, see the [Overview and Installation Requirements](./Prerequisites/Installation) --- diff --git a/docs/assets/Images/Screenshots/MI-columns-dark.png b/docs/assets/Images/Screenshots/MI-columns-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..bb4b749b6ca97e2a8ca49b932fd6aa0077c9050b GIT binary patch literal 193149 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