VIRT-008 · Script
Virtualization Event Audit and Export
Finds and exports administrative virtualization events such as sign-ins, power changes, host changes, permission changes and virtual machine reconfiguration.
What it does
Read-only. Nothing is changed. Exports the events from the last -Hours to a CSV in -ReportDir, each with time, category, user, virtual machine, host, event type and message.
VMware: reads the vCenter Server or ESXi event history and sorts events into categories:
- Logins: user sign-in, sign-out and failed sign-in events
- Power: power on, power off, suspend, reset, guest shutdown and restart
- Hosts: host connected, disconnected, added, removed, maintenance mode
- Permissions: permissions and roles added, changed or removed
Reconfiguration VM settings changed, renamed, migrated or relocated
- Lifecycle: VM created, cloned, deployed, registered or removed
How far back events go depends on your vCenter Server event retention settings.
Hyper-V: reads the Hyper-V management (VMMS) and worker admin event logs on the host and sorts them into the same categories by their message text, which is a best-effort match. With Logins and Permissions included it also reads the host Security log for interactive and remote desktop sign-ins (events 4624 logon types 2 and 10, and failed sign-ins 4625) and for membership changes of the local "Hyper-V Administrators" group (events 4732 and 4733). The Security log needs to be readable by the account running the script.
Runs silently. No prompts.
Requirements
Windows PowerShell 5.1+. Hyper-V: event log read access on the host. VMware: VMware PowerCLI installed by you and read access to events in vCenter Server.
How to run it
- Run from: an admin workstation or scheduled task with the Microsoft modules installed and app sign-in configured
- This is an admin script for your Virtualization tenant, not a per-device endpoint script
- User interaction: none with app-only sign-in
- Schedule: run on demand, or weekly for reports
Settings
| Name | What it does | Options | Default |
|---|---|---|---|
| Platform | HyperV (default) or VMware. | HyperV, VMware | HyperV |
| Hours | How many past hours to export. Default 24. Example: 168 for one week. | 24 | |
| Category | Categories to include. Default all: Logins, Power, Hosts, Permissions, Reconfiguration, Lifecycle. Add Other to also export events that match none of them. | Logins, Power, Hosts, Permissions, Reconfiguration, Lifecycle, Other | Logins, Power, Hosts, Permissions, Reconfiguration, Lifecycle |
| AlertCategory | Categories that should return exit code 1 when any event is found, for example Permissions to be alerted about permission changes. Default none. | Logins, Power, Hosts, Permissions, Reconfiguration, Lifecycle, Other | (none) |
| MaxEvents | Upper limit of events to read, to keep large environments fast. Default 20000. | 20000 | |
| ComputerName | Hyper-V only. Name of a remote Hyper-V host, for example HV01. Leave empty to use this computer. The account running the script needs Hyper-V administrator rights on that host. | ||
| Server | VMware only. vCenter Server or ESXi host name, for example vcenter.school.local. | ||
| CredentialPath | VMware only. Path to a credential file created with Get-Credential | Export-Clixml, for example C:\ProgramData\Runbookia\Secure\vcenter.xml. Create the file as the same account (for example SYSTEM) on the same computer that runs this script; Windows encrypts it so no other account can read it. Not needed with UseExistingSession. | ||
| UseExistingSession | VMware only. Reuse a vCenter Server or ESXi connection that is already open in this PowerShell session (from Connect-VIServer) instead of CredentialPath. | False | |
| IgnoreCertificateErrors | VMware only. Accept an untrusted or self-signed server certificate for this run only. Off by default; the PowerCLI setting on disk is not changed. | False | |
| ReportDir | Folder for CSV reports. Default C:\ProgramData\Runbookia\Reports. | C:\ProgramData\Runbookia\Reports |
Exit codes
- 0 = Export written, no events in AlertCategory
- 1 = Events found in an AlertCategory, or MaxEvents was reached
- 2 = Script error (missing module, connection failed, Hyper-V event logs unreadable)
Testing steps
- Run it on one test tenant or small OU and check the output and log.
- Check the exit code: 0 = OK, 1 = needs attention, 2 = error (see log), 9 = this copy is past its Valid until date.
- Roll out to a small group next, then everyone.
Rollback steps
Report only. Nothing is changed, so nothing needs to be rolled back.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |