Setting Tanium Maintenance Windows with TanREST – Part I

Here we are again; another month has passed in the blink of an eye and I find myself once again scrambling at the 11th hour to do homework that should’ve been done weeks ago. In this post, we’ll be discussing the configuration of maintenance windows in Tanium described in Patch Like You Mean It. This is the first half of a two-part post: the second half can be found at Setting Tanium Maintenance Windows with TanREST – Part II.

That said, I do feel the need to do a little CYA so let’s get into that.

Disclaimer: Any code made available on this site is free to use at your own discretion but it is provided without any explicit or implied guarantees of support, reliability, or functionality. I accept no responsibility in the event that the code, in its original form or any derivative versions thereafter, malfunctions or causes problems. Anything from this site that you decide to work with should be tested thoroughly in development environments in collaboration with your Technical Account Manager (TAM) until such time that you, the responsible party, decides that you are satisfied with its outcomes.

On that same note, there are some things I cannot legally provide to you. While I will make reference to functions from Tanium’s proprietary TanREST module, I am not legally or ethically at liberty to provide you with their work. If you wish to utilize TanREST, you need to do so by requesting the software from your TAM.

Let’s get to the fun stuff.

#
	.SYNOPSIS
		Set Tanium maintenance windows via the platform REST API.
	
	.DESCRIPTION
        This function will configure Tanium maintenance windows for the Patch & Deploy modules; they can be configured independently
        or together depending on the parameters selected.
	
	.PARAMETER Mode
		The Mode dictates what modules will be targeted.  Valid selections are Patch, Deploy, and All.  Default value is All.
	
	.PARAMETER Historical
        The Historical parameter dictates whether or not the modules targeted via the Mode parameter will configure the maintenance windows 
        to be in the future or in the past.  Default value is $false.
	        
    .PARAMETER Notify
        The Notify parameter dictates whether or not a notification email will be sent to the DW-DeviceMgmtandDelivery distribution list.
			
	.EXAMPLE
		PS C:\> Set-TaniumMaintenanceWindows -Mode Patch -Historical
	
	.NOTES
		Additional information about the function.
#

As one might expect, this function has a couple of input options and I feel like they are worth pointing out. Among those options are the Mode, Historical, and Notify parameters.

Mode is simply a way of directing the function to either set maintenance windows for Patch, Deploy, or All (Both types simultaneously). I’ve been instructed that the maintenance window objects in each respective module are being scrutinized and may be unified (Potentially becoming part of the core platform itself) in the future. If such a thing comes to pass, I will likely create a new post detailing these changes and the modifications that will be needed to automate them.

Historical is a switch parameter that lets the function know that the maintenance windows need to be set in the past. This is basically the “STOP THE PRESSES” lever. You may be questioning the utility of such a thing given that you can simply stop a deployment but stopping a deployment results in the associated content being deleted from endpoints. If you have a patch emergency that turns out to have only affected a handful of endpoints, there are situations where you would have been better served by setting historical maintenance windows, assessing the problem, blacklisting the patch or patches on the affected endpoints, and then setting the maintenance windows again to their proper values. If you had disabled the deployment in that scenario, you may have deleted content from tens of thousands of endpoints that will now have to reacquire it and even the P2P content distribution model can take time to saturate an environment of that size.

Notify is a bit misleading as running this function in its current state will send a notification no matter what. In this context, Notify is simply used to include a broader audience whereas not calling it will simply result in the HTML-formatted email being sent to a lone administrator (Presumably you).

function Set-TaniumMaintenanceWindows
{
	[CmdletBinding()]
	param
	(
		[Parameter(Position = 1,
				   HelpMessage = 'Valid values are All, Patch, or Deploy')]
		[ValidateSet('All', 'Patch', 'Deploy')]
        [string]$Mode='All',
        
		[Parameter(Position = 2)]
        [switch]$Historical,
        
		[Parameter(Position = 3)]
        [switch]$Notify
        
	)
    
    #Dot-source prerequisite functions

    . "\\someFileShare\Get-PatchTuesday.ps1"
    . "\\someFileShare\Send-HTMLEmail.ps1"

    if ([bool]$(Get-Command Get-PatchTuesday -ErrorAction SilentlyContinue) -eq $false) {
        Write-Host "The Get-PatchTuesday function is a prerequisite."
        exit
    }

    if ([bool]$(Get-Command Send-HTMLEmail -ErrorAction SilentlyContinue) -eq $false) {
        Write-Host "The Send-HTMLEmail function is a prerequisite."
        exit
    }

This section is where our parameter settings are established and where prerequisites are dot-sourced. In this instance, there is only one parameter with multiple options; the ValidateSet functionality is part of the advanced parameter configuration (Enter Get-Help about_Functions_Advanced_Parameters into PowerShell to find out more) and allows you to constrain the amount of valid options that the function will accept. Sanitizing your inputs and controlling them this way allows for predictability in the subsequent code to follow.

I also have the Historical and Notify switches defined in this section; the switches in this instance have no predefined values unlike the $Mode=’All’ line because they are boolean values; if you do not call the switches in your function invocation, I assume that you do not want them and subsequently treat that as a $false whereas calling them will be addressed with a $true.

Dot-sourcing a script or function calls it into the active session that is executing the current function and allows those subordinate scripts or functions to be leveraged. Get-PatchTuesday.ps1 and Send-HTML.ps1 are prerequisites; the Get-PatchTuesday post entitled Determining Patch Tuesday with Powershell and the Send-HTMLEmail script by Ben Wilkinson describes the functionality and provides a link that you can use to download that content.

There are simple if statements to check and see whether or not those pieces of content are present that will stop execution and exit if they’re not found.

[System.Collections.ArrayList]$configurations = @()
$maintenanceWindows = Import-Csv -Path "\\someFileShare\maintenanceWindowSource.csv"
$patchTuesday = Get-PatchTuesday

I’m doing some simple preparatory work here. First and foremost, I’ve established an ArrayList container in the form of $configurations to feed the individual maintenance window configurations into. As we loop through every maintenance window, the configurations pertinent to that window will be thrown over to the ArrayList to allow them to persist in a form that can be emailed via the Send-HTMLEmail function just prior to the completion of the function.

$maintenanceWindows will serve as a home for the values defined within the CSV so that the function can loop through each row’s values and take specific action on those individual items.

$patchTuesday is simply a variable container to store this month’s Patch Tuesday value for later use.

The CSV values are structured as follows:

• windowName – Indicates the name of the maintenance window. In our process, this name also matches the name of the associated Tanium Computer Group and Active Directory Security Group used for identifying/acting upon maintenance windows. Example: Maintenance_Window_01_1800
• patchTuesdayOffset – Indicates the amount of days that the maintenance window needs to be offset from Patch Tuesday. Example: 6
• startTime – Indicates the time that the maintenance window should begin and is notated in 24-hour time format. Example: 18:00
• hoursDuration – Indicates the amount of hours that the maintenance window should remain open. Example: 8

This post has ended up being lengthier than expected so it has been split into two parts. You may find the second half of the story at Setting Tanium Maintenance Windows with TanREST – Part II.

Disclaimer: Any code made available on this site is free to use at your own discretion but it is provided without any explicit or implied guarantees of support, reliability, or functionality. I accept no responsibility in the event that the code, in its original form or any derivative versions thereafter, malfunctions or causes problems . Anything from this site that you decide to work with should be tested thoroughly in development environments in collaboration with your Technical Account Manager (TAM) until such time that you, the responsible party, decides that you are satisfied with its outcomes.