diff --git a/docs/Data-Gateway/Architecture/Infrastructure.md b/docs/Data-Gateway/Architecture/Infrastructure.md index c65d343..de1ce8f 100644 --- a/docs/Data-Gateway/Architecture/Infrastructure.md +++ b/docs/Data-Gateway/Architecture/Infrastructure.md @@ -1,39 +1,183 @@ -# Infrastructure Diagram +# Infrastructure -The below is the logical infrastructure interaction of the core Discover engine. -Each plugin interacts with the specific service configuration that is being interpreted. +This page describes how Data Gateway is composed and how the core services interact within SHI Cloud. -## Diagram +--- + +## Platform topology ```mermaid -flowchart BT -subgraph shiLab["SHI Lab - Trust Boundary"] - AppService{{"Data Gateway"}} - SqlDb[("General Data
(SQL DB)")] - BulkData(["Bulk Data
(Storage Blob)"]) - UpdateData(["Update Data
(Storage Blob + Table)"]) -end -subgraph microsoftGlobal["Microsoft Global"] - entraId{"Entra ID"} - shiLab -end -subgraph clientEnvironment["Client Environment"] - client[/"REST API Client"\] -end - -AppService --> entraId -AppService -- CRUD Operation + Token --> SqlDb -AppService -- CRUD Operation + Token --> BulkData & UpdateData -BulkData <-- Validate Auth of CRUD Operation --> entraId -SqlDb <-- Validate Auth of CRUD Operation --> entraId -entraId -- Public Keys --> AppService -entraId <-- Log into Entra ID --> client -AppService -- "CRUD Operation + Token. Response included." --> client -UpdateData <-- Validate Auth of CRUD Operation --> entraId +flowchart TD + + %% Entra ID Trust Boundary + subgraph CustomerTrustBoundary[Customer Environment] + Client(["API Client/SDK"]) + Users([Users]) + end + + %% Entra ID Trust Boundary + subgraph EntraTrustBoundary[Microsoft Global Cloud] + Entra{"Entra ID (IDP)"} + end + + %% GitHub Trust Boundary + subgraph GitHubTrustBoundary[GitHub Pages] + Dashboard((Data Gateway UI)) + end + + %% SHI Cloud trust boundary + subgraph ShiTrustBoundary[SHI Cloud] + direction LR + + API{{Data Gateway API}} + + %% Data services + subgraph DataStorage[Data Services] + direction TB + AzSql[("Relational Data (Azure SQL DB)")] + GeneralBlob[/"Bulk data (Azure Blob)"\] + UpdateBlob[/"Update packages (Azure Blob)"\] + AzTable[["Update config (Azure Table)"]] + OpenAi(["LLM Service (Azure OpenAI)"]) + end + end + + %% Relationships + Users --> | HTTPS | Dashboard + Client --> | Public/Secret Client Auth | Entra + Entra --> | Auth Code/Access Tokens | Client + Client --> API + Dashboard --> | Public Client Auth | Entra + Entra --> | Auth Code/Access Tokens | Dashboard + Dashboard --> | HTTPS + JWT | API + API --> | TDS + JWT | AzSql + API --> | HTTPS + JWT | GeneralBlob + API --> | HTTPS + JWT | UpdateBlob + API --> | HTTPS + JWT | AzTable + API --> | HTTPS + JWT | OpenAi ``` -## Threat Model +!!! note "Key points" + - **Identity** - Entra ID is the only identity provider. The UI authenticates users and calls the API with bearer tokens. + - **Data access** - All reads/writes are brokered by the API: + - **Azure SQL Database** for processed relational data + - **Azure Blob Storage** for bulk reports and update packages + - **Azure Table Storage** for update service configuration + - **LicenseGPT** - Chat interactions are transient. Prompts are sent to the API and responses are returned in-session, never stored. + +## SHIELD Update Service + +Data Gateway controls update delivery using **channels** (e.g., stable, beta, alpha) and **rings** (e.g., ring 0, ring 1). Configuration is stored in **Azure Table Storage**; package files are stored in **Azure Blob Storage**. + +### Example Channel Configuration + +The below channel configuration demonstrates how the update system can be configured where various tenants are assigned by default to a ring in a channel. +The tenant's default channel can be overridden by API call. If this happens it defaults to ring 0 on the other channel. +In the below diagram, the channel is not named, all channels follow the below architecture. +There can be an unlimited number of rings in a channel. `N...` represents all numbers above 1. + +The Alpha channel is RBAC gated and is not available by default. SHI has to approve Alpha access per-tenant. + +```mermaid +flowchart TD + +%% Tenant Configs +CxTenant1[/Tenant 1\] +CxTenant2[/Tenant 2\] +CxTenant3[/Tenant 3\] +DevTenant1[/Dev Tenant 1\] +DevTenant2[/Dev Tenant 2\] + +%% Channel Example + subgraph Channel["Channel"] + Ring0(("Ring 0
Latest")) + Ring1(("Ring 1
Latest")) + RingN(("Ring N...
Previous")) + end + +%% Available Versions +Versions["Latest: 3.0.0
Previous: 2.5.0"] + +%% Relationships +Versions --> Channel +Ring0 --> CxTenant1 +Ring1 --> CxTenant2 +RingN --> CxTenant3 +Ring0 --> DevTenant1 +Ring0 --> DevTenant2 +``` + +### Data Flow + +The below chart demonstrates how the data storage systems relate to each other and how the configurations flow to Data Gateway. + +```mermaid +flowchart LR + + %% Tenant and API + Client([SHIELD]) + API{{Data Gateway API}} + + %% Configuration in Table Storage + subgraph AzureTableStorage[Azure Table Storage] + ChannelConfig[["Channels"]] + RingConfig[["Rings"]] + TenantConfig[["Tenant config"]] + end + + %% Packages in Blob + PackageStorage[/"Update Packages (Azure Blob)"\] + + %% Relationships + Client --> | Request Version | API + API --> | Request Config | TenantConfig + TenantConfig --> | Default channel, Ring, Alpha allowed | API + API --> | Request Config | ChannelConfig + ChannelConfig --> | Latest Version, Previous Version | API + API --> | Request Config | RingConfig + RingConfig --> | Is Latest Available | API + API --> | Request Package | PackageStorage + PackageStorage --> | Package Stream | API + API --> | Version or Package Stream | Client +``` + +### Update Selection Process + +1. Tenant defaults define which channel and ring are used, and whether alpha builds are allowed. +2. If you explicitly request a channel and it's permitted, the API applies it; otherwise the tenant default applies. +3. The ring setting (latest or previous) determines the version within that channel. +4. The API returns the resolved version and streams the corresponding package from Blob Storage. + +### Data Flow Lifecycle + +1. **Authenticate** - The UI authenticates with Entra ID and receives a token. +2. **Authorize** - The UI calls the API over HTTPS with the JWT. +3. **Process** - The API validates the token and performs reads/writes against SQL, Blob, or Table Storage. +4. **Respond** - The API returns data or confirmation. +5. **Render** - The UI presents the result to the user. *(LicenseGPT chat is not stored.)* + +### Security and Reliability + +- **Identity** - Entra ID is the single identity provider. +- **Transport** - All calls use HTTPS. +- **Isolation** - Clients never access data stores directly; all access is via the API. +- **Controlled rollout** - Channels and rings enable predictable, staged updates. +- **Resilience** - Operations are designed to handle transient faults. + +### Component Map + +| Component | Backing service(s) | Role | +|---------------------|---------------------------------|----------------------------------------------------------------------| +| Data Gateway UI | Web Browser, [GitHub Pages](https://docs.github.com/en/pages) | Entry point for user interactions (Tenant Manager, LicenseGPT) | +| Data Gateway API | HTTPS, [Entra ID auth](https://learn.microsoft.com/en-us/entra/identity-platform/application-model#multitenant-apps) | Authenticates tokens and brokers access to data stores | +| Processed Data | [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database) | Relational/reporting data; tenant metadata | +| Bulk report Data | [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/) | JSON/report payloads | +| Update Packages | [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/) | Versioned package archives | +| Update Config | [Azure Table Storage](https://learn.microsoft.com/en-us/azure/storage/tables/) | Channels, rings, and tenant update settings | +| LicenseGPT | [Azure OpenAI Services](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/overview) | Provides LLM and Embeddings to the Data Gateway service | -For an annotated threat model of the application's infrastructure architecture, please see the attached Microsoft [Threat Model Tool](https://aka.ms/tmt) representation of the infrastructure architecture. +## See also -📄 [Data Gateway - Threat Model](../assets/threat-models/Data-Gateway.tm7) +- [Usage Guide](../Usage-Guide/index.md) +- [Threat Model](../assets/threat-models/Data-Gateway.tm7) +- [API Reference](https://specs.shilab.com) diff --git a/docs/Data-Gateway/Architecture/index.md b/docs/Data-Gateway/Architecture/index.md new file mode 100644 index 0000000..6fc6c50 --- /dev/null +++ b/docs/Data-Gateway/Architecture/index.md @@ -0,0 +1,5 @@ +# Architecture + +The Architecture section describes how Data Gateway is structured, including trust boundaries, components, and service interactions. + +- [Infrastructure](Infrastructure.md) diff --git a/docs/Data-Gateway/Deployment/index.md b/docs/Data-Gateway/Deployment/index.md new file mode 100644 index 0000000..7f50010 --- /dev/null +++ b/docs/Data-Gateway/Deployment/index.md @@ -0,0 +1,24 @@ +# Deployment + +The Data Gateway service does not require installation in your tenant. +The service is hosted by SHI and is available directly via the UI and API. + +## Permission Grants + +The Data Gateway SaaS requires that permissions be granted before you can access the app. +To grant permissions to a principal in your tenant, please register the `SHI - Data Gateway` app so that SSO is enabled by navigating to the following URL: + +- + +!!! note + To register this app, you may require the [Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) role or higher in your tenant depending on the admin consent settings configured. + +When the app is registered, you will see an Enterprise App that has the name of `SHI - Data Gateway` with the Client ID of `4c40281b-a305-4aaf-90a4-d5bbee6eb8ed`. +This enterprise app allows principals in your tenant to be able to generate Access Tokens (JWT) and make API calls to the Data Gateway service. +This enterprise app does not allow the Data Gateway service to connect into your tenant. + +## Getting Started + +- Sign in with your Entra ID account. +- Navigate the [Usage Guide](../Usage-Guide/index.md) for common tasks. +- See [Reference](../Reference/index.md) for API integration details. diff --git a/docs/Data-Gateway/Reference/index.md b/docs/Data-Gateway/Reference/index.md new file mode 100644 index 0000000..683d74d --- /dev/null +++ b/docs/Data-Gateway/Reference/index.md @@ -0,0 +1,76 @@ +# Reference + +This page is a hub for the **Data Gateway** reference material: how to authenticate, where to find the live API documentation, and a quick tour of the most-used endpoint families. + +## Quick links + +
+ +- :rocket: **Getting Started** + Sign in, navigate the UI, and complete common tasks. + [:octicons-arrow-right-24: Usage Guide](../Usage-Guide/index.md) + +- :triangular_ruler: **Architecture** + Trust boundaries, components, and service interactions. + [:octicons-arrow-right-24: Infrastructure](../Architecture/Infrastructure.md) + +- :gear: **API Reference (Swagger)** + Browse the live OpenAPI reference and try requests in your browser. + [:octicons-link-24: specs.shilab.com](https://specs.shilab.com) + +
+ +## Authentication + +Data Gateway uses **Entra ID** (Microsoft identity platform) for authentication. +All requests must include a valid **JSON Web Token (Bearer/Access Token)** in the `Authorization` header. + +### Steps + +1. Sign in with your organization's Entra ID principal to obtain an access token for the Data Gateway application. +2. Include the token in each API request: + +```bash +curl -sS https://api.shilab.com/datagateway/status \ + -H "Authorization: Bearer " \ + -H "Accept: application/json" +``` + +### Notes + +- Tokens are validated by the API; users do **not** access SQL or Storage directly. +- Tokens expire; refresh them using your chosen auth flow (authorization code, client credentials, etc.). +- LicenseGPT prompts and responses are **not persisted** - the API returns results to the UI for the current session. + +## Endpoint Families + +| Family | Purpose | Typical methods | Common paths* | +|---|---|---|---| +| **Health & metadata** | Service liveness and basic info | `GET` | `/Api/Core/Health` | +| **Tenants** | Read and maintain tenant metadata (display name, parent association) | `GET`, `PATCH` | `/Api/Tenant`, `/Api/Tenant/{tenantId}` | +| **LicenseGPT** | AI-assisted licensing & compliance analysis | `POST` | `/Api/Chat/LicenseGpt` | +| **Updates (channels & rings)** | Resolve version and retrieve update package | `GET` (and streaming) | See Swagger (“Updates”) | + +\* For the complete, authoritative list (parameters, schemas, and responses), use the live reference at **[specs.shilab.com](https://specs.shilab.com)**. + +## Request & Response Basics + +- **Protocol:** HTTPS only +- **Content type:** `application/json; charset=utf-8` (unless explicitly streaming binaries) +- **Date/time:** ISO 8601 in UTC unless stated otherwise +- **Pagination/filters:** When applicable, filter and paging parameters are documented per endpoint in Swagger + +## Error handling + +The API uses standard HTTP status codes with JSON error payloads. Please see [MDN - Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) for more details on specific codes and how they should be interpreted. + +!!! note + The response body typically includes an explanatory message; consult Swagger for exact schemas. + +--- + +## See also + +- [Usage Guide](../Usage-Guide/index.md) +- [Infrastructure](../Architecture/Infrastructure.md) +- [API Reference (Swagger)](https://specs.shilab.com) diff --git a/docs/Data-Gateway/Troubleshooting.md b/docs/Data-Gateway/Troubleshooting.md new file mode 100644 index 0000000..5fbfea0 --- /dev/null +++ b/docs/Data-Gateway/Troubleshooting.md @@ -0,0 +1,5 @@ +# Troubleshooting + +🚧 **This section is coming soon.** + +Guidance for diagnosing common Data Gateway issues will be published here. diff --git a/docs/Data-Gateway/Usage-Guide/index.md b/docs/Data-Gateway/Usage-Guide/index.md new file mode 100644 index 0000000..d6e698b --- /dev/null +++ b/docs/Data-Gateway/Usage-Guide/index.md @@ -0,0 +1,102 @@ +# Usage Guide + +The Data Gateway provides a unified interface for tenant and product data across SHI Cloud. +This guide describes the available modules, what they do, and how they map to backend services. + +--- + +## Overview + +With Data Gateway you can: + +- Run AI-assisted queries on licensing and compliance data +- Manage tenant metadata (rename, associate, disassociate) +- Retrieve processed relational data from **Azure SQL Database** +- Access bulk reports and update package data in **Azure Blob Storage** +- Automate these operations through the **public API** + +--- + +## Features + +### LicenseGPT + +- Conversational interface for licensing and compliance analysis +- Uses the API endpoint `POST /Api/Chat/LicenseGpt` +- Combines data from **Azure SQL Database** (processed relational data) and **Azure Blob Storage** (bulk + update packages) +- Can surface **agentic actions**, such as: + - Retrieve License Report + - Get Correlation IDs +- Designed for compliance validation and license usage insights without writing queries + +```mermaid +flowchart TB + User([User - Browser]) + UI["LicenseGPT (UI)"] + + subgraph DG["Data Gateway API"] + ChatEP{{"/Api/Chat/LicenseGpt"}} + end + + subgraph Data["Data Sources"] + SQL[("Azure SQL Database - Processed Data")] + Blob[/"Azure Blob Storage - Bulk & Updates"\] + end + + User --> UI + UI -->|Prompt| ChatEP + ChatEP --> SQL + ChatEP --> Blob + ChatEP -->|Response JSON| UI +``` + +!!! info "Use case" + LicenseGPT allows teams to validate license compliance without writing queries or exporting raw data. + It reduces manual effort by providing natural-language answers and direct report retrieval, ensuring faster insights for audits and optimization. + +--- + +### Tenant Manager + +- Displays tenant metadata: **Tenant ID**, **Display Name**, **Parent association** +- Supports three operations: + - **Rename** → PATCH `/Api/Tenant/{id}` to update the display name + - **Associate** → PATCH `/Api/Tenant/{id}` to set a parent tenant ID + - **Disassociate** → PATCH `/Api/Tenant/{id}` to clear the parent reference +- All operations persist to the backend database and are reflected in downstream reporting + +```mermaid +flowchart LR + UI["Tenant Manager (UI)"] --> API{{"Data Gateway API (/Api/Tenant)"}} + API --> SQL[("Azure SQL Database - Tenant Records")] +``` + +!!! info "Use case" + Tenant Manager ensures tenant data remains consistent and structured across SHI Cloud. + By maintaining correct naming and parent relationships, organizations avoid reporting errors and ensure accurate compliance analysis. + +--- + +## API Access + +For automation and integration, use the **public OpenAPI specification**: + +- **API Reference:** + +Key endpoints: + +- `POST /Api/Chat/LicenseGpt` - AI-assisted licensing queries +- `GET /Api/Tenant` - retrieve tenant metadata +- `PATCH /Api/Tenant/{tenantId}` - rename, associate, or disassociate tenants +- Endpoints for bulk report retrieval and update package resolution (see Swagger) +- `GET /Api/Core/Health` - health check + +All requests require authentication with **Entra ID tokens** passed as HTTPS bearer tokens, except for the health check. + +--- + +## Related Pages + +- [Architecture Overview](../Architecture/index.md) +- [Troubleshooting](../Troubleshooting.md) +- [API Reference](https://specs.shilab.com) diff --git a/docs/Data-Gateway/index.md b/docs/Data-Gateway/index.md index 3120a9a..3e693a5 100644 --- a/docs/Data-Gateway/index.md +++ b/docs/Data-Gateway/index.md @@ -1,5 +1,85 @@ -# Data Gateway +# SHI - Data Gateway -🚧 **This page is still under development.** +Data Gateway is SHI's secure data layer that unifies access to product and tenant information across SHI solutions. +It provides a single, trusted path for ingesting, storing, and retrieving the data that powers SHIELD and related services. +!!! tip "Who should read this?" + Admins, operators, and analysts who will use the Data Gateway UI or connect via the public API. +--- + +## What you can do + +Data Gateway helps you: + +- **Use the web UI** to explore tenant data and SHI experiences such as **Tenant Manager** and **LicenseGPT**. +- **Integrate via API** with SHI's services using the public OpenAPI/Swagger specification. +- **Authenticate securely** with your organization's Entra ID account to protect data access. +- **Ingest and retrieve reports** including license reports, entitlement data, and telemetry. +- **Manage updates** such as update packages and configuration channels stored in Azure Blob Storage. +- **Access processed relational data** in Azure SQL for compliance and reporting scenarios. + +--- + +## Explore Data Gateway + +
+- 🧭 **Getting Started** + Learn how to sign in, navigate the UI, and complete common tasks. + [:octicons-arrow-right-24: Usage Guide](./Usage-Guide/index.md) + +- 🏗️ **Architecture** + Understand the service layout, trust boundaries, and how Data Gateway connects to SHI Cloud. + [:octicons-arrow-right-24: Architecture Overview](./Architecture/index.md) + +- 🌐 **API Reference** + Browse the live API reference and try requests in your browser. + [:octicons-link-24: specs.shilab.com](https://specs.shilab.com) + +
+ +--- + +## Architecture Overview + +```mermaid +flowchart LR + %% ========================================================== + %% Data Gateway - High-level Architecture (Accessible + Modern) + %% Shapes communicate category: + %% External: ([ ... ]) Components: [ ... ] + %% Data store: [[ ... ]] AI assistant: (( ... )) + %% ========================================================== + + %% ---- External actors ---- + U([Users]) + IDP{"Entra ID (IDP)"} + + %% ---- SHI Cloud trust boundary ---- + subgraph CLOUD [SHI Cloud] + direction LR + + %% Core app components (rectangles) + UI[Data Gateway UI] + API{{Data Gateway API}} + + %% Data layer (double borders) + BLK[/Azure Blob Storage Bulk Data\] + UPD[/Azure Blob Storage Update Packages\] + SQL[(Azure SQL Database Processed Data)] + + %% AI assistant (circle) + LLM([LicenseGPT Azure OpenAI]) + end + + %% ---- Flows ---- + U -->| HTTPS | UI + UI -->| Public/Secret Client Auth Flow | IDP + IDP -->| Auth Code/Tokens | UI + UI -->| HTTPS + JWT | API + + API -->| Read Write | BLK + API -->| Read Write | UPD + API -->| ORM | SQL + API -->| LLM Calls | LLM +``` diff --git a/docs/SHIELD/Defend/Deployment.md b/docs/SHIELD/Defend/Deployment.md index a5921cf..9e4fece 100644 --- a/docs/SHIELD/Defend/Deployment.md +++ b/docs/SHIELD/Defend/Deployment.md @@ -1,6 +1,6 @@ # Deployment -The Defend module is deployed automatically as part of the SHIELD platform’s **Core Infrastructure deployment** process. It does not require any separate deployment scripts or packages. +The Defend module is deployed automatically as part of the SHIELD platform's **Core Infrastructure deployment** process. It does not require any separate deployment scripts or packages. This page clarifies when and how Defend becomes active, and what its dependencies are. @@ -56,4 +56,4 @@ To use Defend, the following must already be deployed: - [Defend Usage Guide](Usage-Guide/index.md) - [Defend Reference](Reference/index.md) - [Troubleshooting](Troubleshooting.md) -- [SHIELD Platform Deployment](../Getting-Started.md) \ No newline at end of file +- [SHIELD Platform Deployment](../Getting-Started.md) diff --git a/docs/SHIELD/Defend/Prerequisites.md b/docs/SHIELD/Defend/Prerequisites.md index cc285f8..d03719e 100644 --- a/docs/SHIELD/Defend/Prerequisites.md +++ b/docs/SHIELD/Defend/Prerequisites.md @@ -21,7 +21,7 @@ The Defend module relies on infrastructure that must be deployed via the Deploy ## Role-Based Permissions -To use Defend’s lifecycle functionality, the signed-in admin must have the following roles in Entra ID: +To use Defend's lifecycle functionality, the signed-in admin must have the following roles in Entra ID: | Role | Reason | |------|--------| @@ -63,4 +63,3 @@ To verify: - [Defend Usage Guide](Usage-Guide/index.md) - [Hardware Requirements](Reference/index.md) - [SHIELD Prerequisites](../Prerequisites/index.md) - diff --git a/docs/SHIELD/Defend/Reference/index.md b/docs/SHIELD/Defend/Reference/index.md index 8e9381a..00aeb19 100644 --- a/docs/SHIELD/Defend/Reference/index.md +++ b/docs/SHIELD/Defend/Reference/index.md @@ -25,7 +25,7 @@ SHIELD enforces hardware baselines per security class, especially for **Privileg | Graphics Support | NVIDIA recommended (avoid AMD graphics) | !!! info "Device Security Considerations" - In ESM/SSM, hardware risks are lower, but it’s still important to avoid unsupported OEMs and poor firmware hygiene. These devices typically handle non-elevated tasks. + In ESM/SSM, hardware risks are lower, but it's still important to avoid unsupported OEMs and poor firmware hygiene. These devices typically handle non-elevated tasks. ### Privileged Mode (PSM) @@ -49,15 +49,19 @@ Each SHIELD lifecycle action is mapped to a standardized backend workflow. The f ### Device Workflow Diagrams #### Commission Device + 📊 [Device - Commission](./Diagrams/Device-Commission.md) #### Decommission Device + 📊 [Device - Decommission](./Diagrams/Device-Decommission.md) #### Assign User to Device + 📊 [Device - Assign](./Diagrams/Device-Assign.md) #### Unassign User from Device + 📊 [Device - Unassign](./Diagrams/Device-Unassign.md) --- @@ -65,9 +69,11 @@ Each SHIELD lifecycle action is mapped to a standardized backend workflow. The f ### User Workflow Diagrams #### Commission User + 📊 [User - Commission](./Diagrams/User-Commission.md) #### Decommission User + 📊 [User - Decommission](./Diagrams/User-Decommission.md) --- @@ -85,4 +91,3 @@ A dedicated section for advanced Privileged workflows, including intermediary lo - [Defend Usage Guide](../Usage-Guide/index.md) - [Device Lifecycle](../Usage-Guide/Device/0-Commission.md) - [User Lifecycle](../Usage-Guide/User/Commission.md) - diff --git a/docs/SHIELD/Defend/Troubleshooting.md b/docs/SHIELD/Defend/Troubleshooting.md index 96f26f4..3159f23 100644 --- a/docs/SHIELD/Defend/Troubleshooting.md +++ b/docs/SHIELD/Defend/Troubleshooting.md @@ -1,16 +1,18 @@ # Troubleshooting -This section addresses common issues encountered when using the Defend module’s lifecycle management features. It also offers clarification on edge cases, expected behaviors, and safe recovery actions. +This section addresses common issues encountered when using the Defend module's lifecycle management features. It also offers clarification on edge cases, expected behaviors, and safe recovery actions. --- ## Issue: Devices not appearing in SHIELD UI **Cause:** + - Devices are not hybrid-joined or cloud-joined to Entra ID - Devices are not enrolled or synced into Intune **Resolution:** + - Confirm the device is joined to Entra ID - Ensure it is visible in the Intune portal ([https://intune.microsoft.com](https://intune.microsoft.com)) - Ensure it is not already managed by another tenant or stale registration @@ -20,11 +22,13 @@ This section addresses common issues encountered when using the Defend module’ ## Issue: Users not showing up when trying to commission **Cause:** + - The user has already been onboarded - The user is filtered out by Entra ID query - Admin does not have required permissions **Resolution:** + - Verify the user exists in Entra ID - Confirm you're operating with Global Reader or User Administrator role - Switch to a different security class to check other eligible users @@ -34,11 +38,13 @@ This section addresses common issues encountered when using the Defend module’ ## Issue: Lifecycle actions failing silently or UI not responding **Cause:** + - Required Defender for Endpoint workspace is not initialized - Scoped Intune tags are missing - Conditional Access policies are not yet deployed **Resolution:** + - Follow workspace setup verification steps in the [Usage Guide](Usage-Guide/index.md), under **Defender for Endpoint Workspace Creation** - Check that SHIELD infrastructure was successfully deployed from the Deploy module - Review prerequisites in [Defend Prerequisites](Prerequisites.md) @@ -48,10 +54,12 @@ This section addresses common issues encountered when using the Defend module’ ## Issue: Privileged device wipe triggered unexpectedly **Cause:** + - Privileged commissioning/unassignment flow triggered without assigned users - Attempted to assign a new user without retaining previous assignment **Resolution:** + - Always include current assigned users in the assignment flow - Ensure wipe behavior for privileged devices is clearly understood (see the [Usage Guide](Usage-Guide/index.md)) @@ -60,10 +68,12 @@ This section addresses common issues encountered when using the Defend module’ ## Issue: Temporary credentials not saved after privileged user creation **Cause:** + - Admin did not record credentials from the popup - UI was closed or refreshed before saving **Resolution:** + - Re-run commissioning with a new user - Contact SHI if lifecycle audit recovery is needed @@ -72,12 +82,15 @@ This section addresses common issues encountered when using the Defend module’ ## FAQs ### Are lifecycle actions idempotent? + Yes. If a device or user is already managed, SHIELD will not reapply the same configuration unless it detects a mismatch. ### Can I reverse a decommission action? + No. Once a user or device is removed, it must be re-commissioned. ### Does the UI prevent mistakes? + Yes — warnings and confirmations are built into the UI. However, wipe actions for privileged devices occur automatically in certain workflows. --- @@ -87,4 +100,3 @@ Yes — warnings and confirmations are built into the UI. However, wipe actions - [Defend Usage Guide](Usage-Guide/index.md) - [Defend Reference](Reference/index.md) - [Defend Prerequisites](Prerequisites.md) - diff --git a/docs/SHIELD/Defend/Usage-Guide/index.md b/docs/SHIELD/Defend/Usage-Guide/index.md index 1967bf7..f622ffb 100644 --- a/docs/SHIELD/Defend/Usage-Guide/index.md +++ b/docs/SHIELD/Defend/Usage-Guide/index.md @@ -13,7 +13,7 @@ Lifecycle Management is triggered from within the SHIELD web interface and allow - Enforce metadata tagging and Intune integration - Apply group policies and conditional access boundaries -All actions are class-aware and scoped by SHIELD’s infrastructure. +All actions are class-aware and scoped by SHIELD's infrastructure. --- @@ -29,6 +29,7 @@ Commissioning a device registers it with SHIELD and assigns lifecycle metadata. 📊 [Workflow Diagram](../Reference/Diagrams/Device-Commission.md) #### UI Example + . ![Select Device - Light](../../../assets/Images/Screenshots/Select-Unmanaged-Device-Light.png#only-light){ loading=lazy width="300" } ![Select Device - Dark](../../../assets/Images/Screenshots/Select-Unmanaged-Device-Dark.png#only-dark){ loading=lazy width="300" } @@ -40,7 +41,7 @@ Commissioning a device registers it with SHIELD and assigns lifecycle metadata. ### Decommission a Device -Removes a device from SHIELD’s lifecycle system. +Removes a device from SHIELD's lifecycle system. 📖 [Decommission a Device](./Device/1-Decommission.md) 📊 [Workflow Diagram](../Reference/Diagrams/Device-Decommission.md) @@ -58,7 +59,7 @@ Assigns one or more users to a privileged device (PAW). All others will be denie ### Unassign a User from a PAW -Removes a user’s access from a PAW. If no users remain, a wipe is issued. +Removes a user's access from a PAW. If no users remain, a wipe is issued. 📖 [Unassign User](./Device/3-Unassign.md) 📊 [Workflow Diagram](../Reference/Diagrams/Device-Unassign.md) @@ -99,7 +100,7 @@ Privileged users are deleted from Entra ID. Non-privileged users are simply remo ## Security Classes -All operations respect SHIELD’s class-based enforcement: +All operations respect SHIELD's class-based enforcement: - **Enterprise**: standard users/devices with baseline protections - **Specialized**: enhanced controls and policy targeting @@ -118,4 +119,4 @@ Class is selected at the top of the UI before performing lifecycle actions. - [Device Commissioning](./Device/0-Commission.md) - [User Commissioning](./User/Commission.md) - [Reference Diagrams](../Reference/index.md) -- [Hardware Requirements](../Reference/Hardware-Selection.md) \ No newline at end of file +- [Hardware Requirements](../Reference/Hardware-Selection.md) diff --git a/docs/SHIELD/Defend/index.md b/docs/SHIELD/Defend/index.md index bbc513c..60a823a 100644 --- a/docs/SHIELD/Defend/index.md +++ b/docs/SHIELD/Defend/index.md @@ -13,19 +13,19 @@ Whereas the Deploy module provisions the infrastructure, **Defend is responsible - Automatic Intune and Entra ID tagging - Lifecycle management rules based on selected security class -All these actions are exposed via the SHIELD Lifecycle UI and the platform’s API endpoints. +All these actions are exposed via the SHIELD Lifecycle UI and the platform's API endpoints. --- ## Security Class Enforcement -Defend strictly applies the lifecycle rules associated with each of SHIELD’s supported security classes: +Defend strictly applies the lifecycle rules associated with each of SHIELD's supported security classes: - **Enterprise (ESM)** – standard business users and workstations - **Specialized (SSM)** – elevated or regulated roles and systems - **Privileged (PSM)** – most secure tier, requires clean hardware, wipes on commission/unassign, and restricted access boundaries -The class is selected in the UI prior to performing any lifecycle action. +The class is selected in the UI prior to performing any lifecycle action. --- @@ -47,4 +47,3 @@ The lifecycle engine handles all object mapping, Intune tagging, group membershi - [Usage Guide](Usage-Guide/index.md) - [Reference](Reference/index.md) - [Troubleshooting](Troubleshooting.md) - diff --git a/docs/SHIELD/Deploy/Deployment/index.md b/docs/SHIELD/Deploy/Deployment/index.md index 717b952..04cb6cc 100644 --- a/docs/SHIELD/Deploy/Deployment/index.md +++ b/docs/SHIELD/Deploy/Deployment/index.md @@ -1,6 +1,6 @@ # Deployment -The Deploy module is provisioned automatically as part of the SHIELD platform’s Core Infrastructure deployment. This page provides clarity on how the Deploy module fits into the broader deployment flow and what is delivered specifically by this module. +The Deploy module is provisioned automatically as part of the SHIELD platform's Core Infrastructure deployment. This page provides clarity on how the Deploy module fits into the broader deployment flow and what is delivered specifically by this module. --- @@ -14,7 +14,7 @@ There is no separate installation or deployment process specific to the Deploy m ## What Is Deployed? -The Deploy module provisions all foundational objects required for SHIELD’s lifecycle and security logic: +The Deploy module provisions all foundational objects required for SHIELD's lifecycle and security logic: - Security groups for each SPA tier (Enterprise, Specialized, Privileged) - Intune Scope Tags for device policy enforcement @@ -40,7 +40,7 @@ From the home screen: 3. Check the agreement box 4. Click **Deploy Infrastructure** -You’ll then see: +You'll then see: - A progress spinner - Automatic status updates @@ -75,4 +75,3 @@ These cannot be renamed or deleted through the SHIELD UI. - [Reference Docs](../Reference/index.md) - [Troubleshooting](../Troubleshooting.md) - [Full SHIELD Deployment](../../Getting-Started.md) - diff --git a/docs/SHIELD/Deploy/Reference/index.md b/docs/SHIELD/Deploy/Reference/index.md index 5e7e5c0..2f8ff83 100644 --- a/docs/SHIELD/Deploy/Reference/index.md +++ b/docs/SHIELD/Deploy/Reference/index.md @@ -1,6 +1,6 @@ # Reference -This reference section provides technical specifications and supporting details for SHIELD’s Deploy module, including identity protection policies and configuration recommendations that align with the SPA architecture. +This reference section provides technical specifications and supporting details for SHIELD's Deploy module, including identity protection policies and configuration recommendations that align with the SPA architecture. --- @@ -14,7 +14,7 @@ These policies are designed to: - Block access to privileged resources if risk conditions are met - Route access through compliant devices and monitored interfaces -This aligns with Microsoft’s Zero Trust security model and helps enforce separation between administrative and user environments. +This aligns with Microsoft's Zero Trust security model and helps enforce separation between administrative and user environments. --- diff --git a/docs/SHIELD/Deploy/index.md b/docs/SHIELD/Deploy/index.md index 7281767..b0dd6bf 100644 --- a/docs/SHIELD/Deploy/index.md +++ b/docs/SHIELD/Deploy/index.md @@ -1,16 +1,16 @@ # Overview -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. -The Deploy module ensures your environment is segmented appropriately and aligns with Microsoft’s Zero Trust principles by separating enterprise and privileged systems. +The Deploy module ensures your environment is segmented appropriately and aligns with Microsoft's Zero Trust principles by separating enterprise and privileged systems. --- ## What Is SPA? -Microsoft’s **Securing Privileged Access (SPA)** model is a layered defense framework designed to protect your most critical systems from identity compromise. SPA separates access tiers between everyday business operations and sensitive administrative functions. +Microsoft's **Securing Privileged Access (SPA)** model is a layered defense framework designed to protect your most critical systems from identity compromise. SPA separates access tiers between everyday business operations and sensitive administrative functions. -The diagram below illustrates SPA’s architecture and how privileged vs enterprise identity flows interact with the environment. +The diagram below illustrates SPA's architecture and how privileged vs enterprise identity flows interact with the environment. ```mermaid flowchart LR @@ -80,4 +80,3 @@ By centralizing and automating the deployment of SPA, the Deploy module: - [Deploy Usage Guide](Usage-Guide.md) - [Deploy Reference](Reference/index.md) - [Troubleshooting Deploy Module](Troubleshooting.md) - diff --git a/docs/SHIELD/Discover/index.md b/docs/SHIELD/Discover/index.md index d972eaa..3515a95 100644 --- a/docs/SHIELD/Discover/index.md +++ b/docs/SHIELD/Discover/index.md @@ -32,7 +32,7 @@ The Discover module is built on a modular architecture that emphasizes extensibi ### Plugin -Discover’s core engine is extensible through plugins. Each plugin is responsible for extracting and evaluating configuration from a specific service, for example: +Discover's core engine is extensible through plugins. Each plugin is responsible for extracting and evaluating configuration from a specific service, for example: - 🔌 **Entra ID Plugin** – Retrieves directory and user-level settings - 🔌 **Defender for Endpoint Plugin** – Retrieves licensing status diff --git a/docs/SHIELD/Prerequisites/index.md b/docs/SHIELD/Prerequisites/index.md index c927b36..9a12482 100644 --- a/docs/SHIELD/Prerequisites/index.md +++ b/docs/SHIELD/Prerequisites/index.md @@ -18,7 +18,7 @@ SHIELD automates secure deployment and lifecycle management using Microsoft 365 - ✅ Deploying user must have **Global Admin Rights** - ✅ Microsoft Defender for Endpoint must be provisioned. See [Defend Usage Guide](../Defend/Usage-Guide/index.md), under **Defender for Endpoint Workspace Creation** - ✅ [Security Defaults](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/concept-fundamentals-security-defaults#disabling-security-defaults) must be disabled in Entra ID -- ✅ [Certificate Authentication](https://learn.microsoft.com/en-us/azure/active-directory/authentication/how-to-certificate-based-authentication#step-2-enable-cba-on-the-tenant) must be disabled for SHIELD’s security groups +- ✅ [Certificate Authentication](https://learn.microsoft.com/en-us/azure/active-directory/authentication/how-to-certificate-based-authentication#step-2-enable-cba-on-the-tenant) must be disabled for SHIELD's security groups --- diff --git a/docs/SHIELD/Reference/Uninstall.md b/docs/SHIELD/Reference/Uninstall.md index cc75abf..70ae895 100644 --- a/docs/SHIELD/Reference/Uninstall.md +++ b/docs/SHIELD/Reference/Uninstall.md @@ -12,7 +12,7 @@ The SHIELD platform uses multiple Microsoft 365 services to create configuration If you uninstall the architecture, **you will clear out any managed objects and configurations** deployed by the Deploy module. This procedure should only be followed if SHI explicitly instructs you to do so. !!! note "Stateless Server Reminder" - SHIELD’s application server is stateless. You can safely redeploy the app after cleanup without losing data stored in the Microsoft cloud (e.g., Intune tags, Entra groups). + SHIELD's application server is stateless. You can safely redeploy the app after cleanup without losing data stored in the Microsoft cloud (e.g., Intune tags, Entra groups). --- @@ -74,4 +74,3 @@ Yes. SHIELD can be redeployed using the same app interface or script, as long as - [Deploy Usage Guide](../Deploy/Usage-Guide.md) - [Deployment](../Deploy/Deployment/index.md) - [Deploy Reference](../Deploy/Reference/index.md) - diff --git a/docs/SHIELD/Usage-Guide.md b/docs/SHIELD/Usage-Guide.md index c585aa4..0a8cbbc 100644 --- a/docs/SHIELD/Usage-Guide.md +++ b/docs/SHIELD/Usage-Guide.md @@ -37,7 +37,7 @@ Lifecycle actions include: - Assigning users to PAWs (Privileged Access Workstations) - Creating and removing privileged users -These operations are triggered directly from the SHIELD app’s **Lifecycle Management** section. +These operations are triggered directly from the SHIELD app's **Lifecycle Management** section. --- @@ -126,4 +126,3 @@ SHIELD will soon support additional lifecycle workflows: - Use Lifecycle Management to adopt and manage devices/users - Task-level actions (commission, assign, etc.) are performed via the SHIELD UI - Each action links to a detailed guide and diagram for deeper understanding - diff --git a/mkdocs.yml b/mkdocs.yml index 67fefcc..43cabe7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -227,5 +227,12 @@ nav: - Data Gateway: - Overview: Data-Gateway/index.md + - Deployment: + - Overview: Data-Gateway/Deployment/index.md + - Usage Guide: Data-Gateway/Usage-Guide/index.md - Architecture: + - Overview: Data-Gateway/Architecture/index.md - Infrastructure: Data-Gateway/Architecture/Infrastructure.md + - Reference: + - Overview: Data-Gateway/Reference/index.md + - Troubleshooting: Data-Gateway/Troubleshooting.md