Contents

How to Manage Osquery With Kolide Launcher and Fleet

This article was originally published on October 20, 2017 and portions of it discuss Kolide Fleet which was formally retired in November of 2020. For posterity, this post is still available, but we encourage you to read the Fleet Retirement Announcement.

In this article, I want to walk-through setting up a local Kolide Fleet server with a local instance of osquery via the Kolide Launcher. Before you dig in, I highly recommend you read our Fleet and Launcher announcement blog posts. This tutorial will build both tools from source to illustrate how to interact with the open-source repositories. First, let’s clone the Fleet repository from GitHub:

$ cd $GOPATH/src/github.com/kolide
$ git clone git@github.com:kolide/fleet.git
$ cd fleet

From the root of the repository, let’s install the application dependencies, generate the JavaScript bundle, and build the binary

$ make deps
$ make generate
$ make

Now, we will test this locally. We’re going to have to do something about the infrastructure requirements (database and cache). The Fleet repo includes Docker Compose tooling for this exact reason. Start the infrastructure with the following command:

$ docker-compose up

To set up the database schema of your new Fleet instance, use the fleet command:

$ ./build/fleet prepare db
Migrations completed.

Now, to run the server locally, the only required flag is --auth_jwt_key which defines the key used for session tokens. For example, you may run:

./build/fleet serve --auth_jwt_key=3zqHl2cPa0tMmaCa9vPSEq6dcwN7oLbP

Note that in production, this value can also be set via environment variables or a config file. Now if you browse to https://localhost:8080, you should see the interactive setup flow:

A screenshot of Kolides' localhost setup flow. This shows a form to set up a username, password and to enter an email address.

After you create your account and log in, you will be able to pull up the “Add New Host” screen, which should look like:

A screenshot of Kolides' add new host screen.

Select “Reveal Secret” and you will be able to see and copy your Fleet server’s enroll secret. You’ll need this to connect a Launcher to Fleet.

Now let’s connect a host via Launcher. For the sake of this example, we will also build Launcher from source. First, we must clone the repository:

cd $GOPATH/src/github.com/kolide/
git clone git@github.com:kolide/launcher.git
cd launcher

Now, we follow a similar flow to Fleet in order to install the dependencies and build the binaries:

make deps
make
./build/launcher --help

Assuming you have the osqueryd installed on your local host (https://osquery.io/downloads/), you can run the following to connect to Fleet:

./build/launcher --debug \
  --hostname=localhost:8080 \
  --enroll_secret="MFyZh3+l1VUFNHE5Q3U9DLc6Xab1c6/C" \
  --insecure

We include --insecure because the TLS certificate we’re using for locahost:8080 does not have a trusted signature. After running this command, you should see the host appear in the web UI:

The manage hosts screen showing the newly added host

Feel free to pause here and go play with the host you’ve just enrolled! Click the little database symbol on the host card to run a live query.

Now, let’s assume you want to get your co-workers enrolled in this too. You need to build a package and send it to them. Luckily, the Launcher includes a tool to generate cross-platform packages for your environment. To build the tool, run the following from the root of the Launcher repo:

make deps
make package-builder
./build/package-builder make --help

First, build a package that will install osquery and connect it to the local Fleet instance that running on https://localhost:8080. Obviously the hostname will be different when you actually deploy Fleet in production, but it’s easy enough to play with the tools, so let’s give it a try! All you have to do is call ./build/package-builder make with the same flags you passed to the Launcher:

./build/package-builder make \
  --hostname=localhost:8080 \
  --enroll_secret="MFyZh3+l1VUFNHE5Q3U9DLc6Xab1c6/C" \
  --insecure

This will print out a list of package paths. Open and install the macOS package.

A window showing that the installation of the macOS package was successful

You should now see another instance of your host in Fleet:

A screenshot showing that the manage hosts screen shows an additional instance has been added

If this was your actual Kolide Fleet instance, you could easily deploy out this package to all of the macOS users in your company and they would be enrolled with an autoupdating osquery package! For more information on deploying Fleet in production, see the Fleet Infrastructure Documentation.