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 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.

Measuring Compliance

When viewing your actively running Checks, they will be listed by their percentage of compliance (from least compliant to most compliant).

The color of the percentage is determined by the following rules:

• Perfect Compliance - Filled Green Circle
• > 80% Compliant - Green Circle
• > 50% Compliant - Yellow Circle
• > 1% Compliant - Red Circle
• Completely Non-Compliant - Filled Red Circle

Each Check’s passing percentage is calculated using the following formula:

• $T$ - Total number of Devices targeted by the Check
• $F$ - Number of failing targets
• $P$ - Number of passing targets, calculated as $\max(T - F, 0)$

$\text{Passing Percentage} = \left\lfloor \left( \frac{P}{T} \right) \times 100 \right\rfloor$

Viewing an Individual Check’s Compliance

From the compliance dashboard, once you click on a Check, you will get a detailed view of the status of each targeted device in the Check Result tab.

A Device is capable of being in one of the following statuses for each Check:

• (Pending) - The device has not yet run the Check for the first time.
• PASS - The device is passing the Check.
• FAIL - The device is failing the Check.
• UNKNOWN - The device is currently in a state where the passing/failing status of the Check cannot be determined (e.g., the system is online but locked, and the agent is unable to collect the needed information).
• N/A - What the Check is meant to verify does not apply to the current Device (e.g., looking for a security setting for an Intel-based CPU on one that is ARM-based).
• ERROR - The Kolide agent encountered an error when running this Check.
• STALE - The status is no longer relevant because the Check’s options have changed since the device last ran it.

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.

Controlling Targets

By default, Checks will automatically target all devices that match each of its compatible platforms. You can customize targeting by platform, or groups (requires Kolide Max).

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 Targets section
4. In the form that appears, check the box preceding the text Run on only a subset of devices…
5. After checking the box, choose the platforms, Okta Groups, or Device Groups you’d like the Check to either explicitly target (or avoid targeting if they are selected in the “Unless It Is Also In The Following Groups” section).
6. Click Save. Once complete you’ll see an updated summary that describes which devices are targeted by the Check.

Remediation Strategies

One of the most effective ways to improve a Check’s success rate across your fleet is to select a remediation strategy.

Kolide offers four distinct strategies:

• Do Nothing (the default)
• Notify Only
• Warn then Block
• Block Immediately

Each strategy is discussed in detail below.

Do Nothing

The “Do Nothing” strategy, also known as “Report Only,” is the default strategy for all Checks in Kolide.

When this strategy is chosen, the Check still runs on devices, but the end-user has no knowledge of their passing or failing state. The end-user will never receive notifications or have their authentication interrupted, regardless of the Check’s status.

Notify Only

The “Notify Only” strategy offers end-users a gentle introduction to Kolide’s ability to interrupt the authentication flow and to produce notifications via the Kolide Menu Bar App without the consequences of blocking.

While the “Notify Only” strategy will increase the compliance percentage of a Check by promoting user awareness, it is likely to have reduced efficacy in comparison to a blocking strategy, due to the lack of consequences for ignoring the notifications.

Deferring Notifications

By default, “Notify Only” will immediately send an end-user a notification as soon as Kolide determines that the device is failing the Check. In some cases, you may wish to delay when this initial notification is sent. For example, when it’s likely that a large percentage of failing devices will resolve a problem on their own without the extra end-user notification (such as an out of date operating system which prompts users to perform an update).

To defer notifications, click the dropdown and select After a delay of and choose the desired number of days.

It’s important to note that when a Check fails, it will still produce an issue, but an end-user will have no knowledge of the Check failure until the deferment window has elapsed.

Warn then Block

“Warn then Block” is the recommended remediation strategy for Checks that you wish to achieve a high degree of compliance, while also giving users adequate time to resolve problems on their own before they are blocked.

Warn / Block Timing

When using the “Warn then Block” remediation strategy, a user will first be warned for a failing Check, and then subsequently blocked if that Check failure has not been resolved within the specified time period.

You can control the precise timing of both the Warning and Blocking phases. Delay intervals can be configured for each, allowing you to fine-tune how long a user will be warned for, and when blocking will begin. This allows you to create blocking schedules such as:

• When a Check fails, start warning user immediately, and block after 4 days.
• When a Check fails, start warning users after 5 days, and block after 8 days.

Delaying when the initial warning is sent can be desirable in situations when it’s likely that a large percentage of failing devices will resolve a problem on their own without explicit end-user intervention.

Block Immediately

“Block Immediately” is the most extreme remediation strategy and should only be used in situations that require an immediate response by end-users. Unlike “Warn then Block,” end-users will receive no prior warning of an issue before they are unable to access any applications protected by Kolide Device Trust.

Using “Do Not Block Until…”

When using either the Block Immediately or the Warn then Block strategies, there are situations where, based on your settings, some devices may become immediately blocked. The Warn Only (Do Not Block) Until setting allows you to set a specific date that blocking is allowed to start, even if the device should have been blocked based on the other aspects of the Remediation Strategy configuration.

This is a great way to ensure users don’t have a negative experience or feel needlessly punished the first time blocking is enabled for a check that’s been running on devices.

Previewing Strategy Changes

As you make changes to the remediation strategy, a popup box will appear to the left of the sidebar to summarize how the remediation options will impact the current population of registered devices.

This popup is organized into four columns:

1. Remediation Stage - Which can be one of the four stages:

   • Pre-Warn/Pre-Notify - The device is failing the check, but the end-user has not been notified/warned about it as they are still within the grace period.
   • Warn/Notify - The device is actively failing the check, and the end-user is being actively notified/warned about it via the Menu Bar app or as they authenticate to a Kolide-protected app.
   • Blocks < 24h - Equivalent to Warn/Notify except the device will transition to a blocked state within 24 hours.
   • Blocked - The device is currently blocked from authenticating to apps protected by Kolide.

2. Current - The outcome of the pre-existing remediation strategy on registered devices across the remediation stages.

3. Proposed - The outcome of the proposed remediation strategy on registered devices across the remediation stages.

4. Net - The difference between Current and Proposed.

In addition to viewing the counts, you can also click any count within the Current and Proposed columns to see a listing of devices that the count represents.

Advanced Settings

Limit Blocking to a Subset of Devices

Similarly to Check Targeting, you can control which Devices the Device Trust Settings apply to. You can the scope of blocking by platform, or by groups (requires Kolide Max).

To get started, check the box Limit blocking to a subset of devices.

After checking the box, choose the platforms, Okta Groups, or Device Groups you’d like the Check to be in-scope for blocking target (or out of scope for blocking if they are selected in the “Unless It Is Also In The Following Groups” section).

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.

Global Settings

Kolide Administrators with “Full Access” can also control end-user remediation strategy behaviors (e.g., controlling how often an end-user has their authentication interrupted by the same failing Check) in End-User Remediation Settings

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