Kolide has flexible customization options that let administrators tailor how Checks operate and provide guidance to end-users.

Customize Check Options

Some Kolide-provided Checks allow you to customize their behavior with a set of bespoke options. If available, these options appear in the Check configuration.

Customizing End-User Fix Instructions

Kolide allows you to customize the text that is shown to the end-user to help them fix an issue on their device. There are two distinct sections you can individually customize: the remediation instructions and the rationale.

When editing a section, you can choose between three options:

• Use Kolide Default Text (default)
• Prepend/Append Custom Text to Kolide’s Defaults
• Compose Custom Text

Markdown & Liquid

All Kolide End-User Fix Instructions can be formatted with markdown and can contain dynamic information using Liquid syntax. As an example, here is a template that uses Liquid to dynamically change the instructions based on the type of web browser.

{% if issue.browser == "chrome" %}
1. Ensure you are logged into the user account `{{issue.profile}}`
2. Open Chrome
3. At the top right, click **More : > More Tools > Extensions**
4. Locate Touch VPN and click  **Remove**
{% elsif issue.browser == "safari" %}
1. Open Safari
2. In the toolbar, choose **Safari > Preferences**
3. Select Touch VPN and click  **Uninstall**
{% elsif issue.browser == "edge" %}
1. Ensure you are logged into the user account `{{issue.profile}}`
2. Open Microsoft Edge
3. To the right of the browser bar, select **Extensions > More actions** next to Touch VPN
4. Select **Remove from Microsoft Edge > Remove** from the main menu
{% elsif issue.browser == "firefox" %}
1. Open Firefox
2. Click the menu button
3. Click **Add-ons and themes > Extensions**
4. Find the Touch VPN extension and click on **..** and select **Remove**
{% else %}
1. Open the web browser
2. Locate the extension manager
3. Find the Touch VPN extension and uninstall it from your browser
{% endif %}
1. Recheck your device to confirm you fixed the problem

Data Simulator

As shown above, when using Liquid, you can alter the instructions Kolide sends to the end-user based on the data from a failing check. To ensure your template functions correctly, utilize the Simulate Notification sidebar to modify the check data used in rendering the preview.

Writing Your Own Checks

Kolide enables you to use the power of osquery to define your own fully custom Checks. To best explain this capability it helps to walk through a complete example.

In this example we will cover a common situation where Apple releases a series of OS updates to quickly mitigate several serious vulnerabilities (in this case CVE-2023-23514 and CVE-2023-23529) in macOS and Safari.

Step 1: Starting the check

To get started, simply click Checks in the top navigation and then click the Add New Checks button in the upper-right. From there, select the Build Your Own tab, and then finally Start With a Blank Template.

Click Create New Draft and then proceed to the next step.

Step 2: Write the Check SQL

The most important part of any Check are the rules to find failing Devices. In Kolide we write these rules using Osquery SQL. The SQL always should emit at least one row that contains a column called KOLIDE_CHECK_STATUS with a value of PASS or FAIL

For this Check, the following SQL does the trick:

WITH
reference_version AS (
  SELECT '13.2.1' AS minimum_version),
version_split AS (
  SELECT version AS current_version,
-- Split minimum_version strings
    CAST(SPLIT(minimum_version, ".", 0)AS int) AS min_ver_major,
    CAST(SPLIT(minimum_version, ".", 1)AS int) AS min_ver_minor,
    CAST(SPLIT(minimum_version, ".", 2)AS int) AS min_ver_patch,
-- Split installed_version strings
    COALESCE(major, 0) AS current_ver_major,
    COALESCE(minor, 0) AS current_ver_minor,
    COALESCE(patch, 0) AS current_ver_patch
   FROM os_version
   LEFT JOIN reference_version
),
failure_logic AS (
  SELECT *,
    CASE
-- Scope to only 13.x devices
      WHEN  current_ver_major = 13
       AND (
-- Check major versions
           (min_ver_major >  current_ver_major)
-- Check minor versions
        OR (
            min_ver_major >= current_ver_major
        AND min_ver_minor >  current_ver_minor)
-- Check patch versions
        OR (
            min_ver_major >= current_ver_major
        AND min_ver_minor >= current_ver_minor
        AND min_ver_patch >  current_ver_patch)
    )
      THEN 'FAIL'
-- Passing Condition: Pass all 12.x versions or < 13.2.1 versions
      WHEN current_ver_major < 13
        OR (
           min_ver_major <= current_ver_major
       AND min_ver_minor <= current_ver_minor
       AND min_ver_patch <=  current_ver_patch
    )
      THEN 'PASS'
      ELSE 'UNKNOWN'
    END AS KOLIDE_CHECK_STATUS
  FROM version_split
)
SELECT * FROM failure_logic;

Paste the SQL into the editor. Once inserted, do a test-run against a few devices and add an example to the sidebar. This will be useful for the last step when we fill out the Privacy Center information.

Once you’ve tested the query and added an example failure to the sidebar, you are ready to proceed to the next tab named Check Details.

Step 3: Write Check Details

The Check Details section lets other admins know what problem this Check detects on Devices. It also allows us to define an issue title that will be display to our end-users on the sign in page.

Here is the info I supplied, if you simply want to copy it over into the form.

• Check Name: macOS CVE-2023-23514
• Issue Title: macOS Urgent Patch Required
• Check Description: This Check verifies the Mac is patched against high severity vulnerability CVE-2023-23514 which impacts macOS Ventura systems.

Once entered in, your screen should look like the screenshot below:

From here, let’s move on to the writing the text our end-users will see when they attempt to remediate the problem. This is done in the Notification Text step.

Step 4: Write End-User Remediation Instructions

This critical step ensures end-users have all the information they need to solve this problem on their own.

On this page there are two important fields to fill out, one being the rationale which explains to users why this important to do. Here is the markdown I wrote:

  Your macOS version needs to be urgently updated to address a serious
  vulnerability that may allow an unauthorized third-party to execute code on
  your system without permission. For more information see
  [Apple's Support Article](https://support.apple.com/en-us/HT213633)

The second are the fix instructions the end-user should follow to fix the issue. In our case, since this vulnerability only impacts macOS 13, we want our instructions to detail how to go through that process using the updated System Settings app.

1. Click the Apple icon in the top left corner of your screen and then select "System Settings" from the drop-down menu.

1. In the left menu pane of the System Settings window, select the menu item labeled "General".

1. Once in the "General" menu, select the submenu labeled "Software Update".

1. Clicking the "Update Now" button will install all missing updates, potentially including major version updates.

1. To install only the missing security update(s), click the "More info" button. This will give you details about each update and you can select specific updates to install. Your device is failing for the following security updates:

1. With the missing update(s) selected, click the "Install" button. If you do not see those updates available, you can use the keyboard shortcut: 'Command + R' to refresh the "Software Update" settings panel. This will force your device to search for additional updates.

1. Clicking the "Update Now" button will install *all* missing updates, potentially including major version updates.

1. To install *only* the missing security update(s), click the "More info" button. This will give you details about the available patches. From this list look for the update that says `macOS Ventura 13.1.2` (or higher).

1. With the missing update(s) selected, click the "Install" button.

**Please Note**: If you do not see those updates available, you can use the keyboard shortcut: `Command + R` to refresh the "Software Update" settings panel. This will force your device
to search for additional updates.

With both of these fields filled out, the tab should look something like the screenshot below.

If that’s looking good, then let’s quickly deal with the Privacy Center tab. This Check does not have any impact on Privacy, so we can simply select the example we generated in the Osquery SQL tab and type in a short-message letting end-users know there isn’t any personal data collected for this Check.

With this last step done, we can now publish the Check.

Step 5: Publishing, Enabling, and Blocking

To finish publishing click the blue button in the upper-right corner that says Review & Publish Check. You’ll see a confirmation screen like the one below:

Clicking Publish Check will complete the process. Next, in the pop-up, you can click Enable Check as shown below:

Once enabled, click the View Check Results link that appears and then the action-menu in the upper-right and finally Configure…. This will bring up the sidebar where you can set the blocking status.

As we said in the intro, this is where you can determine how aggressively you want to mitigate this vulnerability, balancing that around the productivity of end-users. For our own Kolide employees, we thought this vulnerability was serious enough to warrant an immediate block. That said, giving folks an extra day is also a reasonable choice depending on your risk tolerance. If that’s the case, simply click the checkbox where it warns you about blocking devices and decide on a date in the future when you’d like the blocking to start.

Once you have the Check setup, the blocking will look something like this:

And that’s it! The next time your users sign into any app protected by Kolide they will be greeted with the following: