Skip to content

PatchAutomation Toolkit Documentation and Guides

Jump to bottom Edit New page
Alex Hedley edited this page Jun 18, 2020 · 2 revisions

Original: https://www.symantec.com/connect/articles/cwoc-patchautomation-toolkit-documentation-and-guides

[END OF "SUPPORT" NOTICE]

Hello everyone, after close to 5 years maintaining various tools around Symantec Connect this legacy is turning to be more of a burden than anything else.

It's still is a great set of tool and they all have their use, but as such I'm not going to maintain them anymore.

The source code for this tool may still change over time, and can be found on Github: https://github.com/somewhatsomewhere?tab=repositories

[/END OF "SUPPORT" NOTICE]

###################################

Update! Patch ToolKit version 0.7.0 is out now (release notes). This new version of the toolkit includes a set of command line that help avoid the overlap issues between the Microsoft and PatchAll features - namely the /vendor option.

Here is a simple view of what can be done with version 0.7.0:

###################################

Table of content:

  • Introduction
  • Some background information
  • Toolkit common features
  • ZeroDayPatch specific features
  • PatchAutomation specific features
  • Toolkit can and can't do
  • Command line samples)
  • References and links

Introduction:

We are now a couple of month in the project (I made my first commit [733] on the first utility of the Patch Toolkit back in November) and we are now at revision [777] with the two main utilities (ZeroDayPatch [1] and PatchAutomation [2]) now merged into a single Visual Studio Solution and at version 0.6.7.

So I think it's a good time to added to the existing documentation with some use cases and details on what the tools can and can't do, as well as details examples of how much can be done with each one of them, or using the two in combination.

Some background information:

Let's start by a little more on the tool history. Patch Automation is an old hobby of mine, dating back in the 6.1 times when I used the nscript utility and a sample script from ManageFusion to help the deployment of software updates. I updated the tool to 6.2 based on user demand and had a quick look at this option in 7.0 but found it much too complicated to get into (I already had a small project working on a Managed Delivery SDK that went well but was a rather unpleasant experience due to code complexity and certain caveats in the application models - but let's not digress to far here).

Anyhow this winter I went to a customer that needed to fully automate the deployment of Patch in 7.1. The first answer that Symantec had for this problem was to use a Workflow, so I happily went along. But with the very short deadline and the complexity of our Workflow product I could see how this was not going to be a solution the customer or I would really want to implement.

Luckily I found out that the Patch team implemented an API that the Workflow Solution consumes to automate the deployment of patches. And in less time that it took me to get a workflow server up and running I had a proof of concept going: ZeroDayPatch (as the tool aims to allow user environments to be automatically up-and running within 24 hours of a patch release in the Symantec Management Platform). As I build up this first tool I got where I needed to fork out to a second project extending the capabilities toward my customer requirement, naming the tool PatchAutomation (as it includes automatic re-targeting based on preset or command line argument values.

Toolkit common features:

The two project were merged back a few week ago and some refactoring done for release 0.6.7 and prior are allowing both tools to share a certain amount of code and features. These features are key to the tool and visible to the users via the command line arguments listed here: /severity, /patchall, /released_before, /released_after, /test, /dryrun, /debug and /?.

Note! All of those command line switches are optional, so default values are hard coded in the programs and detailed below.

The first 4 entries are real program controls, the next 3 are only there to help test and validate the tool or troubleshoot and the last one is the help message display command. The options are pretty clear to what their use is but it's always best to make everything crystal clear at the risk of making this a little boring (that's documentation hey!), so here are the details for each command:

  • /severity allows you to specify a severity that should be matched (Strict match) for bulletins to be added to the list of bulletins handled by the tool. Additionally we have a wild-card token available ("*", the star character or asterisk) albeit the real usefulness of this won't be clear until we dive in the PatchAutomation custom features.
  • /patchall allows the users to switch the stored procedure that is called to retrieve the bulletins that exist on the SMP database: spPMCoreReport_AllSoftwareBulletins to get the Microsoft Security Bulletins (used by default) or spPMCoreReport_SoftwareBulletinSummary that - unlike the name indicates - returns bulletins from all vendors that are found in the SMP database (so used when the /patchall command line switch is specified.
  • /released_before allows users to define a ceiling (upper value) to reduce the amount of updates to be handled by the program execution. By default this value is set to the program run date.
  • /released_after allows users to define a flower (lower value) to reduce the amount of updates to be handled by the program execution. By default this value is set to the run date - 1 year.
  • /test is useful (as the name indicates) in testing as it limits the number of policies created to 10. This is very useful for my own debugging but also for testing to make sure everything works fine from the command line, before setting the command line in a schedule task.
  • /dryrun very much like test is used pre-production, but allows to check all the operation that the program would undertake without making any changes to the system.
  • /debug is used to trigger a debug switch that controls the output to the console (stdout) and/or the Altiris Server logs. The switch has some extra functionalities depending on the program (specially in PatchAutomation.exe, see below for more details).
  • /? is one I needn't document. It prints out a standard help message, just as it would happen if you ran the program with invalid command line switches.

Additionally there is another feature that is not command line driven but well worth documenting here in details: the custom exclusion table. Here is how the feature is implemented: when creating the list of bulletins to be handled (staged etc) we check if they are excluded by name, that is whether they are in the results set from the following SQL query:

if exists (select 1 from sys.objects where name = 'patchautomation_excluded')
    select bulletin from patchautomation_excluded

The data table is not built by the program, but the following code should be good enough to create the table and avoid duplicate entries:

CREATE TABLE [dbo].[PatchAutomation_Excluded](
	[_id] [int] IDENTITY(1,1) NOT NULL,
	[Bulletin] [nvarchar](255) NOT NULL,
	[CreatedDate] [datetime] NULL DEFAULT (getdate()),
CONSTRAINT [pk_PatchAutomation_Excluded] PRIMARY KEY CLUSTERED 
	(
		[Bulletin] ASC
	)
)

And here are a few sample queries to add or remove entries from the exclusion table:

insert PatchAutomation_Excluded (Bulletin) values ('MS12-081')
insert PatchAutomation_Excluded (Bulletin) values ('MS12-025')

ZeroDayPatch specific features:

On top of the common feature ZeroDayPatch only has an extra 2 configuration items:

  • /vulnerable
  • /targetguid

Let's start with the simplest one: /targetguid. By default we do not specify a target guid when creating the policies. This allows the Default Software Policy target (configure in Patch Management) to be used. As you understand now the /targetguid is an override should you want to create the policies for another target than the default one.

The /vulnerable is a feature added via Symantec Connect (based on user demand) and changes the base dataset (used to create the bulletin list) to start with bulletins that have vulnerable clients in the environment only.

To this avail we have a custom stored procedure that is defined in the code (public const string ZERODAY_GET_VULNERABLE in Constant.cs) and automatically inserted in the DB when this command line switch is used. The procedure is auto-updated when a new version is released (we are currently at version 3 - thus the sp name is 'ZeroDayPatch_GetVulnerableMachines-003') albeit we are not expecting further changes - but who knows what tomorrow will bring.

So this is another customization point, as we only check that the sp name is consistent with a predefined value. This means that you could change the store procedure code to return anything you want as long as you keep the following 4 columns in the result set:

  • _ResourceGuid
  • Bulletin
  • Release
  • Severity

The 4 columns are need but can be present in any order. If the result set is not compliant the program will simply terminated without any error.

PatchAutomation specific features:

The PatchAutomation tool as a few more switches than ZeroDayPatch, but this is because the tool itself as a lot more to do. Please refer to the current workflow ([2]) should you need detailed view of this process.

The command line switches are again pretty straight forward:

  • /targetguid-test=<target_guid>
  • /targetguid-validation=<target_guid>
  • /targetguid-production=<target_guid>
  • /day2validation=<n>
  • /day2production=<n>
  • /custom-sp=<sp_name>

With the three /targetguid-<stage> switches (where the stages are in order 1 - Test, 2 - Validation and 3 - Production). Note that these 3 command line switches are mandatory unless you use the /debug.

The next 2 switches (/day2validation and /day2production) define the difference between the run date and policy date to move from one stage to the next. By default the test policies will be moved to validation when the difference = 2 days and to production when the difference = 12 days.

Note! The date difference is not the same as a number of days. If you run PatchAutomation at 23:50 on day 1 and again 11 minutes later the date difference will be 1 day, whilst only 11 minutes have elapsed between the 2 executions.

Finally the /custom-sp switch allows you to specify a stored procedure name that will be used at run time to get the base list of bulletins to work with. The store procedure code can return anything you want as long as you keep the following 4 columns in the result set:

  • _ResourceGuid
  • Bulletin
  • Release
  • Severity

The 4 columns are need but can be present in any order. If the result set is not compliant the program will simply terminated without any error.

This feature allows users to manage bulletins by custom severity, vendor names or anything they want with as many custom procedures as needed.

Note! This last switch will take priority over the /patchall option, which also sets a custom sp to be executed.

Toolkit can and can't do:

Now, comes an interesting part (sorry for the hidden nugget, so may be I'll put that in a blog post as well).

So with all the many features in ZeroDayPatch and PatchAutomation it feels like anything can be done, but this is not true, There are some hard set limit and incompatibilities between different command line sets.

So, first of all, you can and most likely should use a set of command lines to get the tasks done, as you may want to treat important, critical and other bulletins differently.

So one important consideration to keep in mind when using these tools are the data subsets you are working with. Here's a quick view of what I mean, that makes it all much more meaningful than more words here:

Three command lines are used to manage Microsoft security updates over different period of times, and different severities (selected in pink):

[MISSING IMAGE]

Three command lines are used to manage all vendors updates (/patchall) over different period of times, and different severities (selected in pink):

[MISSING IMAGE]

This may look and be perfectly fine for ZeroDayPatch however this could be an issue in PatchAutomation if you are using different span to validation based on the vendor or severity, as the datasets overlap (in orange):

[MISSING IMAGE]

So, you can do very much but beware of dataset overlaps when you want to implement differentiated services.

For the "can do" I won't list anything here. Rather I invite you to look below to the use cases summary!

Command line samples:

Here are a few command line samples to show the tools capabilities and how to implement it in various environment. It is not exhaustive and a detailed article on how to implement one of the use case will be published soon.

ZeroDayPatch: Stage and create policies for critical bulletins released in 2011.

  • ZeroDayPatch /released-after=2011-01-01 /released-before=2012-01-01 /dryrun
  • ZeroDayPatch /released-after=2011-01-01 /released-before=2012-01-01 /test
  • ZeroDayPatch /released-after=2011-01-01 /released-before=2012-01-01

Note that I always use the /dryrun first to verify the output. Then I use /test to start the process for up to 10 bulletins and finally the command line to be scheduled. only the dryrun command line will be provided in the following samples.

ZeroDayPatch: Stage and create policies for any vendors bulletins that are vulnerable released in 2012.

ZeroDayPatch /released-after=2011-11-30 /patchall /vulnerable /dryrun​

ZeroDayPatch: Stage Microsoft Security bulletins of any severities released in 2012.

ZeroDayPatch /released-after=2011-12-31 /severity=* /dryrun

ZeroDayPatch: Stage Moderate bulletins from all vendors to target with guid {784339d0-f398-4f31-8b30-f9f41326e1f5} (released int he last 12 month)

ZeroDayPatch /severity=moderate /patchall /targetguid=784339d0-f398-4f31-8b30-f9f41326e1f5 /dryrun

PatchAutomation note! In all the samples below we will use the following 3 target guid:

  • targetguid-test = d8c05f62-9381-49f4-a862-ed271645479e
  • targetguid-validation = 8d66d34c-2228-42e1-b5b5-92fc38e9e993
  • targetguid-production= 784339d0-f398-4f31-8b30-f9f41326e1f5

PatchAutomation: automate the deployment of all critical updates since Windows XP SP3 (May 2008):

PatchAutomation /released-after=2008-05-01 /targetguid-test = d8c05f62-9381-49f4-a862-ed271645479e /targetguid-validation = 8d66d34c-2228-42e1-b5b5-92fc38e9e993 /targetguid-production= 784339d0-f398-4f31-8b30-f9f41326e1f5 /dryrun

Patch automation: automate the deployment of Microsoft Security Update for any severities in December 2012:

PatchAutomation /released-after=2012-11-31 /released-before=2013-01-01 /targetguid-test = d8c05f62-9381-49f4-a862-ed271645479e /targetguid-validation = 8d66d34c-2228-42e1-b5b5-92fc38e9e993 /targetguid-production= 784339d0-f398-4f31-8b30-f9f41326e1f5 /dryrun

Patch automation: automate the deployment of All vendors Update with a severity important and released in 2012, with 1 day span to stage test policies to validation and 5 days to stage validation policies to production:

PatchAutomation /severity=important /released-after=2011-12-31 /released-before=2013-01-01 /day2validation=1 /day2production=5 /targetguid-test = d8c05f62-9381-49f4-a862-ed271645479e /targetguid-validation = 8d66d34c-2228-42e1-b5b5-92fc38e9e993 /targetguid-production= 784339d0-f398-4f31-8b30-f9f41326e1f5 /dryrun

References and links:

Add a custom footer
Add a custom sidebar
Clone this wiki locally