Automatically 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.

This project includes:

• A PowerShell presence watcher
• Toast notifications via BurntToast (optional)
• A Windows Scheduled Task to start the watcher automatically
• Event Viewer logging (with file fallback)
• A fully interactive installer that detects your USB devices
• A matching uninstaller
• A clean, self-elevating installation workflow
• GitHub Actions pipelines validating XML, linting PowerShell, and generating releases
• Issue templates + Discussions for structured reporting and community support

⚠️ This script must run using Windows PowerShell 5.1 (the built-in Windows PowerShell).
PowerShell 7+ (pwsh.exe) is not supported for hidden scheduled-task execution, PnP APIs, or BurntToast.

Locks your workstation automatically when your selected USB device disappears — and keeps it locked until the device returns.

If the system is manually unlocked while the USB device is missing, the watcher immediately locks it again.

Requires BurntToast. Indicates:

• Monitoring started
• Device removed
• Device reinserted

Prevents false positives from USB hub glitches (default: 2 consecutive misses required to lock).

Log: Application
Source: USBKeyPresenceWatcher

The installer:

• Detects all USB devices with VID/PID
• Lets you choose the correct USB device or token
• Patches the installed script with your VID/PID
• Hardens directory ACLs
• Creates the EventLog source
• Generates runtime task XML:

Template-USBKeyPresenceLock.xml → Task-USBKeyPresenceLock.xml

The installer grants FullControl to:

• Current user
• SYSTEM
• Administrators

All others are removed.

USBKeyPresenceWatcher/
│
│   Install-USBKeyPresenceWatcher.ps1
│   Uninstall-USBKeyPresenceWatcher.ps1
│   USBKeyPresenceLock.ps1
│   Launch-USBKeyPresenceWatcher.vbs
│   Template-USBKeyPresenceLock.xml
│   lock_toast_64.png
│
│   CHANGELOG.md
│   README.md
│   LICENSE
│   NOTICE
│
│   .editorconfig
│   .gitattributes
│   .gitignore
│   .prettierignore
│
└── .github/
    ├── workflows/
    │     auto-hotfix.yml
    │     auto-nightly.yml
    │     release.yml
    │     validate-powershell.yml
    │     validate-xml.yml
    │     ci-validation.yml
    │
    └── ISSUE_TEMPLATE/
          improvement-roadmap.yml
          bug.yml
          feature.yml
          refactor.yml
          performance.yml
          documentation.yml
          workflow-failure.yml
          security.yml
          ux.yml
          config.yml

The installer registers a task that runs at:

• User logon
• Session unlock

The task executes:

wscript.exe Launch-USBKeyPresenceWatcher.vbs

The VBS wrapper silently launches:

powershell.exe -WindowStyle Hidden -File USBKeyPresenceLock.ps1

This ensures fully hidden execution.

Once per second:

Get-PnpDevice -PresentOnly | Where-Object InstanceId -like "*VID_####&PID_####*"

• Missing device → increment counter
• Present device → reset counter
• After N misses → lock workstation

rundll32.exe user32.dll,LockWorkStation

Optional heartbeat logs help diagnose issues.

A mutex prevents duplicate watchers:

USBKeyPresenceWatcher_<USERNAME>

Logs go to Event Viewer or a fallback local log file.
Toast notifications appear if BurntToast is installed.

The uninstaller:

• Terminates watcher instances
• Removes the scheduled task
• Deletes the installation directory
• Supports -WhatIf

Ensures complete cleanup.

Handles:

• Selecting USB device
• Patching watcher with VID/PID
• Hardening ACLs
• Generating task XML
• Registering the task

Handles:

• Killing watcher processes
• Removing scheduled task
• Cleaning directories
• Supporting dry runs with -WhatIf

The core watcher:

• Polls for device
• Enforces lock-on-missing
• Logs events
• Sends notifications
• Prevents multiple instances

Ensures the watcher runs:

• Hidden
• Under correct session
• Without console windows

Defines triggers, actions, permissions, and runtime environment.

• validate-powershell.yml — PSScriptAnalyzer checks
• validate-xml.yml — XML structure + encoding checks
• release.yml — Automated release generation
• auto-hotfix.yml — Auto hotfix creation based on commit volume
• auto-nightly.yml — Daily builds
• ci-validation.yml — Repository-wide validation

git clone https://github.com/EagleClarinet22/USBKeyPresenceWatcher.git
cd USBKeyPresenceWatcher

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

.\Install-USBKeyPresenceWatcher.ps1

Installer will list all detectable USB devices and let you choose one.

.\Install-USBKeyPresenceWatcher.ps1 -Force

$missingThreshold = 2

Install BurntToast:

Install-Module BurntToast -Scope CurrentUser

Ensure:

• Task runs as logged-in user
• "Run only when user is logged on" is enabled

.\Uninstall-USBKeyPresenceWatcher.ps1

Supports:

• Instance cleanup
• Task removal
• Directory deletion
• -WhatIf

Contributions are welcome!

Use structured issue templates for:

• Bug reports
• Feature requests
• Workflow failures
• UX improvements
• Documentation updates

For general questions or support, start a Discussion:
https://github.com/EagleClarinet22/USBKeyPresenceWatcher/discussions

MIT License. Attribution appreciated but not required.

Happy locking! 🔐