Kandji Packages: Create and Update Custom Apps via API

In Kandji, you can deploy custom apps—software you want your users to have but isn’t available as one of Kandji’s Auto Apps or from the Mac App Store—using our Custom App Library Item. 

In concrete terms, that means creating a new Library Item, uploading installation files—PKG, DMG, or ZIP—to it, setting enforcement policies, adding optional pre- or postinstall scripts, then putting that Library Item in the appropriate Blueprint. Once that’s done, your custom app will appear on all devices assigned to that Blueprint.

But there’s another way to add custom apps: using our recently released API endpoints. These make it possible to manage custom Library Items programmatically.

However, we recognize that building a workable solution on top of APIs can be a technically complex, time-intensive project. That’s why we’re excited to share two new open-source frameworks—Kandji Packages and KAPPA—both of which provide a frictionless way to create and update Custom Apps over API. Here’s how they work.

Kandji Packages: What It Does, How It Works

Kandji Packages is a way to deploy custom installers programmatically so that users always have the current version. (In that respect, it’s similar to Kandji Auto Apps.) 

So if, for example, you want your developers to always have the most current version of the AWS Command Line Interface, you could use Kandji Packages to distribute it to that team.

Packages is appropriate for apps that require customized configurations, such as an installer package for which you need to modify an included file or attach a config file before deploying. It works with command line tools and binaries that have versioning; it can check the current version on a download source against the version that’s already deployed. As long as the vendor provides version information in the package, Kandji Packages can enforce it.

Before you use Kandji Packages, you need a couple of things: a valid Kandji tenant; an API token with these permissions; and (optionally) a Slack token for reporting status.

After that initial configuration, download a macOS app installer—either a PKG or DMG—and point Packages at the download. It will upload to your Kandji instance, auto-populate details like the app name, and post to Slack once it’s finished. As detailed in the README file, there are other customizations available, such as selecting a per-app enforcement type or Self Service category.

It’s important to note that when you use Kandji Packages to initially create a new Custom App, it will not add it to a Blueprint; you still need to use the Kandji web app for that. But if you use it to update an existing Library Item that's already scoped to a Blueprint, it'll update the installer and version for enforcement  (if set) and keep the existing scope as is.

You run Kandji Packages on a Mac (it’s primarily Python, with a little shell scripting to manage setup and configuration). You can also use it as part of a continuous integration/delivery flow to continually update and distribute custom apps as they become available; it can interact with files you have in a repo. (This still requires a Mac node.)

In addition to working with local files, Kandji Packages can also source an installer by name directly from Homebrew. As long as the Homebrew cask source is a PKG or DMG, Packages will execute the same workflow as above when adding that installer to, or updating it in, Kandji.

Kandji Packages and AutoPkg

If all that sounds familiar, it’s because the functionality is similar to what you get from AutoPkg, the venerable automation framework for packaging and distributing macOS software.

Like AutoPkg, Kandji Packages can download installer files from a specified source site, extract them (if archived), parse their versioning information, and provide identifying information about the installation. Unlike AutoPkg, Kandji Packages can then leverage the Kandji API to actually upload the installer file to your Kandji instance for deployment to specific devices.

For customers who are already invested in an AutoPkg environment, we’ve built an AutoPkg processor—the Kandji AutoPkg Processor Actions, or KAPPA for short—to connect such existing AutoPkg infrastructures to Kandji. If you’ve ever used something like Munki, which integrates tightly with AutoPkg to handle package uploads, scoping, and more, the behavior should be familiar; KAPPA hopes to provide similarly seamless integration.

All of their existing recipes and all of the workflows they've set up to download installers and build and assign packages remain the same; they just need to modify their existing recipes to add a step for KAPPA that would, in essence, say, "After this package is built, pass it off to the Kandji processor." You can also create a recipe to define the name of the package, the group it should be assigned to, and where it should appear in Kandji Self Service, among other configuration options.

We do a few things to check on versioning: If it’s just an app bundle that you're distributing—something like Slack—we will read the short version string from its info.plist. We then check the current installation to see which version is running. If it’s a binary, we can record a PKG value instead and then use that for validating the installed version. 

If you’re using the Audit and enforce installation option, you can set a number of days before version enforcement triggers. When enforcement is due, the user will be prompted to close the open app before the update proceeds, with an option to defer once. If it's a binary or background process with an update pending, that update will proceed without issue.

Both frameworks are open source, with licensing details available for Kandji Packages and for KAPPA. We actively welcome contributions and feedback from the community.

About Kandji

Kandji is the Apple device management and security platform that empowers secure and productive global work. With Kandji, Apple devices transform themselves into enterprise-ready endpoints, with all the right apps, settings, and security systems in place. Through advanced automation and thoughtful experiences, we’re bringing much-needed harmony to the way IT, InfoSec, and Apple device users work today and tomorrow.