Overview

A Check is a test that Kolide runs on a device on a regular cadence which typically produces a passing or failing result.

Checks are used to achieve many different use-cases, but are primarily designed to ensure a device is meeting an important, policy, security, and security requirements.

When a Check “run” on a device produces a failing result, Kolide generates an Issue so that administrators can track and ultimately resolve it (usually through Kolide’s end-user driven remediation strategies).

Adding, Enabling, and Pausing

By default, when you first establish your account, Kolide automatically enables Checks that help promote universally accepted best-practices for device security.

Adding a New Check

To add a new Check, follow these instructions:

1. Visit the Check Catalog by selecting Checks > Add New Checks

2. Locate a Check you’d like to add and click its corresponding card. If the Check has multiple versions for different platforms, select the Check you’d like to add for the desired platform.

3. In the preview that appears, click Enable. This will add the check and begin running it in “Report Only” mode.

Pausing a Check

Pausing a Check immediately removes it from the device’s query schedule and prevents any results sent by devices from being accepted or processed. In addition, a paused Check will no longer cause a registered device to be blocked.

To pause a Check, simply press the ellipsis menu on the Check’s results card and choose Pause Check.

If you’d like pause multiple Checks at once, you can select their respective checkboxes, which will reveal the mass-action buttons. Then click Pause Selected.

Removing a Check

Unlike pausing, which temporarily suspends a Check and is easily reversed, removing a Check is a destructive action which deletes all associated Check results, issues, and configuration. Once a Check is removed, it is no longer visible in either the Active or Paused tabs and can only be re-added via the Check Catalog.

To remove a Check, press the ellipsis menu on the Check’s results card and choose Remove Check.

Managing Tags

Given the sheer number of Checks available in Kolide, you may find it easier to categorize them using your own custom tags. Tags can be used to denote severity, use-case, or anything else you’d like! Whenever possible, Kolide will display a Check’s associated tags in the Kolide UI.

To add tags to a single Check:

1. Click the ellipsis menu on the Check’s results card to bring down the menu
2. Choose Configure…
3. In the sidebar that slides over, click the gear to the right of Tags section header to reveal the tag selector.
4. Select the tag(s) you would like to add to the Check (click again to deselect).
5. Once you are happy with your selections, simply click outside of the tag menu which will close it and apply your tags.

If you’d like to manage the tags to multiple Checks at once, you can check the checkboxes next to the Checks you’d like to manage and select Tags in the mass-action menu that appears.

You can add more tags to Kolide by clicking the gear/cog icon and selecting Manage Tags, or by navigating directly to Tag Management.

By default, Kolide automatically creates three tags to get you started when you establish a new account, Critical, Important, and Info.

Configuring Device Trust

One of the most effective ways to improve a Check’s success rate across your fleet is to enable the Device Trust capability. Enabling Device Trust prevents any devices that are failing the Check from authenticating to any resources protected by Kolide’s Okta Integration.

By default, a Check’s Device Trust settings will be in Report Only mode as shown below:

Report only mode disables the Device Trust capabilities of the Check, and the Check’s status is not considered when calculating the Device’s overall status.

How to Enable Blocking

To enable blocking on a single Check:

1. Click the ellipsis menu on the Check’s results card to bring down the menu
2. Choose Configure…
3. In the sidebar that slides over, click Configure… underneath the Device Trust section.
4. In the form that appears, check the box preceding the text Block devices that fail this check..
5. When the dropdown is enabled, select an appropriate Grace Period
   • Immediately - When a device fails the Check it will be blocked right away.
   • After Delay - Gives the end-user a configurable number of days before the device is blocked. The user will still receive warnings about this Check each time Kolide authenticates the device.
     Note:

     The delay period starts when the device is registered or when the issue is detected, whichever date is later. This ensures that the full delay is granted to the registered owner, even if they register the device after an issue is detected.
6. Click Save

In some situations, a Check will not be eligible for Device Trust if it is missing end-user remediation instructions. This is typically the case when a Kolide provided Check has no generic “fix” and needs customer-specific instructions supplied by you.

Check Shelf-Life

When you enable blocking on a Check another dropdown will appear asking you to configure when you want to require a live recheck during authentication. This settings controls the Check run’s shelf-life, or, the amount of time Kolide will consider data fresh enough to use for a Device Trust authentication decision.

If the shelf-life of Check result has expired at the time the user is signing in Kolide will require the user to wait for a fresh Check result to come back before proceeding.

Snoozing

By default, end-users are allowed to receive extra time to fix a Check that is blocking their device from authenticating. This is called snoozing. The goal of snoozing is to ensure that, if an end-user has an emergency, they can still sign in temporarily. Here are some facts about snoozing:

• Snoozing extends the time a Check will block a device by an additional 8 hours.

• A Check can only be snoozed at most once a week. This prevents the feature from being abused to avoid fixing issues regularly.

• An end-user snoozes an entire Check at once, not individual issues failing the Check. This ensures that if new blocking issues are generated for that check during the snooze window, they will also be granted extra time.

End-users can access the Snooze feature by clicking on a failing Check and choosing Snooze Blocking… from the Other Options… menu.

The ability to snooze a block can be turned off on a per-check basis. To turn off Snoozing, simply check the option Do Not Permit Users to Snooze a Blocking Check and click Save.

Configuring 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 show to the end-user to help them fix an issue on the device. There are two distinct sections you can individually customize, the remediation instructions and the rationale.

When editing a section you can choose between completely replacing the Kolide provided text or to prepend or append your own custom text around the official Kolide text.

The latter option is recommended so that you can benefit from any future improvements Kolide may make to the instructions. If you fully customize the text you will be responsible for keeping the text up-to-date going forward.

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 type of web-browser.

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

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 their 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: