{"id":34520154,"url":"https://github.com/eagleclarinet22/usbkeypresencewatcher","last_synced_at":"2026-05-30T06:03:30.423Z","repository":{"id":328088308,"uuid":"1108798429","full_name":"EagleClarinet22/USBKeyPresenceWatcher","owner":"EagleClarinet22","description":"Automatically lock Windows when a YubiKey or security USB device is removed. PowerShell-based presence watcher with Task Scheduler integration.","archived":false,"fork":false,"pushed_at":"2026-02-17T03:30:50.000Z","size":109,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T09:46:17.392Z","etag":null,"topics":["automation","lock-screen","powershell","security","task-scheduler","usb","windows","yubikey"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EagleClarinet22.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-02T23:48:45.000Z","updated_at":"2025-12-05T14:28:26.000Z","dependencies_parsed_at":"2025-12-24T05:07:53.034Z","dependency_job_id":null,"html_url":"https://github.com/EagleClarinet22/USBKeyPresenceWatcher","commit_stats":null,"previous_names":["eagleclarinet22/usbkeypresencewatcher"],"tags_count":95,"template":false,"template_full_name":null,"purl":"pkg:github/EagleClarinet22/USBKeyPresenceWatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EagleClarinet22%2FUSBKeyPresenceWatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EagleClarinet22%2FUSBKeyPresenceWatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EagleClarinet22%2FUSBKeyPresenceWatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EagleClarinet22%2FUSBKeyPresenceWatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EagleClarinet22","download_url":"https://codeload.github.com/EagleClarinet22/USBKeyPresenceWatcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EagleClarinet22%2FUSBKeyPresenceWatcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","lock-screen","powershell","security","task-scheduler","usb","windows","yubikey"],"created_at":"2025-12-24T04:45:49.425Z","updated_at":"2026-02-20T05:03:52.375Z","avatar_url":"https://github.com/EagleClarinet22.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USB Key Presence Lock for Windows\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![PowerShell 5.1](https://img.shields.io/badge/PowerShell-5.1-blue)\n![Windows](https://img.shields.io/badge/Windows-10%20%7C%2011-0078D6)\n![Automation](https://img.shields.io/badge/Scheduled%20Task-Automated-green)\n![BurntToast](https://img.shields.io/badge/Toast%20Notifications-BurntToast-orange)\n![Version](https://img.shields.io/github/v/tag/EagleClarinet22/USBKeyPresenceWatcher?label=version)\n![CI](https://github.com/EagleClarinet22/USBKeyPresenceWatcher/actions/workflows/ci-validation.yml/badge.svg)\n\nAutomatically lock your Windows session when your selected **USB device** (security key, token, or any USB hardware you choose) is removed — and keep the system locked until that device is reinserted.\n\nThis project includes:\n\n- A PowerShell presence watcher\n- Toast notifications via BurntToast (optional)\n- A Windows Scheduled Task to start the watcher automatically\n- Event Viewer logging (with file fallback)\n- A fully interactive **installer** that detects your USB devices\n- A matching **uninstaller**\n- A clean, self-elevating installation workflow\n- **GitHub Actions pipelines** validating XML, linting PowerShell, and generating releases\n- **Issue templates + Discussions** for structured reporting and community support\n\n\u003e ⚠️ This script must run using **Windows PowerShell 5.1** (the built-in Windows PowerShell).  \n\u003e PowerShell 7+ (pwsh.exe) is **not supported** for hidden scheduled-task execution, PnP APIs, or BurntToast.\n\n---\n\n## ✨ Features\n\n### 🔐 Presence-based security\n\nLocks your workstation automatically when your selected USB device disappears — and keeps it locked until the device returns.\n\n### 🔁 Persistent lock enforcement\n\nIf the system is manually unlocked while the USB device is missing, the watcher immediately locks it again.\n\n### 🔔 Toast notifications (optional)\n\nRequires BurntToast. Indicates:\n\n- Monitoring started\n- Device removed\n- Device reinserted\n\n### 🧱 Hub-resilience\n\nPrevents false positives from USB hub glitches (default: **2 consecutive misses** required to lock).\n\n### 🗂 Automatic Event Viewer logging\n\nLog: **Application**  \nSource: **USBKeyPresenceWatcher**\n\n### 🧩 Smart installer workflow\n\nThe installer:\n\n- Detects all USB devices with VID/PID\n- Lets you choose the correct USB device or token\n- Patches the installed script with your VID/PID\n- Hardens directory ACLs\n- Creates the EventLog source\n- Generates runtime task XML:\n\n```\nTemplate-USBKeyPresenceLock.xml → Task-USBKeyPresenceLock.xml\n```\n\n### 🔒 Secure installation directory\n\nThe installer grants FullControl to:\n\n- Current user\n- SYSTEM\n- Administrators\n\nAll others are removed.\n\n---\n\n# 📁 Repository Structure\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick here to view repo structure\u003c/strong\u003e\u003c/summary\u003e\n\n```\nUSBKeyPresenceWatcher/\n│\n│   Install-USBKeyPresenceWatcher.ps1\n│   Uninstall-USBKeyPresenceWatcher.ps1\n│   USBKeyPresenceLock.ps1\n│   Launch-USBKeyPresenceWatcher.vbs\n│   Template-USBKeyPresenceLock.xml\n│   lock_toast_64.png\n│\n│   CHANGELOG.md\n│   README.md\n│   LICENSE\n│   NOTICE\n│\n│   .editorconfig\n│   .gitattributes\n│   .gitignore\n│   .prettierignore\n│\n└── .github/\n    ├── workflows/\n    │     auto-hotfix.yml\n    │     auto-nightly.yml\n    │     release.yml\n    │     validate-powershell.yml\n    │     validate-xml.yml\n    │     ci-validation.yml\n    │\n    └── ISSUE_TEMPLATE/\n          improvement-roadmap.yml\n          bug.yml\n          feature.yml\n          refactor.yml\n          performance.yml\n          documentation.yml\n          workflow-failure.yml\n          security.yml\n          ux.yml\n          config.yml\n```\n\n\u003c/details\u003e\n\n---\n\n# ⚙ How It Works Internally\n\n### 1. **Task Scheduler Startup**\n\nThe installer registers a task that runs at:\n\n- User logon\n- Session unlock\n\nThe task executes:\n\n```\nwscript.exe Launch-USBKeyPresenceWatcher.vbs\n```\n\nThe VBS wrapper silently launches:\n\n```\npowershell.exe -WindowStyle Hidden -File USBKeyPresenceLock.ps1\n```\n\nThis ensures **fully hidden execution**.\n\n---\n\n### 2. **USB Device Detection**\n\nOnce per second:\n\n```powershell\nGet-PnpDevice -PresentOnly | Where-Object InstanceId -like \"*VID_####\u0026PID_####*\"\n```\n\n- Missing device → increment counter\n- Present device → reset counter\n- After N misses → lock workstation\n\n---\n\n### 3. **Locking Logic**\n\n```powershell\nrundll32.exe user32.dll,LockWorkStation\n```\n\nOptional heartbeat logs help diagnose issues.\n\n---\n\n### 4. **Single Instance Control**\n\nA mutex prevents duplicate watchers:\n\n```\nUSBKeyPresenceWatcher_\u003cUSERNAME\u003e\n```\n\n---\n\n### 5. **Event Logging + Toast Notifications**\n\nLogs go to Event Viewer or a fallback local log file.  \nToast notifications appear if BurntToast is installed.\n\n---\n\n### 6. **Uninstallation**\n\nThe uninstaller:\n\n- Terminates watcher instances\n- Removes the scheduled task\n- Deletes the installation directory\n- Supports `-WhatIf`\n\nEnsures complete cleanup.\n\n---\n\n# 🔧 Core Scripts\n\n### `Install-USBKeyPresenceWatcher.ps1`\n\nHandles:\n\n- Selecting USB device\n- Patching watcher with VID/PID\n- Hardening ACLs\n- Generating task XML\n- Registering the task\n\n---\n\n### `Uninstall-USBKeyPresenceWatcher.ps1`\n\nHandles:\n\n- Killing watcher processes\n- Removing scheduled task\n- Cleaning directories\n- Supporting dry runs with `-WhatIf`\n\n---\n\n### `USBKeyPresenceLock.ps1`\n\nThe core watcher:\n\n- Polls for device\n- Enforces lock-on-missing\n- Logs events\n- Sends notifications\n- Prevents multiple instances\n\n---\n\n### `Launch-USBKeyPresenceWatcher.vbs`\n\nEnsures the watcher runs:\n\n- Hidden\n- Under correct session\n- Without console windows\n\n---\n\n### `Template-USBKeyPresenceLock.xml`\n\nDefines triggers, actions, permissions, and runtime environment.\n\n---\n\n# 🤖 GitHub Workflows\n\n- **validate-powershell.yml** — PSScriptAnalyzer checks\n- **validate-xml.yml** — XML structure + encoding checks\n- **release.yml** — Automated release generation\n- **auto-hotfix.yml** — Auto hotfix creation based on commit volume\n- **auto-nightly.yml** — Daily builds\n- **ci-validation.yml** — Repository-wide validation\n\n---\n\n# 🚀 Installation\n\n### 1. Download or clone\n\n```powershell\ngit clone https://github.com/EagleClarinet22/USBKeyPresenceWatcher.git\ncd USBKeyPresenceWatcher\n```\n\n### 2. Enable script execution\n\n```powershell\nSet-ExecutionPolicy -Scope CurrentUser RemoteSigned\n```\n\n### 3. Run the installer\n\n```powershell\n.\\Install-USBKeyPresenceWatcher.ps1\n```\n\n### 4. Select your USB device\n\nInstaller will list all detectable USB devices and let you choose one.\n\n---\n\n# 🔧 Configuration\n\n### Re-select USB device\n\n```powershell\n.\\Install-USBKeyPresenceWatcher.ps1 -Force\n```\n\n### Adjust hub-resilience threshold\n\n```powershell\n$missingThreshold = 2\n```\n\n---\n\n# ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExpand FAQ\u003c/strong\u003e\u003c/summary\u003e\n\n### Do I need VID/PID?\n\nNo — the installer detects everything.\n\n### Does this replace authentication?\n\nNo — this adds presence-based locking only.\n\n### Does this work with Windows Hello?\n\nYes.\n\n### Why Windows PowerShell 5.1?\n\nRequired for PnP APIs, BurntToast, and hidden scheduled-task execution.\n\n\u003c/details\u003e\n\n---\n\n# 🛠 Troubleshooting\n\n### No toast notifications?\n\nInstall BurntToast:\n\n```powershell\nInstall-Module BurntToast -Scope CurrentUser\n```\n\nEnsure:\n\n- Task runs as logged-in user\n- \"Run only when user is logged on\" is enabled\n\n---\n\n# 🧹 Uninstallation\n\n```powershell\n.\\Uninstall-USBKeyPresenceWatcher.ps1\n```\n\nSupports:\n\n- Instance cleanup\n- Task removal\n- Directory deletion\n- `-WhatIf`\n\n---\n\n# 🤝 Contributing\n\nContributions are welcome!\n\nUse structured issue templates for:\n\n- Bug reports\n- Feature requests\n- Workflow failures\n- UX improvements\n- Documentation updates\n\nFor general questions or support, start a Discussion:  \nhttps://github.com/EagleClarinet22/USBKeyPresenceWatcher/discussions\n\n---\n\n# 📜 License\n\nMIT License. Attribution appreciated but not required.\n\n---\n\nHappy locking! 🔐\n\n![GitHub Card](https://githubcard.com/EagleClarinet22.svg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feagleclarinet22%2Fusbkeypresencewatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feagleclarinet22%2Fusbkeypresencewatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feagleclarinet22%2Fusbkeypresencewatcher/lists"}