New API Actions: Assign Device / Issue Live Query

Happy Holidays everyone! Before taking our holiday break, we wanted to announce an exciting set of changes that we just shipped to Kolide's API!

Previously, Kolide's API was read-only and could not make any changes to your Kolide account or the data contained within. Starting today, we are announcing an overhauled API system and two new endpoints that allow you to issue live queries and assign owners to devices programmatically.

New API Key Management Experience

Create Multiple Keys

We have overhauled the API Key management experience to support these new endpoints. Previously, Kolide only allowed you to create a single key for your entire account. Now you can create as many keys as you'd like! 

New Token Format

When you generate a new key (or rotate the token of an existing key), you may notice the secret token has a bit more structure to it.  Ex: k2sk_v1_A2UYhW7OPt2jKKLqmFcaGNK7

This new format conveys information about the key's format and version. Accordingly, tools like semgrep can now detect and alert developers of any clear-text Kolide credentials in their code before they are accidentally committed to an externally accessible repository!  You can read more about the key format in our API docs.

Additional Security & Usage Information

With this new multi-key system, we also took the time to improve the security and auditing of the API Keys.

Kolide now audit logs every time an administrator reveals the secret token of the key. Additionally, we'll track when keys were last used, helping you identify keys that can be safely removed from the system. Finally, each key now has an assigned primary contact responsible for that key's ongoing security and permission management.

Upgraded API Docs

Previously, Kolide was using an older version of Readme.io's automatic API documentation. We've since upgraded it to the latest version and retooled how we generate our openapi.json file to better integrate with this server. 


Granular Permissions

When you create or edit keys, you can now imbue them with granular write permissions the enable them to access these new endpoints. 

In our permissions model, we ask the person imbuing those permissions to explain what the external program will use the permission to accomplish. This will enable Kolide to communicate this information to end-users and other administrators in the audit log or the privacy center.

Starting now and in the future, all new permissions we add will be opt-in; keys will never be granted new permissions automatically.

Programmatically Assign a Device

One of the two new endpoints we are rolling out is assigning a device in Kolide programmatically. Here is an example of how you can accomplish that.

export APIKEY=<your_api_key>
export PERSON_ID=<the ID of the person you want to assign>
export DEVICE_ID=<the ID of the device>

curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer $APIKEY" -d "{ \"owner_type\": \"person\", \"owner_id\": \"${PERSON_ID}\" }" "https://k2.kolide.com/api/v0/devices/${DEVICE_ID}/owner"

When performed correctly, you will get the device owner response.

{"id":5,"owner_type":"Person","name":"Jason Meller","email":"jason@kolide.co"}

If you try to do something not allowed, like assign an owner to a user-owned device, you'll see an error message like this:

{"error":"Device has been marked 'user-owned' and is permanently assigned"}

Like assigning in the UI, these owner assignments are sticky and will not be overridden by any of Kolide's automated assignment processes. Also, just like in the UI, device assignments done via Kolide's API will still produce detailed audit logs and Privacy Center entries. 


As you can see, it's imperative to supply a good user-facing rationale and primary contact, so end-users can understand what mechanism was responsible for assigning a device to and who to contact in case an assignment was done in error.

Unassign Owners From Devices

The assign device permission also allows the API to unassign the current owner. More info on this new DELETE endpoint can be found in the API docs.

Programmatically Create a Live Query Campaign

By popular request, the second new endpoint in this release is the ability to create new Live Query campaigns programmatically. Combined with our other Live Query APIs, you can now issue queries to devices and read their results without using the Kolide UI.

 Here is an example of how it works:

export APIKEY=<your_api_key>

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $APIKEY" -d '{"sql":"select * from system info;","target_all_devices": true, "name": "api test"}' https://k2.kolide.com/api/v0/live_queries

In this example, we target all devices in the campaign, but just like in the UI, we can target specific IDs or groups of devices (like All Macs or All Windows devices).

If your request is successful, you will get the Live Query Campaign JSON back, and you can long-poll this to determine when devices have returned data (and then you can read it out)

This API, like the UI, will also produce errors for invalid SQL or blocked tables. Here is an example when I misspell the word SELECT.

{"error":"Sql is invalid. [1:1] Syntax error found near WITH Clause (Statement)"}

The UI Live Query Campaigns also produce audit logs and privacy center entries. The API is no different.

Additional API Improvements to the Checks API

While we were at it, we've also updated the the checks and issues APIs to include information about the grace period options we announced a few months ago for checks that are configured to notify end-users.

You can read the docs here, but here are some examples that use the super cool jq utility (a great JSON parsing CLI).

export APIKEY=<your_api_key>
export CHECK_ID=<the ID of the check you want the info for>

curl -s -H "Content-Type: application/json" \
        -H "Authorization: Bearer $APIKEY" https://k2.kolide.com/api/v0/checks/37 \
        | jq '. | {id, notification_grace_period}'

This will produce...

{
  "id": 37,
  "notification_grace_period": 1
}

In this case, 1 represents the total number of days the system will wait before marking an issue eligible for end-user notifications.

You can also get the timestamp for when a specific issue becomes eligible for end-user notification (when the grace period has passed). Here is an API call for every issue associated with a check.

export APIKEY=<your_api_key>
export CHECK_ID=<the ID of the check you want the info for>

curl -s -H "Content-Type: application/json" \
        -H "Authorization: Bearer $APIKEY" https://k2.kolide.com/api/v0/checks/${CHECK_ID}/issues/ \
         | jq '.data[] | {id,grace_period_expiration}'

This will produce...

{
  "id": 2,
  "grace_period_expiration": "2021-12-23T15:59:59.338Z"
}

Happy Holidays From All of Us to You

We hope you find this new API functionality useful and would love to get feedback as we look to improve and extend the capabilities of the API. 

If we don't talk to you beforehand, we hope you all have a wonderful holiday season and a happy new year!

See you in 2022!

New: Custom Slack Messages for Checks

At Kolide, we encourage our customers to entrust their users with the responsibility of keeping their devices secure and compliant. If you can communicate honestly and concisely with people about issues on their devices, they will be motivated to fix them, and more importantly, learn something in the process.

We invest a lot of time writing a clear rationale and precise fix instructions for every Check we ship in the product to accomplish this. We try to put ourselves in the shoes of every type of user—from the most technical to someone who has never opened the terminal before— and write Slack messages that are accessible, clear, and actionable.

While we work hard at this, we can never be perfect. Kolide will always be at a disadvantage to admins who work with their users every day and deeply understand their needs. These admins can often improve these messages for their staff in a way that does not apply to every Kolide user.

To that end, It gives me great pleasure to announce that as of today, Kolide allows customers to fully customize the rationale and fix instructions for every Check on the platform. Let me show you how it works.

How to Get Started

To get started, click on the "(...)" actions dropdown next to any Check and click "Configure." Find the section you'd like to change in the Check configuration sidebar and click "Edit..." within the Slack notification preview.


Supplementing an Official Kolide Message

In many cases, you may wish to only add a note, either just before or just after Kolide's official messaging. To support this, Kolide allows you to supplement its existing messages. Supplementing is an excellent choice because it enables you to continue to benefit from any changes Kolide will make to the template but allows you to communicate additional information to your users.


Fully Customizing a Message

Sometimes supplementing is not enough, and you will want to completely change the content of a message to best suit your users. To that end, the "Compose Custom Text" option gives admins complete control over the message without any approval from Kolide.


In both cases (full customization and supplemental changes), Kolide will put your organization name under the header of the section modified so end-users know the instructions came right from your company.



Revision History, Markdown, and Liquid

Kolide will put a notice in the audit log for every change and keep a complete revision history. You can revert to a previous known good state if any undesired changes are introduced to the templates.

As for formatting, instead of asking you to learn a new formatting API, all of Kolide's templates are written in standard markdown and automatically converted to Slack's block format.

For advanced users who want to include conditionals or display data from the Device, Check, or Failure the message is about, Kolide allows you to use the liquid syntax. The documentation for the variables for each Check can be found right in the edit window.



In closing, we are very excited to bring this message customization functionality to Kolide. We cannot wait to continue to improve this experience as folks explore the feature and provide feedback. Happy writing!

More Slack App Improvements and Settings

As a follow-up to our grace period announcement yesterday, we are excited to share more big improvements to the Kolide Slack app.

Failure Summary Options

Kolide only sends a failure summary to end-users when their devices are failing checks and only once every weekday to help reduce alert fatigue.

Sometimes though, getting a message every weekday can feel a bit much. Starting today, Kolide admins can pick the days of the week to send these messages. Whether it's reducing to just three days a week or implementing your very own #kolidefixfriday, we hope the additional flexibility helps you tune the right notification frequency for your company.

Additionally, it can be quite fatiguing to receive a notification for a device that has been sitting in a drawer for a few weeks. To help with that, we've introduced a new option that allows you to only notify users when the device has been seen recently.  We've found this so helpful in practice that we set the default threshold to 7 days or less, but you can choose whatever makes sense for your team.


While end-users won't receive a proactive notification for an offline device, they can still see them in their Kolide app home tab after clicking the Show Offline Devices button.

Escalation Options

In addition to the improvements above, we've shipped new settings options to configure failure escalations

Previously, when you set up the Kolide Slack app, admins could choose only one channel for all failure notifications, automatic escalations, and end-user help requests. With today's release, admins can now choose different channels for all three use cases, including directing user help requests to a dedicated channel where IT staff can more easily see them.

On top of that, we now offer greater customization of the Contact Admin for Help button in Kolide's Slack message. Admins can customize the reply we send users when this button is pressed, allowing for internal guidance — like how to submit an IT ticket. Messages can even include dynamic information from the notifications the end-user escalated!

We hope these help you better customize the Slack app experience for your end-users. Please let us know what you think!

New: Slack Notification Grace Period

Today, when a device fails a Check, Kolide immediately schedules a Slack message to be sent to an end-user during their next notification window (the next weekday afternoon in their local time).

For many Checks, this is desired; Kolide has caught a serious problem, and you want to let the user know about it quickly. Sometimes though, this approach can feel a bit punitive. For example, if Kolide detects a Windows device is missing an important update that was just released, you may want to give the user at least a few days to take care of the problem before triggering a reminder.

To help with this use case, we are excited to introduce a new feature called Notification Grace Periods. When a grace period is configured for a Check, Kolide will generate a failure as soon as it detects a problem but will hold the notification sent to the end-user until the grace period has expired. 

To configure a grace period, go to the Check's configuration page and ensure the Notify Device Owner strategy is selected. If it is, a new dropdown will appear where you can choose how many days you'd like Kolide to wait before notifying the end-user. When the grace period expires, we will notify them during their next notification window.

We highly recommend choosing a delay on any checks where the user's failing state is temporary and will likely be resolved by the end-user within a few days. The Windows and macOS missing important update Checks are great candidates for this new feature.

To help admins better understand the state of a Failure with a grace period, we updated the failure details sidebar to show when the end-user was first notified and when Kolide first detected it. We've also added the first notified time to the table view and the failures API as first_notified_owner_at

While we do not proactively notify end-users about failures in the grace period, we still allow motivated users to see these failures if they wish when interacting with the Kolide Slack app. If a user has failures that meet this requirement, they will see an option to view those failures in their Slack app home tab, or when they type the status command.

We hope you find this new feature useful. As always, we welcome your questions and comments.

Kolide Side Dishes

At Kolide, we typically ship changes and improvements to the product multiple times a day. The vast majority of these changes are modest improvements not worthy of their own change-log post, but together, they can make a big difference. We call these smaller features side dishes!

In this edition of side dishes, we have four exciting features to announce!

Improved Privacy Center Sign-In Experience

Over the last several months, we have invested a lot of energy into Kolide's Privacy Center, including letting users see the full set of device properties, checks, and other queries run on their device. While these improvements are great, end-users can't realize their benefits if they need to spend time fighting with a sign-in screen instead of reading the content. 

We've updated our Slack application to give end-users buttons instead of links to the Privacy Center to make things a lot easier. Unlike the normal Privacy Center links (which will lead most end-users to a sign-in screen), these buttons will actually open the browser using a secret and personalized URL that will automatically sign them in. 

Additionally, we've made some improvements to the privacy command to give end-users more information about their data before sending them to the Privacy Center. You can see an example below:

We've built this with security in mind. For example, Kolide administrators who sign in to the Privacy Center using one of these magic buttons will still need to authenticate fully when they try to access any sensitive functionality.

New Automatic Device Deletion Settings

As our customers continue to grow the number of devices they enroll, many of them are looking for more advanced options to manage when inactive devices are removed automatically or if multiple device records exist in Kolide for a device with the same serial number.

With our new Automatic Device Deletion setting screen, you can tune the behavior of those options to your liking. If you find yourself frustrated by seeing too many retired devices, or old instances of devices that have to be re-provisioned to new users, I highly recommend checking out these new settings.

Renamed Device Privacy to Restrictions

Our Device Privacy settings page has been renamed to Restrictions to reflect the options available on that screen better. Here you will continue to find settings that allow you to turn off features, restrict Osquery tables, and restrict the visibility of data collected about devices.

Kolide MDM Column 

For those taking advantage of our MDM capabilities, we've added a new column in Inventory called "Kolide MDM." This will enable sorting and filtering by the managed state of the device.

Additionally the attribute kolide_mdm was added to the Device API response

New Slack Option - Skip Personal Device Enrollment

A few weeks ago, we introduced a new dedicated options screen for managing the behavior of Kolide's Slack App. This week, we added a new option to this screen for organizations that do not want their end-users to enroll their personal devices into Kolide.


Previously, when any user self-enrolled a device, Kolide's Slack app would ask if it was a personal or organization-owned device. However, some organizations may not want to allow end-users to enroll their personal devices. 

If this sounds like you, change the setting to Allow ONLY organization-owned devices to enroll in Kolide. Once saved, this part of the enrollment process will be skipped, and every newly enrolled device will be marked as organization-owned.

Please Note: This setting does not convert previously enrolled personal devices into organization-owned ones. To convert them, you will need to simply remove/delete those devices from Kolide and have the user re-enroll them with the new correct choice.

API - New Global Failures Endpoints

In March, we introduced a new global failures view to Kolide. This view makes it much easier for administrators to locate failures without clicking into a specific Check. 

Since releasing this feature, we've heard a lot of great feedback from our customers that would love to list failures without needing to know anything about a check beforehand. Well, we've heard you, and we are proud to announce that we've just shipped an update to our API that enables just this use-case. So let's run through the changes.

New Failures Endpoints

View the documentation about this endpoint.

The new failures endpoints make it simple to list and access specific failures without knowing anything about the check or device they belong to. Here are some things you can do today.

List All Failures

https://k2.kolide.com/api/v0/failures

This endpoint lists all failures for all enabled checks, regardless of their resolved/open/ignored state. Once you have an API token, you can call it using the following curl example:

curl -H "Authorization: Bearer $PRODAPIKEY" 'https://k2.kolide.com/api/v0/failures'

List Failures By Status

Failures can be ignored, resolved, or open. Accordingly, you can scope the list of failures using those keywords as shown below:

https://k2.kolide.com/api/v0/failures/open
https://k2.kolide.com/api/v0/failures/resolved
https://k2.kolide.com/api/v0/failures/ignored

curl -H "Authorization: Bearer $PRODAPIKEY" 'https://k2.kolide.com/api/v0/failures/open'

curl -H "Authorization: Bearer $PRODAPIKEY" 'https://k2.kolide.com/api/v0/failures/resolved' 

curl -H "Authorization: Bearer $PRODAPIKEY" 'https://k2.kolide.com/api/v0/failures/ignored' 

All of these endpoints respond with a structure that matches the https://k2.kolide.com/api/v0/devices/<deviceID>/failures https://k2.kolide.com/api/v0/checks/<checkID>/failures endpoints.

Show A Specific Failure

Before, admins could only retrieve details for a single failure through the device or check API endpoints. Now, if you know the failure's ID, you can use just the following endpoint:

curl -H "Authorization: Bearer $PRODAPIKEY" 'https://k2.kolide.com/api/v0/failures/$FAILUREID'

New Failure Attribute - escalation_status

In addition, we've added a new attribute to the failure entity to indicate the escalation status of the failure. The escalation_status attribute can have one of the following values:

  • Not Escalated
  • User contact attempts exhausted
  • User requested help
  • No owner assigned

You can get more information, including full response schemas, on our API documentation site.


As always, we welcome comments and feedback from our API users. If you have a use case, please reach out to us via support@kolide.co or Intercom, and we'd love to chat about it.

New Slack App Access Control Setting

Kolide's Slack app enables end-users to identify and self-resolve important issues on their device. Our Slack app has always been a major part of our Honest Security strategy, so it's important we break down as many barriers as possible to enable every single one of our customers to use it.

To that end, we are excited to be rolling out new access control settings for the Slack app. These settings are perfect for organizations that have widely rolled out the Kolide agent but haven't taken the plunge with the Slack app. Many may want to test the self-remediation workflow with just a handful of users before rolling it out widely.

To support this use case, we just launched a new settings page available to administrators that will control precisely who can and cannot interact with the Slack app.

Notice the section labeled, "Who Can Communicate With the Kolide Slack App." If you choose the option "Only users who have who have been explicitly Onboarded," then anyone who hasn't been explicitly invited to use the app in the onboarding manager will not receive any messages from the Slack app. If these same users try to initiate an interaction with the Slack app, they will be greeted with a message that looks like this...


We've also updated the onboarding manager to make the onboarding status for each user much clearer and highlight important settings that impact the Slack experience front and center.


This new setting truly turns off all possible Slack notifications, even notifications that an administrator may directly initiate. So, for example, if you decide to restrict the Slack app to just onboarded users and then try to ping them manually, you will instead see a gentle reminder to onboard them first. This is true even for sensitive device notifications.

We still recommend the original behavior, but we hope this additional setting can help many organizations test out the Slack application in a controlled manner before committing to a company-wide roll-out.

As always, we welcome your questions, comments, and feedback.

Kolide Side Dishes

At Kolide, we typically ship changes and improvements to the product multiple times a day. The vast majority of these changes are modest improvements not worthy of their own change-log post, but together, they can make a big difference.

While we are working on some 25-pound-turkey sized features we plan on announcing soon, we thought we'd let you dig into some of these side-dishes first! Enjoy.

UX Improvements

Tools Menu

Depending on your level of access to Kolide, you may notice a new item in the main navigation called "Tools". This menu now houses all of the useful features of the product that don't quite need top-billing, but also do not belong in the "settings" section of the website.


Speaking of tools, the "Reporting DB" feature listed here is a feature we are currently beta testing with a few customers. If you are interested in being able to programmatically access all of the data we collect about a device in inventory, and eventually build your own reports on that data with SQL, please reach out to us via Intercom or support@kolide.co and we'd be happy to include you in our next round of testers!

Log Pipeline

The biggest change here is Log Pipeline, a feature that allows you to unlock the full power of the osquery daemon we deploy in the Kolide agent. This feature is now easier to find and users with access to it can also access other related features like creating FIM categories, configuring osquery options, and setting up your own custom decorators! 

As users of the Log Pipeline ourselves, we think all these items living together is a much more intuitive experience. Let us know what you think!

Improved Context For Slack Notifications

When an end-user successfully fixes a failing check, Kolide shows them a congratulatory message. Sometimes though, depending on the timing of the message, or where the message appeared, there might be some confusion about what device this message is referencing.

After a customer pointed this out, we decided to add some additional context to these messages so it's always clear which device Kolide is congratulating you about!

Search By Device and Person ID

If you are a regular user of our API (or are just really good a remembering numbers you see in your browser's location bar), you may have tried to lookup a device or person by their Kolide generated ID in our global search bar. Starting today, searching for both devices or people by their ID will now function as you would expect!

Performance Improvements

Live Query

If you are a regular user of Live Query, you may have noticed that devices now return up to 10x faster after querying them, and present any informational warnings or errors without requiring a page reload! Kolide now better leverages websockets to deliver this information at a much faster pace.

Device CSV Exports

We had reports from several customers that exporting the list of devices via CSV could take a long time. After investigating the issue we were able to improve the speed of this export by over 100x!

Improved User To Device Association

We've made some changes to how we build custom package and optimized our initial device data population routines to improve the accuracy and the speed in which we are able to assign users to a device. Additionally, the file names we generate for the custom packages are also now much shorter!

API Changes

Based on a customer request, we've now added a product_image_url following field to the device API endpoint. In many cases (and in all cases on Apple products), this new field features the visage of the exact hardware model enrolled in Kolide. For those of you creating your own internal experiences, these device images can help give you and your end-users the confidence that they are viewing the right device.

Speaking of product images, we've also now added updated product images for all of the new M1 Macs released by Apple earlier this months, and we've changed many of the icons on the widgets featured in the device detail pages to match the changes in macOS Big Sur!

On the log pipeline side, we've also now added the remote_ip, device_owner_email, and device_owner_type, to the kolide_decorations object in the logs emitted by our product in the log pipeline. This will allow you to easily correlate device activity with specific individual for potential integrations with IDP and authentication services.

We at Kolide hope you are all having a safe, healthy, and joyful holiday season. As always, please reach out with suggestions and feedback. Many of the improvements here were generated from customers just like you!

Introducing the Kolide Slack Home Tab

Kolide recently upgraded its Slack app to take advantage of a new feature called the Home Tab. This new tab allows Slack applications to create a persistent surface where they can display important information to a user that isn't structured like a conversation.

Kolide plans on using this area to increase the discoverability of end-user-focused features. We want to give device owners a clear and easy way to access important information about the security of their devices, without having to remember to type specific commands.

Our initial implementation offers end-users the following:

  • Convenient access to the Privacy Center  
  • A button to easily access the device enrollment workflow
  • Visibility into their assigned devices including their open security recommendations

Here is what it looks like!

As we roll-out new user-focused security features in Kolide, the Home Tab will grow more and more important. We envision this tab being the key place for end-users to start and manage their Kolide journey.

Please stay tuned for future updates!

Show Previous EntriesShow Previous Entries