diff --git a/ROADMAP.md b/ROADMAP.md index fa61cba1..db15d846 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -162,8 +162,11 @@ The dependency is those observations, not the absence of a Windows host. The [issuer/recovery follow-up](docs/roadmap/etw-issuer-recovery.md) adds held thread/process interval proof with fresh full FILETIME joins, an authenticated original-handle cleanup guard and a two-capture packaged qualification. This - narrows E4 and collector-crash cleanup; production/path admission, pre-arm and - simultaneous guard/collector crash, actual reuse and sleep/wake remain open. + narrows E4 and collector-crash cleanup. The subsequent + [failure-boundary qualification](docs/roadmap/etw-failure-boundaries.md) passes + seven packaged cases including pre-arm reservation recovery, guard/broker loss + and abrupt Electron exit. Production/path admission, simultaneous guard/collector + crash, protected recovery, actual reuse and sleep/wake remain open. ## C — existing rules coverage diff --git a/docs/development/packaged-desktop-milestone.md b/docs/development/packaged-desktop-milestone.md index 16852519..395f7837 100644 --- a/docs/development/packaged-desktop-milestone.md +++ b/docs/development/packaged-desktop-milestone.md @@ -210,6 +210,20 @@ two-capture PASS, exact tested source, evidence hashes and retained failed attem Its Read issuer subset and original-handle guard cleanup do not close production path attribution, protected installation or all remaining ETW gates. +### ETW failure boundaries + +Use `--etw-failures` instead of `--etw` for seven planned captures covering +collector exit before start/arm, guard loss, broker loss, abrupt owned Electron +exit and the two-capture issuer/recovery regression. The profile independently +queries session presence/absence and checks visible failure and blocked retry. +It has a 15-minute parent deadline and stops at the first failed scenario. Each +capture needs a same-account UAC decision; a query-only elevated witness may also +be needed when ordinary queries are denied. See the [failure contract](../roadmap/etw-failure-boundaries.md) +for capability boundaries and remaining qualification limits. +The [2026-10-18 evidence](../recon/evidence/etw-packaged-failure-boundaries.json) +records seven actual packaged PASS cases at source `278f0754`, an independently +exercised elevated query witness and the retained initial pre-capture build failure. + ### Other qualification Without `--monitoring`, PASS covers the visible packaged-window lifecycle with modeled installation diff --git a/docs/recon/evidence/etw-packaged-failure-boundaries.json b/docs/recon/evidence/etw-packaged-failure-boundaries.json new file mode 100644 index 00000000..ae9b8e70 --- /dev/null +++ b/docs/recon/evidence/etw-packaged-failure-boundaries.json @@ -0,0 +1,683 @@ +{ + "schemaVersion": 1, + "scope": "Mutable local diagnostic Windows package; no production admission", + "source": { + "head": "278f075438ee7c027f1435be4721a48db4ca0049", + "tree": "c827dbcae264de195e0f6fd55db125f0a8890708", + "lockSha256": "836c4cb4b3791d8822845443668354f7a025b937c1f751542e762c1940634df6" + }, + "host": { + "platform": "win32", + "arch": "x64", + "node": "v24.11.1", + "os": "10.0.26200", + "compilerSha256": "46809206887326d2d24db1eff1f3064de972c3451abe766b49111450a5e08e00" + }, + "qualification": { + "status": "PASS", + "completedAt": "2026-10-18T10:40:06.546Z", + "receiptSha256": "6478a23b2fcf92f877ec8fbfd1a9ccbcc477f3699cff668268589c5f52dd7a7b", + "etwReceiptSha256": "c129c636410303148ef680b2b00bdade101ac4af64d1122495b025a1f022b346", + "packageManifestSha256": "397a3c6c519e2e499493fc82431ac5bae46963d3d1d78af46fb6ce132d942e3f" + }, + "packageSourceCheck": { + "head": "278f075438ee7c027f1435be4721a48db4ca0049", + "trackedRuntimeFiles": 229, + "mismatches": [], + "mutants": [], + "nativeDllMatches": true + }, + "localChecks": { + "nativeSelfTests": 76, + "focusedJavaScriptTests": 145, + "typecheck": true, + "syntheticNativeTransport": true, + "witnessMutationGate": true, + "sequenceMutationGate": true, + "counts": true + }, + "cases": { + "collector-before-start": { + "status": "PASS", + "mode": "collector-before-start", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "before": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "after": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "failureVisible": true, + "noAutomaticRestart": true, + "closureConfirmed": true, + "nativeHelperClosure": "broker verified retained collector and guard exits", + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 0, + "summary": { + "phase": "recovered", + "exitCode": 4, + "collectorExit": 70, + "stopReason": null, + "stopVerified": false, + "recoveryVerified": true, + "observationGap": true, + "finalCounters": { + "queryStatus": 4201, + "eventsLost": null, + "realTimeBuffersLost": null, + "logBuffersLost": null, + "asOfQpc": "568529315121" + }, + "finalTotals": null, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "0", + "filtered": "0", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "0", + "mapResets": "0", + "mapConflicts": "0" + }, + "ringDropped": 0, + "capture": null + } + }, + "collector-before-arm": { + "status": "PASS", + "mode": "collector-before-arm", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "before": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "after": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "failureVisible": true, + "noAutomaticRestart": true, + "closureConfirmed": true, + "nativeHelperClosure": "broker verified retained collector and guard exits", + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 0, + "summary": { + "phase": "recovered", + "exitCode": 4, + "collectorExit": 70, + "stopReason": null, + "stopVerified": false, + "recoveryVerified": true, + "observationGap": true, + "finalCounters": { + "queryStatus": 0, + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "asOfQpc": "568619554175" + }, + "finalTotals": null, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "0", + "filtered": "0", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "0", + "mapResets": "0", + "mapConflicts": "0" + }, + "ringDropped": 0, + "capture": null + } + }, + "guard-exit": { + "status": "PASS", + "mode": "guard-exit", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "liveReady": true, + "before": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "presence": { + "status": 0, + "present": true, + "elevatedWitness": false + }, + "after": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "restartBlocked": true, + "failureVisible": true, + "noAutomaticRestart": true, + "closureConfirmed": true, + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 3, + "summary": { + "phase": "failed", + "exitCode": 2, + "collectorExit": null, + "stopReason": null, + "stopVerified": false, + "recoveryVerified": false, + "observationGap": true, + "finalCounters": null, + "finalTotals": null, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "425955", + "filtered": "425925", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "0", + "mapResets": "0", + "mapConflicts": "0" + }, + "ringDropped": 0, + "capture": { + "buffers": { + "count": 256, + "sizeKiB": 64 + }, + "frequency": "10000000", + "clock": { + "qpc": "568708901672", + "unixMs": "1792319844779", + "uncertaintyQpc": "10358" + } + } + } + }, + "broker-exit": { + "status": "PASS", + "mode": "broker-exit", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "liveReady": true, + "before": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "presence": { + "status": 0, + "present": true, + "elevatedWitness": false + }, + "after": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "restartBlocked": true, + "failureVisible": true, + "noAutomaticRestart": true, + "closureConfirmed": true, + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 3, + "summary": { + "phase": "failed", + "exitCode": 72, + "collectorExit": null, + "stopReason": null, + "stopVerified": false, + "recoveryVerified": false, + "observationGap": true, + "finalCounters": null, + "finalTotals": null, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "251624", + "filtered": "251594", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "4", + "mapResets": "4", + "mapConflicts": "0" + }, + "ringDropped": 0, + "capture": { + "buffers": { + "count": 256, + "sizeKiB": 64 + }, + "frequency": "10000000", + "clock": { + "qpc": "569137698049", + "unixMs": "1792319887658", + "uncertaintyQpc": "10219" + } + } + } + }, + "app-exit": { + "status": "PASS", + "mode": "app-exit", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "liveReady": true, + "before": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "presence": { + "status": 0, + "present": true, + "elevatedWitness": false + }, + "after": { + "status": 4201, + "present": false, + "elevatedWitness": false + }, + "abruptAppExit": true, + "appExitCode": 73, + "closureConfirmed": true, + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 3 + } + }, + "regression": { + "crash": { + "status": "PASS", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "liveReady": true, + "failureVisible": true, + "noAutomaticRestart": true, + "closureConfirmed": true, + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 3, + "summary": { + "phase": "recovered", + "exitCode": 4, + "collectorExit": 70, + "stopReason": null, + "stopVerified": false, + "recoveryVerified": true, + "observationGap": true, + "finalCounters": { + "queryStatus": 0, + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "asOfQpc": "570047444805" + }, + "finalTotals": null, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "330143", + "filtered": "325905", + "dropped": "4097", + "ingressDropped": "4097", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "6", + "mapResets": "6", + "mapConflicts": "0" + }, + "ringDropped": 0, + "capture": { + "buffers": { + "count": 256, + "sizeKiB": 64 + }, + "frequency": "10000000", + "clock": { + "qpc": "569747021961", + "unixMs": "1792319948591", + "uncertaintyQpc": "10318" + } + } + } + }, + "normal": { + "status": "PASS", + "packaged": true, + "diagnosticBuild": true, + "windowInputIsolated": true, + "liveReady": true, + "closureConfirmed": true, + "contentExcluded": true, + "noDiagnosticAudit": true, + "observedAppPids": 5, + "observedHelperPids": 3, + "summary": { + "phase": "stopped", + "exitCode": 0, + "collectorExit": null, + "stopReason": "shutdown", + "stopVerified": true, + "recoveryVerified": false, + "observationGap": false, + "finalCounters": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "queryStatus": 0, + "asOfQpc": "570298162745" + }, + "finalTotals": { + "delivered": "140623", + "filtered": "140288", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "2", + "mapResets": "2", + "mapConflicts": "0" + }, + "maxima": { + "eventsLost": "0", + "realTimeBuffersLost": "0", + "logBuffersLost": "0", + "delivered": "140623", + "filtered": "140288", + "dropped": "0", + "ingressDropped": "0", + "outputDropped": "0", + "outputOverflowDropped": "0", + "outputInvalidatedDropped": "0", + "decoderErrors": "0", + "mapEpoch": "2", + "mapResets": "2", + "mapConflicts": "0" + }, + "ringDropped": 78, + "capture": { + "buffers": { + "count": 256, + "sizeKiB": 64 + }, + "frequency": "10000000", + "clock": { + "qpc": "570138118078", + "unixMs": "1792319987700", + "uncertaintyQpc": "10332" + } + } + } + }, + "newSessionAfterRecovery": true, + "readWitnesses": { + "crash": { + "sync": { + "native": { + "command": "sync", + "pid": 48164, + "tid": 44548, + "birth": "134367935454198101", + "reads": 160, + "pending": 0, + "fromQpc": "569747655489", + "toQpc": "569797813799" + }, + "observation": { + "eventId": 15, + "version": 1, + "qpc": "569773143263", + "issuerStatus": "verified", + "issuerPid": 48164, + "issuingTid": 44548, + "issuerInterval": { + "fromQpc": "569767750055", + "toQpc": "569788235082" + }, + "generationStatus": "verified", + "generationWitness": "134367935454198101", + "generationSource": "createTime100ns", + "generationInterval": { + "fromQpc": "569788223225", + "toQpc": "569788235082" + }, + "agent": "Aider", + "instanceId": "48164:1792319945419", + "pathEvidence": "unresolved" + } + }, + "async": { + "native": { + "command": "async", + "pid": 48164, + "tid": 44548, + "birth": "134367935454198101", + "reads": 160, + "pending": 160, + "fromQpc": "569798135266", + "toQpc": "569848075583" + }, + "observation": { + "eventId": 15, + "version": 1, + "qpc": "569817754891", + "issuerStatus": "verified", + "issuerPid": 48164, + "issuingTid": 44548, + "issuerInterval": { + "fromQpc": "569767750055", + "toQpc": "569837776195" + }, + "generationStatus": "verified", + "generationWitness": "134367935454198101", + "generationSource": "createTime100ns", + "generationInterval": { + "fromQpc": "569837776136", + "toQpc": "569837776195" + }, + "agent": "Aider", + "instanceId": "48164:1792319945419", + "pathEvidence": "unresolved" + } + } + }, + "normal": { + "sync": { + "native": { + "command": "sync", + "pid": 31624, + "tid": 23984, + "birth": "134367935845919097", + "reads": 160, + "pending": 0, + "fromQpc": "570138511727", + "toQpc": "570188769886" + }, + "observation": { + "eventId": 15, + "version": 1, + "qpc": "570163443405", + "issuerStatus": "verified", + "issuerPid": 31624, + "issuingTid": 23984, + "issuerInterval": { + "fromQpc": "570158841794", + "toQpc": "570178477313" + }, + "generationStatus": "verified", + "generationWitness": "134367935845919097", + "generationSource": "createTime100ns", + "generationInterval": { + "fromQpc": "570178465845", + "toQpc": "570178477313" + }, + "agent": "Aider", + "instanceId": "31624:1792319984591", + "pathEvidence": "candidate-object" + } + }, + "async": { + "native": { + "command": "async", + "pid": 31624, + "tid": 23984, + "birth": "134367935845919097", + "reads": 160, + "pending": 160, + "fromQpc": "570188921868", + "toQpc": "570238867205" + }, + "observation": { + "eventId": 15, + "version": 1, + "qpc": "570198296932", + "issuerStatus": "verified", + "issuerPid": 31624, + "issuingTid": 23984, + "issuerInterval": { + "fromQpc": "570158841794", + "toQpc": "570218856348" + }, + "generationStatus": "verified", + "generationWitness": "134367935845919097", + "generationSource": "createTime100ns", + "generationInterval": { + "fromQpc": "570218856295", + "toQpc": "570218856348" + }, + "agent": "Aider", + "instanceId": "31624:1792319984591", + "pathEvidence": "candidate-object" + } + } + } + } + }, + "independentElevatedQuery": { + "status": 4201, + "present": false, + "elevatedWitness": true, + "exitCode": 0, + "receiptSha256": "140fbdaed7ac0e29417b216bf5e7e6f26d20b4b3c99847be663284c7b033f97d" + }, + "allProfileAuditCheck": [ + { + "scenario": "collector-before-start", + "profileBytes": 8607765, + "allAuditRows": 51, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "collector-before-arm", + "profileBytes": 8576327, + "allAuditRows": 52, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "guard-exit", + "profileBytes": 8674494, + "allAuditRows": 81, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "broker-exit", + "profileBytes": 8767510, + "allAuditRows": 141, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "app-exit", + "profileBytes": 8562508, + "allAuditRows": 24, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "collector-after-ready", + "profileBytes": 8703410, + "allAuditRows": 103, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + }, + { + "scenario": "normal", + "profileBytes": 8719322, + "allAuditRows": 109, + "etwTypeRows": 0, + "fixtureFileAccessRows": 0 + } + ], + "earlierAttempts": [ + { + "status": "FAIL", + "phase": "package", + "noEtwCapture": true, + "sourceSha": "278f075438ee7c027f1435be4721a48db4ca0049", + "reason": "Mutation fixtures raced Electron packaging; gates completed before the separate successful package run", + "receiptSha256": "5e697515960082bc3a273f4f39835b427ccae76355dd410a2834f8e22c94c184" + } + ], + "limits": [ + "Simultaneous collector/guard loss requires protected recovery authority and is not qualified", + "Actual sleep/wake, alternate credentials, protected installation, complete I/O coverage, forced real PID/TID reuse and production/path admission remain open", + "Access-denied fallback trigger was not induced; an explicit elevated query witness was separately exercised", + "Counter maxima are sampled history; unverified final counters/totals stay null", + "Raw receipts/profiles/screenshots and failed attempts stay private under manual seven-day review; projections omit paths and trace capabilities" + ] +} diff --git a/docs/roadmap/etw-failure-boundaries.md b/docs/roadmap/etw-failure-boundaries.md new file mode 100644 index 00000000..52a8afa1 --- /dev/null +++ b/docs/roadmap/etw-failure-boundaries.md @@ -0,0 +1,79 @@ +# Remaining diagnostic ETW failure boundaries + +The optional `--etw-failures` packaged qualification exercises five additional +boundaries plus the existing collector-crash/read-attribution and fresh normal +capture regression. It is a mutable local diagnostic build. Ordinary packages, +production admission, path confirmation and protected installation remain gated. + +The collector's authenticated guard now acknowledges a random per-capture session +GUID reservation before StartTrace. If the collector dies before transferring its +successful StartTrace handle, the guard queries the fixed name without stopping +anything. Only a matching reserved GUID with a nonzero native HistoricalContext +can become an original-handle candidate. Recovery rechecks that handle/GUID before +stopping by handle and independently queries absence. A foreign occupied name, +invalid handle or failed query never grants stop authority. Before-start absence +is status 4201 with unknown counters, rather than a fabricated successful zero-loss +stop. No reservation or raw handle is persisted or exposed to renderer IPC. + +This closes a diagnostic ownership handoff gap; it does not establish a protected +service or durable recovery authority. The random GUID is an in-memory capability +shared only over the mutually authenticated owner/guard pipe. Microsoft documents +[ControlTrace query/stop semantics](https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-controltracew), +and its [TraceEvent session implementation](https://github.com/microsoft/perfview/blob/main/src/TraceEvent/TraceEventSession.cs) +uses queried Wnode.HistoricalContext as the session handle. Unlike generic session +attachment, this implementation requires the preannounced GUID and rejects foreign +identity before any handle-based recovery operation. + +The fixed fault modes exit only their own process: collector before StartTrace, +collector after StartTrace/before guard arm, guard after arm, broker after ready, +and the owned Electron main process. The latter bypasses normal app quit. No user +process intervention, arbitrary elevated kill, session-prefix cleanup or automatic +capture retry occurs. Native fault modes are selectable by main only in a marked +diagnostic package with one valid root and one exact whitelisted flag. + +Pre-ready collector faults require an authenticated guard receipt and broker exit +4. A lost guard or broker leaves main FAILED and restart blocked even if a separate +qualification witness subsequently observes absence. Failed runs retain maxima +from previous samples, but final counters/totals are null unless a valid terminal +stop/recovery and its expected process exit were both observed. Observation gaps +remain explicit. Nothing infers zero loss from a previous heartbeat. + +The query-only helper checks only the fixed session name. It cannot stop a trace, +select a provider or write an elevated output file. Status 0 proves presence; +4201 proves name absence; access denial and other errors are unknown. The normal +qualification owner retains bounded output. If an ordinary query is denied, it +explicitly launches a same-account query-only elevated peer over a restricted, +mutually authenticated pipe. Each scenario records before/after queries; ready +scenarios also require actual presence before the fault. Pre-ready helper exits +are confirmed by the broker's retained peer objects; later scenarios additionally +record independent owned PID enumeration. + +Run the isolated desktop qualifier with `--etw-failures` instead of `--etw`. +Seven planned captures each request one normal same-account UAC decision; query +witness UAC may additionally be needed if ordinary queries are denied. There is a +15-minute parent deadline, bounded per-case waits and private receipts/screenshots. +Any failed case stops the sequence before another capture. Diagnostic artifacts +use the existing manual seven-day review policy and preserve failed attempts. + +Simultaneous loss of collector and guard still needs protected recovery authority; +this profile does not deliberately orphan such a session or claim it recovered. +Actual sleep/wake, alternate credentials, complete I/O coverage, real forced +PID/TID reuse and the remaining E1-E8 gates are separate qualification work. + +The 2026-10-18 [packaged evidence](../recon/evidence/etw-packaged-failure-boundaries.json) +records all seven scenarios PASS at `278f075438ee7c027f1435be4721a48db4ca0049`. +Before-start exit produced status 4201 with unknown counters; pre-arm exit produced +verified guard cleanup with native query status 0. Guard/broker loss kept FAILED, +retry blocked and final counters/totals null, while independent queries subsequently +observed absence. Abrupt Electron exit 73 also left no observed owned helper or +session. The existing actual sync/pending-overlapped issuer proof, collector crash +and new normally stopped capture passed unchanged. A separate explicit elevated +query-only witness passed; the access-denied fallback trigger was not induced. + +All 229 packaged main/shared JS/JSON files matched the clean worktree; the published +native DLL matched its packaged copy and no mutation fixture entered the archive. +The first packaging attempt failed before ETW because a concurrently running +mutation gate removed a temporary file while the packager enumerated it. That +receipt is retained; the successful run started after both gates completed. The +evidence also hashes the raw receipts/package manifest and independently checks +all audit rows in all seven retained profiles for diagnostic admission. diff --git a/docs/roadmap/etw-issuer-recovery.md b/docs/roadmap/etw-issuer-recovery.md index a9f44575..3c3b0300 100644 --- a/docs/roadmap/etw-issuer-recovery.md +++ b/docs/roadmap/etw-issuer-recovery.md @@ -1,5 +1,10 @@ # Diagnostic issuer proof and collector recovery +The subsequent [failure-boundary follow-up](etw-failure-boundaries.md) adds +pre-start reservation and qualifies the diagnostic pre-arm gap, guard/broker loss +and abrupt Electron exit. The historical two-capture evidence below retains its +original scope and does not itself qualify those later cases. + Protocol `etw-file/6` adds a narrow Read v1 issuer proof and independent cleanup guard. Production capture, path confirmation and downstream FileEvent admission remain gated. This document describes implementation; each live receipt binds its @@ -34,9 +39,9 @@ Broker exit 4 plus a validated recovery receipt confirms cleanup while preservin FAILED capture health. Application-stage totals remain null and `observationGap` stays true. No receipt, receipt without expected exit, guard failure or conflicting session GUID blocks retry. Explicit retry after confirmed cleanup is permitted; -there is no automatic relaunch/UAC. Crash before guard arming, simultaneous guard -and collector loss, protected installation, alternate credentials and actual -sleep/wake remain open. Held-handle PID/TID reuse is modeled in deterministic +there is no automatic relaunch/UAC. The original two-capture qualification left +crash before guard arming, simultaneous guard and collector loss, protected +installation, alternate credentials and actual sleep/wake open. Held-handle PID/TID reuse is modeled in deterministic tests; real reuse is not forced by the packaged check. The optional packaged profile runs two planned captures: controlled collector diff --git a/frontend/observatory/tests/etw-failure-scenario.mjs b/frontend/observatory/tests/etw-failure-scenario.mjs new file mode 100644 index 00000000..1f3b8bdd --- /dev/null +++ b/frontend/observatory/tests/etw-failure-scenario.mjs @@ -0,0 +1,199 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import crypto from 'node:crypto'; +import { _electron as electron } from 'playwright'; +import { exitWithin, ownedPids, inspectProfile } from './sensor-support.mjs'; +import { delay, diagnostics, scenarioPaths, observeQuit, traceHelpers } from './etw-support.mjs'; +import { inspectSession, waitOwnedExit } from './etw-failure-support.mjs'; + +/** Exercise one actual fault in a marked packaged app; no provider/backend injection. + * @param {object} options executable/out/mode. @returns {Promise} @since v0.19.2 + */ +export async function runFailure({ executable, out, mode }) { + const canary = 'AEGIS_ETW_FAILURE_' + crypto.randomUUID(); + const p = scenarioPaths(out, canary); + const env = { ...process.env, USERPROFILE: p.home, HOME: p.home, TEMP: p.temp, TMP: p.temp }; + delete env.ELECTRON_RUN_AS_NODE; + const helper = path.join(path.dirname(executable), 'resources/etw-file/EtwFile.exe'); + const r = { + status: 'FAIL', + mode, + startedAt: new Date().toISOString(), + productionAdmission: false, + }; + let app, child, page; + const final = path.join(out, 'shutdown.json'); + const errors = []; + try { + r.before = await inspectSession(helper, out, 'before', env); + assert.equal(r.before.present, false); + app = await electron.launch({ + executablePath: executable, + env, + timeout: 30000, + args: [ + '--user-data-dir=' + p.profile, + '--etw-file-diagnostic-root=' + p.fixture, + ...(mode === 'app-exit' ? [] : ['--etw-file-diagnostic-fault=' + mode]), + ], + }); + child = app.process(); + Object.assign( + r, + await app.evaluate(({ app, BrowserWindow }) => { + const require = process.mainModule + .require('node:module') + .createRequire(app.getAppPath() + '/package.json'); + const w = BrowserWindow.getAllWindows()[0]; + w.setIgnoreMouseEvents(true); + w.setFocusable(false); + w.blur(); + return { + packaged: app.isPackaged && app.getAppPath().endsWith('app.asar'), + diagnosticBuild: require('./package.json').aegisEtwDiagnostic === true, + windowInputIsolated: !w.isFocusable() && !w.isFocused(), + }; + }), + ); + assert(r.packaged && r.diagnosticBuild && r.windowInputIsolated); + page = await app.firstWindow(); + page.on('pageerror', (e) => { + if (errors.length < 10) errors.push(e.message); + }); + await observeQuit(app, final); + await page.getByRole('heading', { name: 'Monitoring', level: 1, exact: true }).waitFor(); + console.log('Waiting for one same-account capture UAC decision: ' + mode); + const early = mode.startsWith('collector-before-'); + let data; + const readyUntil = Date.now() + 135000; + do { + data = await diagnostics(app); + if (early ? data.summaries.length : data.phase === 'running') break; + if (!early && data.summaries.length) throw Error('Capture failed before ready'); + await delay(100); + } while (Date.now() < readyUntil); + r.ownedPids = await ownedPids(app, child.pid, env); + r.helperPids = early ? [] : traceHelpers(r.ownedPids, env); + if (early) { + r.summary = data.summaries.at(-1); + assert.equal(r.summary?.recoveryVerified, true, 'Reservation cleanup not verified'); + assert.equal(r.summary.capture, null, 'Pre-ready fault produced a ready capture'); + assert.equal(r.summary.exitCode, 4); + assert.equal(r.summary.collectorExit, 70); + assert.equal(r.summary.finalTotals, null); + assert.equal(r.summary.observationGap, true); + assert.equal(data.restartBlocked, false); + assert.equal( + r.summary.finalCounters.queryStatus, + mode === 'collector-before-start' ? 4201 : 0, + ); + r.nativeHelperClosure = 'broker verified retained collector and guard exits'; + } else { + assert.equal(data.phase, 'running'); + assert(r.helperPids.length >= 3); + r.liveReady = true; + r.presence = await inspectSession(helper, out, 'during', env); + assert.equal(r.presence.present, true); + } + await page.locator('.sidebar').getByRole('button', { name: 'Statistics', exact: true }).click(); + await page + .getByRole('navigation', { name: 'Statistics sections', exact: true }) + .getByRole('button', { name: 'Sensors', exact: true }) + .click(); + const card = page.locator('article').filter({ hasText: 'Windows file events' }); + if (mode === 'app-exit') { + await card.getByText('Degraded', { exact: true }).waitFor({ timeout: 10000 }); + await card.scrollIntoViewIfNeeded(); + await page.screenshot({ path: path.join(out, 'before-exit.png') }); + // Exit only this owned Electron main process, bypassing its normal quit path. + await app.evaluate(() => process.exit(73)).catch(() => {}); + r.appExitCode = await exitWithin(child); + assert.equal(r.appExitCode, 73); + r.abruptAppExit = true; + } else { + const until = Date.now() + 55000; + while (!data.summaries.length && Date.now() < until) { + await delay(100); + data = await diagnostics(app); + } + r.summary = data.summaries.at(-1); + assert(r.summary, 'No ended capture summary'); + assert.equal(data.records.length, 0); + if (!early) { + assert.equal(data.restartBlocked, true, 'Unverified cleanup permitted retry'); + assert.equal(r.summary.recoveryVerified, false); + assert.equal(r.summary.exitCode, mode === 'broker-exit' ? 72 : 2); + assert.equal(r.summary.finalCounters, null); + assert.equal(r.summary.finalTotals, null); + assert.equal(r.summary.observationGap, true); + r.restartBlocked = true; + } + const health = await page.evaluate(async () => (await window.aegis.getStats()).appHealth); + assert.equal(health.sensors.byId['etw-file'].state, 'FAILED'); + assert.equal(health.populationReliable, true); + await card.getByText('Failed', { exact: true }).waitFor({ timeout: 10000 }); + r.failureVisible = true; + await card.scrollIntoViewIfNeeded(); + await page.screenshot({ path: path.join(out, 'failed.png') }); + const sessions = data.summaries.length; + await delay(1500); + const still = await diagnostics(app); + assert.equal(still.summaries.length, sessions); + assert.equal(still.restartBlocked, !!r.restartBlocked); + r.noAutomaticRestart = true; + if (r.helperPids.length) await waitOwnedExit(r.helperPids, env); + const closed = app.waitForEvent('close', { timeout: 22000 }); + await page.getByRole('button', { name: 'Quit AEGIS', exact: true }).click(); + await page + .getByRole('dialog', { name: 'Quit AEGIS?', exact: true }) + .getByRole('button', { name: 'Quit AEGIS', exact: true }) + .click(); + await closed; + assert.equal(await exitWithin(child), 0); + } + await waitOwnedExit([...new Set([...r.ownedPids, ...r.helperPids])], env); + r.closureConfirmed = true; + r.after = await inspectSession(helper, out, 'after', env); + assert.equal(r.after.present, false, 'ETW session remains after fault'); + const audit = inspectProfile(p.profile, p.fixture, -1, canary); + assert(!audit.some((row) => row.type === 'file-access' || row.type?.startsWith('etw-'))); + r.contentExcluded = true; + r.noDiagnosticAudit = true; + assert.deepEqual(errors, []); + r.status = 'PASS'; + } catch (error) { + r.failure = error.message; + r.pageErrors = errors; + process.exitCode = 1; + if (app && child?.exitCode === null) { + r.lastDiagnostics = await diagnostics(app) + .then((d) => ({ ...d, records: d.records.slice(-16) })) + .catch(() => null); + await page + ?.screenshot({ path: path.join(out, 'failure.png'), timeout: 5000 }) + .catch(() => {}); + } + } finally { + if (app && child?.exitCode === null) { + await app.close().catch(() => { + r.appCleanupUnconfirmed = true; + }); + await exitWithin(child).catch(() => { + r.appCleanupUnconfirmed = true; + }); + } + if (r.status !== 'PASS' && fs.existsSync(final) && fs.statSync(final).size <= 262144) + r.failureShutdown = JSON.parse(fs.readFileSync(final)).summaries.at(-1); + if (r.appCleanupUnconfirmed) { + r.status = 'FAIL'; + process.exitCode = 1; + } + r.completedAt = new Date().toISOString(); + const json = JSON.stringify(r, null, 2); + assert(Buffer.byteLength(json) <= 262144); + fs.writeFileSync(path.join(out, 'receipt.json'), json, { flag: 'wx' }); + console.log(JSON.stringify({ status: r.status, mode, failure: r.failure })); + } + return r; +} diff --git a/frontend/observatory/tests/etw-failure-support.mjs b/frontend/observatory/tests/etw-failure-support.mjs new file mode 100644 index 00000000..efaa88b8 --- /dev/null +++ b/frontend/observatory/tests/etw-failure-support.mjs @@ -0,0 +1,61 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { execFileSync } from 'node:child_process'; +import { boundedCommand } from '../../../tools/development/bounded-command.mjs'; +import { delay, remainingPids } from './etw-support.mjs'; + +/** Query the fixed session independently; denial stays unknown, never absent. + * An explicitly requested elevated witness only queries and writes to its pipe. + * @param {string} helper @param {string} out @param {string} label @param {object} env + * @returns {Promise} Native status/boolean receipt. @since v0.19.2 + */ +export async function inspectSession(helper, out, label, env) { + async function run(mode) { + const log = path.join(out, label + '-' + mode + '.log'); + const r = await boundedCommand(helper, [mode], { cwd: out, env, log, timeoutMs: 135000 }); + assert(r.code === 0 && !r.reason && !r.error, 'Read-only session witness failed'); + assert(fs.statSync(log).size <= 2048, 'Read-only witness output exceeded budget'); + return JSON.parse(fs.readFileSync(log, 'utf8')); + } + let value = await run('inspect'); + if (value.status === 5) { + console.log('Explicit read-only session witness requires one same-account UAC decision.'); + value = await run('inspect-elevated'); + } + assert( + (value.status === 0 && value.present === true) || + (value.status === 4201 && value.present === false), + 'Session query is unknown, not absence', + ); + return value; +} + +/** Wait only for observed owned IDs using read-only enumeration. + * @param {number[]} pids @param {object} env @returns {Promise} @since v0.19.2 + */ +export async function waitOwnedExit(pids, env) { + const until = Date.now() + 25000; + while (remainingPids(pids, env).length && Date.now() < until) await delay(100); + assert.equal(remainingPids(pids, env).length, 0, 'An observed owned app/helper remains'); +} + +/** Compile the existing normal-token synthetic read initiator in a private folder. + * @param {string} root @param {string} out @param {object} env @returns {string} @since v0.19.2 + */ +export function compileReadFixture(root, out, env) { + const file = path.join(out, 'aider.exe'); + execFileSync( + path.join(process.env.WINDIR, 'Microsoft.NET/Framework64/v4.0.30319/csc.exe'), + [ + '/nologo', + '/target:exe', + '/platform:x64', + '/warnaserror+', + '/out:' + file, + path.join(root, 'tests/fixtures/etw-read-process.cs'), + ], + { env, windowsHide: true, timeout: 30000, maxBuffer: 65536 }, + ); + return file; +} diff --git a/frontend/observatory/tests/etw-failures-electron.mjs b/frontend/observatory/tests/etw-failures-electron.mjs new file mode 100644 index 00000000..302680fb --- /dev/null +++ b/frontend/observatory/tests/etw-failures-electron.mjs @@ -0,0 +1,84 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { runFailure } from './etw-failure-scenario.mjs'; +import { runScenario } from './etw-scenario.mjs'; +import { compileReadFixture } from './etw-failure-support.mjs'; +import { etwFailuresPassed } from '../../../tools/development/etw-failure-contract.mjs'; + +const { values } = parseArgs({ + options: { executable: { type: 'string' }, output: { type: 'string' } }, +}); +assert(process.platform === 'win32' && process.arch === 'x64'); +assert(path.isAbsolute(values.executable ?? '') && path.isAbsolute(values.output ?? '')); +const out = path.resolve(values.output); +fs.mkdirSync(out); +fs.mkdirSync(path.join(out, 'temp')); +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'); +const r = { + status: 'FAIL', + schemaVersion: 1, + startedAt: new Date().toISOString(), + productionAdmission: false, + cases: {}, + scope: + 'Five remaining fault boundaries plus collector-crash and fresh-capture attribution regression', + simultaneousGuardCollectorLoss: 'not-qualified; requires protected recovery authority', + protectedInstallationSleepWakeAndPathAdmission: 'not-qualified', +}; +try { + for (const mode of [ + 'collector-before-start', + 'collector-before-arm', + 'guard-exit', + 'broker-exit', + 'app-exit', + ]) { + r.cases[mode] = await runFailure({ + executable: values.executable, + out: path.join(out, mode), + mode, + }); + assert.equal(r.cases[mode].status, 'PASS', 'Fault case incomplete; no next planned capture'); + } + const fixtureExe = compileReadFixture(root, out, { + ...process.env, + TEMP: path.join(out, 'temp'), + TMP: path.join(out, 'temp'), + }); + const crash = await runScenario({ + executable: values.executable, + fixtureExe, + out: path.join(out, 'collector-after-ready'), + fault: true, + }); + assert.equal(crash.status, 'PASS'); + const normal = await runScenario({ + executable: values.executable, + fixtureExe, + out: path.join(out, 'normal'), + fault: false, + }); + assert.equal(normal.status, 'PASS'); + r.regression = { + status: 'PASS', + productionAdmission: false, + crash, + normal, + newSessionAfterRecovery: crash.summary.sessionId !== normal.summary.sessionId, + }; + r.status = 'PASS'; + assert(etwFailuresPassed(r), 'Incomplete boundary qualification'); +} catch (e) { + r.status = 'FAIL'; + r.failure = e.message; + process.exitCode = 1; +} finally { + r.completedAt = new Date().toISOString(); + const json = JSON.stringify(r, null, 2); + assert(Buffer.byteLength(json) <= 262144); + fs.writeFileSync(path.join(out, 'receipt.json'), json, { flag: 'wx' }); + console.log(JSON.stringify({ status: r.status, failure: r.failure, output: out })); +} diff --git a/sidecar/etw-file/FileBroker.cs b/sidecar/etw-file/FileBroker.cs index 8f5d6485..d79e8246 100644 --- a/sidecar/etw-file/FileBroker.cs +++ b/sidecar/etw-file/FileBroker.cs @@ -6,7 +6,7 @@ internal static class FileBroker { internal static async Task Run(string[] args) { - bool live = args[0] is "broker" or "broker-crash-check"; + bool live = args[0] is not ("check-broker" or "check-loss-broker"); if (Security.Current().Elevated || !FileWire.Id(args[1]) || !FileWire.Id(args[2])) return 3; var scope = new FileScope(args[3]); // Validate before any UAC request. string pipeId = Guid.NewGuid().ToString("N"); @@ -16,7 +16,9 @@ internal static async Task Run(string[] args) if (!Security.RestrictedAcl(pipe)) return 3; if (recoveryPipe != null && !Security.RestrictedAcl(recoveryPipe)) return 3; var self = Security.Current(); - string collector = live ? args[0] == "broker-crash-check" ? "crash-collector" : "collector" : + string collector = live ? args[0] switch { + "broker-crash-check" => "crash-collector", "broker-prestart-check" => "prestart-collector", + "broker-prearm-check" => "prearm-collector", "broker-guard-check" => "guard-loss-collector", _ => "collector" } : args[0] == "check-loss-broker" ? "check-loss-collector" : "check-collector"; var info = Program.Child(collector, args[1], args[2], pipeId, self.Pid.ToString(), self.Birth.ToString(), scope.Root, FileWire.Profile); @@ -71,6 +73,8 @@ internal static async Task Run(string[] args) var frame = await read.ReadFrame(pipe, false, lifetime.Token); if (frame.Message.t == "stopped") Volatile.Write(ref terminalObserved, 1); await performance.Forward(output, frame, lifetime.Token); + if (frame.Message.t == "ready" && args[0] == "broker-exit-check") _ = Task.Run(async () => + { await Task.Delay(30000); Environment.Exit(72); }); if (frame.Message.t == "stopped") return; } } diff --git a/sidecar/etw-file/FileCollector.cs b/sidecar/etw-file/FileCollector.cs index 4cced902..e47b8cc0 100644 --- a/sidecar/etw-file/FileCollector.cs +++ b/sidecar/etw-file/FileCollector.cs @@ -6,7 +6,7 @@ internal static class FileCollector { internal static async Task Run(string[] args) { - bool live = args[0] is "collector" or "crash-collector"; + bool live = args[0] is "collector" or "crash-collector" or "prestart-collector" or "prearm-collector" or "guard-loss-collector"; if (Security.Current().Elevated != live || !FileWire.Id(args[1]) || !FileWire.Id(args[2]) || args[7] != FileWire.Profile) return 3; using var parent = Process.GetProcessById(int.Parse(args[4])); using var pipe = Security.Client(args[3]); @@ -22,7 +22,8 @@ internal static async Task Run(string[] args) using var lifetime = new CancellationTokenSource(); using var trace = live ? new FileTrace() : null; using var capture = live ? new FileCapture(ingress) : null; - await using var guard = live ? await FileGuardOwner.Start(args[8], parent, ulong.Parse(args[5]), pipe) : null; + await using var guard = live ? await FileGuardOwner.Start(args[8], parent, ulong.Parse(args[5]), pipe, + trace!.Reservation, args[0] == "guard-loss-collector") : null; FileStats stats = new(50, null, null, null, null, null); bool owns = false, stopped = false, drained = false; string? stopRequest = null; @@ -38,7 +39,7 @@ internal static async Task Run(string[] args) { await send.Write(pipe, "hello", new { - build = live ? "etw-file-diagnostic-6-held-guard" : "etw-file-synthetic-check-6", + build = live ? "etw-file-diagnostic-6-reserved-guard" : "etw-file-synthetic-check-6", profile = FileWire.Profile, schemas = FileWire.Schemas }, lifetime.Token); @@ -48,8 +49,11 @@ internal static async Task Run(string[] args) if (start.t != "start") throw new InvalidDataException(); if (trace != null) { + if (guard?.Alive != true) throw new IOException(); + if (args[0] == "prestart-collector") Environment.Exit(70); stats = trace.Start(); owns = true; if (stats.Status != 0 || stats.Buffers == null || stats.Size == null) throw new InvalidOperationException(); + if (args[0] == "prearm-collector") Environment.Exit(70); await guard!.Arm(trace.Token); // Ready is impossible before the independent guard is armed. capture!.Start(); trace.Enable(); stats = trace.Query(); if (stats.Status != 0) throw new InvalidOperationException(); diff --git a/sidecar/etw-file/FileGuard.cs b/sidecar/etw-file/FileGuard.cs index 63e7a622..ba17a774 100644 --- a/sidecar/etw-file/FileGuard.cs +++ b/sidecar/etw-file/FileGuard.cs @@ -14,6 +14,7 @@ internal static async Task Run(string[] args) using var brokerPipe = Security.Client(args[4]); Security.Verify(brokerPipe, broker, ulong.Parse(args[6]), false, false); FileTraceToken? owned = null; + string? reservation = null; var collectorGone = collector.WaitForExitAsync(); var brokerGone = broker.WaitForExitAsync(); FileGuardResult result = new("unverified", false, false, null, null); @@ -33,18 +34,30 @@ internal static async Task Run(string[] args) break; } var command = await input; + if (command.kind == "reserve" && reservation == null && command.handle == null && + Guid.TryParseExact(command.guid, "N", out var reserved) && reserved != Guid.Empty) + { + reservation = reserved.ToString("N"); + using var reserveLimit = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + await FileGuardWire.Write(ownerPipe, new FileGuardCommand("reserved"), reserveLimit.Token); + continue; + } if (command.kind == "arm" && owned == null && command.handle != null && command.guid != null) { + if (reservation == null || command.guid != reservation) throw new InvalidDataException(); var token = new FileTraceToken(command.handle, command.guid); var query = FileTrace.GuardControl(token, 0); if (query.Stats.Status != 0 || query.Identity.ToString("N") != token.Guid) throw new InvalidDataException(); owned = token; using var writeLimit = new CancellationTokenSource(TimeSpan.FromSeconds(5)); await FileGuardWire.Write(ownerPipe, new FileGuardCommand("armed"), writeLimit.Token); + if (args[7] == "exit-after-arm") _ = Task.Run(async () => + { await Task.Delay(30000); Environment.Exit(71); }); continue; } if (command.kind != "disarm" || command.handle != null || command.guid != null) throw new InvalidDataException(); - bool absent = owned == null || FileTrace.GuardAbsent(FileTrace.GuardControl(owned, 0).Stats.Status); + bool absent = owned != null ? FileTrace.GuardAbsent(FileTrace.GuardControl(owned, 0).Stats.Status) : + reservation != null && FileTrace.RecoverReservation(reservation).absent; result = new(absent ? "disarmed" : "unverified", absent, absent, null, null); using var limit = new CancellationTokenSource(TimeSpan.FromSeconds(5)); await FileGuardWire.Write(ownerPipe, result, limit.Token); @@ -59,6 +72,7 @@ internal static async Task Run(string[] args) if (!collector.HasExited) try { await collectorGone.WaitAsync(TimeSpan.FromSeconds(7)); } catch { } if (owned != null) result = FileTrace.Recover(owned); + else if (reservation != null) result = FileTrace.RecoverReservation(reservation); result = result with { collectorExit = collector.HasExited ? collector.ExitCode : null }; try { diff --git a/sidecar/etw-file/FileGuardOwner.cs b/sidecar/etw-file/FileGuardOwner.cs index f327d6b7..1b7d7902 100644 --- a/sidecar/etw-file/FileGuardOwner.cs +++ b/sidecar/etw-file/FileGuardOwner.cs @@ -12,14 +12,15 @@ internal sealed class FileGuardOwner : IAsyncDisposable private bool ended; internal bool Alive => !child.HasExited; private FileGuardOwner(NamedPipeServerStream channel, Process guard) { pipe = channel; child = guard; } - internal static async Task Start(string recoveryPipe, Process broker, ulong brokerBirth, Stream data) + internal static async Task Start(string recoveryPipe, Process broker, ulong brokerBirth, Stream data, + string reservation, bool diagnosticExit) { string id = Guid.NewGuid().ToString("N"); var pipe = Security.Server(id); if (!Security.RestrictedAcl(pipe)) { pipe.Dispose(); throw new UnauthorizedAccessException(); } var self = Security.Current(); var info = Program.Child("guard", id, self.Pid.ToString(), self.Birth.ToString(), - recoveryPipe, broker.Id.ToString(), brokerBirth.ToString()); + recoveryPipe, broker.Id.ToString(), brokerBirth.ToString(), diagnosticExit ? "exit-after-arm" : "normal"); info.RedirectStandardInput = info.RedirectStandardOutput = info.RedirectStandardError = false; var child = Process.Start(info) ?? throw new InvalidOperationException(); var owner = new FileGuardOwner(pipe, child); @@ -32,6 +33,10 @@ internal static async Task Start(string recoveryPipe, Process br await FileGuardWire.Write(data, new FileGuardHello(child.Id, identity.Birth.ToString()), limit.Token); var ack = await FileGuardWire.Read(data, limit.Token); if (ack.kind != "connected" || ack.handle != null || ack.guid != null) throw new InvalidDataException(); + await FileGuardWire.Write(pipe, new FileGuardCommand("reserve", null, reservation), limit.Token); + var reserved = await FileGuardWire.Read(pipe, limit.Token); + if (reserved.kind != "reserved" || reserved.handle != null || reserved.guid != null || !owner.Alive) + throw new InvalidDataException(); return owner; } catch { await owner.DisposeAsync(); throw; } diff --git a/sidecar/etw-file/FileInspect.cs b/sidecar/etw-file/FileInspect.cs new file mode 100644 index 00000000..bd2f7daa --- /dev/null +++ b/sidecar/etw-file/FileInspect.cs @@ -0,0 +1,54 @@ +using System.Diagnostics; +using System.Text.Json; + +namespace Aegis.EtwLifecycle; + +internal sealed record FileSessionState(uint status, bool? present, bool elevatedWitness); + +// Fixed-name, query-only qualification witness. No GUID/handle leaves this helper, +// no output path or stop command exists, and access denial is never absence. +internal static class FileInspect +{ + private static FileSessionState Query() + { + uint code = FileTrace.Lookup().Stats.Status; + return new(code, code == 0 ? true : code == 4201 ? false : null, Security.Current().Elevated); + } + internal static async Task Run(string[] args) + { + if (args[0] == "inspect-peer") + { + if (!Security.Current().Elevated) return 3; + using var parent = Process.GetProcessById(int.Parse(args[2])); + using var client = Security.Client(args[1]); + Security.Verify(client, parent, ulong.Parse(args[3]), false, false); + using var limit = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + await FileGuardWire.Write(client, Query(), limit.Token); + return 0; + } + FileSessionState result; + if (args[0] == "inspect") result = Query(); + else + { + if (Security.Current().Elevated) return 3; + var self = Security.Current(); + string id = Guid.NewGuid().ToString("N"); + using var pipe = Security.Server(id); + if (!Security.RestrictedAcl(pipe)) return 3; + var info = Program.Child("inspect-peer", id, self.Pid.ToString(), self.Birth.ToString()); + info.UseShellExecute = true; info.Verb = "runas"; info.WindowStyle = ProcessWindowStyle.Hidden; + info.RedirectStandardInput = info.RedirectStandardOutput = info.RedirectStandardError = false; + using var child = Process.Start(info) ?? throw new IOException(); + using var limit = new CancellationTokenSource(TimeSpan.FromSeconds(120)); + using var expiry = limit.Token.Register(() => pipe.Dispose()); + var peer = Security.Observe(child); + await pipe.WaitForConnectionAsync(limit.Token); + Security.Verify(pipe, child, peer.Birth, true, true); + result = await FileGuardWire.Read(pipe, limit.Token); + await child.WaitForExitAsync().WaitAsync(TimeSpan.FromSeconds(5)); + if (child.ExitCode != 0) return 2; + } + Console.WriteLine(JsonSerializer.Serialize(result)); + return 0; + } +} diff --git a/sidecar/etw-file/FileReservationTests.cs b/sidecar/etw-file/FileReservationTests.cs new file mode 100644 index 00000000..9b1bdaec --- /dev/null +++ b/sidecar/etw-file/FileReservationTests.cs @@ -0,0 +1,43 @@ +namespace Aegis.EtwLifecycle; + +internal static class FileReservationTests +{ + internal static void Run(Action test) + { + var expected = Guid.NewGuid(); + FileStats Stats(uint code) => new(code, code == 0 ? 0u : null, code == 0 ? 0u : null, + code == 0 ? 0u : null, null, null); + void Check(bool value) { if (!value) throw new InvalidOperationException("reservation-proof"); } + test("pre-arm recovery stops only the reserved session by independently rechecked handle", () => + { + var calls = new List(); + var result = FileTrace.RecoverReservation(expected.ToString("N"), () => new(Stats(0), expected, 123), code => + { calls.Add(code); return (Stats(calls.Count == 3 ? 4201u : 0u), expected); }); + Check(result.stopped && result.absent && calls.SequenceEqual(new uint[] { 0, 1, 0 })); + }); + test("pre-start reservation absence is distinct from a successful measured stop", () => + { + var result = FileTrace.RecoverReservation(expected.ToString("N"), () => new(Stats(4201), Guid.Empty, 0), + _ => throw new InvalidOperationException("must-not-stop")); + Check(result.absent && result.stopped && result.counters?.Status == 4201 && result.counters.Events == null); + }); + test("foreign occupied name and failed reservation query never grant stop authority", () => + { + foreach (var value in new[] { new FileTraceLookup(Stats(0), Guid.NewGuid(), 123), + new FileTraceLookup(Stats(5), expected, 123), new FileTraceLookup(Stats(87), expected, 0), + new FileTraceLookup(Stats(0), expected, 0) }) + { + var result = FileTrace.RecoverReservation(expected.ToString("N"), () => value, + _ => throw new InvalidOperationException("must-not-control")); + Check(!result.stopped && !result.absent); + } + }); + test("a changed handle target is rechecked and never stopped", () => + { + var calls = new List(); + var result = FileTrace.RecoverReservation(expected.ToString("N"), () => new(Stats(0), expected, 123), code => + { calls.Add(code); return (Stats(0), Guid.NewGuid()); }); + Check(!result.stopped && !result.absent && calls.SequenceEqual(new uint[] { 0 })); + }); + } +} diff --git a/sidecar/etw-file/FileTests.cs b/sidecar/etw-file/FileTests.cs index ca69a1bb..e5c338bd 100644 --- a/sidecar/etw-file/FileTests.cs +++ b/sidecar/etw-file/FileTests.cs @@ -140,6 +140,7 @@ void Name(FileMapping map, long qpc = 1, ulong obj = 1, ulong key = 0, string pa FileBurstTests.Run(Test); FileIssuerTests.Run(Test); FileGuardTests.Run(Test); + FileReservationTests.Run(Test); FileOutputTests.Run(Test); FilePerformanceTests.Run(Test); FileOutputProfileTests.Run(Test); diff --git a/sidecar/etw-file/FileTrace.cs b/sidecar/etw-file/FileTrace.cs index ef638989..906fd781 100644 --- a/sidecar/etw-file/FileTrace.cs +++ b/sidecar/etw-file/FileTrace.cs @@ -5,6 +5,7 @@ namespace Aegis.EtwLifecycle; internal sealed record FileStats(uint Status, uint? Events, uint? RealTime, uint? Log, uint? Buffers, uint? Size); internal sealed record FileTraceToken(string Handle, string Guid); +internal sealed record FileTraceLookup(FileStats Stats, Guid Identity, ulong Handle); // Fixed diagnostic session. Only StartTrace success grants handle-based stop authority. internal sealed class FileTrace : IDisposable @@ -13,6 +14,7 @@ internal sealed class FileTrace : IDisposable private ulong handle; private bool owned; private readonly Guid identity = Guid.NewGuid(); + internal string Reservation => identity.ToString("N"); internal FileTraceToken Token => owned ? new(handle.ToString(), identity.ToString("N")) : throw new InvalidOperationException(); [StructLayout(LayoutKind.Sequential)] private struct Wnode @@ -138,6 +140,35 @@ internal static (FileStats Stats, Guid Identity) GuardControl(FileTraceToken tok } internal static bool GuardAbsent(uint status) => status is 4201 or 6 or 87; + // Query only: a name never grants stop authority. The guard already holds the + // random reservation from its authenticated owner before StartTrace can run. + internal static FileTraceLookup Lookup() + { + var memory = Allocate(Guid.Empty); + try + { + uint status = ControlTrace(0, Name, memory, 0); + if (status != 0) return new(new(status, null, null, null, null, null), Guid.Empty, 0); + var value = Marshal.PtrToStructure(memory); + return new(new(0, value.EventsLost, value.RealTimeBuffersLost, value.LogBuffersLost, + value.NumberOfBuffers, value.BufferSize), value.Wnode.Guid, value.Wnode.HistoricalContext); + } + finally { Marshal.FreeHGlobal(memory); } + } + internal static FileGuardResult RecoverReservation(string reservation, + Func? lookup = null, Func? control = null) + { + if (!Guid.TryParseExact(reservation, "N", out var expected) || expected == Guid.Empty) throw new InvalidDataException(); + var found = (lookup ?? Lookup)(); + if (found.Stats.Status == 4201) + return new("recovered", true, true, found.Stats, null, Stopwatch.GetTimestamp().ToString()); + if (found.Stats.Status != 0 || found.Identity != expected || found.Handle == 0) + return new("unverified", false, false, null, null); + // Recover performs another exact handle/GUID query before stopping by + // handle. The fixed-name query itself never adopts or stops a session. + return Recover(new(found.Handle.ToString(), reservation), control); + } + // Only an armed guard may use this token, received over the retained owner's // authenticated pipe after StartTrace success. A foreign GUID is never stopped. internal static FileGuardResult Recover(FileTraceToken token, diff --git a/sidecar/etw-file/Program.cs b/sidecar/etw-file/Program.cs index 4dbe4372..8f934758 100644 --- a/sidecar/etw-file/Program.cs +++ b/sidecar/etw-file/Program.cs @@ -23,9 +23,13 @@ private static async Task Main(string[] args) try { if (args is ["self-test"]) return FileTests.Run(); - if (args.Length == 4 && args[0] is "broker" or "broker-crash-check" or "check-broker" or "check-loss-broker") return await FileBroker.Run(args); - if (args.Length == 7 && args[0] == "guard") return await FileGuard.Run(args); - if (args.Length == 9 && args[0] is "collector" or "crash-collector") return await FileCollector.Run(args); + if (args.Length == 1 && args[0] is "inspect" or "inspect-elevated") return await FileInspect.Run(args); + if (args.Length == 4 && args[0] == "inspect-peer") return await FileInspect.Run(args); + if (args.Length == 4 && args[0] is "broker" or "broker-crash-check" or "broker-prestart-check" or + "broker-prearm-check" or "broker-guard-check" or "broker-exit-check" or "check-broker" or "check-loss-broker") return await FileBroker.Run(args); + if (args.Length == 8 && args[0] == "guard" && args[7] is "normal" or "exit-after-arm") return await FileGuard.Run(args); + if (args.Length == 9 && args[0] is "collector" or "crash-collector" or "prestart-collector" or + "prearm-collector" or "guard-loss-collector") return await FileCollector.Run(args); if (args.Length == 8 && args[0] is "check-collector" or "check-loss-collector") return await FileCollector.Run(args); return 3; } diff --git a/sidecar/etw-file/README.md b/sidecar/etw-file/README.md index c0d310ff..aaec7ad3 100644 --- a/sidecar/etw-file/README.md +++ b/sidecar/etw-file/README.md @@ -183,6 +183,12 @@ exit. The read-only main-module getter used by qualification adds no renderer IP ## Current evidence and limits +The [failure-boundary follow-up](../../docs/roadmap/etw-failure-boundaries.md) +adds pre-start GUID reservation and the `--etw-failures` packaged profile for +pre-ready collector, guard, broker and abrupt Electron exits. It preserves blocked +retry after unverified cleanup and does not qualify simultaneous collector/guard +loss or protected recovery authority. + See [backend implementation record](../../docs/roadmap/etw-file-backend.md). The [packaged issuer/recovery record](../../docs/recon/evidence/etw-packaged-issuer-recovery.json) binds the two-capture Windows PASS to `c4d4cf472c3f594d179d531830c5a046c16827c5`. @@ -198,7 +204,8 @@ absence witnessing and protected installation remain incomplete. The authenticat guard now carries the original session handle/GUID for bounded collector-crash cleanup, with independent handle queries and a separate broker receipt. Recovery retains FAILED health, unknown application-stage losses and an observation gap. -Pre-arm crash and simultaneous collector/guard loss remain unqualified. +Pre-arm recovery now has the bounded local qualification above; simultaneous +collector/guard loss and protected recovery authority remain unqualified. Warm mmap, Fast I/O and the remaining B1/E4–E8 coverage questions remain open. The 2026-09-11 [burst-handling follow-up](../../docs/roadmap/etw-burst-handling.md) diff --git a/src/main/platform/etw-file-diagnostics.js b/src/main/platform/etw-file-diagnostics.js index 278e9ad8..ea17db7d 100644 --- a/src/main/platform/etw-file-diagnostics.js +++ b/src/main/platform/etw-file-diagnostics.js @@ -99,6 +99,7 @@ function createDiagnostics(clock = process.hrtime.bigint) { function createSummary(state, { capture, diagnostics, stopReason, code, endedAt }) { const recoveryVerified = state.phase === 'recovered' && code === 4 && state.recovery?.absent === true; + const stopVerified = state.phase === 'stopped' && code === 0; return { launchId: state.launchId, sessionId: state.sessionId, @@ -107,16 +108,22 @@ function createSummary(state, { capture, diagnostics, stopReason, code, endedAt reasons: [...state.reasons], maxima: { ...state.maxima }, capture, - finalCounters: structuredClone(state.recovery?.counters ?? state.latest?.counters ?? null), - finalTotals: state.recovery ? null : structuredClone(state.latest?.totals ?? null), + finalCounters: structuredClone( + recoveryVerified + ? state.recovery.counters + : stopVerified + ? (state.latest?.counters ?? null) + : null, + ), + finalTotals: stopVerified ? structuredClone(state.latest?.totals ?? null) : null, ringDropped: diagnostics.dropped, collectorPerformance: structuredClone(state.latest?.performance ?? null), mainPerformance: diagnostics.performance(), stopReason, exitCode: code, - stopVerified: state.phase === 'stopped' && code === 0, + stopVerified, recoveryVerified, - observationGap: state.recovery?.observationGap === true, + observationGap: !stopVerified, collectorExit: state.recovery?.collectorExit ?? null, }; } diff --git a/src/main/platform/etw-file-runtime.js b/src/main/platform/etw-file-runtime.js index 33bd0396..42d53a99 100644 --- a/src/main/platform/etw-file-runtime.js +++ b/src/main/platform/etw-file-runtime.js @@ -26,6 +26,14 @@ function createRuntime({ const roots = argv.filter((value) => value.startsWith(prefix)); const root = roots[0]?.slice(prefix.length); const faults = argv.filter((value) => value.startsWith('--etw-file-diagnostic-fault=')); + const faultModes = { + 'collector-exit': 'broker-crash-check', + 'collector-before-start': 'broker-prestart-check', + 'collector-before-arm': 'broker-prearm-check', + 'guard-exit': 'broker-guard-check', + 'broker-exit': 'broker-exit-check', + }; + const fault = faults[0]?.slice('--etw-file-diagnostic-fault='.length); const diagnosticPackage = packageMetadata.aegisEtwDiagnostic === true; const executable = app.isPackaged && diagnosticPackage @@ -40,7 +48,7 @@ function createRuntime({ spawnBroker: (launchId, sessionId) => spawnProcess( executable, - [faults.length ? 'broker-crash-check' : 'broker', launchId, sessionId, root], + [faults.length ? faultModes[fault] : 'broker', launchId, sessionId, root], { windowsHide: true, shell: false, @@ -70,7 +78,7 @@ function createRuntime({ (!app.isPackaged || !diagnosticPackage || faults.length !== 1 || - faults[0] !== '--etw-file-diagnostic-fault=collector-exit') + !Object.hasOwn(faultModes, fault)) ) sensor.setUnavailable('FAILED', 'invalid-diagnostic-fault'); else if (!exists(executable)) sensor.setUnavailable('FAILED', 'diagnostic-broker-missing'); diff --git a/tests/main/etw-package.test.js b/tests/main/etw-package.test.js index 699ec353..02742c3b 100644 --- a/tests/main/etw-package.test.js +++ b/tests/main/etw-package.test.js @@ -1,5 +1,6 @@ import { describe, expect, it } from 'vitest'; import { etwPassed, etwRecoveryPassed } from '../../tools/development/etw-package.mjs'; +import { etwFailuresPassed } from '../../tools/development/etw-failure-contract.mjs'; function receipt() { return { @@ -152,6 +153,92 @@ function recoveryReceipt() { }; } +function failureReceipt() { + return { + status: 'PASS', + productionAdmission: false, + regression: recoveryReceipt(), + cases: Object.fromEntries( + [ + 'collector-before-start', + 'collector-before-arm', + 'guard-exit', + 'broker-exit', + 'app-exit', + ].map((mode) => [ + mode, + { + mode, + status: 'PASS', + packaged: true, + diagnosticBuild: true, + windowInputIsolated: true, + closureConfirmed: true, + contentExcluded: true, + noDiagnosticAudit: true, + before: { status: 4201, present: false }, + after: { status: 4201, present: false }, + presence: { status: 0, present: true }, + failureVisible: true, + noAutomaticRestart: true, + abruptAppExit: mode === 'app-exit', + appExitCode: 73, + restartBlocked: !mode.startsWith('collector-before-'), + summary: { + recoveryVerified: mode.startsWith('collector-before-'), + capture: null, + finalTotals: null, + observationGap: true, + collectorExit: 70, + exitCode: mode.startsWith('collector-before-') ? 4 : mode === 'broker-exit' ? 72 : 2, + finalCounters: mode.startsWith('collector-before-') + ? { queryStatus: mode === 'collector-before-start' ? 4201 : 0 } + : null, + }, + }, + ]), + ), + }; +} +describe('packaged ETW failure boundaries', () => { + it('requires all five boundaries plus actual attribution and fresh-session regression', () => { + expect(etwFailuresPassed(failureReceipt())).toBe(true); + }); + it.each([ + (r) => { + delete r.cases['guard-exit']; + }, + (r) => { + r.cases['collector-before-arm'].summary.recoveryVerified = false; + }, + (r) => { + r.cases['collector-before-start'].summary.finalCounters.queryStatus = 0; + }, + (r) => { + r.cases['guard-exit'].restartBlocked = false; + }, + (r) => { + r.cases['broker-exit'].summary.finalCounters = { queryStatus: 0 }; + }, + (r) => { + r.cases['guard-exit'].after = { status: 5, present: false }; + }, + (r) => { + r.cases['app-exit'].appExitCode = 0; + }, + (r) => { + r.cases['app-exit'].presence = { status: 4201, present: false }; + }, + (r) => { + r.regression.normal.asyncProof.native.pending = 0; + }, + ])('rejects missing, unknown or inconsistent boundary evidence (%#)', (mutate) => { + const r = failureReceipt(); + mutate(r); + expect(etwFailuresPassed(r)).toBe(false); + }); +}); + describe('packaged ETW recovery qualification', () => { it('requires separate failed-but-cleaned and normally stopped captures with independent read witnesses', () => { expect(etwRecoveryPassed(recoveryReceipt())).toBe(true); diff --git a/tests/main/platform/etw-file-supervisor.test.js b/tests/main/platform/etw-file-supervisor.test.js index d03d936c..2d885f46 100644 --- a/tests/main/platform/etw-file-supervisor.test.js +++ b/tests/main/platform/etw-file-supervisor.test.js @@ -80,6 +80,43 @@ function harness(options = {}) { } describe('ETW diagnostic supervisor', () => { + it('accepts verified reservation cleanup before ready without inventing a capture', () => { + const h = harness(); + h.sensor.start(); + const child = h.children[0]; + child.message('hello', 1); + child.flush(); + child.message('recovered', 2); + child.emit('close', 4); + const d = h.sensor.getDiagnostics(); + expect(d.restartBlocked).toBe(false); + expect(d.summaries[0]).toMatchObject({ + capture: null, + recoveryVerified: true, + observationGap: true, + finalTotals: null, + }); + expect(h.sensor.getHealth().state).toBe('FAILED'); + }); + it.each([2, 72])( + 'keeps guard/broker failure blocked and never calls sampled totals final (exit %s)', + (code) => { + const h = harness(); + const child = h.running(); + child.message('heartbeat', 3, telemetry()); + child.emit('close', code); + const d = h.sensor.getDiagnostics(); + expect(d.restartBlocked).toBe(true); + expect(d.summaries[0]).toMatchObject({ + finalCounters: null, + finalTotals: null, + observationGap: true, + recoveryVerified: false, + }); + expect(h.sensor.restart()).toBe(false); + expect(h.spawnBroker).toHaveBeenCalledOnce(); + }, + ); it('publishes health transitions promptly without a per-observation stats storm', () => { const onHealthChange = vi.fn(); const h = harness({ onHealthChange }); @@ -435,23 +472,29 @@ describe('ETW backend runtime gate', () => { expect(spawnProcess).not.toHaveBeenCalled(); expect(sensor.getHealth().state).toBe('FAILED'); }); - it('selects the fixed crash check only in a marked explicit diagnostic package', () => { - const spawnProcess = vi.fn(() => { - throw new Error('test launch failure'); - }); - const { sensor } = make({ - app: { isPackaged: true }, - packageMetadata: { aegisEtwDiagnostic: true }, - resourcesPath: 'C:\\candidate\\resources', - argv: [ - '--etw-file-diagnostic-root=C:\\fixture', - '--etw-file-diagnostic-fault=collector-exit', - ], - spawnProcess, - }); - sensor.start(); - expect(spawnProcess.mock.calls[0][1][0]).toBe('broker-crash-check'); - }); + it.each([ + ['collector-exit', 'broker-crash-check'], + ['collector-before-start', 'broker-prestart-check'], + ['collector-before-arm', 'broker-prearm-check'], + ['guard-exit', 'broker-guard-check'], + ['broker-exit', 'broker-exit-check'], + ])( + 'selects only fixed crash mode %s in a marked explicit diagnostic package', + (fault, command) => { + const spawnProcess = vi.fn(() => { + throw new Error('test launch failure'); + }); + const { sensor } = make({ + app: { isPackaged: true }, + packageMetadata: { aegisEtwDiagnostic: true }, + resourcesPath: 'C:\\candidate\\resources', + argv: ['--etw-file-diagnostic-root=C:\\fixture', '--etw-file-diagnostic-fault=' + fault], + spawnProcess, + }); + sensor.start(); + expect(spawnProcess.mock.calls[0][1][0]).toBe(command); + }, + ); it('does not auto-launch on resume or unpause; removes power listeners', () => { const { sensor, powerMonitor, spawnProcess } = make({ argv: ['--etw-file-diagnostic-root=C:\\fixture'], diff --git a/tools/development/etw-failure-contract.mjs b/tools/development/etw-failure-contract.mjs new file mode 100644 index 00000000..45554e91 --- /dev/null +++ b/tools/development/etw-failure-contract.mjs @@ -0,0 +1,71 @@ +import { etwRecoveryPassed } from './etw-package.mjs'; + +/** Require actual packaged boundary failures with independent session queries. + * @param {object} r Private seven-capture receipt. @returns {boolean} @since v0.19.2 + */ +export function etwFailuresPassed(r) { + const modes = [ + 'collector-before-start', + 'collector-before-arm', + 'guard-exit', + 'broker-exit', + 'app-exit', + ]; + const cases = r?.cases; + return Boolean( + r?.status === 'PASS' && + r.productionAdmission === false && + cases && + etwRecoveryPassed(r.regression) && + modes.every((mode) => { + const c = cases[mode]; + if ( + !c || + c.status !== 'PASS' || + c.mode !== mode || + c.packaged !== true || + c.diagnosticBuild !== true || + c.windowInputIsolated !== true || + c.closureConfirmed !== true || + c.contentExcluded !== true || + c.noDiagnosticAudit !== true || + c.before?.status !== 4201 || + c.before.present !== false || + c.after?.status !== 4201 || + c.after.present !== false + ) + return false; + if (mode === 'app-exit') + return ( + c.abruptAppExit === true && + c.appExitCode === 73 && + c.presence?.status === 0 && + c.presence.present === true + ); + if ( + c.failureVisible !== true || + c.noAutomaticRestart !== true || + c.summary?.finalTotals !== null || + c.summary.observationGap !== true + ) + return false; + if (mode.startsWith('collector-before-')) + return ( + c.summary.recoveryVerified === true && + c.summary.exitCode === 4 && + c.summary.collectorExit === 70 && + c.summary.capture === null && + c.summary.finalCounters?.queryStatus === (mode === 'collector-before-start' ? 4201 : 0) && + c.restartBlocked !== true + ); + return ( + c.restartBlocked === true && + c.summary.recoveryVerified === false && + c.summary.finalCounters === null && + c.summary.exitCode === (mode === 'broker-exit' ? 72 : 2) && + c.presence?.status === 0 && + c.presence.present === true + ); + }), + ); +} diff --git a/tools/development/etw-qualification.mjs b/tools/development/etw-qualification.mjs new file mode 100644 index 00000000..a205825a --- /dev/null +++ b/tools/development/etw-qualification.mjs @@ -0,0 +1,37 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import crypto from 'node:crypto'; +import { etwRecoveryPassed } from './etw-package.mjs'; +import { etwFailuresPassed } from './etw-failure-contract.mjs'; + +/** Run one selected ETW profile against the actual package and bind its receipt. + * @param {string} root @param {string} output @param {string} candidate + * @param {Function} command Bounded owner runner. @param {boolean} failures + * @returns {Promise} Receipt and SHA256. @since v0.19.2 + */ +export async function qualifyEtw(root, output, candidate, command, failures) { + await command( + 'etw', + process.execPath, + [ + path.join( + root, + failures + ? 'frontend/observatory/tests/etw-failures-electron.mjs' + : 'frontend/observatory/tests/etw-electron.mjs', + ), + '--executable', + path.join(candidate, 'AEGIS - AI Monitoring & Threat Detection.exe'), + '--output', + path.join(output, 'etw'), + ], + failures ? 900000 : 420000, + ); + const file = path.join(output, 'etw/receipt.json'); + if (fs.statSync(file).size > 262144) throw new Error('ETW receipt too large'); + const bytes = fs.readFileSync(file), + etw = JSON.parse(bytes); + if (!(failures ? etwFailuresPassed(etw) : etwRecoveryPassed(etw))) + throw new Error('Packaged ETW profile incomplete'); + return { etw, etwReceiptSha256: crypto.createHash('sha256').update(bytes).digest('hex') }; +} diff --git a/tools/development/packaged-desktop.mjs b/tools/development/packaged-desktop.mjs index 4d9367f0..efcac3ef 100644 --- a/tools/development/packaged-desktop.mjs +++ b/tools/development/packaged-desktop.mjs @@ -9,7 +9,8 @@ import { boundedCommand } from './bounded-command.mjs'; import { desktopPassed, monitoringPassed, sensorsPassed } from './desktop-contract.mjs'; import { processCoreSources } from '../../tests/fixtures/protected-gui-process/harness.mjs'; import { produceGuiManifest } from '../../scripts/produce-protected-gui-manifest.mjs'; -import { prepareEtwPackage, etwRecoveryPassed } from './etw-package.mjs'; +import { prepareEtwPackage } from './etw-package.mjs'; +import { qualifyEtw } from './etw-qualification.mjs'; const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'); const { values } = parseArgs({ @@ -19,11 +20,14 @@ const { values } = parseArgs({ monitoring: { type: 'boolean', default: false }, sensors: { type: 'boolean', default: false }, etw: { type: 'boolean', default: false }, + 'etw-failures': { type: 'boolean', default: false }, }, }); +const etwFailures = values['etw-failures']; +if (values.etw && etwFailures) throw new Error('Select one ETW profile'); if (!path.isAbsolute(values.output ?? '') || !/^[a-f0-9]{40}$/.test(values['source-sha'] ?? '')) throw new Error( - 'Usage: node tools/development/packaged-desktop.mjs --source-sha <40-hex> --output [--monitoring] [--sensors] [--etw]', + 'Usage: node tools/development/packaged-desktop.mjs --source-sha <40-hex> --output [--monitoring] [--sensors] [--etw | --etw-failures]', ); const output = path.resolve(values.output); if ( @@ -79,9 +83,17 @@ const receipt = { ? 'monitoring-with-ordinary-current-user-and-playwright' : 'not-run', fileNetworkSensors: values.sensors ? 'native-owned-fixture-and-public-tcp' : 'not-run', - etw: values.etw ? 'live-diagnostic-candidates-only' : 'not-run', + etw: etwFailures + ? 'seven-planned-failure-and-regression-captures' + : values.etw + ? 'live-diagnostic-candidates-only' + : 'not-run', modeledPrincipalProtectionAccountServiceVmAndJournal: true, - uac: values.etw ? 'two-planned-interactive-same-account-captures' : 'not-run', + uac: etwFailures + ? 'seven-planned-same-account-captures-and-query-only-witness-if-denied' + : values.etw + ? 'two-planned-interactive-same-account-captures' + : 'not-run', guiEnrollment: false, realGuestProvider: 'not-run', elapsedThirtyMinuteExpiry: 'not-run', @@ -143,7 +155,8 @@ try { [path.join(root, 'node_modules/electron/install.js')], 240000, ); - const etwConfig = values.etw ? await prepareEtwPackage(root, output, command) : null; + const etwConfig = + values.etw || etwFailures ? await prepareEtwPackage(root, output, command) : null; await command( 'package', process.execPath, @@ -256,25 +269,8 @@ try { if (!sensorsPassed(receipt.sensors)) throw new Error('Packaged sensor scenario incomplete'); receipt.sensorReceiptSha256 = hash(sensorReceipt); } - if (values.etw) { - await command( - 'etw', - process.execPath, - [ - path.join(root, 'frontend/observatory/tests/etw-electron.mjs'), - '--executable', - path.join(candidate, 'AEGIS - AI Monitoring & Threat Detection.exe'), - '--output', - path.join(output, 'etw'), - ], - 420000, - ); - const file = path.join(output, 'etw/receipt.json'); - if (fs.statSync(file).size > 262144) throw new Error('ETW receipt too large'); - receipt.etw = JSON.parse(fs.readFileSync(file)); - if (!etwRecoveryPassed(receipt.etw)) - throw new Error('Packaged ETW attribution/recovery incomplete'); - receipt.etwReceiptSha256 = hash(file); + if (values.etw || etwFailures) { + Object.assign(receipt, await qualifyEtw(root, output, candidate, command, etwFailures)); } if ( hash(manifest) !== receipt.packageManifestSha256 ||