Content update - #75
Conversation
jtdauria-shi
commented
Aug 14, 2026
- Onboarding documentation
- Policy structure
- Update Zensicle
Updated installation, prereqs, network inspection, & app permissions to enhance customer onboarding and converted multiple policy pages into a single page
…tallationUpdates Updated customer onboarding + policy structure
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Warning Review the following alerts detected in dependencies. According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR updates SHIELD documentation structure by reorganizing the nav, replacing the old “Required Graph API Permissions” doc with a new “Application Permissions” page, consolidating Conditional Access policy docs into a single “Entra Conditional Access” reference page, and bumping the zensical version used to build the site.
Changes:
- Updated
zensical.tomlnav to reflect new prerequisite pages and a new “Policies” section under Deploy reference. - Replaced the removed “Required Graph API Permissions” page with a new “Application Permissions” page and updated an internal link.
- Consolidated many Conditional Access policy pages into
Entra-Conditional-Access.mdand updated the docs tool version inrequirements.txt.
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| zensical.toml | Updates site navigation to new prerequisites and the new Deploy → Reference → Policies structure. |
| requirements.txt | Bumps zensical from 0.0.51 to 0.0.53. |
| docs/SHIELD/Reference/Settings/Configure-Managed-Identity.md | Updates the permissions doc link to point to the new page. |
| docs/SHIELD/Prerequisites/Required-Graph-API-Permissions.md | Removes the old permissions page. |
| docs/SHIELD/Prerequisites/Network-Traffic-Inspection.md | Adds a new prerequisite page describing network traffic inspection constraints. |
| docs/SHIELD/Prerequisites/Installation.md | Rewrites installation/onboarding steps and networking requirements text. |
| docs/SHIELD/Prerequisites/index.md | Expands prerequisites landing page with pricing/security/data-structure content and reorganized sections. |
| docs/SHIELD/Prerequisites/Application-Permissions.md | Adds the replacement permissions page and permission tables. |
| docs/SHIELD/Deploy/Reference/Policies/Entra-Conditional-Access.md | Adds consolidated Conditional Access policy documentation. |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/User-Risk.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Token-Binding.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Sign-In-Risk.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Session-Persistence.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/OS-Enforcement.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/MFA.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Location.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Legacy-Auth.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Join-Type.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Hardware-Enforcement.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Disable-CA-Resilience-Downgrade.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Compliance.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Block-Non-Priv.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Privileged/Conditional-Access/Authentication-Methods.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Enterprise/Conditional-Access/MFA.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Enterprise/Conditional-Access/MDCA.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Enterprise/Conditional-Access/Location.md | Removes legacy per-policy page (now consolidated). |
| docs/SHIELD/Deploy/Reference/Architecture/SHIELD/Enterprise/Conditional-Access/Compliance.md | Removes legacy per-policy page (now consolidated). |
Suppressed comments (2)
docs/SHIELD/Prerequisites/Application-Permissions.md:89
- Same admonition formatting issue as above: the unindented blank line after
!!! notemay break rendering (and turn the following indented text into a code block).
!!! note
`Policy.Read.All` is necessary due to a known issue with the current Graph API, in the future `Policy.ReadWrite.ConditionalAccess`/`Policy.Read.ConditionalAccess` will be all that is necessary.
See this link for Microsoft's official statement: [Graph API Known Issues Portal](https://developer.microsoft.com/en-us/graph/known-issues/?search=13671)
docs/SHIELD/Prerequisites/Application-Permissions.md:80
- Typo: “license lability” should be “license liability”.
| [`SecurityIdentitiesAccount.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#securityidentitiesaccountreadall){:target="_blank"} | ✅ | Used in Discover to measure the Defender for Identity license lability. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| !!! note | ||
|
|
||
| Permissions marked with '✅' are assigned by SHIELD to itself. Permissions marked as '❌' have to be assigned by an admin ahead of time. |
| The PowerShell app will graphically list all the managed identities, let you select one, then graphically list all the Graph API permissions you can assign it. | ||
| Assign the permissions listed here: | ||
| [Required Graph API Permissions](../../Prerequisites/Required-Graph-API-Permissions) | ||
| [Required Graph API Permissions](../../Prerequisites/Application-Permissions) |
| ## Overview | ||
|
|
||
| This application is a self-hosted application that exists in the customer tenant on an Azure App Service, collecting and processing the requisite data only within the customer tenant before provided abstracted & fully anonymized data results back to SHI for reporting. All requirements can be set up by the delivery team or customer prior to engagement. | ||
| SHIELD is a self-hosted application deployed in a customer’s Azure App Service tenant. SHIELD collects and processes all necessary data exclusively within the customer’s environment, then returns only abstracted and fully anonymized results back to SHI for reporting. All requirements can be set up by the delivery team or customer prior to engagement. This guide explains how to install the SHIELD - Desktop application and run your first scan. For more information about requirements, pricing, and more, see [Prerequisites](/SHIELD/Prerequisites). |
| - According to [Microsoft Documentation](http://aka.ms/pnc){:target="_blank"}, Traffic Inspection of any kind via a tool like Palo, Zscaler, or nginx (caching) violates Microsoft's Terms & Conditions (as well as each major cloud provider) as traffic that was decrypted and is heading to Microsoft is indistinguishable from man in the middle attacks. | ||
| - As a result, all traffic inspected is promptly dropped by Microsoft. As we rely on Azure Networking for SHIELD to run, this prevents SHIELD from functioning. | ||
| - Please validate that **ALL** Microsoft traffic is excluded from any form of Network Inspection: this is a requirement for SHIELD to function, as it is against Microsoft's terms and conditions. | ||
| 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"}. |
| | [`IdentityRiskEvent.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#identityriskeventreadall){:target="_blank"} | ✅ | Used in Discover to evaluate the license liability for Entra ID Identity Protection. | | ||
| | [`IdentityRiskyUser.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#identityriskyuserreadall){:target="_blank"} | ✅ | Used in Discover to evaluate the license liability for Entra ID Identity Protection. | | ||
| | [`Policy.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#policyreadall){:target="_blank"} and [`Policy.ReadWrite.ConditionalAccess`](https://learn.microsoft.com/en-us/graph/permissions-reference#policyreadwriteconditionalaccess){:target="_blank"} | ✅ | Used to manage the conditional access policies for individual users during the lifecycle management and for when the initial deployment occurs to implement health checks, and identity partitioning. | | ||
| | [`SecurityIdentitiesAccount.Read.All`](https://learn.microsoft.com/en-us/graph/permissions-reference#securityidentitiesaccountreadall){:target="_blank"} | ✅ | Used in Discover to measure the Defender for Identity license lability. | |