myITforum.com : SMS Feature Pack Scan Tool

The one piece of the SMS Software Update Services Feature Pack (SUS FP) that is directly interconnected in one way or another to everything is the Scan Tool. In my last article ( http://www.myitforum.com/articles/1/view.asp?id=5281) we broke down the base component, the Sync Tool. Now, we’ll look at what the Scan Tool does, how it functions, and how it interacts with the other facets of the SUS FP. Finally, we’ll go through some troubleshooting steps for common errors and review what you can do to resolve them.

The Scan Tool in my opinion is really the neatest piece of the SUS FP. It also seems to unfortunately be the most commonly overlooked and misunderstood. Even if you decide not to use the patch distribution at your site, there really is no reason not to use the Scan Tool in order to gather a complete inventory of the state of security hotfix distribution in your enterprise. The ability to accurately identify what clients in your enterprise are missing security updates is an invaluable addition to any infrastructure no matter what method you ultimately use for patch deployment. Additionally, with the Scan Tool getting updated information as new hotfixes come out by the Sync Tool automating the security bulletin update process, you won’t need to make any configuration changes after setting up both pieces in your company.

One major mistake that many people make with the Scan Tool is not distributing it to all clients by only auditing a group of clients with common configurations. There are a few reasons why this is not the best choice to make. First, you need to get an accurate accounting of security hotfixes deployed to all workstations in your enterprise. How can you do this if the method you are using to gather your data has not run on every client? It’s essentially the same as only letting some of the 50 states vote in the next presidential election (although that would probably be a good way to get rid of hanging Chad’s). Secondly, the Scan Tool has the ability to accurately gather currently installed hotfixes as well as missing ones. When it has this information it rolls it all up into WMI on the client which we’ll go into a bit later. Why is this good? Say you have a savvy user that’s poking around on their workstation and finds that the security hotfixes that were deployed to them are able to be uninstalled and decide to do so. The Scan Tool will see this next time when it runs on the workstation and will update the local information in WMI with this data as well as send these delta changes back to SMS. Lastly, the Scan Tool must run on the workstation beforehand if you decide to use the Distribute Software Updates Wizard (DSUW) to roll out updates to your client because the patch installation agent (patchinstall.exe) calls the Scan Tool at runtime to evaluate patch status. It’s a good idea to read that last sentence again because I cannot over emphasize this point enough. Many times I’ve seen fellow administrators struggling with deploying updates with the SUS FP recently when it is this simple reason why their distributions are failing.

I also highly recommend testing the Scan Tool on all your platforms before rolling it out to your site. This can be done through the use of the predefined collections that the SUS FP sets up for you, especially with some of the changes that it can make to the system. You can do this by advertising it to the “Security Update Tool (site code) (pre-production)” collection and adding test machines to it. Once you are ready to roll it out, simply change the collection rules for the “Security Update Tool (side code)” collection to contain all of your clients. The best method here is to make this query based and slowly open it up to your site eventually encapsulating all target clients that you wish to scan.

A couple of things before we begin: The Scan Tool is designed to run silently behind the scenes on your clients and gather data. With this in mind, you should turn off site-wide Advertised Program notifications because they can make silent script execution like the Scan Tool a real pain. Here’s a good customization you can make at your site if you need your users to see a countdown: http://myitforum.com/articles/1/view.asp?id=4897. Also, if you’re new to the SUS FP as well and are trying to come to grips with the basics, don’t read this article just yet. Start by reading documentation on the Microsoft SMS homepage ( http://www.microsoft.com/smserver/evaluation/overview/featurepacks/default.asp) and also Mike Mott’s quick start guide “SUS FP, The Missing Documentation”: ( http://myitforum.com/articles/1/view.asp?id=4679).

So now that you know what to do with the Scan Tool, you want to know how it works right? Ok, let me break it down for you:

What it does:
The Scan Tool’s job is to “scan” the workstation for both installed and missing security hot fixes. From this point forward I’ll refer to “missing” as “applicable” since the SUS FP tools do this and it’ll be less confusing if you come to grips with this terminology now rather than later. The Scan Tool is essentially a monitoring instrument with both front end and backend components. The first thing you should know is the Scan Tool wasn’t magically created in some high level language such as C++ or even Visual Basic. The Scan Tool was coded with SMS Installer in the same way that you would create any package at your site. With this in mind, the main components that the Scan Tool uses to gather hot fix data are:

Microsoft Baseline Security Analyzer (MBSA) 1.1
ScanHlpr.dll
hfnetchkconv.exe

These tools are used in conjunction with each other at separate times by the Scan Tool to gather relevant information about the installed and applicable patches, compile the results, and add it all into WMI. Realistically everything that Microsoft does nowadays is in one way or another connected to a class in WMI, but the reason here is because ultimately this information will be rolled up during the next hardware inventory cycle that runs on the client and be sent back to your SMS database to base distributions off of, generate reports from, etc. The class that you should remember that the Scan Tool interacts with is Win32_PatchState so no tinkering with it or the Scan Tool could act incorrectly on your clients! The information that is propagated in this class is not only directly related to how the Scan Tool functions, but also the SUS FP web reports and the Distribute Software Updates Wizard’s functionality. The good thing is that when this is all happening, there is no need for you to do anything to gather this information because the Scan Tool has taken care of all this for you (meaning there is no need modify your SMS_DEF.MOF or create custom MIFs to gather information from Win32_PatchState). Another added bonus here is that the Scan Tool actually does housekeeping for Win32_PatchState and ages out old (or to borrow a term from a friend) “dog food” data that no longer needs to be there and is not actively being refreshed. Once the Scan Tool has logged into WMI that a patch is missing and reported this information back to SMS for you to act upon, why does it need to be there any longer? If old patches were forever left here then this class would grow very large with new security patches coming out at a sometimes daunting rate. An example of this would be if you were using the Feature Pack for both Security and Office updates. How would the Office patch data be removed if you discontinued the use of the Office Scan Tool? The remaining Scan Tool owns the process of aging out items that are inactive. This design assumes that on a regular basis items will be refreshed and items that are not should be removed after this configurable amount of time. Regardless of this though, hardware inventory history of this on your site server will still hold this information even after it has been aged out on the client side. Another reason of aging out this data is that the SUS FP team was looking towards the future. Many patches that are released still hold incorrect names such as “Windows XP GOLD” which obviously isn’t the correct name of the product. As hot fix installer technologies become more organized and streamlined in the future you won’t need to deal with older data that still resides on your clients. The default age that patches are kept in Win32_PatchState is 20 days. This is fully configurable for you to change at your site if hardware inventory doesn’t run at a frequent enough schedule to pick up this data before it is aged out. Simply edit the scan.ini file with any text editor and change the “PatchAge” section to a more desirable timeframe. This file is located in the package source directory. Refresh your distribution points (or wait for the Sync Tool to do this) and the new configuration will be applied the next time the Scan Tool runs on the client.

How it works:
First thing you should know is how to separate the Scan Tool from the Sync Tool. It is true that the Scan Tool and Sync Tool use the same SMS package and source directory, but this is where the similarities end. Broken down, the file differences are:

The Scan Tool is s_scan.exe
The Sync Tool is SyncXML.exe

Another thing you need to know is that the version of the Scan Tool we’ll be breaking down is the latest released by Microsoft on April 11th, 2003 to include version 1.1 of the MBSA. If you weren’t aware of this updated version because you are just learning about the SUS FP or because you’ve just been living under a rock, you can grab it here:

http://www.microsoft.com/SMServer/downloads/20/featurepacks/suspack/default.asp

To verify that you have the latest version as of this article, navigate to the package source directory for the SUS FP, and view the file version for mbsacli.exe. If the file version is 1.1.0.5 then you should be good to go(**UPDATE** After the writing of this article, on Friday 5/9/03 the Scan Tool s_scan.exe executable was update to default to English when running on a system to fix a problem when running on systems with multiple languages installed. The above information still applies, but it's a good idea to grab this latest version if you haven't already). Ok, so a typical scenario is that a client receives the Scan Tool advertisement and executes s_scan.exe. The parameters that it can accept are:

/s – Silent Mode
/kick – Runs a Hardware Inventory cycle after completion
/cache – Attempts to use some files locally rather than from the Distribution Point

The first two are pretty much self explanatory. One thing to note about /kick is that it only sends Delta (changed) information back to your SMS database and only if changes have been made. This helps to cut down on network congestion. The /cache switch is a little more involved though but also helps to alleviate the load on your network. In the context of the Scan Tool, think of the “cache” as a group of files used as utilities for script execution – which we’ll go over in a moment. Specifying /cache in the command line for s_scan.exe will verify that this “cache” on the client is up to date with the copies on the DP and if not, re-copy the files. If you don’t specify /cache in the command line the files will be copied to the client each time the Advertisement runs (NOTE: It is best NOT to specify /cache if you have clients that are still using the FAT file system since the files in the cache cannot be as secure as if they were running on the NTFS file system). When s_scan.exe is first executed, it does some basic checks to see where the Temp directory is located and opens up the logging here in a file called SecurityPatch.log (NOTE: I can’t help but re-emphasize that the TEMP directory can be located in different places on the workstation depending on the account executing the Scan Tool, operating system, etc. The best idea when trying to troubleshoot issues with the Scan Tool is to search the entire drive for SecurityPatch.log). This log is recreated in the target TEMP directory at the beginning of runtime so no need to worry about old data. Next a check is made to see if the client is NT based and exits if it’s not as the Scan Tool won’t run on 9x platforms. Sorry. After that some basic data is gathered such as Service Pack level, Internet Explorer version (minimum is 5.0), and user rights level. This is where we first are introduced to ScanHlpr.dll, a custom library written for the SUS FP to perform a multitude of tasks, one of them being a check to determine Administrative Rights. ScanHlpr.dll is called with a function of IsAdmin, returning a Boolean 1 for true if so. After this, the rest of the data that the Scan Tool needs to run is gathered from Scan.ini and written to SecurityPatch.log. This is where the “PatchAge” data is read for future use. I suggest looking through scan.ini to become familiar with the settings, not necessarily to change anything but to help become more familiar with the tool.

The Scan Tool then tries to determine if it is running from local cache or not. When your command line for s_scan.exe contains /cache and it is running from local cache, checks are first done on the following group of files:

s_scan.exe
scan.ini
ScanHlpr.dll
SecurityPatch.ini

The checks compare the “File Date / Time Modified” information of the files located on the Distribution Point where the package is running and the files locally on the workstation. If they are not up to date on the client, then they will be copied down from the DP to the client even if you have specified /cache, otherwise the files on the client will be left alone. If no command line additions have been made then they will be updated automatically. This can help to cut down on your network congestion if you are advertising the Scan Tool on a regular schedule on a crowded network. The Scan Tool registry keys are then created logging where s_scan.exe and its companion files will be located on the target workstation. All data for the Scan Tool is located under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\VPCache. If you look here you will see a value of “Path” which is where the Scan Tool directory is located (usually something like C:\WINDOWS\System32\VPCache). Underneath this key you will see another key mirroring the name of the package in SMS, such as Security Update Tool (ABC), which contains the rest of the information that was read from scan.ini including the Scan Path folder name under the directory that you found just before in the “Path” key. This is also the SMS package ID. Once the process of updating the registry with this data is complete, ScanHlpr.dll is called upon again. This is where the maintenance of Win32_PatchState is done when the library is called with a function of “RemoveAgedOutPatches” where the patch age that was defined earlier in scan.ini is a parameter. Disk space is next calculated with 10 mb being the minimum needed to run or the Scan Tool will exit out.

In the following steps, the Scan Tool is setting up for later adding new patch information that it will gather to WMI. You might notice on a machine that has run s_scan.exe already a file called HFNetChk.MOF. This will contain the results from the full scan process. If present already at this point HFNetChk.MOF is deleted so that old information will not be used. Along with this, some information for later on in the process is gathered such as creating temporary files in the TEMP directory. These will be used in the process to create HFNetChk.MOF as will be outlined in a bit. The next step is setting up the process of running the MBSA. The Scan Tool makes sure that the workstation is running at least version 3.0 of the Microsoft XML parser by grabbing file version information from MSXML3R.DLL in the System32 directory and if it is lower than 8.20.8730.1 it will actually update the XML parsing engine on the workstation to 3.0. This is very important to note and evaluate during testing and deployment at your site, for if you have a web based application that a client is hosting or something of the sort that is dependent on a particular version of MSXML you will not want to distribute the Scan Tool to it. The process of updating the client is to un-register and rename to *.BAK the following files in the System32 directory:

MSXML3.dll
MSXML3A.dll
MSXML3R.dll

If the Scan Tool has determined that MSXML needs updating, the 3 corresponding files from above (but ending in .tmp rather than .dll) are copied down to the client from the DP, renamed to *.DLL, and registered. It’s important to note this process incase the update causes problems for you on a system and you need to roll back. The process isn’t too difficult because the Scan Tool backs up the files rather than deleting them.

After this update to MSXML ScanHlpr.dll is once again asked to give some assistance, this time it’s to get the system language though. The function name is GetSystemLangID and if it fails s_scan.exe defaults to 1033 or English. This is needed because mssecure.cab is copied to the “ScanPath” directory that was identified earlier when referencing the registry, in a folder named after the system language (ex: English might be C:\WINDOWS\system32\VPCache\ASC00071\1033). Now if the Scan Tool is running with /cache specified, the properties for this feature kick in once more. The same process as outlined before of gathering “Date / Time Modified” information of files in the local scan directory and on the DP are done but this time it is for the following files:

Mssecure.cab
Mbsacli.exe
Hfnetchkconv.exe
Products.xml

These are the files needed to do the scanning process to gather installed and applicable hot fix information, as well as convert the data into a format compatible to be entered into WMI. The reason this comparison is done now against the local cache rather than before is because now the Scan Tool has all the information it needs and can continue to run. This also helps cut down on network congestion because if it had failed earlier than it wouldn’t need to update any files unnecessarily.

Now that the Scan Tool is ready to evaluate the machine, it needs to get the database of patches to reference – mssecure.xml. It does this by calling expand.exe in the System32 directory to pull mssecure.xml out of mssecure.cab into the “nshc” directory located in the local scan directory. Here is where the MBSA (mbsacli.exe) does its work. The same basic call is done with mbsacli.exe, but once to gather the installed patches and once to gather the applicable patches. The only difference is the use of “–h 1” in the command line when listing installed patches on the workstation. So examples calls to find installed and applicable hot fixes in the same method that the Scan Tool does would be as follows:

Installed:
C:\WINDOWS\system32\VPCache\ABC00071\nshc\mbsacli.exe -hf -s 2 -nosum -x C:\WINDOWS\system32\VPCache\ABC00071\nshc\mssecure.xml -history 1 -v -o wrap > C:\WINDOWS\system32\VPCache\ABC00071\GLF1072.tmp

Missing:
C:\WINDOWS\system32\VPCache\ABC00071\nshc\mbsacli.exe -hf -s 2 -nosum -x C:\WINDOWS\system32\VPCache\ABC00071\nshc\mssecure.xml -v -o wrap > C:\WINDOWS\system32\VPCache\ABC00071\GLF1074.tmp

In between these calls, the resulting output files, such as GLF1074.tmp above, are converted to MOF format by hfnetchkconv.exe into Missing.MOF and Installed.MOF. These files contain the results from when the MBSA ran and gathered both applicable and installed hot fix information by parsing through mssecure.xml and evaluating what is installed and what is applicable on the client. Now you can see why it is so important that the Sync Tool is running correctly at your site. As I said in my previous article, the Sync Tool is the foundation for everything.

So now what? Well its time to add this information to Win32_PatchState so that the data can be rolled up into SMS. Missing.MOF and Installed.MOF are converted into HFNetChk.MOF which is why the Scan Tool deleted this earlier so that false data would not be reported. With HFNetChk.MOF now containing both applicable and installed patch information, it’s time to add them to WMI. No need to mess with mofcomp here!!! ScanHlpr.dll is called with a function of “SetPatchStates” and uses HFNetChk.MOF as a parameter to update Win32_PatchState. Two other key files that are used here that many people have asked about are SMSReport.MOF and SWUDefine.MOF. These two MOF files are also used as parameters to define the format and what information in HFNetChk.MOF will be entered into WMI on the client. This saves you the trouble of needing to alter your SMS_DEF.MOF to gather the patch data because it is already done here for you. Then if you had specified /kick in your s_scan.exe command line, ScanHlpr.dll is called for a final time with a function of “StartHardwareInventory” to begin an SMS Hardware Inventory cycle on the client.

Troubleshooting:
As with the Sync Tool, the best place to start is by reviewing the FAQ that Microsoft has put together on the SUS FP: http://www.microsoft.com/smserver/support/susfaq.asp

SMS Status Messages: The same as the Sync Tool, the Scan Tool is a normal advertised package to your clients. Any success or failure messages will be reported back through advertisement status messages. The majority of failure messages will be pretty much self explanatory and are outlined below. A successful exit code is “0” with the message of “Security software updates scan completed successfully”.

One common status message is “The program for advertisement "00123489" failed ("Security Update Tool (ABC)" - "Security Update Tool (ABC) (expedited)"). The failure description was "XML database (mssecure.xml) not found." If you are seeing this issue in your SMS Status Messages for the Scan Tool advertisement, check to make sure that your DP’s are updating correctly. This can indicate a failure of mssecure.cab not replicating properly.

Another problem seen at times is that the Scan Tool is running properly on Windows NT 4.0 and 2000 workstations but not at all on XP platforms. If this is the case you will need to upgrade your site to Service Pack 4 so that XP will be listed as a target platform: http://support.microsoft.com/default.aspx?scid=kb;EN-US;308271.

SecurityPatch.Log: This file will be located in the TEMP directory on the client. The TEMP directory can be located in either the system Temp directory such as C:\Temp or inside of the user profile that the Scan Tool ran under the context of such as C:\Documents and Settings\SMSCliToknAcct&\Local Settings\Temp so make sure to search the entire drive. It’s an environment variable so you can see this information actively by typing “SET TEMP” from a command prompt to see the TEMP path.

This log is usually quite large as all the data that the Scan Tool uses is gathered such as the hot fix information that the MBSA gathers. A successful log will usually start like this:

Initialized log file.
User Account: SMSCliSvcAcct&
User Profile: C:\Documents and Settings\SMSCliToknAcct&
Inside IsAdmin() $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>
Determining Admin rights $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>
Successfully determined that user has Admin rights $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>
IsAdmin() return with return value -- 1 $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>
Scan Agent = Security Update Tool (ABC)
Patch Type = Security
PatchAge = 20
Package Name = Security Update Tool (ABC)
Package ID = ABC00071
Program1 = Security Update Tool (ABC)
Command1 = s_scan.exe /s /cache
Program2 = Security Update Tool (ABC) (expedited)
Command2 = s_scan.exe /s /cache /kick
Source Directory = \\smsserver\dp$\SMSPKG\ABC00071
Cache Directory = C:\WINDOWS\system32\VPCache\ABC00071
Not running from cache - Copy of the necessary files will be attempted
The cached copy or tools and data will be attempted if current.
VPCACHE registry key not found, trying to create this key
Calling scan helper function to remove aged out patch inventory
Inside RemoveAgedOutPatches $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>
Getting List of Patches from WMI $$<Software Update Scan> <Mon Apr 21 11:49:13 2003>

Then it will have A LOT of information about the patch status, installed and applicable as well as the MOF format. If everything is successful the following will be at the end:

Total new Software Updates for given Inventory Agent and Patch Type 14 $$<Software Update Scan> <Mon Apr 21 11:49:21 2003>
Removing instances from the Original class, not found in new scan $$<Software Update Scan> <Mon Apr 21 11:49:21 2003>
Adding new instances scanned during current scan $$<Software Update Scan> <Mon Apr 21 11:49:21 2003>
Updating WMI ... $$<Software Update Scan> <Mon Apr 21 11:49:21 2003>
Update to WMI successful $$<Software Update Scan> <Mon Apr 21 11:49:21 2003>
Done.

Common Errors:
“Current OS is not NT-based, exiting.” The client must be NT 4.0 Service Pack 5 or higher for the Scan Tool to run.

“You need to have Internet Explorer Version 5 or later, to run Scan tool. Updates scan will not be done; exiting.” Solution to this error is upgrading the Internet Explorer version. The Scan Tool is reading the version data from HKLM\Software\Microsoft\Internet Explorer for troubleshooting if this does not resolve the Scan Tool error for you.

“Unable to load ScanHlpr.dll.” As outlined in the Scan Tool process flow, ScanHlpr.dll is utilized several times to perform different tasks. Depending on where in the log file this failure occurs will help you troubleshoot why this is happening. 90% of the time, this is caused by network congestion and re-running the advertisement on the machine results in s_scan.exe running successfully without any changes on your part. Usually if you are seeing this error, the Scan Tool won’t even get past the Administrative Rights check because it’s failing when calling ScanHlpr.dll to determine this. A typical log entry would look like:

Initialized log file.
User Account: SMSCliSvcAcct&
User Profile: C:\Documents and Settings\SMSCliToknAcct&

Some other things to check when seeing this error:

See if this is only happening on a particular DP to narrow down the problem
This can also be caused on incorrect permissions being set on the installation directory where the account calling s_scan.exe does not have rights. In this case you should review the file permissions on both the DP it is executing from and client scan path directory.
Network connectivity for a client or subnet. Make sure full IP and NetBIOS communication from the client(s) in question is working correctly and that a UNC mapping to the DP can be reached.
See if a client is holding onto the file and kill the connection if it is. You can view this in Computer Management->Shared Folders->Open Files.

“C:\WINDOWS\system32\VPCache\ABC00071\nshc\mssecure.xml does not exist. Cannot continue without XML database. This is a terminal error.” This error is basically a result of mssecure.xml not being extracted correctly from mssecure.cab by expand.exe. If you are seeing this, check:

The location of expand.exe on the client. Make sure that it falls within the PATH environment variable on the system inside of System32 since that is where s_scan.exe is calling it from. To verify, type “SET PATH” from a command prompt.
File level permissions to the scan path directory. Administrators should have full control
Verify that you can run expand.exe successfully from a command prompt on the client having problems

“HFNetChk.MOF not found. Some problem with scan tool or scan database. This is a terminal error.” Similarly to the error with mssecure.xml above, your environment variables may not be correct. Make sure that the command processor, cmd.exe, is functioning correctly. Verify that the copy command is working properly on the client since HFNetChk.mof is created with a command similar to:

cmd.exe /c copy /B Missing.MOF + Installed.MOF HFNetChk.MOF

You may also notice an inconsistency at times between what the Scan Tool reports and Windows Update. This is because the two catalogs are roughly 7 days out of sync with Windows Update being ahead. This is a known issue which is being worked on by the Microsoft SUS FP Team.

Most of the problems that exist with the Scan Tool revolve around limitations with the MBSA that are being worked on. As you can see from the flow that was outlined above, much thought and development time have gone into the design of the Scan Tool and should provide as a valuable resource for any SMS site even if the distribution pieces of the SUS FP aren’t utilized. As always, feel free to contact me anytime with any comments or problems that you may be experiencing that this article does not address at richardt@qualcomm.com.

Special thanks goes out to Rob Wickham of Microsoft for serving as a technical reviewer and contributor on this article.


		myITforum.com ©2010 \| Legal \| Privacy