diff --git a/docs/hosts/mac-enterprise.md b/docs/hosts/mac-enterprise.md new file mode 100644 index 0000000000..80f9cbfded --- /dev/null +++ b/docs/hosts/mac-enterprise.md @@ -0,0 +1,27 @@ +# Enrolling multiple Macs + +If you're managing an enterprise environment with multiple Mac devices, you likely have an enterprise deployment tool like [Munki](https://www.munki.org/munki/) or [Jamf Pro](https://www.jamf.com/products/jamf-pro/) to deliver software to your mac. You can deploy osqueryd and enroll all your macs into kolide using your software management tool of choice. + +First, [download](https://osquery.io/downloads/) and import the osquery package into your software management repository. You can also use the community supported autopkg [recipe](https://github.com/autopkg/keeleysam-recipes/tree/master/osquery) +to keep osqueryd updated. + + +Next, you will have to create an enrollment package to get osqueryd running and talking to kolide. Here, you'll have to create a custom package because you have to provide specific information about your kolide setup. We created a Makefile to help you build a macOS enrollment package. + +First, download the kolide repository from Github and navigate to the `tools/mac` directory. + +Next, you'll have to edit the `config.mk` file. You'll find all the necessary information by clicking "Add New Host" in your kolide server. + + - Set the `KOLIDE_HOSTNAME` variable to the FQDN of your kolide server. + - Set the `ENROLL_SECRET` variable to the enroll secret you got from kolide. + - Paste the contents of the kolide TLS certificate after the following line: + ``` + define KOLIDE_TLS_CERTIFICATE + ``` + +Note that osqueryd requires a full certificate chain, even for certificates which might be trusted by your keychain. The "Fetch Kolide Certificate" button in the Add New Host screen will attempt to fetch the full chain for you. + +Once you've configured the `config.mk` file with the corect variables, you can run `make` in the `tools/mac` directory. Running `make` will create a new `kolide-enroll.pkg` file which you can import into your software repository and deploy to your macs. + +The enrollment package must installed after the osqueryd package, and will install a LaunchDaemon to keep the osqueryd process running. + diff --git a/tools/mac/Makefile b/tools/mac/Makefile new file mode 100644 index 0000000000..a6a51a60ca --- /dev/null +++ b/tools/mac/Makefile @@ -0,0 +1,25 @@ +PKGNAME=kolide-enroll +PKGVERSION=1.0.0 +PKGID=co.kolide.osquery.enroll + +-include config.mk + +export KOLIDE_FLAGS +export KOLIDE_TLS_CERTIFICATE + + +all: clean build +clean: + rm -rf out/ + rm -rf root/etc/osquery + +build: clean + mkdir -p out + mkdir -p root/etc/osquery + echo $(ENROLL_SECRET) > root/etc/osquery/kolide_secret + echo "$$KOLIDE_TLS_CERTIFICATE" > root/etc/osquery/kolide.crt + + # validate the certificate + openssl x509 -in root/etc/osquery/kolide.crt -text > /dev/null + echo "$$KOLIDE_FLAGS" > root/etc/osquery/kolide.flags + pkgbuild --root root --scripts scripts --identifier ${PKGID} --version ${PKGVERSION} out/${PKGNAME}-${PKGVERSION}.pkg diff --git a/tools/mac/config.mk b/tools/mac/config.mk new file mode 100644 index 0000000000..2a17c24045 --- /dev/null +++ b/tools/mac/config.mk @@ -0,0 +1,40 @@ +# Kolide hostname. Make sure omit https:// or the path +KOLIDE_HOSTNAME=kolide.acme.co + +# Osquery Enroll Secret. Replace with the secret set in Kolide. +ENROLL_SECRET=CHANGEME + +# Paste your kolide certificate chain below. +define KOLIDE_TLS_CERTIFICATE +CHANGEME +endef + +# Osquery flag file. No need to modify. +define KOLIDE_FLAGS +--force=true +--host_identifier=hostname +--verbose=true +--debug +--tls_dump=true + +--tls_hostname=$(KOLIDE_HOSTNAME) +--tls_server_certs=/etc/osquery/kolide.crt +--enroll_secret_path=/etc/osquery/kolide_secret + +--enroll_tls_endpoint=/api/v1/osquery/enroll + +--config_plugin=tls +--config_tls_endpoint=/api/v1/osquery/config +--config_tls_refresh=10 + +--disable_distributed=false +--distributed_plugin=tls +--distributed_interval=10 +--distributed_tls_max_attempts=3 +--distributed_tls_read_endpoint=/api/v1/osquery/distributed/read +--distributed_tls_write_endpoint=/api/v1/osquery/distributed/write + +--logger_plugin=tls +--logger_tls_endpoint=/api/v1/osquery/log +--logger_tls_period=10 +endef diff --git a/tools/mac/root/Library/LaunchDaemons/co.kolide.osquery.enroll.plist b/tools/mac/root/Library/LaunchDaemons/co.kolide.osquery.enroll.plist new file mode 100644 index 0000000000..aaf4b04687 --- /dev/null +++ b/tools/mac/root/Library/LaunchDaemons/co.kolide.osquery.enroll.plist @@ -0,0 +1,20 @@ + + + + + Label + co.kolide.osquery.enroll + ProgramArguments + + /usr/local/bin/osqueryd + --flagfile=/etc/osquery/kolide.flags + + RunAtLoad + + StandardErrorPath + /var/log/osquery/osquery-error.log + StandardOutPath + /var/log/osquery/osquery-output.log + + + diff --git a/tools/mac/scripts/postinstall b/tools/mac/scripts/postinstall new file mode 100755 index 0000000000..8614d665dd --- /dev/null +++ b/tools/mac/scripts/postinstall @@ -0,0 +1,7 @@ +#!/bin/bash + +[[ $3 != "/" ]] && exit 0 + +/bin/launchctl load /Library/LaunchDaemons/co.kolide.osquery.enroll.plist + +exit 0