Creating an Automox Worklet

Created by David Esposito, Modified on Fri, 25 Oct at 1:01 PM by David Esposito

Summary

Automox’s documentation describes Worklets as, “an automation script, written in Bash or PowerShell, designed for seamless execution on endpoints – at scale – within the Automox platform.”

Automox Worklets, like other Automox policies, can be triggered manually for a host or group of hosts via the Automox API. Premade Worklets are available from both the Automox Worklets Catalog or the Community Worklets Library, but we can also easily define custom Worklets to deliver payloads or execute scripts.

In the following example, we will create a manually triggered Worklet that restarts the user’s Google Chrome browser on user interaction with an Amplifier Slack engagement.

Note that the user’s existing Chrome tabs will be reopened when the restart is complete, but unsaved work like web forms may be interrupted. Also note that any other applications reliant on the Chrome framework will also restart.

Creating the Worklet

Worklets are managed alongside other Automox policies. Begin by logging into your Automox instance and selecting the Manage -> Policies item from the dropdown menu at the top of the console.
On the right-hand side of the Policies portal, click the Create Policy button.
On the Create Policy page, choose the macOS option under the Worklet Policy section.
On the Create Worklet screen, name the Worklet Restart Chrome Browser and fill out a brief description. Ensure that the macOS option is selected for the Operating System value.
Use the ASSOCIATE GROUPS button to associate the Worklet with the user groups that you intend to execute against. In this case, we will simply choose the Default group and hit ASSOCIATE.
For this simple Worklet, we can ignore more advanced options like INPUTS and Payload. Instead, scroll down to the SCOPE section, where we will fill in our scripted commands
For this simple Worklet, we can ignore more advanced options like INPUTS and Payload. Instead, scroll down to the SCOPE section, where we will fill in our scripted commands.
For our Evaluation Code, we will simply exit with a non-zero status. We do this to ensure that the Worklet always executes the Remediation Code, which is responsible for the manual restart of the Chrome browser.

Evaluation Code
```
#!/bin/bash
# Exit with a failure code
exit 1
```
Remediation Code
```
#!/bin/bash

# Restart the Google Chrome application
osascript -e 'tell application "Google Chrome" to open location "chrome://restart"'
```
Since we are executing the Worklet manually on-demand, leave all options in the SCHEDULE and USER NOTIFICATIONS sections blank and hit the CREATE POLICY button.
At this point the Automox console will warn you that the Worklet is not scheduled and will need to be executed manually. Accept the warning to continue.
Back at the Policies portal, your new Worklet should be listed.
Click on the Worklet’s name in the list to see its details page. Above the page, in the browser’s URL bar, you will see an Automox URL in the format
https://console.automox.com/manage/policies/<policyId>?o=<organizationId>

Both the policyId and organizationId numbers will be needed to create an Amplifier action that triggers the Worklet execution, so make note of these fields.

Creating an Amplifier Action to Trigger a Worklet

Summary

Now that we have a Worklet that we intend to manually execute, we can set up an Action in the Amplifier application to execute the Worklet as part of an Engagement. To simplify the process Amplifier provides a helper function performs a look up of the devices id so that you can easily trigger policies. We accomplish this by first doing a filtered lookup of devices and then running the policy on each matching device. As long as a finding has an associated device, we can use the serialNumber though Dynamic Variables to run the policy.

Creating the Amplifier Action

From the ENGAGEMENT STUDIO portal, choose the ACTIONS tab and hit the ADD NEW ACTION button on the right side of the page.
On the modal that appears, choose the CUSTOM ACTION / API Call pane.
You will be presented with the CUSTOM ACTION modal. On the first screen, create an Action Name and Description as desired, then hit the NEXT button.
On the following REQUEST CONFIGURATION screen, we will fill out the details that enable Amplifier to call the Automox Worklet on behalf of your organization.

Note: the following instructions assume that you have already created an Automox API token with access to execute API actions. If you do not have an API token, please refer to Automox’s documentation on Managing API Keys.
1. URL - The URL field should be populated with the following Amplifier action URL:
  
  https://actions.amplifiersecurity.io/automox/actions/explode
2. METHOD - The Method field should be set to POST.
3. PAYLOAD - The Payload Format should be set to JSON, and the structured payload itself should resemble the example payload below. To complete this step you will need the policyId and organizationId that you gathered from the Automox policy details screen earlier in this document.
```
{
    "token": "add-your-token-here",
    "actionUrl": "https://console.automox.com/api/policies/set-policyId/action?o=set-orgId",
    "filter": {
        "device_filters": [
            {
                "field": "serial_number",
                "op": "like_any",
                "value": [
                    "{{asset.serialNumber}}"
                ]
            }
        ],
        "server_groups": [
            set-serverGroupId-here
        ]
    }
}
```
  This code tells Amplifier to trigger the policy at the actionUrl for any asset whose serial number matches the asset.serialNumber provided by the upstream Amplifier Security Finding. In this way individual Automox-managed hosts can be acted against arbitrarily.
  
  Hit NEXT to continue, and leave the fields on the following ADVANCED SETTINGS screen empty.
4. Now your new action is visible inside Amplifier ENGAGEMENT STUDIO portal.
5. Your Automox Worklet is now set up to be triggered as part of a user engagement. In the following example, the user is presented with the option to restart their Chrome immediately using the Resolve Now button in their Slack or Teams-based Amplifier engagement.