4238553a2e
* Docs: Start of Santa Docs * Docs: /exec()/execve()/ * Docs: /sync-server/sync server/ * Docs: review updates
3.6 KiB
Building
Santa makes use of rake for building and testing Santa. All of the releases are made using this same process. Santa's releases are codesigned with Google's KEXT signing certificate. This allows Santa to be loaded with SIP fully enabled.
Cloning
Clone the source and change into the directory.
git clone https://github.com/google/santa
cd santa
The above command will default to using the master branch. If you wanted to build, run or test a specific version of Santa use this command.
git checkout <version, i.e. 0.9.19>
Building
Build a debug version of Santa. This keeps all the debug symbols, adds additional logs and does not optimize the compiled output. For speed sensitive tests make sure to benchmark a release version too.
rake build:debug
Build a release version of Santa.
rake build:release
Both of these just output the binaries that makeup Santa in the default Xcode build location. To actually run what was built, see the next section.
Running
On macOS 10.11+ System Integrity Protection (SIP) prevents loading of kernel extensions that are not signed by an Apple KEXT signing certificate. To be able to load and test a non-release version of Santa, SIP will have to be configured to allow non-Apple KEXT signing certificates.
This is only to be done a machine that is actively developing, unloading and loading kernel extensions.
- Boot into Recovery Mode: Reboot and hold down
command+r - From the utilities menu select
Terminal - Disable the KEXT feature of SIP:
csrutil enable --without kext - Reboot
You should now be able to load and run a non-release version of Santa.
Build and run a debug version of Santa.
rake reload:debug
Build and run a release version of Santa.
rake reload:release
Debugging
Xcode and lldb can be used to debug Santa, just like any other project. Instead of clicking the play button to launch and attach to a process, you can attach to an already running, or soon to by running, component of Santa. To do this select the Debug menu and choose Attach to Process by PID or Name… . Below are the four components of Santa and who to debug the process as.
Note: santa-driver (the kernel extension) cannot be debugged by attaching with Xcode.
Note: Xcode can attach to santad without interruption, however any breakpoints in the decision making codepath can deadlock the machine. Using lldb directly to attach to santad will deadlock the machine.
| process | user |
|---|---|
| santad | root |
| Santa* | me |
| santactl | me |
| santabs | root |
Xcode will then wait for the process to start. Issue this command to restart all the Santa processes in debug mode.
*The Santa (GUI) process is the only component of Santa that can be launched and debugged from Xcode directly. All the other components are launched with privileges and/or are scoped to an XPC service that launchd scopes to a hosting bundle. Thus the need for the Attach to Process by PID or Name… technique. See the ipc document for for details.
rake reload:debug
Now the process is attached in Xcode and you can debug your day away.
Tests
Run all the logic / unit tests
rake tests:logic
Run all of santa-driver kernel extension tests
rake tests:kernel
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 or kernel panics much easier.
rake dist