What's a Worklet?

  • 13 December 2021
  • 0 replies

Userlevel 1

What can I use a Worklet for? 

Worklets can automate any scriptable action on Windows, macOS, or Linux, so the possibilities are nearly endless. Worklets can be leveraged to remediate zero days or unpatched vulnerabilities, configure devices, remove unauthorized applications, roll back patches, and much more.


What devices can Worklets run on?

As we mentioned, Worklets can run on Windows, macOS, or Linux provided that they meet the baseline requirements for the Automox Agent to install. If you have older Windows OSes (e.g. Win7 or Server 2008 R2), make sure you have PowerShell 2.0 or later as well as .NET Framework 3.5 or later. 

Worklets run in PowerShell for Windows OS, and in Bash for macOS and Linux devices. If you’re running a Worklet on a 64-bit Windows machine, the PowerShell session still runs in 32-bit. If you need to access 64-bit registries, you’ll need to leverage a ScriptBlock. For more information, visit our support page.

Any device with the agent installed should also have at least 3 GB of free space, this is to ensure that there’s plenty of space for files/patches to download and install.


How does it work?

At the core, Worklets function as a “if, then” statement. The evaluation section tests a condition (e.g. is USB storage disabled) each time the device is scanned, so the evaluation code’s run frequency is based on the scan interval you set in the Group(s) attached to the Worklet. Based on the exit code output, Automox will either flag the device for remediation when the Worklet is next scheduled to run (any non-zero exit code return), or leave the device un-flagged due to successful evaluation (exit code return of 0).

For those of you that are visual learners, let's look at the evaluation code for a Windows USB storage policy Worklet from the catalog.


In the above remediation code (in PowerShell) you can see that if the policy is enabled, the code returns 0, and Automox does not flag the device for remediation the next time the Worklet runs. If the policy is disabled, the code returns 1, and Automox flags the device for remediation, so the Worklet remediation code will run on the flagged devices next time the Worklet is scheduled.

If the evaluation code returns any non-zero result when the devices associated with the Worklet are scanned, Automox flags those devices so that remediation code will run on them when the Worklet is scheduled.

Worklet remediation code is flexible, if you can script it with Bash or PowerShell, you can automate it with a Worklet. In addition to executing remediation scripts against a device, you can attach a file to the Worklet and call it with the script. Just be sure that your file size is 1 GB or less.

Both the evaluation and remediation code run as System in the C:/ProgramData/amagent/ folder for Windows, /Library/Application Support/Automox/ for macOS, and /var/lib/amagent/ for Linux systems.


Where do I start?

If you aren’t sure where to start, or need some inspiration from others, check out the Automox Community Worklet topic, there’s a ton of ideas and questions from Automox staff and users that can get you started. Community Worklets is also a great resource, you can review and adopt Worklets reviewed and approved by our experts at Automox, directly from the console, here’s how: 

First, navigate to the Community Worklets menu within the console.


All Worklets available within the Community Worklets menu have been reviewed and approved by Automox experts. For each Worklet, we’ll set a descriptive name, OS for the Worklet, category, who created the Worklet from Automox, and when it was last updated. 


Before adopting the policy to your organization, review the evaluation and remediation code. Our team includes thorough descriptions within each code block, so you understand what the code is doing, and whether or not you need to customize the code. After you determine the Worklet fits your needs, you can Create a Policy and add Groups to the Worklet to start automating! As with any process that changes settings in production, we strongly recommend running the Worklet (or any policy) against a test device group to ensure the changes are affected on devices as-desired.



What does Manual Worklet Execution do? 

Running a Worklet manually can offer quick remediation. However, it’s important to remember that running a Worklet manually will trigger the remediation script against the applicable devices, regardless of the evaluation code results or overall compliance status of the device. In fact, if you run a Worklet manually, the evaluation code will not even run. 

There are two ways to run a Worklet manually, on a single device via the device details or from the policy menu itself, with the Run Policy action available from the Actions column for the policy. Running the Worklet from the policy menu will run against all attached groups, while running a Worklet from the Device Details will only run the Worklet against that device, regardless of group assignment on the Worklet.


How do I Test a Worklet?

The best way to test Worklets is running them from Automox. If you need to test a PowerShell Script before pasting into a Worklet, use the 32-bit version of PowerShell, this is what Automox will use. It’s best to test your scripts as SYSTEM, since this is the context the Automox Agent runs under. You can test a script in this context by using PSExec. To launch, you can use the following command:


PsExec.exe -s -i %windir%\syswow64\WindowsPowerShell\v1.0\PowerShell_ISE.exe


If you need to test your evaluation script, manually running the Worklet will not work. There are two primary methods to test your evaluation script. If you have the Worklet added to a device group, you can manually scan the device from the Device Details page (see below). The Worklet will display  3DU5ANFuvtm2PZKmMlILsEJfFXVCxJ4jXxElr9EXzeTDVU6Xx7QNr6ScYTaexrm-DB5kfvn2oEpsWNOUFyKii3QYkOohbNiq1-8qLGTazE38ACERgetydwK6JDficjNFPgocqUhc if the evaluation code returns 0 and the device is compliant (and therefore doesn’t require remediation). If the code returns 1 (or any non-zero value), the Worklet will display fo7MHOmij7jgoe3EGy2L1tGbohNb5APVijJqx8wdfYhLv9pdFp6X4Nd_zR7Mm06onu8CrL6MhXQW6matZ9-_8Z7F6LyZ6he7o6s9DlN07_3xZWS65K-OyIYvqOBtd7GVN1AiDMon and the remediation code will run at the next scheduled interval.


Another option to test evaluation code ad-hoc is to put the evaluation code in the remediation code section of the Worklet. This will run the code (your eval code) in the remediation code section when you manually run the Worklet. Write the results to the Activity Log with Write-Output “Text to include in Activity Log” for PowerShell or stdout (or echo)“Text to include in Activity Log” for Bash scripts.


How do I troubleshoot?

The Activity Log tracks all automated and manual remediation actions taken on devices in your organization. This means that you’ll be able to easily review Worklet results and potential errors within the console. Since this log tracks remediation actions only, we won’t track changes to devices, policies, nor reboots.  

To review actions taken by Worklets, simply filter the log to policies with a type of Worklet. You can further refine your search by policy name, to see only actions taken by a specific Worklet. The log can also be filtered by device. This is especially useful if you’re testing Worklets on a certain device, or are trying to determine if a Worklet ran on a device.



How do I disable a Worklet?

If you need to disable a Worklet from running in your organization, the safest way (aside from removing it altogether) is to simply remove all assigned Groups from the Worklet. When no groups are associated with the Worklet (or any policy), the only way it could run against a device is if an administrator manually ran the Worklet from the Device Details for a device.




Worklets are one of the most powerful automation tools at your disposal in Automox. Taking full advantage of Worklets will allow your organization to reach its full automation potential, and eliminate routine tasks and compliance enforcement on any device - macOS, Windows, or Linux.

This topic has been closed for comments