Initiate SCEP Full Scan by script using SCCM Client Operations

Lets assume you have a security device that detects computers possibly infected by some malware. Wouldn’t it be nice to automatically initiate some immediate action for remediation? I recently had such a requirement where we wanted to automatically start a definition download and full scan on those computers. It’s pretty easy to trigger e.g. System Center Orchestrator to invoke this, however it wasn’t as easy as I hoped to actually execute it via ConfigMgr.

There are several blog posts on how to connect to the local computer and initiate it via the MPCmdrun.exe or the Powershell MPProvider Module. There are also some that explain how to create a package or application, which are basically just wrapping the same calls. You might want to have a look on the post “Automating Microsoft Endpoint Full System Scan upon Infection with Email Notification” by Mick Pletcher who explains an interesting approach running this based on event log entries. However, if you are familiar with the Configuration Manager console, you can just right-click any computer or device collection and easily execute those actions.

This uses a feature that was added in Configuration Manager 2012 SP1 called “Client Notification” that implements a push-based client communication mechanism. Please see Fast Channel for System Management for further details on how this process works. The interesting piece about this approach is, that ConfigMgr will actually try to enforce the execution as soon as possible if the computer is online or comes online within the next hour.

However, there is not really any documentation at all on how to actually script those operations, at least none that I was able to find. After searching through the Configuration Manager WMI classes for a bit, I found the “SMS_ClientOperation” class, that has a method called “InitiateClientOperation“. Sounds pretty much like what I was looking for.

This method takes 4 arguments:

• Type
• TargetCollectionID
• RandomizationWindow
• TargetResourceIDs

Type defines the Client Operation, that shall be initiated. The different types are listed in the PrimaryActionType property of the SMS_ClientOperation class, however not all of them should be used for the InitiateClientOperation method, as certain types are used by other methods. The ones that are usefull for this method are:

• 1 = Full Scan
• 2 = Quick Scan
• 3 = Download Definition
• 4 = Evaluate Software Update
• 8 = Request Policy Now

RandomizationWindow can be ignored for now. TargetCollectionID is self-speaking and must be supplied. TargetResourceIDs is an optional array of ResourceIDs. If ommited, all members of the collection will be enforced to initiate the specified Client Operation.

Using some PowerShell, we can now easily initiate a Client Operation on the Provider server like

assuming XYZ as site code and 123456 and 234567 as valid ResourceIDs. Just be aware, that the order of the 4 arguments doesn’t fit the order from the documentation! They have to be specified in the following order:

1. RandomizationWindow
2. TargetCollectionID
3. TargetResourceIDs
4. Type

In case you don’t want to mess around with the correct order, we can also make use of the new CIM based powershell cmdlets that are available since version 3 and allow to pass in a hashtable instead of a simple array. This way the argument name can be used and the order doesn’t really matter anymore:

That’s it already!

Nah, not really. This is just the bare basic command to get it done. To become really usefull, one would need to cover additional things like resolving a collection name to the appropriate CollectionID, resolve device names to ResourceIDs, have a describing name for the different types instead of a number, and if possible also be able to cancel or delete any of those operations.

I have already written and published a script that takes those additional steps to make your life easier. It’s available on GitHub at https://github.com/MaikKoster/ConfigMgr called Set-ClientOperation.ps1. In my next blog post I will cover how to properly execute this script.