From 34edadf0dbfeebc20f6176673206e9dad7097624 Mon Sep 17 00:00:00 2001 From: Oliver Kieselbach Date: Thu, 16 Jul 2026 19:14:36 +0200 Subject: [PATCH] docs(rules): document observability limits of the ZTD known-issue rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agent is normally installed by an IME platform script AFTER MDM enrollment succeeded, so pre-enrollment failures (enrollment blockers, TPM attestation) are invisible in the normal flow — no enrollment means no agent and no authenticable session. Await-enrollment mode does not help either: the binary only polls for the MDM certificate and cannot authenticate without it. Only bootstrap-token deployments (one pilot customer) can report pre-MDM. - New Observability section in docs/agent/autopilot-ztd-diagnostics.md with a per-rule visibility matrix (normal / bootstrap / await) and the follow-up option of backfilling Autopilot-channel error records - ANALYZE-ENRL-003/004 descriptions state the limitation explicitly so portal users understand why these rules rarely fire Co-Authored-By: Claude Fable 5 --- docs/agent/autopilot-ztd-diagnostics.md | 22 ++++++++++++++++++++++ rules/analyze/ANALYZE-ENRL-003.json | 2 +- rules/analyze/ANALYZE-ENRL-004.json | 2 +- rules/dist/analyze-rules.json | 4 ++-- 4 files changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/agent/autopilot-ztd-diagnostics.md b/docs/agent/autopilot-ztd-diagnostics.md index 4a01a94e..e689c80f 100644 --- a/docs/agent/autopilot-ztd-diagnostics.md +++ b/docs/agent/autopilot-ztd-diagnostics.md @@ -84,6 +84,28 @@ blank cache. | `*.microsoftaik.azure.net` (+ per-vendor EK cert URLs) | TPM attestation for self-deploying/pre-provisioning. | not probed | | `lgmsapeweu.blob.core.windows.net` | Intune automatic diagnostics upload. | deliberately not probed (decision 2026-07-16: not mission-critical) | +# Observability — when the agent can actually see these errors + +The agent's install timing bounds what the known-issue rules can ever observe. In the +normal deployment model the agent is installed by an **Intune platform script via IME — +i.e. only AFTER MDM enrollment succeeded**. Everything that happens before that point +(profile download, TPM attestation in self-deploying/pre-provisioning, the MDM enrollment +handshake itself) is over before our process exists. + +| Failure class | Normal flow (IME install) | Bootstrap token mode | Await-enrollment mode | +| --- | --- | --- | --- | +| Enrollment blocked (0x80180014/18, 0xC1036501, 0x801C03F3 → ANALYZE-ENRL-004) | **Invisible** — no enrollment ⇒ no agent, no session. | **Visible** — the bootstrap token exists precisely to report pre-MDM (as of 2026-07: one customer piloting). | **Invisible to the backend** — the agent binary is present but only polls for the MDM certificate; without the cert it cannot authenticate, and monitoring starts only after the cert appears. A hard blocker ends in the await timeout (default 480 min) with nothing uploaded. | +| TPM attestation (ANALYZE-ENRL-003) | **Almost never live** — attestation precedes enrollment. Retry-then-success leaves the earlier errors in the Autopilot channel, but the continuous watcher is live-only and the startup backfill targets ManagementService 509 only, so they are not forwarded. | Visible. | Same limits as normal flow once monitoring starts. | +| Hybrid-join 0x80004005 (ANALYZE-ENRL-005) | **Visible** — the ODJ/hybrid phase runs during device ESP while the agent is active. | Visible. | Visible after cert arrival. | +| Clock skew (ANALYZE-DEV-007) | **Always** — ntp_time_check is our own event. | Always. | Always. | + +The rules stay enabled despite the narrow normal-flow windows: they are evidence-gated +(zero cost when the codes never appear) and they future-proof the bootstrap and +await-enrollment paths. Known follow-up option: extend the ModernDeploymentTracker +startup backfill to also replay Autopilot-channel Error-level records (807/809/815/908, +171/172) from before agent start — that would make the retry-then-success TPM case and +late-visible ZTD errors observable in the normal flow too. + # Schema — Error codes (backend known-issue map) Codes documented in the known-issues / troubleshooting-FAQ pages that appear in ESP/enrollment diff --git a/rules/analyze/ANALYZE-ENRL-003.json b/rules/analyze/ANALYZE-ENRL-003.json index d3426e46..6f793217 100644 --- a/rules/analyze/ANALYZE-ENRL-003.json +++ b/rules/analyze/ANALYZE-ENRL-003.json @@ -2,7 +2,7 @@ "$schema": "../schema/analyze-rule.schema.json", "ruleId": "ANALYZE-ENRL-003", "title": "TPM Attestation Failure — Known Error Code", - "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).", + "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Observability: attestation precedes MDM enrollment, so in the normal deployment model (agent installed via IME after enrollment) these codes are rarely visible — the rule primarily serves bootstrap-token deployments. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).", "severity": "high", "category": "enrollment", "version": "1.0.0", diff --git a/rules/analyze/ANALYZE-ENRL-004.json b/rules/analyze/ANALYZE-ENRL-004.json index baa62c49..46afc53d 100644 --- a/rules/analyze/ANALYZE-ENRL-004.json +++ b/rules/analyze/ANALYZE-ENRL-004.json @@ -2,7 +2,7 @@ "$schema": "../schema/analyze-rule.schema.json", "ruleId": "ANALYZE-ENRL-004", "title": "MDM Enrollment Blocked — Known Error Code", - "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).", + "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Observability: a blocked MDM enrollment normally means no agent gets installed at all (IME install happens after enrollment) — this rule can realistically only fire for bootstrap-token deployments (pre-MDM reporting) or mixed retry scenarios. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).", "severity": "high", "category": "enrollment", "version": "1.0.0", diff --git a/rules/dist/analyze-rules.json b/rules/dist/analyze-rules.json index 859651e9..5c6fe740 100644 --- a/rules/dist/analyze-rules.json +++ b/rules/dist/analyze-rules.json @@ -1317,7 +1317,7 @@ { "ruleId": "ANALYZE-ENRL-003", "title": "TPM Attestation Failure — Known Error Code", - "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).", + "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Observability: attestation precedes MDM enrollment, so in the normal deployment model (agent installed via IME after enrollment) these codes are rarely visible — the rule primarily serves bootstrap-token deployments. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).", "severity": "high", "category": "enrollment", "version": "1.0.0", @@ -1402,7 +1402,7 @@ { "ruleId": "ANALYZE-ENRL-004", "title": "MDM Enrollment Blocked — Known Error Code", - "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).", + "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Observability: a blocked MDM enrollment normally means no agent gets installed at all (IME install happens after enrollment) — this rule can realistically only fire for bootstrap-token deployments (pre-MDM reporting) or mixed retry scenarios. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).", "severity": "high", "category": "enrollment", "version": "1.0.0",