In my previous post I discussed auditing permissions in vCenter via PowerCLI.  Going through the process of identifying account and group permissions and what objects they have been set on.  In this second of a two part post, I look at creating a vCenter Alarm in PowerCLI that will trigger when a permission is Added / Removed / or Modified which will then show up in vCenter Alarms.

Part 2 -- Generating a custom alarm on a vCenter permission change

The objective here is not to catch someone out (though you could see how it could help).  The Alarm is by no means meant to be as a deterrent or even used for auditing.  Where it’s useful is as an identifier that a permission add / remove / modification as taken place.  Once triggered a person can review the new permissions and acknowledge the alarm.

Working with vCenter Alarms in PowerCLI hasn’t reached the maturity as many other Cmdlets.  So creating new alarms with PowerCLI is not as straight forward as using a Cmdlet.  To create a new alarm ww have to use the powerful Get-View Cmdlet which exposes us to all the richness of the SDK APIs of vCenter.

Creating an alarm requires a few pieces of information.  First we create the alarm object, give it a name, description, and set its state.

Next we create our Triggers or expressions.  Creating the expression is where the magic lays.  The key piece is the EventTypeID.  This is the specific vCenter event that will trigger the alarm.  I found finding this information through VMware was extremely difficult.    With a little searching though, and playing around, I found the information I was after with Get-View eventManager.

$event = get-view eventManager
$eventman.description.eventinfo | Where-Object {$_.key -like "*permission*"}

Running the above without any filters returned a huge amount of information with possible events to trigger on.  Using the Where-Object Cmdlet I was able to filter the results to anything with the word ‘permission’.  This narrowed down the results to just four.  The key three being  PermissionAddEvent,  PermissionRemoveEvent, and PermissionUpdatedEvent.  Of course if you want to see everything just remove the pipe and everything after it.

With these events and a little more research I had enough information to now create a script for an alarm.  Below I created three expressions.  One for each Permission event and set it’s status to Yellow if triggered.  The alarm is created in the root of vCenter and will propagate down to all objects.

$alarmMgr = Get-View AlarmManager

# Create AlarmSpec object
$alarm = New-Object VMware.Vim.AlarmSpec
$alarm.Name = "Permission Modification"
$alarm.Description = "Track permission changes"
$alarm.Enabled = $TRUE

# Event expression 1 - Permission Added
$expression1 = New-Object VMware.Vim.EventAlarmExpression
$expression1.EventType = "EventEx"
$expression1.EventTypeId = "vim.event.PermissionAddedEvent"
$expression1.ObjectType = "VirtualMachine"
$expression1.status = "Yellow"

# Event expression 2 - Permission Removed
$expression2 = New-Object VMware.Vim.EventAlarmExpression
$expression2.EventType = "EventEx"
$expression2.EventTypeId = "vim.event.PermissionRemovedEvent"
$expression2.ObjectType = "VirtualMachine"
$expression2.status = "Yellow"

# Event expression 3 - Permission Modified
$expression3 = New-Object VMware.Vim.EventAlarmExpression
$expression3.EventType = "EventEx"
$expression3.EventTypeId = "vim.event.PermissionUpdatedEvent"
$expression3.ObjectType = "VirtualMachine"
$expression3.status = "Yellow"

# Add event expressions to alarm
$alarm.expression = New-Object VMware.Vim.OrAlarmExpression
$alarm.expression.expression += $expression1
$alarm.expression.expression += $expression2
$alarm.expression.expression += $expression3

# Create alarm in vCenter root
$alarmMgr.CreateAlarm("Folder-group-d1",$alarm)

# Add action to email alarm
#Get-AlarmDefinition $alarm.Name | New-AlarmAction -Email -Subject "vCenter Permission Modification Occurred" -To [email protected]
#Get-AlarmDefinition $alarm.Name | Get-AlarmAction | New-AlarmActionTrigger -StartStatus 'Green' -EndStatus 'Yellow'

Commented out is also the ability to email a notification out when an event occurs.  This just feels a little overkill but never the less is a notification option.

The beauty of this script is that it can also easily be modified to alarm on any trigger-able event in vCenter.  Whether you need one expression or multiple expressions it’s easily modifiable.

Virten.net has a good article on how to create custom alarms and find events that I used for a reference.  If you don’t want to search for your own events to alarm on.  Virten maintains a database of all events that can be alarmed on.  I’m not sure how current it is but it’s a good starting point.

References

How to create custom vCenter Alarms from Events | Virten.net

Vmware Data Object -- EventAlarmExpression

In this two part post I discuss and cover how to audit vCenter permission using PowerCLI.  How to enumerate basic permissions and then expand it out and send it to a CSV file for further auditing.  In Part 2, I’ll discuss how to create custom alerts using PowerCLI to trigger an event on a vCenter permission modification.

Part 1 -- Auditing vCenter Permissions

Reviewing and auditing vCenter permissions has always been awkward at the best of times.  Unless you’re on top of permissions from day one, over time you can be left with a mess of vCenter permissions.  If you’re not explicitly looking for it you won’t know it either.  This is certainly what I found recently in one of my vCenter environments.

There are a few different ways to view permissions in the C# and Web Client.  You can click on an object and view the Permissions tab or you can go to Roles.  The Roles section is certainly much more useful but still far from ideal.  You have to click on each Role and there is no way to export that information.  Using PowerCLI on the other hand you can consolidate the above two methods into one view and have it exportable.  The quickest and easier way to get started is with Get-VIPermission once connected to a vCenter in PowerCLI.

Get-VIPermission | Format-Table -AutoSize

Get-VIPermission in its default form gives you a quick overview of all Principals / Users defined with explicit permissions along with their Role, whether it’s a group, and if it’s set to propagate down the tree .  Ideally you’ll only have a few groups listed here and nothing else.  Unlike myself, where I had a large amount of individual users explicitly listed on many different objects.

When using Format-Table we loss a little information on the screen. Namely, we can’t see on what objects these permissions are set on.  So we can work with the Get-VIPermission cmdlet to expand it out a little further.

 Get-VIPermission | sort | Format-Table Entity, EntityID, Role, Principal -AutoSize

The two extra values we are looking for here are Entity and EntityID.  In most cases Entity will aid in identifying the vCenter object that has the explicit permissions set on it so you can review.  The Entity could be a Virtual Machine, a Cluster, or a Datastore.  In some cases, though, you will find the Entity is blank.

Again, in my case I had a lot of permissions with a blank Entity.  Using EntityID I could see that the objects appeared to be networking related.  So in this case we need to get a little more creative with the querying of the SDK APIs using Get-View.

Get-VIPermission | sort | ft @{N=”ObjectName”;E={(get-view -Id $_.EntityID).name}}, Entity, EntityID, Role, Principal -AutoSize

This now gets us 95% of the way there.  We use Get-View using the EntityID as the Get-View ID to find the actual name of the vCenter object for that missing Entity value.  In the case of the networking objects we will now get the exact names of the networking switches.

Putting it all together.  In this last part I turn the one liner into a little script, make sure the correct snap-in is loaded, make it a little easier to read, and have it output to a CSV file that can be used to audit and review at a later stage.

# Import Snap-in
if ((Get-PSSnapin | where {$_.Name -ilike "Vmware*Core"}).Name -ine "VMware.VimAutomation.Core")

{
Write-Host "Loading PS Snap-in: VMware VimAutomation Core"
Add-PSSnapin VMware.VimAutomation.Core -ErrorAction SilentlyContinue
}

$Date = (get-date).tostring("yyyyMMddHHmm")
$result = Get-VIPermission | sort-object -Property Principal | Select @{N="ObjectName";E={(get-view -Id $_.EntityID).name}}, EntityID, Role, IsGroup, Principal

$result | Export-CSV -Path "$pwd\vCenter_PermissionAudit-$date.csv" -NoTypeInformation -UseCulture

In the above script the results are outputted to a CSV file appended with the date.  The benefit of doing this is you can schedule it to run and now have a history of the state of permissions over time.  Simple as it is, I think it’s really handy.

In the next post I will look at creating a basic Alarm in vCenter that will trigger when a permission is modified on an object.