Building
Santa uses Bazel for building, testing and releases. The main
branch on GitHub is the source-of-truth with features developed in personal forks.
Cloning
Clone the source and change into the directory.
git clone https://github.com/northpolesec/santa
cd santa
The above command will default to using the main
branch. All releases are built from tagged commits, so if you wanted to build, run or test a specific release you can checkout that tag:
git checkout 2022.5
If you want to list all the tags in reverse order:
git tag --sort=-creatordate
Building
Build a debug version of Santa:
bazel build //Source/gui:Santa
This will build and sign all of the santa components (UI and services).
For developers who do not have access to North Pole’s code signing certificate and provisioning profiles, use the --define=SANTA_BUILD_TYPE=adhoc
flag. This will adhoc sign Santa and does not require provisioning profiles.
Note: In order to run an adhoc signed Santa SIP must be disabled. See the running section below.
bazel build //Source/gui:Santa --define=SANTA_BUILD_TYPE=adhoc
Running
When working on Santa, it’s useful to have a way to quickly reload all of the Santa components. For this reason, there’s a special rule in the Santa BUILD file that will build Santa, unload Santa if it’s running, install the new Santa in the right place and attempt to load it.
Non-adhoc debug builds of Santa can only be run by North Pole developers. This is because of bundle id and provisioning profile restrictions bound to Apple developer accounts.
bazel run :reload
Non-North Pole developers can use an adhoc build to run development builds of Santa. System Integrity Protection (SIP) will need to be disabled in order to run an adhoc build.
This is only to be done a machine that is actively developing Santa.
- Boot into Recovery Mode:
- For Intel Macs reboot and hold down
command+r
. - For Apple Silicon Macs press and hold the power button until “Loading startup options” appears. Click Options, then click Continue. If asked, select a volume to recover, then click Next.
- For Intel Macs reboot and hold down
- From the utilities menu select
Terminal
- Disable the KEXT feature of SIP. The kext wording is legacy but the command still works well for loading adhoc signed system extensions:
csrutil enable --without kext
- Reboot
You should now be able to load and run a non-release version of Santa.
Build and run an adhoc debug version of Santa.
bazel run :reload --define=SANTA_BUILD_TYPE=adhoc
Note: if you are currently running a release or non-adhoc dev build of Santa, this new adhoc build will show up as a second instance of Santa. Remove the non-adhoc instance like so:
systemextensionsctl uninstall ZMCG7MLDV9 com.northpolesec.santa.daemon
IDE Setup
We don’t generally use Xcode when working on Santa but it’s very useful to be able to use an IDE when developing. We generally use clangd for this, using a tool that will extract the appropriate compile commands automatically from our Bazel build rules. To use this:
1) Run bazel run @hedron_compile_commands//:refresh_all
to generate the compile_commands.json
file.
2) Follow the instructions for setting up your editor.
Debugging
lldb can be used to debug Santa, similarly to any other project, with some exceptions. lldb can attach to com.northpolesec.santa.daemon, however any breakpoints in the decision making codepath can deadlock the machine.
Tests
Run all the logic / unit tests
bazel test :unit_tests --define=SANTA_BUILD_TYPE=adhoc --test_output=errors
Testing Config Options Using /var/db/santa/config-overrides.plist
Debug versions of Santa have the ability to set/override config settings using an override file, that will be applied over the top of the configuration from a profile.
- Create a plist in
/var/db/santa/config-overrides.plist
For example to point Santa at a sync server running on localhost here would be the config-override file.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>SyncBaseURL</key>
<string>http://localhost:8080/v1/santa/</string>
<key>SyncClientContentEncoding</key>
<string>gzip</string>
</dict>
</plist>
:warning: Warning Make sure the file is readable.
- run
bazel run //:reload
to rebuild and restart the Santa daemon.
Releases
Creates a release build of Santa with a version based of the newest tag. Also saves the dsym files for each component of Santa. This makes debugging and interpreting future crashes much easier. Releases are handled by North Pole internal infrastructure.
bazel build --apple_generate_dsym -c opt //:release