Interpreting the Table

The part relevant to your scripted detection rule is the second column header: Data read from STDOUT.

STDOUT, or Standard Out, is a stream to which a program outputs its data. The way your detection script is going to use it is to output data to the screen by using a native PowerShell cmdlet.

Figure 4-2 (a cropped version of the table shown in Figure 4-1) shows it is the third row you are interested in: to signify a successful installation your script will need to write to the STDOUT data stream. In other words, if the data read from STDOUT is not empty (in other words, it has been written to), then the application detection state will be installed.

A screenshot of a table has 5 columns and 4 rows. Column headers are script exit code, data from S T D O U T, S T D E R R, result, and application detection. The third entry is highlighted.

File/Folder Presence

One of the simpler detection methods is to verify the existence of a file or folder.

(You can add or leave trailing backslashes when setting the path variable as Join-Path sorts this out for you.) Listing 4-3 detects the presence of the text file: All Servers.txt stored in C:ohtemp.

Testing for folder existence is achieved using the same method, specifying a folder name instead of a file name for the $fileOrFolderName variable.

Executable Presence

Executable detection is identical code to file or folder detection, the only difference being the variable named $fileOrFolderName has been renamed to $Executable for clarity; particularly important if other people may eventually use your scripts.

In Listing 4-5, the code detects the presence of the Java executable, java.exe, found in the path C:ProgramFiles(x86)javajre1.8.0_333in

Executable Version

While the previous example of detecting the presence of a specific executable can be useful, often it is more helpful to detect the version number of the executable.

Continuing to use java.exe as the example executable, let us now make sure it is also the expected version number.

In this instance, the version number of the .exe is 80.3330.2 as shown by right-clicking the java.exe file and looking at the Details tab on the properties page. (See Figure 4-6)

A screenshot of a window titled the java dot e x e properties. It lists the details descriptions in a table. The product version 8.0.3330.2 is highlighted.

Finding the Build Number

Sometimes you will want the complete build number to use in the detection rule. For example, the Firefox.exe properties page presents the following information:

• File version: 103.0.2.8255

• Product version: 103.0.2

Figure 4-7 shows the properties page of Firefox exe where you can view this information.

A snapshot of the firefox dot e x e properties. It lists the details descriptions in a table. The product version 103.0.2 is highlighted.

If you use Get-Item to retrieve either the file version or product version of Firefox.exe, the only value returned is 103.0.2. (See Figure 4-8)

A screenshot of the administrator windows powershell. The file version 103.0.2 for firefox dot e x e is returned.

If your detection rule requires confirming the full file version number of 103.0.2.8255, then you will need to use the rudely named property, FilePrivatePart to retrieve the build number separately from the file version number. (See Figure 4-9)

(Get-Item "C:Program FilesMozilla ↩ Firefoxfirefox.exe").VersionInfo.FilePrivatePart

A snapshot of the administrator windows powershell. The file name file private part is used to retrieve the build number.

The resulting detection rule tests for both parts, the file version number and the build number, and expects both to be present to signify a successful installation. It does this by using -and to evaluate two conditions: one for the file version and one for the build number, and both conditions need to be true.

In English, it would read as, “If the file version equals 103.0.2 and the build number equals 8255 then write to STDOUT to signify a successful application detection.”

Listing 4-7 shows the resulting detection rule.

$versionNumber = '103.0.2'

$buildNumber = '8255'

$executable = "firefox.exe"

$path = "$Env:ProgramFilesMozilla Firefox"

If ((Get-item (Join-Path -Path $path -ChildPath $executable) -ErrorAction ↩ SilentlyContinue).VersionInfo.FileVersion -eq $versionNumber -and (Get-item ↩

(Join-Path -Path $path -ChildPath $executable) -ErrorAction ↩ SilentlyContinue).VersionInfo.FilePrivatePart -eq $buildNumber) {

    Write-Host "Detected!"

}

Listing 4-7

The detection rule checks for both the file version and the build number

Registry Subkey

It is rare to only wish to detect the presence of a registry subkey. For accuracy, you would want to detect a specific value/data pair.

Should you need to though, the detection rule would resemble this. (By now I’m sure I don’t need to tell you to adjust the variable $RegistrySubKey in the code to meet your needs.)

Figure 4-10 shows the Google Chrome registry subkey the detection rule in Listing 4-8 is testing for.

A screenshot of the Google chrome registry editor subkey. It lists 14 files and the chrome file is selected.

Registry Value/Data Pair

Now, this is more like it. Often, when you are using the registry for detection rules, you will be trying to detect a specific value and its corresponding data to signify a successful deployment.

For this example, if you have deployed the application Git for Windows you may decide to use the registry as the detection rule.

You want to be certain that version 2.32.0.2 has been deployed and decide to detect its registry value CurrentVersion and its corresponding data. (See Figure 4-11)

A screenshot of the registry editor. The git for windows file opens to a table with 3 columns and 4 rows. The current version entry is highlighted.

Custom File Detection

You may prefer to create a file to detect as part of the application deployment. Then, once the application has been installed the detection rule looks for the presence of the file just created, which, in turn, signifies a successful application detection.

One advantage of this method over detecting a default file or folder shown previously is that you can rename the created file on each updated deployment of the same application. For example, the first deployment of app1.exe creates an empty text file named App1-001.txt. If App1.exe is then updated and needs to redeploy, this time around the deployment creates and detects App1-002.txt.

As alluded to earlier, the text file is created in the same PowerShell script that deploys the application, and you should do this in the pre- or post-application install phase. It does not matter if you create the file before or after the application is installed because (and let’s face the ugly truth here), if you are using this method of application detection then you are either unable to detect the application through conventional means, or, and I hope this is not the case, you just don’t care.

When using this bad practice of detection, a good practice to follow is to create the custom files in a specific folder at a specific location, and out of reach of standard users.

You should write to the Windows directory, in a subdirectory named after the company you work for, followed by a directory called: Custom Detection. This fulfills two tasks: users are unable to delete its contents, (it is assumed that users log in with standard user permissions – if not you should ask yourself, “Why?”), and the directory then becomes the central storage area for any future projects you may end up working on where you need a repository for custom output or storage.

Here is an imaginary scenario to hammer home this concept.

Scenario: Yum-Yum Dog Foods Inc

Your manager approaches you with the following task: a new application, MyApp.exe, needs to be deployed to all staff.

You install the application on your test system and work out the installation command line.

You discover that once installed, there is no easy method of detecting the installation; having scoured the registry and file system you cannot find anything relevant to use as a detection rule.

You decide to use custom file detection and will create a file called: MyApp-001.log as part of the application deployment script and this can then be used in the detection rule you will write. You also add code to create the directory structure if it’s not present; if the structure is already present it will just create the file to detect.

To use this code, replace the values for the variables: $companyName and $fileName where Yum Yum Dog Foods Inc is the name of the company you work for and MyApp-001.log is the name of the file to be created.

Listing 4-13 shows the PowerShell code used in the application deployment script to create the custom file.

$companyName = 'Yum Yum Dog Foods Inc'

$fileName = 'MyApp-001.log'

$detectionPath = Join-Path -Path "$env:SystemRoot" ↩

-ChildPath "$CompanyNameCustom Detection"

if (!(Test-Path $DetectionPath)) {

      New-Item -Path $DetectionPath -ItemType Directory | ↩

Out-Null

}

New-Item -Path $DetectionPath -Name $FileName -ItemType ↩

File -Force | Out-Null

Listing 4-13

PowerShell code for writing a custom file to be used by the detection script

Figure 4-12 shows the resulting file, MyApp-001.log, ready for detection. The file structure Yum Yum Dog Foods IncCustom Detection is created if it did not already exist, otherwise, just the file MyApp-001.log is created.

A snapshot of the custom detection file. The myapp-001 dot log file is located in this P C, O S disk, windows, Yum yum dog foods section.

You decide to use the code shown in Listing 4-14 to use as the detection rule.

$fileOrFolderName = "MyApp-001.log"

$path = "$env:SystemRootYum Yum Dog Foods Inc ↩

Custom Detection"

If (Test-Path (Join-Path -Path $path -ChildPath ↩ $fileOrFolderName)) {

    Write-Host "Detected!"

}

Listing 4-14

The detection rule used for MyApp-001.log

Custom Registry Detection

You may prefer to write to the registry instead of the file system for your custom detection and, much like creating custom files, and for the same reasons, it’s best to write to the registry in an organized structure; this keeps everything neat.

Once again, the PowerShell code in Listing 4-15 will first check to see if this location exists in the registry already, and if not, create it before finally writing the value and data to be used for detection.

Figure 4-13 shows the resulting registry value and data pair ready for the custom detection rule.

A screenshot of the registry editor. The location of the custom detection section and myapp entry on the right is highlighted.

Final Thoughts on Custom Detection

Don’t use it! Joking aside, there may come a time when this is the only method available to you and it is good to have this knowledge in your toolbelt, just in case.

Remember though, creating items for custom rules to detect is not good practice and won’t verify the deployed application is installed. They should only be used as a last resort. They do, however, get you out of a bind in times of need.

By Office Bitness

In this example detection rule, querying the installed Microsoft Office “bitness” will cause code execution to branch to the correct detection rule to use, based on if the query result is either 32-bit or 64-bit.

In English, the code reads something like this: “If the installed Office version is x86 (32-bit) then use this detection rule. If the Office version is x64 (64-bit) then use this other detection rule.”