Contents

New API Actions: Assign Device / Issue Live Query

December 23rd, 2021

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"
}

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.