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!

Configure Multiple Checks at Once!


Happy Monday everyone! We are starting this week off with several key improvements to the Checks section of the app. Check it out!

Mass-Actions for Checks

Kolide's checks page just got a lot easier to use with the introduction of checkboxes! If you've ever found yourself in a situation where you want to make a change to dozens of checks at once, but instead needed to change each check, one at a time, this feature should dramatically speed up the process.

Simply select the checks you want to action, and as soon as you do, a new menu will appear allowing you to add/remove Tags, change Notification Strategies, and alter the check's Status.

That's it! Don't worry, there's no catch. Audit logs and any other events will still be created as if you were performing these actions one by one.

New Iconography & Better Names

You may have also noticed lately that the checks page received a small visual upgrade. Each check now features a representative icon, making it easier to visually scan the list and find the checks you need. 

Additionally, we've also changed how we've named our checks. In the past, a Check's name was the same as the name of the Issue we would generate if the Check was in a failing state (eg. macOS Firewall Disabled). We (and many of our customers) found this confusing, so instead checks are now named after the underlying objective they are looking to achieve. 

To accommodate this change, we've also flipped the percentages to now show the percentage of devices passing a check. This means the higher the number, the better your organization is doing!

We've added the new names and the icons to the global search as well!



For our API users, we've added a new API column called display_name which will include this new naming convention.

Filter By Checklist

Checks get their icon's through their membership to a new concept called a checklist. This is a way for users to logically groups checks so that they are easier to discover. Unlike topics, a check can only belong to a single list. You can now easily filter checks by their list in the side-bar.



These changes are all helping us build towards the expansion of checks that we offer to our customers. Keep your eyes peeled for more improvements before the end of this year!

Support for the New M1 MacBook Pros

Know some lucky ducks 🦆 in your company that happened to get their hands on one of the new M1 MacBook Pros this week? Well, we just got a few in at Kolide and we couldn't wait to add first-class support into our product. 

New Serial Number Format

The new M1 MacBook Pros are the first Macs to feature Apple's new randomized serial number format. Unlike the old format which was 11 - 12 characters long and encoded a wealth of information about the device, this new format is shorter and, well, random!

So now, instead of using portions of the serial number to determine things like the Mac's product name (ex: MacBook Pro (16-inch 2019)) we have upgraded our approach to pull this information in its new location, the I/O Registry. Everything should "just work!"

Detailed CPU Data

These new MacBook Pros feature two variants of the M1 CPU, the M1 Pro and the M1 Max. Previously, Kolide did not feature the true name of the CPU in our Device overview page; but now, we not only have the correct name for the chip, we also show you the logo!

Additionally, for all Apple Silicon processors, Kolide now reports the number of performance cores and efficiency cores.


Product Images

We've always been a stickler about using the real product images for enrolled devices whenever possible. In keeping with that tradition, we now have updated our product image catalog to include all current Apple Silicon Macs!

Installation Packages

Our endpoint agent has natively supported Apple Silicon for a while, but while we are waiting for osquery to release an arm64 build, we have updated our installation package to correctly pre-install Rosetta2 if needed on M1 Macs running Monterey. This is super helpful in situations where you are deploying our package via an MDM on a brand new device.


As always, we hope you enjoy the update. Please reach out if you have any ideas about things you'd like to see from these new Macs.

Until next time!

We've Renamed Failures to Issues

Summary: We have switched UI, Slack App, Web URLs, and API endpoints to use the word "Issue" instead of the word "Failure." Any existing APIs endpoints and properties using the term "Failure" will still work, and any Webhooks fired for "Failures" will still fire as before. With that said, we highly encourage you to move over to their Issue counterparts. See the API documentation for more information.


When communicating directly with end-users, choosing your language precisely is essential. It's so essential we spent a bit of time talking about this precise topic in our Honest Security guide.

In Kolide, we have several areas where language can be improved, but one of the biggest problem-areas was using the word "Failure" to describe how we track the problems we find on a device. This is not a great word choice. For many, the word failure calls to mind other negative terms like "neglect," "dereliction," or a "screw-up." It's also a word that has a degree of finality to it. It's a word designed to define a bad end-state, not one that necessarily invites action.

Instead of the word failure, we are going with the word that still communicates our intent but softens the language and makes it easier to associate with a device, not a person. That word is Issue. The word is short, easy to spell, and most importantly, doesn't carry the same weight and implied finality as the word failure. Saying, "Your device has Issues that need your attention," flows much better than it would if we kept Failures.

To that end, our UI, Slack app, our URLs, and even back-end APIs will now feature the word 'Issues' over the word 'Failures.' 

While we have made this change throughout the app, we will continue to refer to Check status as "Failing" or "Passing." The only difference is a device that Fails a Check will produce an Issue (not a Failure).

To help with the transition, we are doing the following:

  • URLs: We will automatically redirect any existing URLs that contain the word Failures to the corresponding Issue URL. Ex: https://k2.kolide.com/x/inventory/devices/x/failures would become https://k2.kolide.com/x/inventory/devices/x/issues
  • API: We have not removed any API endpoints or properties with the word Failure in them. We've only made additive changes to the API.
  • Webhooks: We will still fire any original "Failure" webhooks, in addition to firing the new "Issue" webhooks. 

We hope you find this change an improvement. If you have other suggestions on improving the language throughout the app (especially in the Slack app), please reach out and let us know.

New Inventory: Microsoft Office Add-Ins

As part of our mission to provide world-class ground truth about devices enrolled in Kolide, I am excited to announce the latest addition to Inventory, Microsoft Office Add-Ins.

Why List Microsoft Office Add-ins?

For the unfamiliar, Microsoft Office Add-ins are extensions that end-users can install with most Microsoft Office products like Word, Excel, and Outlook. These extensions can support new media types, extend the user interface, or even integrate with third-party services (ex: Zoom or Wikipedia).

Like web browsing, the documents employees interact with within Microsoft Office are often incredibly sensitive and contain confidential information essential to the business or customers. Add-ins (depending on their permissions) have unprecedented access to documents and emails, allowing them to read or even alter their contents. While Microsoft does a reasonable job of vetting obvious malicious add-ins, there are sometimes cases where an add-in provides a service by transmitting parts or potentially all content in a document to the third-party serve (ex: Grammarly). These freemium services may be undesirable or potentially even violate the company's existing data sharing and privacy agreements like the GDPR.

To that end, we wanted to provide a way to easily enumerate these add-ins, their capabilities, and other relevant info, right in Inventory, for both Mac and Windows devices.

Feature Overview

Every Office Add-in has a manifest file that gives us unique insight into the add-in capabilities, permissions, and type on both Mac and Windows devices. To view this information across the fleet, browse directly to the Microsoft Add-in section in Inventory.

There are many types of add-ins and specific capabilities associated with each. We encourage you to refer to the official Microsoft Office developer documentation to learn more about interpreting this data in Inventory.

In addition, Microsoft Office Add-ins join many other "installable" Inventory items in our global search. Here is an example of finding an add-in called "Wikipedia." You can also search for Add-ins by their unique identifiers.


Microsoft Add-in Store Enhancement

Beyond collecting data from each endpoint, Kolide will also attempt to source data about the add-in from Microsoft's Add-in Store called Microsoft App Source. From there, we can pull essential data like the latest published version, the last release date, and the average rating.

Privacy Center & Data Collection

Like all of our device properties, we have documented the purpose, privacy information, and a representative example data set, which a Mac or Windows device will return in the Privacy Center.


We collect Microsoft Add-ins by default. If you don't want to collect this data from your devices, you can also use our new data collection opt-out feature.


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!

New Inventory: Safari Extensions

Up until today, Kolide has not attempted to collect Safari Extensions. Osquery's built-in support has been broken since Safari 11, and with the extension API story still shaking out on the Apple side, it wasn't clear if our efforts would be made obsolete in a future Safari version.

But with the recent release of Safari 15, things have moved in a positive direction. Apple has dramatically improved the reliability of, and consequently the developer experience around, web extensions. We expect that more and more app developers will begin porting their Firefox Addons and Chrome Extensions to Safari with these changes. In turn, end-users will install them as they become available.

Unfortunately, with a more diverse library of extensions comes a greater opportunity for bad actors to abuse it to potentially publish extensions of dubious value in exchange for an over-reach into the end-user's privacy. The first step of preparing for this eventuality is to gain greater visibility into the extensions installed across your fleet.

To help our customers do just that, we are excited to announce the inclusion of Safari Extensions in Inventory.

Starting today, Kolide can collect extension data from Safari 14 and Safari 15, including extensions built with the still relatively new web extension SDK (even including permission entitlements).

In addition, Safari extensions join many other "installable" Inventory items in our global search. Here is an example of finding an APP extension that comes with NetNewsWireApp.

Apple App Store Enhancement

Beyond collecting data from each Mac endpoint, Kolide will also attempt to send the bundle_identifier of the extension to Apple's App Store API to determine the latest version and when that version was published, among other data.

Privacy Center & Data Collection

Like all of our device properties, we have documented the purpose, privacy information, and a representative example data set, which a Mac will return in the Privacy Center.

We collect Safari Extensions by default. If you don't want to collect this data from your Mac fleet, you can also take advantage of our new data collection opt-out feature.


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.

Customize the Privacy Center

We hope you are enjoying your summer (or winter for our friends in the Southern Hemisphere). We've been working hard on our end on a slew of changes to Kolide's Privacy Center. These new features are now available and can be found in the new Privacy Center Configuration screen

You can now limit who can sign into the Privacy Center (great when you are in the process of rolling out Kolide) and can control which authentication methods are shown to end-users when they are prompted to sign in. These new options join the major changes we made to the sign-in process we announced earlier this year.

With that said, perhaps my favorite feature is the ability to customize the content within the Privacy Center.

Add a Custom Section to the Privacy Center

Many of our customers have embraced the Privacy Center, which has quickly become the home base for end-users to learn about the company's endpoint security strategy. 

Over time we've gotten many requests to customize the content to include important company information relevant to their end-users. 

Starting today, Kolide administrators can create a custom section with any information they'd like. Text, links, and any other markdown formatted content can be displayed at the top of the Privacy Center for all end-users.

You can find these customization options in the new Privacy Center configuration screen under settings.

We hope everyone takes advantage of the Privacy Center customization to improve their end-users understanding of Kolide and point them to important security and IT resources. 

Show Previous EntriesShow Previous Entries