On this page:

Extending Guaranteed State

In this Lab we will use TIMS to create some fragments to extend the functionality for our rules beyond what is available out of the box in Guaranteed State.

Creating a Product Pack for Guaranteed State

We will now use TIMS to create a simple test fragment for use in Guaranteed State. The fragments that we create and import into Tachyon contain the items that we can use in our rules to evaluate device state and remediate the issues. Fragments must have a specific schema defined. They must have at least one column Passed (case-sensitive) and can have an optional column named Data to display some data from the device. In this scenario, we need to determine if certain files are present on our devices.

Many times, a malware outbreak can be identified by looking for specific files. First, we will create a fragment that will check to see if a file is on the device. We will add a parameter that will allow our rule to supply the name of the file to search for, so that our Rule will test for any files that our Admin chooses. We will then modify the schema of our fragment so that it contains what is required for Guaranteed State to use the fragment. Once we have the fragment written we will import it into Guaranteed State and create a policy that will check our devices and view our results.

  1. Open the SkyTap Shared Drive shortcut from the desktop and navigate to 1E Tachyon - Course Content\Tachyon 5.0 Course Content and download AdditionalProductPacks.zip extract the contents and copy to c:\temp

Creating the Fragment

  1. Logged into 1ETRNW72 as 1ETRN\Manager1
  2. Navigate to \\1etrnap\temp and copy Tims-x86.msi to C:\Tools
  3. Install TIMS on this device using the steps from the first exercise
  4. No need to worry about the Code Signing Certificate our Guaranteed State fragments do not need to be code signed.
  5. Launch TIMS
  6. Open File Explorer and create a text file called MyFile.txt. Putting it in the root of the C: drive is fine. We will use this for testing our fragment as we create it.
  7. In the code block pane type in
  8. @file = FileSystem.FindFileByName(FileName:"myfile.txt", Fast:true);
  9. Click Run
  10. Notice our results. This SCALE command searches the drive for the existence of myfile.txt and dumps the location into a variable called file
  11. Remember that @file is a different variable than @File in SCALE.
  12. In the code block pane type in the following on the line 2
  13. IF (@file)
    This starts our If statement to do something based on the results for our first line that we dumped into our a temp table. This line basically says if @file contains data (so is true) do the next line that we will create now. We could also do the opposite and use IF NOT (@a) which in this case would be true if our variable did not contain any values. Without the NOT our If statement is true if our variable has value.
  14. On line 3 type in the following:
  15. SELECT 0 as Passed, "MyFile.txt exists" as Data;
  16. On line 4 type:
  17. ELSE
  18. On line 5 type in:
  19. SELECT 1 as Passed, "MyFile.txt does not exist" as Data;
  20. On line 6 type:
  21.  ENDIF;
  22. Click Run
  23. Notice our results pane now. In the first query we saw a table with 1 row and 3 columns (details about the file), now we see a table with 1 row and 2 columns only because of what was returned based on our IF statement. Guaranteed State only needs the Passed value to be a 0 for failed (Non Compliant) or a 1 for passed (Compliant). The Data column is optional but allows us to expose some information in our View Details screen. The Data we will return will contain our specific file name using our parameter which we will create after we test our code block.
  24. Notice here that the file existing is a "fail". Our Policy is going to be looking for files that we do not want on our devices. There will be times in which you want the state to exist for compliant and other times that you want the state to not exist. It will depend on the specific item that you are evaluating.

Your code block should look like this 

  1. Open File Explorer and navigate to the location of your MyFile.txt – rename it to myfile.old click Yes on the warning
  2. Back in TIMS and click Run
  3. You should now see that MyFile.txt does not exist in our Data column. Passed should contain 1
  4. Now we will add a parameter that will allow us to substitute any file name for our myfile.txt. This will make our fragment more versatile
  5. Click on Add parameter in the ribbon
  6. In the Instruction Parameter box Name field type in FileName. Notice that the pattern field is populated for us
  7. In the Hint Text field type in Unauthorized File Name
  8. In the Control section Type field, click the drop-down to see the available options
  9. We are using Free Text which requires our Admin to type in something without any help. We could also use a Value Picker and then create a list of values that will populate the drop-down. Using a Value Picker makes it easier and quicker for the Admin, if you know the values that should be selected for this parameter. We could also use custom properties and values that we have added into Tachyon (remember how we set up Coverage tags). We want our Admin to be able to use this one for any file, so we will leave it as Free Text
  10. Click OK to close the box

Your parameter should look like this:

  1. In our code block pane change our myfile.txt to "%FileName%"
  2. Adding the parameter will prompt for the value – if this was a regular instruction it would be filled when you ask the question in Explorer – since this is a fragment the value will be supplied by the rule we create in Guaranteed State. Notice how we call a variable value in SCALE with the % sign at the front and the end of our variable name. This is different from other scripting languages you might be accustomed to where the symbol is only at the front of the variable name.
  3. In lines 3 and 5 change the myfile.txt to %FileName%
  4. The quotation marks should be around the entire data that we are passing, for example "%FileName% exists"
  5. Click Run. In the Parameters box type in MyFile.txt in the FileName field. Click OK
  6. The code should look like this:

    @file = FileSystem.FindFileByName(FileName:"%FileName%", Fast:true);
    IF (@file)
    SELECT 0 AS Passed, "%FileName% exists" AS Data;
    SELECT 1 AS Passed, "%FileName% does not exist" AS Data;
    Notice that our results did not change – now we will test our fragment in some additional ways to be sure it is working as expected
  7. Click Run again and this time enter notepad.exe in the popup. Notice the results
  8. Click Run again this time enter your name .myname – we know this file will not exist
  9. Now we need to format our fragment for use by Guaranteed State
  10. Click the Schema button in the ribbon. Choose Yes to create the schema. Clicking yes here will allow TIMS to create the schema based on what your instruction brings back for the responses. You have the chance to modify this on the next screen
  11. Look at our Schema – see that we are passing 2 columns
  12. In the Data row leave Data Type as String, Change the Length to 1024
  13. The columns are case-sensitive and must be exactly Passed and Data (although Data is optional). Maximum allowed length is 1024 characters but less can be configured depending on your data.

Your schema should look like this:

  1. Click OK to close the Schema window
  2. In the Instruction Definition pane Comments field type in Checks to see if the unauthorized file is on the drive
  3. In the Description field type in Does this machine have an unauthorized file?
  4. Leave InstructionType as Question
  5. Change the Name to 1E-GuaranteedState-General-Check-SpecificFile
  6. In the Readable Payload field type in Check for %FileName%
  7. The readable payload is what will show in the Guaranteed State application selection list, so name them something that will allow you to determine which one you will need to select. Since we have a parameter defined in our instruction or fragment we need to reference it in our readable payload.
  8. Click the Start button and type in \\1ETRNAP\Temp in the Search Bar. Click on the temp folder to launch File Explorer copy AdditionalProductPacks\Product_Pack_Templates folder to C:\Tools
  9. Our Product_Pack_Template folders will be missing the folders for Fragments, InstructionSets, Policies, Rules and TriggerTemplates. Because of the way our code is stored in OneDrive we will need to create these folders. These folders are where you place all those objects prior to import. In this exercise we are only going to import a Fragment that will be used for our check rule. We will then go into Guaranteed State and create our Rule, Policy, and Trigger (reusing ones we have imported previously). Notice we have a custom icon file. We are using the Folder.ico so it appears to be another folder. We will create .xml files and the folders to import those into Guaranteed State to auto-create our objects in later exercises.
  10. Open the AdditionalProductPack\Product_Pack_Templates\Unauthorized File Product Pack folder and create a folder called Fragments
  11. Open the Fragments folder and create a folder called Check
  12. Back in TIMS Click File – Save As – click OK on the Validation window. Navigate to C:\Tools\AdditionalProductPacks\Product_Pack_Templates\Unauthorized File Product Pack\Fragments\Check and save it there as 1E-GuaranteedState-General-Check-SpecificFile.xml
  13. Click Save

Viewing the Contents of an Integrated Product Pack

Before we make our own Integrated Product Pack to import into Guaranteed State, we will look at the format and contents of one of the default Integrated Product Packs.

  1. Still logged into 1ETRNW72 as 1ETRN\Manager1
  2. Navigate to C:\Tools\tachyonplatform.v5.0.0.592\ProductPacks\Integrated and copy NomadClientHealth.zip to the root of C:\Tools
  3. Right click on C:\Tools\NomadClientHealth.zip and select extract all
  4. Navigate to C:\Tools\NomadClientHealth and look at the contents of the folder
  5. The Fragments folder contains a Check, Fix and Precondition folder. Open each one of these and look at the .xml files in each one
  6. Notice the naming convention of each of the .xml files. Each type of object to be imported into Guaranteed State should have a specific naming convention related to the specific object type.
  7. Open each of the folders and look at the contents
  8. Note the InstructionSets folder
  9. Any fragments referring to an embedded resource must have the instruction embedded in the Product Pack. The embedded resource must be available in the Tachyon Background Channel in order to be downloadable. Uploading a fragment does not populate the background channel the way that uploading an instruction set does. We include them in the Product Pack, and the Deployment Tool creates the instruction set. Once this is done, both the fragment and the instruction will be able to retrieve the resource.

Creating the Product Pack

In order to import our Fragment into Tachyon we need to create a Product Pack. The Product Pack contains the objects needed for use by Tachyon and a manifest file. We will then import our Product Pack into Guaranteed State.

  1. Still Logged into 1ETRNW72 as 1ETRN\Manager1
  2. Navigate to C:\Tools\AdditionalProductPacks\Product_Pack_Templates\Unauthorized File Product Pack
  3. Right click on the Manifest.xml and select Edit to open in Notepad++
  4. In the Name section replace Name of Product Pack with Unauthorized File
  5. In the Description section replace Description of Product Pack with Checks for specified file
  6. Notice we have already specified folder.ico in the Icon section
  7. Save the file without changing the name or folder location and close Notepad++
  8. Multi-Select all the files and folders in C:\Tools\AdditionalProductPacks\Product_Pack_Templates\Unauthorized File Product Pack, right click, then choose Send To – Compressed (zipped) Folder
  9. Rename the file to Unauthorized File Product Pack.zip
  10. Make sure your folders are all in the root of the zip file. If the tool does not see the subfolders in the root it will fail to upload.
  11. Copy Unauthorized File Product Pack.zip to C:\Tools\tachyonplatform.v5.0.0.592\ProductPacks\Integrated

Importing into Guaranteed State

Now that we have created our Product Pack, we will import it into Guaranteed State using the Tachyon Product Pack deployment tool.

  1. Still logged into 1ETRNW72 as 1ETRN\Manager1
  2. Double click C:\Tools\tachyonplatform.v5.0.0.592\ProductPacks\Tachyon.ProductPackDeploymentTool.exe
  3. We could also run Tachyon.ProductPackDeploymentTool.exe from a command prompt and add -log TRACE to increase the logging level for troubleshooting. The Tachyon.ProductPackDeploymentTool.log gets created in the same folder as the executable.
  4. In the Server field change the URL to https://tachyon.1etrn.local/Consumer
  5. Click Test Connection
  6. The results pane should show Connected to Tachyon version
  7. Uncheck Select all
  8. Select our Unauthorized File Product Pack and click Upload selected
  9. In this version of the Product Pack Deployment Tool re-uploading a Product Pack will only re-upload any Instruction Sets whose versions have changed. If the version is not higher it will be skipped. Naming conventions for Instruction Sets are important and you should have a unique name for each one. Fragments are not versioned so make sure they are correct prior to uploading since the re-upload is skipped and the Cleanup button deletes everything.
  10. Scroll back in the results and look for "Creating fragment 1E-GuaranteedState-General-Check-SpecificFile"

Creating the Rule

Now that we have our Product Pack imported, we will create our rule that will use that fragment.

  1. Still logged into 1ETRNW72 as 1ETRN\Manager1
  2. Open Google Chrome and Launch Guaranteed State, if it is not already open
  3. Navigate to Administration->Rules. Click New
  4. In the Name field type in Unauthorized File Check
  5. In the Description field type in Checks to see if a specific file is present
  6. In the Type field select Check
  7. In the Triggers box Choose Periodic (minutes) and type in 60 in the Interval Minutes field
  8. In production you do not want to use the time interval trigger, as this processes the rules even if nothing has changed on the device. Instead, you want to use the specific trigger of that item state changing. The Tachyon Agent has built in intelligence so that we do not need to run things to ensure nothing has changed.
  9. Leave Precondition empty
  10. Click on Check. Type in Check for and Choose our Check for <Unauthorized File Name>
  11. In the FileName field type in Myfile.txt and click Save
  12. The title of our fragment for the check field comes from our Readable Payload. If we have a Parameter hint configured (which we did) that will show in the <> to your Guaranteed State Admin. If you do not have a hint configured the letters of your variable will show without the %. In our example, it will appear as Check for <FileName>
  13. Open File Explorer and navigate to your myfile.old and name it back to myfile.txt so that this machine will have the file we are looking for

Creating the Policy

Now that we have created our Rule, we need to create a policy that we will assign and deploy containing the rule we just created.


  1. In Guaranteed State navigate to Administration->Policies
  2. Click New
  3. In the Name field type in Unauthorized File Check
  4. In the Description field type in Checks for Unauthorized Files – if found device is non-compliant
  5. In the All Rules pane select Unauthorized File Check and move it to Assigned Rules
  6. Click Save

Assign and Deploy the Policy

  1. Still logged into 1ETRNW72 as 1ETRN\Manager1 with Google Chrome still open to Guaranteed State
  2. Select Unauthorized File Check Policy and click Assign
  3. Choose All Devices in Management Groups. Click Save
  4. Click Deploy. Click OK

View the Results

  1. Navigate to Overview. Click Refresh
  2. Select Unauthorized File Check in the drop-down. It may take a few moments until they all report in. Wait until you have an orange slice in your Device State tile to continue
  3. Hover over the pie in the Device State tile. Notice that we have 6 devices that are compliant (they do not have the file in question) and 1 device that is non-compliant (it has our bad file)
  4. Click on the olive slice (Compliant) in the Device State tile
  5. Click on View History for one of the devices
  6. Notice the history for our Unauthorized File Check policy
  7. Navigate back to Overview
  8. Click on the orange slice (Non-compliant) in the Device State tile
  9. Click View History on the next page to see the details of our Unauthorized File Check policy

RansomWare Attack

In this task we will create a policy that will contain a check rule for a common ransomware attack. The policy will contain a fix rule that will send an email to our Admin Team and then isolate the device from both the network and the internet, to prevent further infection. The trigger for this policy will be the change of a file to .nem3end as this ransomware encrypts all of the files on all the drives of the device, including mapped drives.

Files that will be used by our fragment

  1. Open the SkyTap Shared Drive shortcut on the desktop and navigate to 1E Tachyon - Course Content\Tachyon 5.0 Course Content and download full.zip extract the contents to c:\temp and copy the full folder to c:\windows on this device and on 1ETRNW71 and 1ETRNW72

Create the Fragments

First, we will create a fragment that will contain our check for the outbreak. We will then create the fragment for our fix. The fix for this issue will be to send an email to Tachyon_AdminG to notify them about the infection. It will then display a message to the user of the device and finally quarantine the device. The device will then only be reachable by the Tachyon server with no access to the internet, so this notification will be important.

  1. Logged into 1ETRNW72 as 1ETRN\Manager1
  2. Launch TIMS
  3. In our code block pane type in the following
  4. @Outbreak = FileSystem.FindFileByName(FileName:"cmtrace.nem3end", Fast:true);
    This module and method will find a file, in our case we are using CMTrace since we know this file is on all of our devices. We also know that this ransomware attack renames almost all of the files on the system to .nem3end. If our CMTrace.exe gets renamed our Fix Rule will take action.
  5. On the second line of the code block type in the following. This will start our loop if the device is infected
  6. //IF (@Outbreak) SELECT 0 as Passed, "CMTrace was renamed to CMTrace.nem3end" as Data;
    Note the double slashes in front of our IF statement. This is how we can add comments to our Instructions. These characters will be ignored by Tachyon and skipped. We have commented out this line of code to allow us to test our code block. We will remove the slashes later to test the code block further.
  7. Under the last line of code type on the following
  8. @Device = Device.GetSummary();
  9. Run just this line of code
  10. Note the results
  11. Add the following on line 4 of the code block
  12. @DeviceName = @Device.Fqdn;
  13. Highlight the last 2 lines of code and select Run
  14. Note the results
  15. This uses native language Device module and GetSummary method to grab the device name and put it into a temp table named @Device
    The second line creates a new temp table (@DeviceName) and pulls only the Fqdn column from our Device.GetSummary results. Remember that @Device is a different table than @device
  16. On the next lines of our code block add the following
  17. ELSE
    SELECT 1 as Passed, "CMTrace was not renamed" as Data;
  18. Complete the Instruction Definition section as follows:
  19. FieldComment
    Comments Malware Outbreak Check Rule
    Description Checks for Malware
    Name 1E-GuaranteedState-Check-RansomwareAttack
    ReadablePayload Malware Check
  20. Remove the // at the beginning of line 2 of the code block
  21. Click Run and observe the results

  22. The code should look like this:

    @Outbreak = FileSystem.FindFileByName(FileName:"cmtrace.nem3end", Fast:true);
    IF (@Outbreak)
        SELECT 0 as Passed, "CMTrace was renamed to CMTrace.nem3end" as Data;
    @Device = Device.GetSummary();
    @DeviceName = @Device.Fqdn;
        SELECT 1 as Passed, "CMTrace was not renamed" as Data;
  23. Click on the Schema button in the ribbon. Click Yes to create a schema. Change the columns names to Passed and leave Data Type as int64. Change column 2 to Data and set type as string with 128 as length. Click OK.
  24. Save the file as C:\Tools\AdditionalProductPacks\Product_Pack_Templates\RansomWare Attack\Fragments\Check\1E-GuaranteedState-Check-RansomwareAttack.xml
  25. Now we will create the fix rule.
  26. Add the following code below the current line 4 (making this line the new line 5 above the ELSE line) 
  27. NativeServices.RunCommand(CommandLine:"c:\\windows\\full\\full\\blat.exe -server 1etrndc.1etrn.local -f Tachyon_AdminG@1etrn.local -to Manager1@1etrn.local -subject \"Ransomware Outbreak\" -body \"A device has suffered a ransomware attack and has been quarantined\"", IgnoreExitCode:true);
    This part of the code will send a message to the Tachyon Admin regarding the infection using blat, a command line mailing utility - https://www.blat.net/. We are executing blat using our NativeServices module with the RunCommand method. Notice our path to the blat.exe file – the extra \ is our escape character. We have to use it again when our command line calls for a " (notice our subject and our body) since we have spaces blat needs us to use " around the string. We have to escape this for Tachyon so we add \". Now we will add our Module and Method to display a message to the user of the device that is about to be quarantined.
  28. Open File Explorer and navigate to C:\Tools and rename CMTrace.exe to CMTrace.nem3end
  29. Click Run to execute the entire code block
  30. Notice the results. Since TIMS shows you the results from the very last operation you are seeing the return code from our blat command line utility. You should have a 0 exit code.
  31. Launch Live Mail and check the Inbox for the notification message (check the Junk folder)
  32. On Line 6 of our code block type in the following (above the ELSE)
  33. NativeServices.RunCommand(CommandLine:"MSG * Your device is infected with ransomware and will be quarantined");
  34. This part of the code will display a message to the user of the infected device. This will be important because the next line will actually quarantine the device
  35. Highlight the line of the code that we just added and select Run
  36. Ensure that the message is displayed properly
  37. In the code block under that last line that you added type in (above the ELSE)
  38. Security.QuarantineDevice();
    The device will only be able to contact the Tachyon server and will have no access to any other devices or the internet. We will not test this part of the code in TIMS as we cannot go into quarantine from the TIMS environment.
  39. In the Definition Pane type in the following:
  40. FieldComment
    CommentsMalware Outbreak Fix Rule
    Description Sends email to admin, notifies the user, then quarantines the device
    Instruction Type Question
    Name 1E-GuaranteedState-Fix-RansomwareAttack
    ReadablePayloadMalware Fix -Quarantine
  41. Click File and Save as C:\Tools\AdditionalProductPacks\Product_Pack_Templates\RansomWare Attack\Fragments\Fix\1E-GuaranteedState-Fix-RansomwareAttack.xml
  42. Rename cmtrace back to CMTrace.exe - very important before you create and deploy the policy or this device will also be quarantined.

Edit the Manifest File

  1. In File Explorer navigate to C:\Tools\AdditionalProductPacks\Product_Pack_Templates\RansomWare Attack and edit the Manifest.xml with Notepad ++
  2. In the Name section change it to RansomWare Attack
  3. Add a description for the Product Pack
  4. Notice our icon file
  5. Save the file

Create the Product Pack

Now that we have our fragments created we will put them into our Product Pack.

  1. In File Explorer navigate to C:\Tools\AdditionalProductPacks\Product_Pack_Templates\Ransomware Attack.
  2. Multi-select all of the files and folders in the RansomWare Attack folder. Right click and choose Send to->Compressed (zipped) folder. Click OKif you get a warning that empty folders could not be added. Tachyon does not care that folder are either missing or empty
  3. Rename the .zip file that you just created to RansomWare.zip
  4. Copy the .zip file you just created to C:\Tools\tachyonplatform.v5.0.0.592\ProductPacks\Integrated

Upload to Guaranteed State

  1. Launch Tachyon.ProductPackDeploymentTool.exe
  2. In the Server name field change .acme.local to .1etrn.local and click on Test Connection
  3. Uncheck Select all and only select our Ransomware Attack Product Pack
  4. Click Upload selected

Create the Rule

  1. In Google Chrome - Still open to Guaranteed State. Navigate to Administration - Rules
  2. Click New
  3. In the Name field type in Malware Outbreak
  4. In the Description field type in a meaningful description
  5. In the Type field choose Fix
  6. Select the Triggers tab and choose When a file changes (Windows only)
  7. In the File Name field type in c:\tools\CMTrace.exe
  8. Select the Check tab and choose Malware Check
  9. Select the Fix tab and choose Malware Fix - Quarantine
  10. Click Save

Create the Policy

  1. Navigate to Administration - Policies. Click New type in Ransomware Attack in the name field and add a description for your policy. Add your Malware Outbreak rule to the policy.

Deploy the Policy

  1. Navigate to the Guaranteed State application
  2. Open Administration->Policies
  3. Select the Ransomware Attack Policy
  4. Click the Assign button
  5. Select the All Devices Management Group
  6. Click Save
  7. Click the Deploy button. Click OK on the Are you sure? box

Set the Stage for the Outbreak

  1. Launch File Explorer and navigate to C:\Tools
  2. Right click on CMTRACE.exe and choose Rename
  3. Rename the file to CMTRACE.nem3end
  4. Click OK on the warning that opens

View the Results of the Policy

  1. Launch Guaranteed State and navigate to Overview
  2. Select Ransomware Attack in the policy dropdown
  3. Once the policy shows as non-compliant you can continue with the exercises. You may need to click refresh a few times
  1. You should see the message to the user regarding the outbreak detection
  1. Launch Live Mail
  2. You should see the email with the notice that an outbreak has been detected
  1. Open a command prompt and try to ping 1ETRNDC
  2. It should fail as the device has been quarantined
  3. Open Google Chrome
  4. Try to access the internet
  5. This should also fail
  6. At this point the device has been quarantined and can only be managed by Tachyon.

Remove the Device from Quarantine

  1. In Tachyon Explorer navigate to the Home node
  2. In the I want to know field type in quar
  3. Select Are my devices quarantined?
  4. Click Ask this question
  5. You should see that 1ETRNW71 is currently quarantined
  6. Click on Actions
  7. In the Follow-up Action box type in quar
  8. Choose Releases selected devices from quarantine
  9. Click Perform this action
  10. You will need to type in the password and then use the code from email to authenticate
  1. Launch the Explorer application
  2. Navigate to the Notifications node
  3. You should see one notification - type in some comments and approve the action
  4. This will release the device from quarantine
  5. Wait a few moments for the quarantine to release
  6. From the Home node of Tachyon Explorer
  7. In the I want to know box type in quar
  8. Select Are my devices quarantined?
  9. Click Ask this question
  10. You should see that no devices are currently quarantined

Lab Summary

In this lab we learned how to write fragments for Guaranteed State and create the .xml files to automatically generate our Rules and Policies. We learned how to put the files together in a product pack and upload it into the Tachyon Platform.

Next Page
Ex 8 - TCN Adv 5.0 - Real World Examples for Guaranteed State