Video Screencast Help
Symantec Appoints Michael A. Brown CEO. Learn more.

{CWoC} PatchAutomation Toolkit - Documentation and Guides

Created: 02 Jan 2013 • Updated: 18 Feb 2013 | 8 comments
Language Translations
Ludovic Ferre's picture
+6 6 Votes
Login to vote

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

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:

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.

Back to top

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.

Back to top

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')

Back to top

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.

Back to top

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.

Back to top

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):

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

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):

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!

Back to top

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

Back to top

References and links:

[1] https://www-secure.symantec.com/connect/downloads/patch-automation-tool-pms-71-sp2
[2] https://www-secure.symantec.com/connect/blogs/patch-71-automation-version-20

Back to top

Comments 8 CommentsJump to latest comment

Ludovic Ferre's picture

Quick update on this matter: the latest version of the toolkit (ZeroDayPatch and PatchAutomation 0.7.0 and later) can now handle updates per vendor.

So the overlap between "All vendors" and "Microsoft" is no longer an issue, as you can craft an automation policy per vendor and other criteria.

I am currently off-net, on a retreat of some kind. I'll be back real soon, and you sure will hear from me then ;-).

Ludovic FERRÉ
Principal Remote Product Specialist
Symantec

+1
Login to vote
Pascal KOTTE's picture

Thanks a lot, but, now seems to be part of the 7.5 version, as Symantec PPT told about 

"Automatically download and deploy patches based on pre-defined criteria: Vendor, Patch Type and Filters"

Except  do not find anything of that under current 7.5 console, or documentation !!

Is it a new "hidden" feature, or I miss some doc somewhere ???

Or worst: a good Joke from Symantec (don't know sales against techs, or techs against sales...) ?

~Pascal @ Kotte.net~ Do you speak French? Et utilisez Altiris: venez nous rejoindre sur le GUASF

0
Login to vote
Ludovic Ferre's picture

Hello Pascal,

I actually had the same reaction as you did when I got my hand on the 7.5 alpha / beta.

I went back to product management and mentionned those slides. The response was that the features would not be built-in as Symantec has my great tool available! No, only kidding. It wouldn't be built-in because the same can be done via Workflow, so that's it.

I was just as disappointed as you are, as I think workflow is an expensive (in term or resources) technology and that you can achieve the same with a few kilo-bytes of c# MSIL.

In all cases, you can find my toolkit built for 7.5 on the dwoload section of Connect. Or you can go with Workflow :D.

I am currently off-net, on a retreat of some kind. I'll be back real soon, and you sure will hear from me then ;-).

Ludovic FERRÉ
Principal Remote Product Specialist
Symantec

+1
Login to vote
Pascal KOTTE's picture

More over, I think if Symantec decides using Workflow for building such automation, why don't they provide this Workflow ?

Why asking each customer to build their own, spend days and days, instead of providing what we are expecting:

  • an automate, ready to use  :)
  • instead of an empty toolbox, we have to configure & build everything for being able to use it... :(

Thanks your answer Ludovic.

~Pascal @ Kotte.net~ Do you speak French? Et utilisez Altiris: venez nous rejoindre sur le GUASF

0
Login to vote
Ludovic Ferre's picture

I'm going to say something silly again, but I think it's because they (who?) like me very much and would worry I would get bored if I didn't have the opportunity to write such tools on my own.

Mind you maintaining all the code I have generated now is quite a bit of a project in itself.

Beside, I would rather see trending data making it in the platform and better reporting capabilities as this is a major area for improvements!

I am currently off-net, on a retreat of some kind. I'll be back real soon, and you sure will hear from me then ;-).

Ludovic FERRÉ
Principal Remote Product Specialist
Symantec

0
Login to vote
Pascal KOTTE's picture

After this talk; I receive info about Workflow "Zero Day Patch" available in Workflow Solution Center

~Pascal @ Kotte.net~ Do you speak French? Et utilisez Altiris: venez nous rejoindre sur le GUASF

0
Login to vote
Pascal KOTTE's picture

Dear Ludovic as now the solution center

https://www-secure.symantec.com/connect/content-external/2950821/workflow-solutions-center

What should we do? what do you think or plan?

Can you provide a comparative; and plan to maintain yours, or not?

thanks in advance ;)

~Pascal @ Kotte.net~ Do you speak French? Et utilisez Altiris: venez nous rejoindre sur le GUASF

0
Login to vote
Ludovic Ferre's picture

Hi Pascal,

I still have my version working and maintained for 7.1 and 7.5.

I have no intention to deprecated the tool in favour of the workflow. That's because I'm a command line type of persons ;).

Which takes us to the comparative: single executable that you can run in cmd.exe or in Task, versus running a workflow in workflow.

This is the key differentiator to me (ontop of the 7.1 version).

I am currently off-net, on a retreat of some kind. I'll be back real soon, and you sure will hear from me then ;-).

Ludovic FERRÉ
Principal Remote Product Specialist
Symantec

0
Login to vote