# Windows Endpoint Triage & Escalation Packager (`win-endpoint-triage`) [![tests](https://github.com/ToritsejuBoyo/win-endpoint-triage/actions/workflows/tests.yml/badge.svg)](https://github.com/ToritsejuBoyo/win-endpoint-triage/actions/workflows/tests.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)]() [![Dependencies](https://img.shields.io/badge/dependencies-zero%20(stdlib%20only)-brightgreen.svg)](CONTRIBUTING.md) [![Security](https://img.shields.io/badge/security-read--only%20%7C%20no%20egress-informational.svg)](SECURITY.md) [![Standard](https://img.shields.io/badge/standard-agentskills.io-blueviolet.svg)](https://agentskills.io) > **Eliminate 45-minute Event Viewer hunts and incomplete L1-to-L2 ticket escalations with deterministic PowerShell telemetry and structured AI root-cause synthesis.**\n\n![win-endpoint-triage demo](assets/demo.gif) --- ## What Problem Does This Solve? In most IT departments and MSPs, when an end-user reports: > *"My laptop is running painfully slow and Outlook keeps freezing."* 1. **L1 Technicians spend 30 to 45 minutes** clicking through Task Manager, guessing, rebooting, and sifting through 50,000 Event Viewer logs. 2. When they can't fix it, they escalate a vague ticket to L2: *`"User laptop slow. Rebooted. Issue persists. Please advise."`* 3. **L2 Engineers angrily reject or bounce the ticket back** because there are no logs, no verified error codes, and no proof of what was tested. 4. **Result:** Days of ticket ping-pong and frustrated users. `win-endpoint-triage` solves this in under 3 minutes: - **15-second local collection:** Runs a zero-dependency, 100% read-only PowerShell collector. - **Instant AI Root-Cause Synthesis:** Correlates 6 critical operational domains to identify the real hidden issue. - **"Can L1 Fix It Now?" Verdict:** Tells frontline technicians immediately whether to apply a verified 5-minute fix or escalate. - **Copy-Paste Escalation Brief:** Auto-generates an airtight ticket note formatted for ServiceNow, Jira, HaloPSA, or ConnectWise. --- ## Installation & Setup Guide ### 1. Prerequisites * **Operating System:** Windows 10, Windows 11, Windows Server 2016+ * **PowerShell Runtime:** Windows PowerShell 5.1 or PowerShell 7+ (pre-installed on all Windows systems) * **Python Runtime:** Python 3.10+ (only needed if running the local unit test suite) * **Zero Dependencies:** Uses only native Windows APIs (WMI/CIM, Event Viewer). No software to install, compile, or approve. ### 2. Getting the Repository #### Option A: Clone with Git ```bash git clone https://github.com/ToritsejuBoyo/win-endpoint-triage.git cd win-endpoint-triage ``` #### Option B: Zero-Install Execution (Pinned and Checksum-Verified) You do not need to clone the repository to use it on an affected endpoint. Download the collector pinned to an immutable commit, verify its SHA256, then run it. Do not pipe a remote script straight into `iex`: `main` is a moving target, and an upstream change or a branch compromise would execute unreviewed code on a production endpoint. ```powershell $Pin = '81e9fef363ba8eac2acd50d881e917a9934e1bda' $Hash = '000bf0fd814c693b57611e616dd465b4c20c1032e7adda0156efdb0f682b3deb' $Dest = Join-Path $env:TEMP 'collect-win-triage.ps1' Invoke-WebRequest -UseBasicParsing ` -Uri "https://raw.githubusercontent.com/ToritsejuBoyo/win-endpoint-triage/$Pin/scripts/collect-win-triage.ps1" ` -OutFile $Dest $Actual = (Get-FileHash -Path $Dest -Algorithm SHA256).Hash if ($Actual -ne $Hash.ToUpper()) { Remove-Item $Dest -Force throw "Checksum mismatch. Expected $Hash but got $Actual. Aborting - do not run." } & $Dest -HoursBack 48 -Sanitize ``` ### 3. Verify Your Installation Run the automated verification suite to validate all 4 synthetic failure fixtures: ```bash python tests/validate-skill.py ``` ### 4. Installing as an AI Agent Skill (`agentskills.io`) * **Google Antigravity:** Place or symlink into `~/.gemini/skills/win-endpoint-triage/` * **Cursor / Windsurf / VS Code:** Place into `.cursor/skills/win-endpoint-triage/` or your workspace root * **Claude / ChatGPT / Ollama (Offline Web UI):** Paste `SKILL.md` as system instructions and upload the generated `win-triage.json`. --- ## How to Run in 30 Seconds ### Step 1: Run the 15-Second Collector on the Windows Endpoint #### Option A: Verified Remote Download (AnyDesk, TeamViewer, Splashtop, RMM Terminal) Paste this into Windows PowerShell (or your RMM background CLI). It pins the collector to an immutable commit and refuses to run it if the checksum does not match: ```powershell $Pin = '81e9fef363ba8eac2acd50d881e917a9934e1bda' $Hash = '000bf0fd814c693b57611e616dd465b4c20c1032e7adda0156efdb0f682b3deb' $Dest = Join-Path $env:TEMP 'collect-win-triage.ps1' Invoke-WebRequest -UseBasicParsing ` -Uri "https://raw.githubusercontent.com/ToritsejuBoyo/win-endpoint-triage/$Pin/scripts/collect-win-triage.ps1" ` -OutFile $Dest $Actual = (Get-FileHash -Path $Dest -Algorithm SHA256).Hash if ($Actual -ne $Hash.ToUpper()) { Remove-Item $Dest -Force throw "Checksum mismatch. Expected $Hash but got $Actual. Aborting - do not run." } & $Dest -HoursBack 48 -Sanitize ``` #### Option B: Local Execution (from Clone or USB) ```powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\collect-win-triage.ps1 -HoursBack 48 -Sanitize ``` *Output generated: `win-triage-.json` (compact, sanitized, ~18 KB).* --- ### Step 2: Analyze with Your AI Assistant Take the generated `win-triage.json` file into your AI of choice: * **In Claude Code / Antigravity / Cursor:** Run `@win-endpoint-triage analyze .\win-triage.json` (or point the agent to the folder). * **In ChatGPT, Claude Web, or Google Gemini:** Drag and drop `win-triage.json` into chat and ask: > *"Analyze this Windows endpoint triage bundle. Give me the suspected root cause, safe L1 commands, and an L2 ticket escalation note."* * **100% Offline via Local Ollama (Air-Gapped / Bank / Defense):** ```bash ollama run qwen2.5-coder:14b "Analyze this triage bundle using the win-endpoint-triage rules: $(Get-Content .\win-triage.json -Raw)" ``` --- ## Enterprise Trust, Security & Compliance Why IT Security (SecOps), Compliance, and Change Advisory Boards trust this tool: | Security Fear | How `win-endpoint-triage` Solves It | | --- | --- | | **"Will it break production?"** | **100% Read-Only.** The collector contains zero `Set-`, `Remove-`, or `Stop-` commands. It performs zero writes, zero reboots, and zero service restarts. | | **"Does it require Local Admin?"** | **Privilege-Adaptive.** Standard users can run it without elevation. It collects all accessible user/process/event logs without throwing red errors, gracefully unlocking deep security telemetry when elevated. | | **"Will it leak employee PII?"** | **Automated Masking (`-Sanitize`).** Strips computer names, usernames, internal domain names, and masks private IPv4 octets. | | **"Are there hidden malware risks?"** | **Plaintext & Zero-Dependency.** Native PowerShell 5.1/7+ cmdlets only. No compiled `.exe`, no third-party DLLs, no npm/pip packages. Can be audited in 60 seconds. | | **"Can it run in air-gapped networks?"** | **Offline Compatible.** Works with local offline LLMs (Ollama / Llama.cpp). Zero bytes leave your corporate perimeter. | --- ## The 6 Diagnostic Domains ```text 1. System Baseline & Hygiene -> Uptime, Fast Startup zombie sessions, Pending Reboot flags. 2. Reliability Stability Index -> Built-in 1-10 Windows Reliability Score & 14-day crash history. 3. Storage & BitLocker Health -> Free space %, SSD bad blocks (Event 7), Controller timeouts (Event 153). 4. Crash & Exception Stacks -> BugCheck stop codes (BSOD 0x116, 0x9F), App Error 0xc0000005 access violations. 5. Modern Workplace & Entra ID -> dsregcmd check for missing Primary Refresh Token (AzureAdPrt: NO) & DNS mismatch. 6. Hardware & Thermal Health -> Event ID 37 CPU frequency capping (clogged fans/bad charger) & battery wear. ``` --- ## Sample Escalation Output ```text ================================================================================ L1 TO L2/L3 ESCALATION BRIEF (TRIAGE VERIFIED) ================================================================================ HOST / DEVICE : ENDPOINT-REDACTED (Dell Inc. Latitude 5440) OPERATING SYSTEM : Microsoft Windows 11 Enterprise (Build 22631, 64-bit) UPTIME & HYGIENE : 7.26 days | FastStartup: True | PendingReboot: False RELIABILITY SCORE: 2.1 / 10 (CRITICAL INSTABILITY) REPORTED SYMPTOM : User reports laptop freezing every few minutes and Outlook hanging. ROOT CAUSE VERDICT: Physical Media Degradation (Event ID 7 Bad Block) & Storage Starvation (98.2% Disk Full) Confidence: 95% VERIFIED TELEMETRY: - Storage Status : Drive C: 8.5 GB Free (1.8% free) | BitLocker: Protected - Memory & Procs : 73.8% Used | Top: chrome (1850 MB) - Identity / SSO : AzureAdJoined: YES | AzureAdPrt: YES - Critical Events: * [2026-11-04T14:15:00Z] ID 7 (disk): The device \Device\Harddisk0\DR0 has a bad block (14 occurrences). * [2026-11-04T14:10:00Z] ID 153 (stornvme): The IO operation at LBA 0x12a80 was retried (22 occurrences). L1 ACTIONS TESTED & RULED OUT: 1. Verified free space (< 10GB threshold exceeded). 2. Checked disk SMART logs; confirmed recurring hardware bad block events. 3. Ruled out network and Entra PRT token issues. REQUESTED L2/L3 ACTION: Initiate immediate user data backup and dispatch replacement NVMe SSD under hardware warranty. Do NOT attempt Windows in-place repair (unrecoverable bad blocks on NAND flash). ================================================================================ ``` --- ## Directory Structure ```text win-endpoint-triage/ ├── README.md # This guide ├── SKILL.md # Core Agent Skills diagnostic specification ├── scripts/ │ └── collect-win-triage.ps1 # Read-only privilege-adaptive PowerShell collector v2.0 ├── references/ │ └── windows-event-ids-and-thresholds.md # Comprehensive diagnostic lookup matrix ├── assets/ │ └── l2-escalation-brief-template.md # Multi-ITSM escalation templates (Markdown & Plaintext) └── tests/ ├── validate-skill.py # Automated quality and schema validator └── fixtures/ # 4 synthetic failure test cases ├── fixture-disk-failing-badblock.json ├── fixture-entra-prt-sso-failure.json ├── fixture-bsod-driver-tdr.json └── fixture-thermal-throttling.json ``` --- ## Installation Install via the open `skills.sh` registry: ```bash npx skills add ToritsejuBoyo/win-endpoint-triage ``` Or copy the `win-endpoint-triage` folder directly into your workspace or `.gemini/skills/` directory.