diff --git a/.gitattributes b/.gitattributes index 85af92e..0742fe4 100644 --- a/.gitattributes +++ b/.gitattributes @@ -8,3 +8,6 @@ *.png binary *.webp binary *.jpg binary +tools/microsoft-365-incident-triage-toolkit/** text eol=lf +scripts/package-triage-toolkit.ps1 text eol=lf +assets/downloads/*.zip binary diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 451758c..ed3a5e5 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -29,6 +29,13 @@ jobs: - name: Test offline Entra sign-in triage shell: pwsh run: ./scripts/test-entra-sign-in-triage.ps1 + - name: Test offline Microsoft 365 incident triage toolkit + shell: pwsh + run: | + # Isolate expected failure cases from the workflow host's exit code. + pwsh -NoProfile -File ./tools/microsoft-365-incident-triage-toolkit/tests/Test-M365IncidentTriage.ps1 + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + ./scripts/package-triage-toolkit.ps1 -Check - name: Check build guards and resolved routing run: bundle exec ruby scripts/test-build.rb - name: Build once diff --git a/README.md b/README.md index 6431ce7..d01a793 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,18 @@ The normal content validator checks strict sitemap XML, unique canonical URLs, e After publication, check that the public sitemap and robots file return HTTP 200. In the verified `dleontev.com` property in Google Search Console and Bing Webmaster Tools, submit the sitemap and inspect Home, About, the Projects index, a project, and a recent article. Review indexing/canonical results and Bing AI Performance where available. Local preview URLs cannot be submitted; account verification and live deployment must come first. +## Microsoft 365 incident triage toolkit + +The Microsoft 365 incident triage toolkit source, offline tests, and synthetic samples live in `tools/microsoft-365-incident-triage-toolkit/`, which is excluded from Jekyll output. The downloadable ZIP is built from an explicit file list. After changing toolkit files, use PowerShell 7.5 or later: + +```powershell +./tools/microsoft-365-incident-triage-toolkit/tests/Test-M365IncidentTriage.ps1 +./scripts/package-triage-toolkit.ps1 +./scripts/package-triage-toolkit.ps1 -Check +``` + +The offline tests do not connect to a tenant. Published samples must stay synthetic; live output belongs outside the repository. + ## Article navigation and search `jekyll-feed` generates `/feed.xml` as an Atom feed of the ten most recent published articles, including full content, summaries, canonical article links, and the shared author name. `{% feed_meta %}` adds feed discovery in the shared head, and the footer exposes a Subscribe link. The feed remains outside the HTML sitemap. Content validation checks strict Atom XML, article coverage and order, author identity, and discovery/Subscribe links. diff --git a/_config.yml b/_config.yml index 3070219..90bf4f9 100644 --- a/_config.yml +++ b/_config.yml @@ -70,6 +70,7 @@ exclude: - playwright.config.cjs - tests - scripts + - tools - docs - test-results - playwright-report diff --git a/_posts/2026-09-15-building-a-microsoft-365-incident-triage-toolkit-with-powershell.md b/_posts/2026-09-15-building-a-microsoft-365-incident-triage-toolkit-with-powershell.md new file mode 100644 index 0000000..eab112e --- /dev/null +++ b/_posts/2026-09-15-building-a-microsoft-365-incident-triage-toolkit-with-powershell.md @@ -0,0 +1,248 @@ +--- +title: 'Building a Microsoft 365 Incident Triage Toolkit with PowerShell' +description: 'Build a read-only PowerShell toolkit that captures Microsoft 365 service health, records incident context, and generates a consistent escalation report.' +tags: [Microsoft 365, PowerShell, Microsoft Graph, IT Operations] +related_project: /projects/microsoft-365-support-operations-toolkit/ +related_posts: + - /blog/microsoft-365-service-ownership-framework + - /blog/entra-sign-in-troubleshooting-framework +--- + +A user reports that Outlook is slow. A second ticket mentions Teams. Someone asks whether Microsoft has an incident open, while another person starts checking the network. + +Before deciding what to change, the response needs a shared starting point: the observed problem, its business impact, the relevant service-health information, and the evidence already collected. + +PowerShell can make that starting point repeatable. + +This walkthrough builds a small toolkit that records incident details, reads Microsoft 365 service health through Microsoft Graph, and produces a Markdown handoff report with supporting JSON. The collector makes no tenant configuration changes. + +The complete implementation includes an offline demo, synthetic sample output, an escalation template, and regression tests. **The code has been tested offline with synthetic data and mocked Graph requests; live tenant integration has not been tested.** Treat the first tenant run as a validation exercise before adopting it in an operational runbook. + +[Download the complete toolkit ZIP]({{ '/assets/downloads/microsoft-365-incident-triage-toolkit.zip' | relative_url }}) · [Browse the source and tests](https://github.com/dleontev/dleontev.github.io/tree/main/tools/microsoft-365-incident-triage-toolkit) + +
+On this page + +
+ +## Start with a useful triage boundary + +The first version should answer a few specific questions: + +- What action is failing, when was it first observed, and who is affected? +- What service-health information does Microsoft currently expose for this tenant? +- Which advisories deserve comparison with the reported symptoms? +- Did evidence collection finish, and what does the next responder still need? + +That leads to a deliberately small data model. + +| Input or collection | What it contributes | +| --- | --- | +| Incident ID, symptom, impact, first-observed time | Operator-supplied context | +| Service health overviews | Reported status for subscribed services | +| Service-health issues | Advisory IDs, descriptions, status, and timestamps | +| Collection results | Completion state, pages received, and failure reasons | +| Handoff fields | Reproduction, checks, owner, escalation request, next update | + +Microsoft Graph exposes the overview through `GET /admin/serviceAnnouncement/healthOverviews` and issue details through `GET /admin/serviceAnnouncement/issues`. Both support the `ServiceHealth.Read.All` permission. This implementation uses their v1.0 endpoints. [Health overview API](https://learn.microsoft.com/en-us/graph/api/serviceannouncement-list-healthoverviews?view=graph-rest-1.0), [service-health issues API](https://learn.microsoft.com/en-us/graph/api/serviceannouncement-list-issues?view=graph-rest-1.0). + +User inventories, sign-in logs, mailbox contents, and tenant configuration are outside this version's scope. Those collections have different permission and evidence-handling requirements. Keeping them separate also makes the first report easier to review. + +## Try the toolkit without a tenant + +Extract the ZIP and open **PowerShell 7.5 or later** in the extracted directory. The offline checks were run with PowerShell 7.6.5. Windows PowerShell 5.1 is not supported. + +The package contains: + +```text +Export-M365IncidentTriage.ps1 +M365IncidentTriage.psm1 +demo-snapshot.json +escalation-template.md +README.md +samples/ + evidence.json + report.md +tests/ + Test-M365IncidentTriage.ps1 +``` + +Review the scripts, then run the synthetic example: + +```powershell +$incident = @{ + IncidentId = 'DEMO-INC-001' + Symptom = 'Outlook on the web loads slowly for a fictional pilot group.' + Impact = 'Six fictional users; email response work delayed.' + FirstObservedUtc = '2026-09-14T16:00:00Z' +} + +./Export-M365IncidentTriage.ps1 -Demo @incident +``` + +Demo mode makes no network requests and needs no Microsoft module or account. It uses a fixed snapshot from `2026-09-14T16:30:00Z`, so keep the example first-observed time when reproducing the sample. + +The command returns its collection status and output directory. Each run creates a new folder under `$HOME/m365-triage`; use `-OutputRoot` to choose an approved location. Repeating the same incident ID preserves the earlier evidence. + +Open `report.md` for the readable handoff and `evidence.json` for the structured snapshot. The packaged `samples` folder shows the same synthetic scenario without requiring execution. + +## Establish the Graph connection explicitly + +For live collection, use an organizational account and a tenant-approved delegated `ServiceHealth.Read.All` permission. Microsoft lists this permission as requiring administrator consent. Arrange that consent through the organization's normal process before an incident. [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference#servicehealthreadall). + +Only the authentication module is required. If your organization permits installation from PowerShell Gallery: + +```powershell +Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Repository PSGallery +``` + +Use a fresh PowerShell process and connect to the intended tenant: + +```powershell +Import-Module Microsoft.Graph.Authentication +$tenantId = Read-Host 'Tenant ID (GUID)' + +$connection = @{ + TenantId = $tenantId + Scopes = 'ServiceHealth.Read.All' + ContextScope = 'Process' +} +Connect-MgGraph @connection -NoWelcome + +Get-MgContext | Select-Object TenantId, AuthType, Environment, Scopes +``` + +`ContextScope Process` confines the authentication context to the current PowerShell process. Review the returned tenant and scopes before collecting evidence. The collector checks for the required scope; it does not remove additional permissions from an existing session. [Graph PowerShell authentication](https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0). + +This version supports delegated authentication in the **Global** Graph environment. It rejects a different tenant, app-only authentication, a different cloud environment, or a missing required scope before collection. Supporting another environment requires an explicit implementation and validation of its endpoints and connection settings. + +The collector itself does not sign in, install modules, or disconnect a session someone else may be using. The operator controls that lifecycle. + +## Collect service health through Microsoft Graph + +The module starts with one request per collection and follows additional pages as needed. It requests selected properties to keep the output focused; issue discussion posts and their HTML content are excluded. + +The transport is small enough to inspect directly: + +```powershell +$request = { + param($uri) + Invoke-MgGraphRequest -Method GET -Uri $uri -OutputType Hashtable -ErrorAction Stop +} + +$health = Read-TriageCollection -Resource healthOverviews -Request $request +$issues = Read-TriageCollection -Resource issues -Request $request +``` + +These functions are provided by `M365IncidentTriage.psm1`, which the entry script imports. The explicit `GET` is the only HTTP method used by the collector. `Invoke-MgGraphRequest` supplies the authenticated Graph transport. [Command reference](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/invoke-mggraphrequest?view=graph-powershell-1.0). + +Pagination matters even when a test tenant returns only a few rows. Graph returns an `@odata.nextLink` when more results are available. Follow that URL until no continuation remains; an empty page alone does not end collection. [Microsoft Graph paging](https://learn.microsoft.com/en-us/graph/paging). + +The implementation also checks that each continuation stays on HTTPS, the expected Graph host, and the same collection path. Repeated links or more than 100 pages stop that collection and mark it incomplete. + +The Graph SDK provides retry handling for throttled requests. This toolkit adds no second retry loop; a request that still fails is recorded as a collection failure. Repeatedly launching new collectors during throttling would add traffic rather than resolve it. [Microsoft Graph throttling guidance](https://learn.microsoft.com/en-us/graph/throttling). + +## Keep collection status separate from service status + +A report containing no advisories can mean several things: the collection succeeded with no matching records, a request failed, the chosen time window excluded older updates, or Microsoft has not published a matching issue. + +The output needs to preserve those differences. + +Each collection records its completion state, successfully validated pages, retained rows, and a failure reason. A failure on a later page preserves the earlier pages. If either collection is incomplete, the script writes the available evidence and then raises a terminating error. Running it through `pwsh -File` therefore returns a nonzero exit code. + +| Result | Interpretation | +| --- | --- | +| Complete collection | Both API collections finished successfully | +| Incomplete collection | At least one collection failed or stopped early | +| No candidate issues | No collected rows met the report's selection rule | +| Reported service degradation | Microsoft reported a status that needs investigation | + +**Complete describes evidence collection, not service health.** Likewise, a reported advisory is a candidate for correlation; it does not establish the cause of a user's problem. + +If collection fails, inspect `FailureReason`. `RequestFailed` calls for checking access, consent, connectivity, or throttling. `InvalidResponse` or `InvalidItem` means the returned data did not meet the collector's expectations. Continuation and page-limit failures mean the result set was deliberately left incomplete. Raw HTTP error bodies are excluded from the handoff bundle. + +Invalid input or connection context fails before API collection. Local file-write errors also terminate; check that both output files exist before treating a run as usable evidence. + +## Choose issues for review without claiming a match + +The JSON retains the selected fields from every successfully collected issue. The report narrows that set to: + +```text +Unresolved issues +OR +Issues last modified on/after FirstObservedUtc minus LookBackHours +``` + +The default look-back is 24 hours. An unresolved issue remains a candidate even if its last update is older. A recently resolved issue can also be useful when investigating something users experienced earlier. + +This is a local selection rule over currently available API results. It is not a historical query, and it cannot recover issues the API no longer returns. It also does not filter by service or automatically compare symptoms. + +In the synthetic example, the report includes `DEMO-EX-001`, an unresolved Exchange issue, and `DEMO-TM-002`, a recently updated resolved Teams issue. The older resolved `DEMO-SP-003` remains in JSON but falls outside the report window. These are invented identifiers, not real Microsoft incidents. + +The sample's collection results look like this: + +| Collection | Result | Pages | Retained items | +| --- | --- | --- | --- | +| HealthOverviews | Complete | 1 | 3 | +| Issues | Complete | 1 | 3 | + +The report contains two candidate issues, while JSON retains all three collected issues. That difference follows the selection rule and does not indicate missing evidence. + +For each candidate, compare the service, failing action, start time, affected population, and current advisory details. An unrelated Teams advisory should not explain an Outlook symptom merely because both appear in the report. + +## Run a live collection and complete the handoff + +After connecting, enter the actual incident details. Timestamps must use the explicit UTC form shown by the prompt: + +```powershell +$incident = @{ + IncidentId = Read-Host 'Incident ID' + Symptom = Read-Host 'Observed symptom' + Impact = Read-Host 'Confirmed business impact and affected scope' + FirstObservedUtc = Read-Host 'First observed UTC (YYYY-MM-DDTHH:mm:ssZ)' +} + +try { + ./Export-M365IncidentTriage.ps1 -TenantId $tenantId @incident -LookBackHours 24 +} finally { + Disconnect-MgGraph +} +``` + +Use letters, digits, hyphens, and underscores for the incident ID, up to 60 characters. Record an observed first-failure time where possible; ticket creation time may be later. + +The generated report already includes the incident context, snapshot timestamps, collection results, service statuses, and candidate issue details. Its final section leaves explicit fields for the work automation cannot establish: + +- Reproduction steps and an unaffected comparison. +- Checks performed and their results. +- Whether an advisory actually matches the symptom and timeline. +- Workaround, changes made, and verification results. +- The requested escalation action, owner, and next update time. + +The separate `escalation-template.md` provides more room for that handoff. A useful request might be: “Please investigate the mailbox-access failures reproduced at the recorded UTC times; confirm whether the candidate advisory's scope includes this behavior.” It should identify what the receiving team needs to decide or investigate. + +Review both output files before attaching them. The real bundle includes the tenant ID, operator-entered incident details, and service-health text; it is not automatically anonymized. Prefer references to approved logs over copying personal information into free-text fields. The collector creates files locally and does not send an escalation message. + +## Verify the toolkit and extend it deliberately + +Run the included offline checks from the toolkit directory: + +```powershell +./tests/Test-M365IncidentTriage.ps1 +``` + +The 15 checks cover pagination through an empty page, partial failures, invalid continuations, loop limits, malformed responses, issue selection, context validation, report escaping, repeated runs, timestamp validation, and the live entry point with a fake Graph module. They also verify that the transport uses GET requests only. + +Those tests validate the collector's local behavior. They do not validate real sign-in, administrator consent, tenant-specific access, or the live SDK/API combination. The JSON records the PowerShell and Graph authentication module versions to make a tenant smoke test reproducible. + +Before operational adoption, run it with an approved account, compare the resulting snapshot with the Microsoft 365 admin center, and confirm that another responder can understand the report. A successful command is only part of that check. + +Useful extensions include a separate Entra sign-in evidence collector, a workload-specific runbook, or a stakeholder-update template. Each should have its own permissions, evidence boundary, and failure behavior. Keep remediation behind a separate, reviewed procedure. + +This is the first implementation in the [Microsoft 365 Support Operations Toolkit]({{ '/projects/microsoft-365-support-operations-toolkit/' | relative_url }}). It applies the repeatable support practices from [the service ownership framework]({% post_url 2026-08-27-microsoft-365-service-ownership-framework %}); when identity evidence points toward an access problem, [the Entra sign-in troubleshooting framework]({% post_url 2026-08-01-entra-sign-in-troubleshooting-framework %}) provides a next investigation path. + +The useful outcome is a handoff another administrator can act on: what failed, what is affected, which evidence is available, what remains uncertain, and who owns the next step. diff --git a/_projects/04-microsoft-365-support-operations-toolkit.md b/_projects/04-microsoft-365-support-operations-toolkit.md index e5c3822..2caa718 100644 --- a/_projects/04-microsoft-365-support-operations-toolkit.md +++ b/_projects/04-microsoft-365-support-operations-toolkit.md @@ -1,25 +1,33 @@ --- title: Microsoft 365 Support Operations Toolkit order: 4 -status: Planned +status: In progress tools: [Microsoft 365, PowerShell, Support Engineering] -description: A planned collection of reusable templates and safe automation patterns for technical triage, stakeholder updates, escalation evidence, and service documentation. +description: A read-only Microsoft 365 incident triage collector with a walkthrough, synthetic examples, offline tests, and an escalation template. +article: /blog/building-a-microsoft-365-incident-triage-toolkit-with-powershell permalink: /projects/microsoft-365-support-operations-toolkit/ --- # Microsoft 365 Support Operations Toolkit -**Status:** Planned +**Status:** In progress — first toolkit available -This project will collect reusable, sanitized support-engineering resources for Microsoft 365 operations. +This project collects reusable support-engineering resources for Microsoft 365 operations. The first release captures incident context and Microsoft Graph service-health data, then generates a consistent escalation report. -## Planned scope +## Available now -- Initial triage and evidence collection templates -- Stakeholder update and escalation templates -- Service-health and known-issue checks +- [Building a Microsoft 365 Incident Triage Toolkit with PowerShell]({% post_url 2026-09-15-building-a-microsoft-365-incident-triage-toolkit-with-powershell %}) +- [Download the toolkit, synthetic examples, tests, and escalation template]({{ '/assets/downloads/microsoft-365-incident-triage-toolkit.zip' | relative_url }}) +- [Browse the PowerShell source](https://github.com/dleontev/dleontev.github.io/tree/main/tools/microsoft-365-incident-triage-toolkit) + +Version 1.0 uses read-only Graph requests and delegated authentication in the Global environment. Offline tests use synthetic data and a mocked Graph connection; live tenant integration has not been tested. + +## Further work + +- Workload-specific evidence collectors and runbooks +- Stakeholder update templates - Troubleshooting runbook structure - Safe PowerShell and Microsoft Graph examples - Verification, rollback, and closure checklists -Scripts will use safe defaults, limited permissions, mock data, and preview or dry-run behavior when practical. No credentials, tokens, tenant details, or employer-specific data will be published. +Published examples contain synthetic data. Real output should remain in an approved incident location and be reviewed before sharing. Future collectors will keep permissions and failure behavior explicit, with remediation handled through separate reviewed procedures. diff --git a/assets/downloads/microsoft-365-incident-triage-toolkit.zip b/assets/downloads/microsoft-365-incident-triage-toolkit.zip new file mode 100644 index 0000000..603f73a Binary files /dev/null and b/assets/downloads/microsoft-365-incident-triage-toolkit.zip differ diff --git a/scripts/package-triage-toolkit.ps1 b/scripts/package-triage-toolkit.ps1 new file mode 100644 index 0000000..717b659 --- /dev/null +++ b/scripts/package-triage-toolkit.ps1 @@ -0,0 +1,49 @@ +#requires -Version 7.5 +[CmdletBinding()] +param([switch]$Check) +$ErrorActionPreference = 'Stop' +$repo = Split-Path $PSScriptRoot -Parent +$source = Join-Path $repo 'tools/microsoft-365-incident-triage-toolkit' +$destination = Join-Path $repo 'assets/downloads/microsoft-365-incident-triage-toolkit.zip' +$files = @('Export-M365IncidentTriage.ps1', 'M365IncidentTriage.psm1', 'README.md', + 'demo-snapshot.json', 'escalation-template.md', 'samples/evidence.json', + 'samples/report.md', 'tests/Test-M365IncidentTriage.ps1') | Sort-Object +$sample = Get-Content -LiteralPath (Join-Path $source 'samples/evidence.json') -Raw | ConvertFrom-Json -AsHashtable -DateKind String +if ($sample.Mode -ne 'Demo' -or $sample.TenantId -ne 'SYNTHETIC — no tenant') { + throw 'Only the synthetic demo sample may be packaged.' +} +Add-Type -AssemblyName System.IO.Compression +if ($Check) { + $zip = [IO.Compression.ZipFile]::OpenRead($destination) + try { + if ($zip.Entries.Count -ne $files.Count) { throw 'Unexpected archive entries.' } + foreach ($file in $files) { + $entry = $zip.GetEntry($file) + if (-not $entry) { throw "Missing archive file: $file" } + $stream = $entry.Open() + $buffer = [IO.MemoryStream]::new() + try { + $stream.CopyTo($buffer) + $expected = [Convert]::ToBase64String([IO.File]::ReadAllBytes((Join-Path $source $file))) + if ([Convert]::ToBase64String($buffer.ToArray()) -cne $expected) { throw "Stale archive file: $file" } + } finally { $stream.Dispose(); $buffer.Dispose() } + } + } finally { $zip.Dispose() } + Write-Host 'Toolkit ZIP matches all eight source files; sample is synthetic.' +} else { + $null = [IO.Directory]::CreateDirectory((Split-Path $destination -Parent)) + $stream = [IO.File]::Open($destination, [IO.FileMode]::Create) + $zip = [IO.Compression.ZipArchive]::new($stream, [IO.Compression.ZipArchiveMode]::Create) + try { + foreach ($file in $files) { + $entry = $zip.CreateEntry($file) + $entry.LastWriteTime = [datetimeoffset]'2000-01-01T00:00:00Z' + $entryStream = $entry.Open() + try { + $bytes = [IO.File]::ReadAllBytes((Join-Path $source $file)) + $entryStream.Write($bytes, 0, $bytes.Length) + } finally { $entryStream.Dispose() } + } + } finally { $zip.Dispose(); $stream.Dispose() } + Write-Host "Packaged $destination" +} diff --git a/tests/site.spec.cjs b/tests/site.spec.cjs index c01d64d..7ed1f2a 100644 --- a/tests/site.spec.cjs +++ b/tests/site.spec.cjs @@ -139,17 +139,22 @@ test('content, Home and contents remain available without JavaScript',async({bro await page.locator('.article-toc summary').click(); await expect(page.locator('.article-toc nav')).toBeVisible(); await context.close(); }); -test('message trace and release commands scroll by keyboard without JavaScript',async({browser})=>{ +test('PowerShell examples scroll by keyboard without JavaScript',async({browser})=>{ const context=await browser.newContext({javaScriptEnabled:false,viewport:{width:390,height:844}}); try { const page=await context.newPage(); for (const [route,count] of [ ['/blog/where-did-the-email-go-troubleshooting-exchange-online-with-message-trace',4], + ['/blog/building-a-microsoft-365-incident-triage-toolkit-with-powershell',6], ['/projects/pomodoro-timer/',1], ]) { await page.goto('http://127.0.0.1:4000'+route); const examples=page.locator('.language-powershell pre'); await expect(examples).toHaveCount(count); + for (const example of await examples.all()) { + await expect(example).toHaveAttribute('tabindex','0'); + await expect(example).toHaveAccessibleName('Code example'); + } const example=examples.first(); await expect(example).toHaveAccessibleName('Code example'); expect(await example.evaluate(el=>el.scrollWidth>el.clientWidth)).toBe(true); diff --git a/tools/microsoft-365-incident-triage-toolkit/Export-M365IncidentTriage.ps1 b/tools/microsoft-365-incident-triage-toolkit/Export-M365IncidentTriage.ps1 new file mode 100644 index 0000000..b6d2734 --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/Export-M365IncidentTriage.ps1 @@ -0,0 +1,89 @@ +#requires -Version 7.5 +<# +.SYNOPSIS +Collect a read-only Microsoft 365 service-health snapshot and incident handoff. +.DESCRIPTION +Demo mode uses packaged synthetic data without Graph. Live mode requires an existing +delegated Graph connection to the explicit tenant in the Global environment. +Each run creates a new directory under OutputRoot. Incomplete collection writes the +available evidence, then throws; pwsh -File returns a nonzero exit code. +#> +[CmdletBinding(DefaultParameterSetName = 'Live')] +param( + [Parameter(Mandatory, ParameterSetName = 'Demo')][switch]$Demo, + [Parameter(Mandatory, ParameterSetName = 'Live')][guid]$TenantId, + [Parameter(Mandatory)][ValidatePattern('^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$')][string]$IncidentId, + [Parameter(Mandatory)][ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })][ValidateLength(1, 2000)][string]$Symptom, + [Parameter(Mandatory)][ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })][ValidateLength(1, 2000)][string]$Impact, + [Parameter(Mandatory)][string]$FirstObservedUtc, + [ValidateRange(0, 168)][int]$LookBackHours = 24, + [ValidateNotNullOrEmpty()][string]$OutputRoot = (Join-Path ([Environment]::GetFolderPath('UserProfile')) 'm365-triage') +) +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +Import-Module (Join-Path $PSScriptRoot 'M365IncidentTriage.psm1') -Force +$first = [datetimeoffset]::ParseExact($FirstObservedUtc, "yyyy-MM-dd'T'HH:mm:ss'Z'", + [cultureinfo]::InvariantCulture, [Globalization.DateTimeStyles]::AssumeUniversal) +$started = [datetimeoffset]::UtcNow +$mode = 'Live' +$graphVersion = $null +if ($PSCmdlet.ParameterSetName -eq 'Demo') { + $mode = 'Demo' + $fixture = Get-Content -LiteralPath (Join-Path $PSScriptRoot 'demo-snapshot.json') -Raw | + ConvertFrom-Json -AsHashtable -DateKind String + $started = [datetimeoffset]::Parse($fixture.snapshotAtUtc, [cultureinfo]::InvariantCulture) + $tenantLabel = 'SYNTHETIC — no tenant' + $request = { + param($uri) + $resource = ([uri]$uri).Segments[-1] + if (-not $fixture.collections.Contains($resource)) { throw 'Unknown demo collection.' } + $fixture.collections[$resource] + }.GetNewClosure() +} else { + Import-Module Microsoft.Graph.Authentication -ErrorAction Stop + Assert-TriageContext -Context (Get-MgContext) -TenantId $TenantId + $graphVersion = (Get-Module Microsoft.Graph.Authentication).Version.ToString() + $tenantLabel = $TenantId.ToString() + $request = { + param($uri) + Invoke-MgGraphRequest -Method GET -Uri $uri -OutputType Hashtable -ErrorAction Stop + } +} +if ($first -gt $started) { throw 'FirstObservedUtc must not be after the snapshot time (the demo uses 2026-09-14T16:30:00Z).' } +$since = $first.AddHours(-$LookBackHours) +$health = Read-TriageCollection -Resource healthOverviews -Request $request +$issues = Read-TriageCollection -Resource issues -Request $request +$status = if ($health.Status -eq 'Complete' -and $issues.Status -eq 'Complete') { 'Complete' } else { 'Incomplete' } +$finished = if ($mode -eq 'Demo') { $started } else { [datetimeoffset]::UtcNow } +$evidence = [ordered]@{ + SchemaVersion = '1.0' + ToolkitVersion = '1.0.0' + Mode = $mode + TenantId = $tenantLabel + PowerShellVersion = $PSVersionTable.PSVersion.ToString() + GraphAuthenticationVersion = $graphVersion + StartedAtUtc = $started.ToUniversalTime().ToString('o') + FinishedAtUtc = $finished.ToUniversalTime().ToString('o') + Incident = [ordered]@{ + IncidentId = $IncidentId; Symptom = $Symptom; Impact = $Impact + FirstObservedUtc = $first.ToUniversalTime().ToString('o') + } + IssuesSinceUtc = $since.ToUniversalTime().ToString('o') + CollectionStatus = $status + Collections = [ordered]@{ HealthOverviews = $health; Issues = $issues } + CandidateIssues = @(Select-TriageIssue -Issues $issues.Items -SinceUtc $since) +} +# Unique directories preserve previous evidence, even for repeated runs of the same incident. +$root = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputRoot) +$null = [IO.Directory]::CreateDirectory($root) +$runName = $IncidentId + '-' + [datetimeoffset]::UtcNow.ToString('yyyyMMddTHHmmssfffZ') + '-' + [guid]::NewGuid().ToString('N') +$runDirectory = Join-Path $root $runName +$null = New-Item -ItemType Directory -Path $runDirectory -ErrorAction Stop +$json = ($evidence | ConvertTo-Json -Depth 20) -replace "`r`n", "`n" +$report = ConvertTo-TriageReport -Evidence $evidence +Set-Content -LiteralPath (Join-Path $runDirectory 'evidence.json') -Value ($json + "`n") -Encoding utf8NoBOM -NoNewline +Set-Content -LiteralPath (Join-Path $runDirectory 'report.md') -Value ($report + "`n") -Encoding utf8NoBOM -NoNewline +[pscustomobject]@{ CollectionStatus = $status; Mode = $mode; OutputDirectory = $runDirectory } +if ($status -ne 'Complete') { + throw "Collection is incomplete. Review collection results in $runDirectory before using this evidence." +} diff --git a/tools/microsoft-365-incident-triage-toolkit/M365IncidentTriage.psm1 b/tools/microsoft-365-incident-triage-toolkit/M365IncidentTriage.psm1 new file mode 100644 index 0000000..ebb0dc5 --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/M365IncidentTriage.psm1 @@ -0,0 +1,177 @@ +#requires -Version 7.5 +Set-StrictMode -Version Latest + +function Assert-TriageContext { + param($Context, [guid]$TenantId) + if (-not $Context -or $Context.AuthType -ne 'Delegated' -or + $Context.Environment -ne 'Global' -or + [string]$Context.TenantId -ne $TenantId.ToString() -or + @($Context.Scopes) -notcontains 'ServiceHealth.Read.All') { + throw 'Connect to the requested tenant in Global with delegated ServiceHealth.Read.All first.' + } +} + +function Read-TriageCollection { + [CmdletBinding()] + param( + [Parameter(Mandatory)][ValidateSet('healthOverviews', 'issues')][string]$Resource, + [Parameter(Mandatory)][scriptblock]$Request, + [ValidateRange(1, 100)][int]$MaxPages = 100 + ) + $path = "/v1.0/admin/serviceAnnouncement/$Resource" + $fields = if ($Resource -eq 'healthOverviews') { + @('id', 'service', 'status') + } else { + @('id', 'title', 'service', 'status', 'classification', 'startDateTime', + 'endDateTime', 'lastModifiedDateTime', 'isResolved', 'impactDescription') + } + $next = 'https://graph.microsoft.com' + $path + '?$select=' + ($fields -join ',') + $seen = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) + $items = [System.Collections.Generic.List[object]]::new() + $pages = 0 + $stage = 'RequestFailed' + try { + while ($next) { + $stage = 'UnsafeContinuation' + $uri = [uri]$next + if (-not $uri.IsAbsoluteUri -or $uri.Scheme -ne 'https' -or + $uri.Host -ne 'graph.microsoft.com' -or $uri.Port -ne 443 -or + $uri.UserInfo -or $uri.Fragment -or $uri.AbsolutePath -cne $path) { + throw 'Continuation must stay on the same Graph collection.' + } + $stage = 'RepeatedContinuation' + if (-not $seen.Add($next)) { throw 'Repeated continuation.' } + $stage = 'PageLimit' + if ($pages -ge $MaxPages) { throw 'Page limit reached.' } + $stage = 'RequestFailed' + $page = & $Request $next + $stage = 'InvalidResponse' + if ($page -isnot [System.Collections.IDictionary] -or + -not $page.Contains('value') -or $page.value -isnot [array]) { + throw 'Expected an object containing a value array.' + } + # Validate a whole page before retaining it; never count a malformed page as complete. + $pageItems = [System.Collections.Generic.List[object]]::new() + foreach ($item in $page.value) { + $stage = 'InvalidItem' + if ($item -isnot [System.Collections.IDictionary]) { throw 'Expected an object.' } + foreach ($required in @('id', 'service', 'status')) { + if ([string]::IsNullOrWhiteSpace([string]$item[$required])) { + throw 'Missing a required property.' + } + } + if ($Resource -eq 'issues') { + if ($item.isResolved -isnot [bool]) { throw 'Missing resolution state.' } + foreach ($dateField in @('startDateTime', 'lastModifiedDateTime')) { + if ([string]::IsNullOrWhiteSpace([string]$item[$dateField])) { throw 'Missing date.' } + $null = [datetimeoffset]::Parse([string]$item[$dateField], [cultureinfo]::InvariantCulture) + } + } + $selected = [ordered]@{} + foreach ($field in $fields) { $selected[$field] = $item[$field] } + $pageItems.Add($selected) + } + foreach ($item in $pageItems) { $items.Add($item) } + $pages++ + $stage = 'InvalidResponse' + $continuation = $page['@odata.nextLink'] + if ($null -ne $continuation -and + ($continuation -isnot [string] -or [string]::IsNullOrWhiteSpace($continuation))) { + throw 'Invalid continuation value.' + } + $next = [string]$continuation + } + return [ordered]@{ Status = 'Complete'; Pages = $pages; FailureReason = $null; Items = $items.ToArray() } + } catch { + # Do not copy HTTP response bodies, tokens, or request URLs into an escalation bundle. + return [ordered]@{ Status = 'Incomplete'; Pages = $pages; FailureReason = $stage; Items = $items.ToArray() } + } +} + +function Select-TriageIssue { + param([AllowEmptyCollection()][object[]]$Issues, [datetimeoffset]$SinceUtc) + foreach ($issue in $Issues) { + if (-not $issue.isResolved -or + [datetimeoffset]::Parse([string]$issue.lastModifiedDateTime, [cultureinfo]::InvariantCulture) -ge $SinceUtc) { + $issue + } + } +} + +function ConvertTo-TriageText { + param([AllowNull()][object]$Value) + # Numeric entities prevent operator/API text from introducing Markdown or HTML structure. + $text = ([string]$Value -replace '[\r\n\t]+', ' ').Trim() + if (-not $text) { return 'Not reported' } + [regex]::Replace($text, '[&<>"''`*_|\[\]\\]', { + param($match) + '&#' + [int][char]$match.Value + ';' + }) +} + +function ConvertTo-TriageReport { + param([System.Collections.IDictionary]$Evidence) + $e = $Evidence + $lines = [System.Collections.Generic.List[string]]::new() + $lines.Add('# Microsoft 365 incident triage') + $lines.Add('') + if ($e.Mode -eq 'Demo') { $lines.Add('**SYNTHETIC DEMO — no tenant data or live requests.**'); $lines.Add('') } + $lines.Add('Collection: **' + $e.CollectionStatus + '**. This is collection status, not service health.') + $lines.Add('') + foreach ($field in @('IncidentId', 'Symptom', 'Impact', 'FirstObservedUtc')) { + $lines.Add('- ' + $field + ': ' + (ConvertTo-TriageText $e.Incident[$field])) + } + $lines.Add('- Tenant: ' + (ConvertTo-TriageText $e.TenantId)) + $lines.Add('- Snapshot started (UTC): ' + $e.StartedAtUtc) + $lines.Add('- Snapshot finished (UTC): ' + $e.FinishedAtUtc) + $lines.Add('- Issue selection: unresolved OR last modified on/after ' + $e.IssuesSinceUtc) + $lines.Add('') + $lines.Add('## Collection results') + $lines.Add('') + $lines.Add('| Collection | Result | Pages | Retained items | Failure reason |') + $lines.Add('| --- | --- | --- | --- | --- |') + foreach ($name in @('HealthOverviews', 'Issues')) { + $c = $e.Collections[$name] + $lines.Add("| $name | $($c.Status) | $($c.Pages) | $(@($c.Items).Count) | $($c.FailureReason) |") + } + $lines.Add('') + $lines.Add('## Service health snapshot') + $lines.Add('') + $lines.Add('| Service | Reported status |') + $lines.Add('| --- | --- |') + foreach ($health in $e.Collections.HealthOverviews.Items) { + $lines.Add('| ' + (ConvertTo-TriageText $health.service) + ' | ' + (ConvertTo-TriageText $health.status) + ' |') + } + if (-not @($e.Collections.HealthOverviews.Items).Count) { $lines.Add('| No rows collected; check collection results | Unknown |') } + $lines.Add('') + $lines.Add('## Issues to review') + $lines.Add('') + $lines.Add('These are candidates for manual review. Their presence does not establish the cause of this incident.') + $lines.Add('') + foreach ($issue in $e.CandidateIssues) { + $lines.Add('### ' + (ConvertTo-TriageText $issue.id) + ': ' + (ConvertTo-TriageText $issue.title)) + $lines.Add('') + foreach ($field in @('service', 'status', 'classification', 'isResolved', 'startDateTime', 'endDateTime', 'lastModifiedDateTime', 'impactDescription')) { + $lines.Add('- ' + $field + ': ' + (ConvertTo-TriageText $issue[$field])) + } + $lines.Add('') + } + if (-not @($e.CandidateIssues).Count) { + $lines.Add('No candidate issues in the collected rows. This does not establish that the service is healthy.') + $lines.Add('') + } + $lines.Add('## Handoff — complete before escalating') + $lines.Add('') + $lines.Add('- Confirmed observations and reproduction steps: [complete]') + $lines.Add('- Affected and unaffected users, clients, locations, and networks: [complete]') + $lines.Add('- Candidate Microsoft issue and symptom/time match: [complete; correlation unconfirmed]') + $lines.Add('- Checks performed, evidence references, and results: [complete]') + $lines.Add('- Changes made and verification/rollback status: [complete; this collector changes no tenant settings]') + $lines.Add('- Workaround and business impact: [complete]') + $lines.Add('- Escalation request, owner, and next update (UTC): [complete]') + $lines.Add('') + $lines.Add('Review and redact this report and evidence.json before sharing; neither is automatically anonymized.') + $lines -join "`n" +} + +Export-ModuleMember -Function Assert-TriageContext, Read-TriageCollection, Select-TriageIssue, ConvertTo-TriageReport diff --git a/tools/microsoft-365-incident-triage-toolkit/README.md b/tools/microsoft-365-incident-triage-toolkit/README.md new file mode 100644 index 0000000..38998de --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/README.md @@ -0,0 +1,95 @@ +# Microsoft 365 Incident Triage Toolkit + +Version 1.0.0. A read-only, interactive service-health collector for the Microsoft Graph Global environment. Tested offline on PowerShell 7.6.5 with synthetic fixtures and a mocked Graph module. Live tenant integration has not been tested. + +## Contents + +- `Export-M365IncidentTriage.ps1`: command-line entry point. +- `M365IncidentTriage.psm1`: context checks, collection, selection, and report formatting. +- `demo-snapshot.json`: fixed synthetic API responses, dated 2026-09-14. +- `samples/report.md` and `samples/evidence.json`: generated synthetic output. +- `escalation-template.md`: editable handoff checklist. +- `tests/Test-M365IncidentTriage.ps1`: dependency-free offline regression tests. + +## Try the offline demo + +Use PowerShell 7.5 or later (`pwsh`), not Windows PowerShell 5.1. Extract the complete ZIP and open PowerShell in that directory. Review downloaded scripts before running them; follow your organization's script-signing/execution policy. + +```powershell +$incident = @{ + IncidentId = 'DEMO-INC-001' + Symptom = 'Outlook on the web loads slowly for a fictional pilot group.' + Impact = 'Six fictional users; email response work delayed.' + FirstObservedUtc = '2026-09-14T16:00:00Z' +} +./Export-M365IncidentTriage.ps1 -Demo @incident +``` + +Demo mode needs no Microsoft module, account, or network. It uses a fixed snapshot time of `2026-09-14T16:30:00Z`, so use the example timestamp. Every run creates a new directory under `$HOME/m365-triage`, even when the incident ID is reused. `-OutputRoot` overrides that location. Read `report.md`; use `evidence.json` for structured evidence. Neither file contains credentials. Real reports do contain your tenant ID, incident text, and selected service-health data and are not automatically anonymized. + +## Connect and collect live data + +The tenant must approve the delegated `ServiceHealth.Read.All` permission, which requires administrator consent. Use your organization's approved Graph application/account. The examples use the standard Graph PowerShell application; no app-only, scheduled, or sovereign-cloud mode is implemented. + +If needed, install the authentication module from your approved source. For an organization that permits PowerShell Gallery: + +```powershell +Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Repository PSGallery +``` + +Connect in a new PowerShell process and collect: + +```powershell +Import-Module Microsoft.Graph.Authentication +$tenantId = Read-Host 'Tenant ID (GUID)' +$connection = @{ + TenantId = $tenantId + Scopes = 'ServiceHealth.Read.All' + ContextScope = 'Process' +} +Connect-MgGraph @connection -NoWelcome +Get-MgContext | Select-Object TenantId, AuthType, Environment, Scopes + +$incident = @{ + IncidentId = Read-Host 'Incident ID (letters, digits, hyphens, underscores; up to 60 characters)' + Symptom = Read-Host 'Observed symptom' + Impact = Read-Host 'Confirmed business impact and affected scope' + FirstObservedUtc = Read-Host 'First observed UTC (YYYY-MM-DDTHH:mm:ssZ)' +} +try { + ./Export-M365IncidentTriage.ps1 -TenantId $tenantId @incident -LookBackHours 24 +} finally { + Disconnect-MgGraph +} +``` + +The collector itself does not connect or disconnect your session. It validates tenant ID, delegated authentication, Global environment, and the required scope before issuing GET requests. It does not require or enforce that the session has *only* that scope; use a fresh process and review the context. It neither installs modules nor changes tenant settings. + +## Collection and failure behavior + +Only these v1.0 collections are requested: + +- `/admin/serviceAnnouncement/healthOverviews`: ID, service, status. +- `/admin/serviceAnnouncement/issues`: ID, title, service, status, classification, start/end/update times, resolution flag, impact description. + +The collector follows `@odata.nextLink` unchanged, checks the scheme/host/port/path, rejects loops, and stops after 100 pages per collection. The SDK supplies its standard retry behavior; no additional retry loop is layered on top. A final request failure produces an incomplete collection. + +JSON retains the selected properties from all successfully validated pages, including older resolved issues. Report candidates are unresolved issues **or** issues last modified on/after `FirstObservedUtc - LookBackHours`. This is a local selection rule, not a historical API query, root-cause match, or service filter. It cannot recover records the API no longer returns. No issue posts, sign-in logs, mailbox data, user inventory, or configuration are collected. + +`CollectionStatus: Complete` means both collections finished. `Incomplete` means at least one did not; review each collection's `Status`, `Pages`, `FailureReason`, and retained items. Available evidence is written before a terminating error is raised. A `pwsh -File` invocation returns nonzero for incomplete collection. Invalid input, context, or local write failures also terminate and may produce no complete bundle. + +Failure reasons: `RequestFailed` (check authentication, consent, connectivity, or throttling); `UnsafeContinuation`, `RepeatedContinuation`, `PageLimit` (collection stopped); `InvalidResponse`, `InvalidItem` (unexpected API data). Raw HTTP error bodies are deliberately excluded. Investigate a request failure in the approved administrative environment instead of pasting raw diagnostics into a public report. + +Service status strings are retained as reported. A complete empty collection or zero candidates is not proof of health. Compare candidates against symptom, time, service, and affected scope; check the current admin-center advisory before citing it. + +## Run the offline tests + +```powershell +./tests/Test-M365IncidentTriage.ps1 +``` + +The tests exercise pagination, partial failures, response validation, tenant/scope/cloud checks, selection, escaping, repeat-run preservation, and the live entry point using a local fake Graph module. Test files remain in the printed temporary directory for inspection. No real tenant is contacted. Real authentication, consent, tenant-specific permissions, and live SDK/API behavior require a separate tenant smoke test before operational adoption. + +Article: https://dleontev.com/blog/building-a-microsoft-365-incident-triage-toolkit-with-powershell + +API references: [health overviews](https://learn.microsoft.com/en-us/graph/api/serviceannouncement-list-healthoverviews?view=graph-rest-1.0), [issues](https://learn.microsoft.com/en-us/graph/api/serviceannouncement-list-issues?view=graph-rest-1.0), [authentication](https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0), [paging](https://learn.microsoft.com/en-us/graph/paging), [throttling](https://learn.microsoft.com/en-us/graph/throttling). diff --git a/tools/microsoft-365-incident-triage-toolkit/demo-snapshot.json b/tools/microsoft-365-incident-triage-toolkit/demo-snapshot.json new file mode 100644 index 0000000..92f824e --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/demo-snapshot.json @@ -0,0 +1,53 @@ +{ + "synthetic": true, + "snapshotAtUtc": "2026-09-14T16:30:00Z", + "collections": { + "healthOverviews": { + "value": [ + { "id": "demo-exchange", "service": "Exchange Online", "status": "ServiceDegradation" }, + { "id": "demo-teams", "service": "Microsoft Teams", "status": "ServiceOperational" }, + { "id": "demo-sharepoint", "service": "SharePoint Online", "status": "ServiceOperational" } + ] + }, + "issues": { + "value": [ + { + "id": "DEMO-EX-001", + "title": "Synthetic example: delayed mailbox access", + "service": "Exchange Online", + "status": "ServiceDegradation", + "classification": "incident", + "startDateTime": "2026-09-14T15:45:00Z", + "endDateTime": null, + "lastModifiedDateTime": "2026-09-14T16:20:00Z", + "isResolved": false, + "impactDescription": "Fictional users may experience delayed mailbox access. This is not a real Microsoft advisory." + }, + { + "id": "DEMO-TM-002", + "title": "Synthetic example: resolved meeting join delays", + "service": "Microsoft Teams", + "status": "ServiceRestored", + "classification": "advisory", + "startDateTime": "2026-09-13T17:00:00Z", + "endDateTime": "2026-09-13T18:00:00Z", + "lastModifiedDateTime": "2026-09-13T18:15:00Z", + "isResolved": true, + "impactDescription": "Fictional meeting join delays have ended; included to demonstrate recently updated resolved issues." + }, + { + "id": "DEMO-SP-003", + "title": "Synthetic example: older resolved issue", + "service": "SharePoint Online", + "status": "ServiceRestored", + "classification": "advisory", + "startDateTime": "2026-09-01T10:00:00Z", + "endDateTime": "2026-09-01T11:00:00Z", + "lastModifiedDateTime": "2026-09-01T11:15:00Z", + "isResolved": true, + "impactDescription": "Outside the demo selection window; retained in evidence but omitted from report candidates." + } + ] + } + } +} diff --git a/tools/microsoft-365-incident-triage-toolkit/escalation-template.md b/tools/microsoft-365-incident-triage-toolkit/escalation-template.md new file mode 100644 index 0000000..a612ac3 --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/escalation-template.md @@ -0,0 +1,35 @@ +# Microsoft 365 incident escalation + +Complete placeholders before sending. Use UTC timestamps. Keep personal information and detailed logs in the approved incident system; reference them here when possible. + +## Incident and impact + +- Incident ID: [ticket reference] +- Service and failing user action: [specific symptom] +- First observed (UTC): [YYYY-MM-DDTHH:mm:ssZ] +- Affected population and business impact: [confirmed scope; distinguish estimates] +- Unaffected comparison: [working user/client/location/network] +- Current severity and owner: [per your incident process] + +## Evidence and working assessment + +- Snapshot start/end (UTC): [from evidence.json] +- Collection status: [Complete/Incomplete; list failed collections] +- Microsoft advisory candidate(s): [ID, service, last update, symptom/time match] +- Correlation assessment: [confirmed observations; what remains unverified] +- Reproduction steps and result: [client, version, time, action, observed error] +- Checks performed: [time, action, result, evidence reference] +- Recent changes and relevance: [known facts; avoid assuming causation] +- Workaround and verification: [tested outcome and limits] +- Changes made during response: [none, or change record plus rollback/verification status] + +## Requested action and next update + +- Escalation destination: [owning team or vendor] +- Specific help requested: [decision or investigation needed] +- Evidence attachments: [reviewed/redacted report, JSON, and approved log references] +- Next action, owner, and deadline (UTC): [complete] +- Next stakeholder update (UTC): [complete] +- Closure verification: [affected user action succeeds; scope and observation period] + +Collection success does not establish service health or root cause. The generated files are not automatically anonymized; review them before attaching or sending. diff --git a/tools/microsoft-365-incident-triage-toolkit/samples/evidence.json b/tools/microsoft-365-incident-triage-toolkit/samples/evidence.json new file mode 100644 index 0000000..439c8c5 --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/samples/evidence.json @@ -0,0 +1,111 @@ +{ + "SchemaVersion": "1.0", + "ToolkitVersion": "1.0.0", + "Mode": "Demo", + "TenantId": "SYNTHETIC — no tenant", + "PowerShellVersion": "7.6.5", + "GraphAuthenticationVersion": null, + "StartedAtUtc": "2026-09-14T16:30:00.0000000+00:00", + "FinishedAtUtc": "2026-09-14T16:30:00.0000000+00:00", + "Incident": { + "IncidentId": "DEMO-INC-001", + "Symptom": "Outlook on the web loads slowly for a fictional pilot group.", + "Impact": "Six fictional users; email response work delayed.", + "FirstObservedUtc": "2026-09-14T16:00:00.0000000+00:00" + }, + "IssuesSinceUtc": "2026-09-13T16:00:00.0000000+00:00", + "CollectionStatus": "Complete", + "Collections": { + "HealthOverviews": { + "Status": "Complete", + "Pages": 1, + "FailureReason": null, + "Items": [ + { + "id": "demo-exchange", + "service": "Exchange Online", + "status": "ServiceDegradation" + }, + { + "id": "demo-teams", + "service": "Microsoft Teams", + "status": "ServiceOperational" + }, + { + "id": "demo-sharepoint", + "service": "SharePoint Online", + "status": "ServiceOperational" + } + ] + }, + "Issues": { + "Status": "Complete", + "Pages": 1, + "FailureReason": null, + "Items": [ + { + "id": "DEMO-EX-001", + "title": "Synthetic example: delayed mailbox access", + "service": "Exchange Online", + "status": "ServiceDegradation", + "classification": "incident", + "startDateTime": "2026-09-14T15:45:00Z", + "endDateTime": null, + "lastModifiedDateTime": "2026-09-14T16:20:00Z", + "isResolved": false, + "impactDescription": "Fictional users may experience delayed mailbox access. This is not a real Microsoft advisory." + }, + { + "id": "DEMO-TM-002", + "title": "Synthetic example: resolved meeting join delays", + "service": "Microsoft Teams", + "status": "ServiceRestored", + "classification": "advisory", + "startDateTime": "2026-09-13T17:00:00Z", + "endDateTime": "2026-09-13T18:00:00Z", + "lastModifiedDateTime": "2026-09-13T18:15:00Z", + "isResolved": true, + "impactDescription": "Fictional meeting join delays have ended; included to demonstrate recently updated resolved issues." + }, + { + "id": "DEMO-SP-003", + "title": "Synthetic example: older resolved issue", + "service": "SharePoint Online", + "status": "ServiceRestored", + "classification": "advisory", + "startDateTime": "2026-09-01T10:00:00Z", + "endDateTime": "2026-09-01T11:00:00Z", + "lastModifiedDateTime": "2026-09-01T11:15:00Z", + "isResolved": true, + "impactDescription": "Outside the demo selection window; retained in evidence but omitted from report candidates." + } + ] + } + }, + "CandidateIssues": [ + { + "id": "DEMO-EX-001", + "title": "Synthetic example: delayed mailbox access", + "service": "Exchange Online", + "status": "ServiceDegradation", + "classification": "incident", + "startDateTime": "2026-09-14T15:45:00Z", + "endDateTime": null, + "lastModifiedDateTime": "2026-09-14T16:20:00Z", + "isResolved": false, + "impactDescription": "Fictional users may experience delayed mailbox access. This is not a real Microsoft advisory." + }, + { + "id": "DEMO-TM-002", + "title": "Synthetic example: resolved meeting join delays", + "service": "Microsoft Teams", + "status": "ServiceRestored", + "classification": "advisory", + "startDateTime": "2026-09-13T17:00:00Z", + "endDateTime": "2026-09-13T18:00:00Z", + "lastModifiedDateTime": "2026-09-13T18:15:00Z", + "isResolved": true, + "impactDescription": "Fictional meeting join delays have ended; included to demonstrate recently updated resolved issues." + } + ] +} diff --git a/tools/microsoft-365-incident-triage-toolkit/samples/report.md b/tools/microsoft-365-incident-triage-toolkit/samples/report.md new file mode 100644 index 0000000..08aae7e --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/samples/report.md @@ -0,0 +1,67 @@ +# Microsoft 365 incident triage + +**SYNTHETIC DEMO — no tenant data or live requests.** + +Collection: **Complete**. This is collection status, not service health. + +- IncidentId: DEMO-INC-001 +- Symptom: Outlook on the web loads slowly for a fictional pilot group. +- Impact: Six fictional users; email response work delayed. +- FirstObservedUtc: 2026-09-14T16:00:00.0000000+00:00 +- Tenant: SYNTHETIC — no tenant +- Snapshot started (UTC): 2026-09-14T16:30:00.0000000+00:00 +- Snapshot finished (UTC): 2026-09-14T16:30:00.0000000+00:00 +- Issue selection: unresolved OR last modified on/after 2026-09-13T16:00:00.0000000+00:00 + +## Collection results + +| Collection | Result | Pages | Retained items | Failure reason | +| --- | --- | --- | --- | --- | +| HealthOverviews | Complete | 1 | 3 | | +| Issues | Complete | 1 | 3 | | + +## Service health snapshot + +| Service | Reported status | +| --- | --- | +| Exchange Online | ServiceDegradation | +| Microsoft Teams | ServiceOperational | +| SharePoint Online | ServiceOperational | + +## Issues to review + +These are candidates for manual review. Their presence does not establish the cause of this incident. + +### DEMO-EX-001: Synthetic example: delayed mailbox access + +- service: Exchange Online +- status: ServiceDegradation +- classification: incident +- isResolved: False +- startDateTime: 2026-09-14T15:45:00Z +- endDateTime: Not reported +- lastModifiedDateTime: 2026-09-14T16:20:00Z +- impactDescription: Fictional users may experience delayed mailbox access. This is not a real Microsoft advisory. + +### DEMO-TM-002: Synthetic example: resolved meeting join delays + +- service: Microsoft Teams +- status: ServiceRestored +- classification: advisory +- isResolved: True +- startDateTime: 2026-09-13T17:00:00Z +- endDateTime: 2026-09-13T18:00:00Z +- lastModifiedDateTime: 2026-09-13T18:15:00Z +- impactDescription: Fictional meeting join delays have ended; included to demonstrate recently updated resolved issues. + +## Handoff — complete before escalating + +- Confirmed observations and reproduction steps: [complete] +- Affected and unaffected users, clients, locations, and networks: [complete] +- Candidate Microsoft issue and symptom/time match: [complete; correlation unconfirmed] +- Checks performed, evidence references, and results: [complete] +- Changes made and verification/rollback status: [complete; this collector changes no tenant settings] +- Workaround and business impact: [complete] +- Escalation request, owner, and next update (UTC): [complete] + +Review and redact this report and evidence.json before sharing; neither is automatically anonymized. diff --git a/tools/microsoft-365-incident-triage-toolkit/tests/Test-M365IncidentTriage.ps1 b/tools/microsoft-365-incident-triage-toolkit/tests/Test-M365IncidentTriage.ps1 new file mode 100644 index 0000000..4223523 --- /dev/null +++ b/tools/microsoft-365-incident-triage-toolkit/tests/Test-M365IncidentTriage.ps1 @@ -0,0 +1,181 @@ +#requires -Version 7.5 +[CmdletBinding()] +param([string]$OutputRoot = (Join-Path ([IO.Path]::GetTempPath()) ('triage-tests-' + [guid]::NewGuid().ToString('N')))) +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +$kit = Split-Path $PSScriptRoot -Parent +Import-Module (Join-Path $kit 'M365IncidentTriage.psm1') -Force +$null = [IO.Directory]::CreateDirectory($OutputRoot) +$passed = 0 +function Assert($Condition, [string]$Message) { if (-not $Condition) { throw $Message } } +function Test([string]$Name, [scriptblock]$Body) { + & $Body + $script:passed++ + Write-Host "PASS $Name" +} +function Assert-Throws([scriptblock]$Body) { + $threw = $false + try { & $Body | Out-Null } catch { $threw = $true } + Assert $threw 'Expected a terminating error.' +} +$fixturePath = Join-Path $kit 'demo-snapshot.json' +$fixture = Get-Content -LiteralPath $fixturePath -Raw | ConvertFrom-Json -AsHashtable -DateKind String +$healthRow = $fixture.collections.healthOverviews.value[0] +$baseUri = 'https://graph.microsoft.com/v1.0/admin/serviceAnnouncement/healthOverviews' +$page2 = $baseUri + '?$skiptoken=synthetic' + +Test 'Pagination follows an empty first page' { + $healthRow = $healthRow; $page2 = $page2 + $calls = [Collections.Generic.List[string]]::new() + $request = { + param($uri) + $calls.Add($uri) + if ($uri -eq $page2) { return @{ value = @($healthRow) } } + @{ value = @(); '@odata.nextLink' = $page2 } + }.GetNewClosure() + $r = Read-TriageCollection healthOverviews $request + Assert ($r.Status -eq 'Complete' -and $r.Pages -eq 2 -and $r.Items.Count -eq 1) 'Lost a later page.' + Assert ($calls[1] -ceq $page2) 'Continuation was rebuilt rather than followed.' +} +Test 'A later request failure retains earlier evidence and marks it incomplete' { + $healthRow = $healthRow; $page2 = $page2 + $request = { + param($uri) + if ($uri -eq $page2) { throw 'Synthetic HTTP failure; do not export this body.' } + @{ value = @($healthRow); '@odata.nextLink' = $page2 } + }.GetNewClosure() + $r = Read-TriageCollection healthOverviews $request + Assert ($r.Status -eq 'Incomplete' -and $r.Items.Count -eq 1 -and $r.FailureReason -eq 'RequestFailed') 'Partial failure was hidden.' +} +Test 'A foreign continuation is rejected before a request' { + $healthRow = $healthRow + $calls = [Collections.Generic.List[string]]::new() + $request = { param($uri); $calls.Add($uri); @{ value = @($healthRow); '@odata.nextLink' = 'https://example.org/collect' } }.GetNewClosure() + $r = Read-TriageCollection healthOverviews $request + Assert ($r.FailureReason -eq 'UnsafeContinuation' -and $calls.Count -eq 1) 'Requested a foreign host.' +} +Test 'Cross-resource, insecure, and credential-bearing continuations are rejected' { + foreach ($bad in @('https://graph.microsoft.com/v1.0/users', + 'http://graph.microsoft.com/v1.0/admin/serviceAnnouncement/healthOverviews', + 'https://user@graph.microsoft.com/v1.0/admin/serviceAnnouncement/healthOverviews')) { + $request = { param($uri); @{ value = @(); '@odata.nextLink' = $bad } }.GetNewClosure() + $r = Read-TriageCollection healthOverviews $request + Assert ($r.FailureReason -eq 'UnsafeContinuation') "Accepted $bad" + } +} +Test 'Repeated pages and page limits stop collection' { + $page2 = $page2 + $request = { param($uri); @{ value = @(); '@odata.nextLink' = $page2 } }.GetNewClosure() + Assert ((Read-TriageCollection healthOverviews $request).FailureReason -eq 'RepeatedContinuation') 'Loop not detected.' + Assert ((Read-TriageCollection healthOverviews $request -MaxPages 1).FailureReason -eq 'PageLimit') 'Page limit ignored.' +} +Test 'Malformed responses cannot look like empty success' { + foreach ($badPage in @(@{}, @{value = $null}, @{value = 'invalid'}, @{value = @(@{id = 'x'})})) { + $request = { param($uri); $badPage }.GetNewClosure() + Assert ((Read-TriageCollection healthOverviews $request).Status -eq 'Incomplete') 'Malformed data treated as success.' + } +} +Test 'Missing issue state or date is incomplete' { + foreach ($property in @('isResolved', 'lastModifiedDateTime')) { + $row = $fixture.collections.issues.value[0].Clone() + $row.Remove($property) + $request = { param($uri); @{value = @($row)} }.GetNewClosure() + Assert ((Read-TriageCollection issues $request).FailureReason -eq 'InvalidItem') 'Invalid issue accepted.' + } +} +Test 'Selection retains open issues and recently updated resolved issues' { + $rows = @(Select-TriageIssue $fixture.collections.issues.value ([datetimeoffset]'2026-09-13T16:00:00Z')) + Assert ($rows.Count -eq 2 -and $rows.id -contains 'DEMO-TM-002' -and $rows.id -notcontains 'DEMO-SP-003') 'Incorrect date selection.' + $rows = @(Select-TriageIssue $fixture.collections.issues.value ([datetimeoffset]'2026-09-15T00:00:00Z')) + Assert ($rows.Count -eq 1 -and $rows[0].id -eq 'DEMO-EX-001') 'Old unresolved issue was dropped.' +} +Test 'Tenant, delegated scope, and cloud checks fail closed' { + $context = @{TenantId = '00000000-0000-0000-0000-000000000001'; AuthType = 'Delegated'; Environment = 'Global'; Scopes = @('ServiceHealth.Read.All')} + Assert-TriageContext $context ([guid]$context.TenantId) + Assert-Throws { Assert-TriageContext $null ([guid]$context.TenantId) } + foreach ($change in @(@{TenantId = '00000000-0000-0000-0000-000000000002'}, @{AuthType = 'AppOnly'}, @{Environment = 'USGov'}, @{Scopes = @('User.Read')})) { + $badContext = $context.Clone() + foreach ($key in $change.Keys) { $badContext[$key] = $change[$key] } + Assert-Throws { Assert-TriageContext $badContext ([guid]$context.TenantId) } + } +} +$demoParams = @{ + Demo = $true; IncidentId = 'DEMO-INC-001' + Symptom = 'Outlook on the web loads slowly for a fictional pilot group.' + Impact = 'Six fictional users; email response work delayed.' + FirstObservedUtc = '2026-09-14T16:00:00Z'; OutputRoot = $OutputRoot +} +Test 'Demo runs offline and produces a labeled, parseable bundle' { + $run = & (Join-Path $kit 'Export-M365IncidentTriage.ps1') @demoParams + $e = Get-Content -LiteralPath (Join-Path $run.OutputDirectory 'evidence.json') -Raw | ConvertFrom-Json -AsHashtable -DateKind String + $report = Get-Content -LiteralPath (Join-Path $run.OutputDirectory 'report.md') -Raw + Assert ($e.Mode -eq 'Demo' -and $e.CollectionStatus -eq 'Complete' -and $e.CandidateIssues.Count -eq 2) 'Demo output is wrong.' + Assert ($report.Contains('SYNTHETIC DEMO') -and $report.Contains('DEMO-TM-002')) 'Missing synthetic label or candidate.' + $script:firstRun = $run.OutputDirectory +} +Test 'Repeat runs preserve prior evidence and escape report text' { + $before = (Get-FileHash -LiteralPath (Join-Path $firstRun 'evidence.json')).Hash + $params = $demoParams.Clone() + $params.Symptom = " | [click](https://example.org)`n# forged heading" + $run = & (Join-Path $kit 'Export-M365IncidentTriage.ps1') @params + $report = Get-Content -LiteralPath (Join-Path $run.OutputDirectory 'report.md') -Raw + Assert ($run.OutputDirectory -ne $firstRun -and $before -eq (Get-FileHash -LiteralPath (Join-Path $firstRun 'evidence.json')).Hash) 'Prior evidence overwritten.' + Assert (-not $report.Contains('