Docs: Start of Santa Docs #192

tburgin · 2017-08-11T16:45:17Z

The start of Santa Docs

What is good

Provides a framework of topics to cover
Most documents have a lot of good detail
Read the docs support

What is not good

Some docs need more detail
More diagrams are needed
More examples of the syncing API are needed

russellhancox

I've only read the first several files but here's a first batch of comments.

russellhancox · 2017-08-11T21:37:52Z

Docs/details/events.md

@@ -0,0 +1,154 @@
+# Events
+
+Events are a notion core to how Santa interacts with a sync-server. Events are generated when there is a blocked `exec()` while in lockdown or monitor mode. Events are also generated in monitor mode for an `exec()` that was allowed to run, but would have been blocked in lockdown mode. This allows an admin to roll out Santa to their macOS fleet in monitor mode, but still collect meaningful data. The events collected while in monitor can be used to build a fairly comprehensive whitelist of signing certificates and binaries before switching the fleet to lockdown mode.


I'd probably change exec() to execve() here as all other exec*() functions call up to execve. It also catches posix_spawn, which is separate.

sgtm, done throughout

russellhancox · 2017-08-11T21:38:10Z

Docs/details/events.md

@@ -0,0 +1,154 @@
+# Events
+
+Events are a notion core to how Santa interacts with a sync-server. Events are generated when there is a blocked `exec()` while in lockdown or monitor mode. Events are also generated in monitor mode for an `exec()` that was allowed to run, but would have been blocked in lockdown mode. This allows an admin to roll out Santa to their macOS fleet in monitor mode, but still collect meaningful data. The events collected while in monitor can be used to build a fairly comprehensive whitelist of signing certificates and binaries before switching the fleet to lockdown mode.


sync server, 2 words.

sgtm, done throughout

russellhancox · 2017-08-11T21:39:13Z

Docs/deployment/configuration.md

@@ -0,0 +1,113 @@
+# Configuration
+
+There are two types of configurations that can be utilized to control Santa. The first is a local configuration. The second is a sync-server controlled configuration.


utilized to control Santa. The first is a local configuration. The second is a sync-server

to:

utilized to control Santa: local configuration and a sync server controlled configuration

russellhancox · 2017-08-11T21:40:13Z

Docs/deployment/configuration.md

+| MachineIDPlist                | String     | The path to a plist that contains the MachineOwnerKey / value pair. |
+| MachineIDKey                  | String     | The key to use on MachineIDPlist.        |
+
+*protected keys: santad cannot be running to make a change


protected keys: If a sync server is configured, this setting cannot be changed while santad is running as it is assumed the setting will be provided by the sync server.

russellhancox · 2017-08-11T21:41:30Z

Docs/details/events.md

+
+###### Archived Object
+
+Events are temporarily stored in a sqlite3 database `/var/db/santa/events.db` until they uploaded to the sync server. They are stored in the [NSKeyedArchiver](https://developer.apple.com/documentation/foundation/nskeyedarchiver?language=objc) format.  Here is an example of a Firefox event in the  events.db awaiting upload.


I'm not sure it's worth mentioning the archived object format as this might change in future. It's not generally intended that anyone reads from the event database. Even the format of the database is not fixed, there's a possibility we might switch to LevelDB in future.

Since we are somewhat conflating dev and user docs I think this is worth keeping. Just added a note explaining the intention of the section.

russellhancox · 2017-08-11T21:43:16Z

Docs/details/events.md

+##### Event Lifecycle
+
+1. santad will generate a new event
+2. santad checks / adds the event's SHA-256 file hash to a in memory cache with a timeout of 10 min. If an event with the same SHA-256 file hash has been sent for upload within the past 10 min, the event is dropped.


In the markdown, you can leave the items in an ordered list all as 1, the actual numbers will be calculated during rendering. It's less maintenance if they don't need changing :-)

But that's a pain in Typora :(

russellhancox · 2017-08-11T21:43:58Z

Docs/details/events.md

+2. santad checks / adds the event's SHA-256 file hash to a in memory cache with a timeout of 10 min. If an event with the same SHA-256 file hash has been sent for upload within the past 10 min, the event is dropped.
+3. santad saves the event to `/var/db/santa/events.db`. A unique ID is assigned as a key.
+4. santad sends an XPC message to the santactl daemon. The messages contains the event with instructions to upload the event immediately. This is non-blocking and is performed on a background thread.
+5. santad waits for a reply from santactl. Again, this is non-blocking and is performed on a background thread.


santad isn't really waiting for a reply, it just happens to receive a message, right?

True, I was getting related bundle events mixed up with regular events. Removed 5.

russellhancox · 2017-08-11T21:44:53Z

Docs/details/ipc.md

+
+The santad and Santa (GUI) processes are both started and kept alive by launchd as LaunchDaemon and LaunchAgent respectively. This means santad runs as root, and Santa (GUI) runs as the console user. There can be multiple Santa (GUI) process running, one per logged in user.
+
+When using a sync-server the santactl process is started by santad with a `fork()` and `exec()` of  `santactl sync —-daemon`.  Before the new process starts, all privileged are dropped. So santactl runs as nobody.


the fork+exec stuff is a bit in the weeds.

also, all privileges

russellhancox · 2017-08-11T21:45:39Z

Docs/details/ipc.md

+
+When using a sync-server the santactl process is started by santad with a `fork()` and `exec()` of  `santactl sync —-daemon`.  Before the new process starts, all privileged are dropped. So santactl runs as nobody.
+
+The santabs process is started by launchd by way of an XPC service connection from santad. XPC services inherit their initiator's privileges so santabs runs as root.


runs as root

Which is necessary to ensure santabs has permission to read all the files.

Coleeb · 2017-08-11T19:12:44Z

Docs/deployment/configuration.md

@@ -0,0 +1,113 @@
+# Configuration
+
+There are two types of configurations that can be utilized to control Santa. The first is a local configuration. The second is a sync-server controlled configuration.


Two configuration methods can be used to control Santa: Local Configuration and Sync-Server Controlled Configuration.

Coleeb · 2017-08-11T19:14:00Z

Docs/deployment/configuration.md

+
+| Key                           | Value Type | Description                              |
+| ----------------------------- | ---------- | ---------------------------------------- |
+| ClientMode*                   | Integer    | 1 for Monitor or 2 for Lockdown          |


1 = MONITOR, 2 = LOCKDOWN

Does this have a default value?

Coleeb · 2017-08-11T19:23:55Z

Docs/deployment/configuration.md

+| ModeNotificationLockdown      | String     | The notification text to display when the client goes into lockdown mode. Defaults to "Switching into Lockdown mode". |
+| SyncBaseURL*                  | String     | The base URL of the sync server.         |
+| ClientAuthCertificateFile     | String     | If set, this contains the location of a PKCS#12 certificate to be used for sync authentication. |
+| ClientAuthCertificatePassword | String     | Contains the password for the pkcs#12 certificate. |


pkcs#12 should be capitalized here.

Coleeb · 2017-08-11T19:32:19Z

Docs/deployment/configuration.md

+| Key                            | Value Type | Description                              |
+| ------------------------------ | ---------- | ---------------------------------------- |
+| client_mode                    | String     | MONITOR or  LOCKDOWN. Defaults to MONITOR. |
+| clean_sync**                   | Bool       | If set to True Santa will clear all local rules and download a fresh copy from the sync-server. Defaults to False. |


Can TRUE and FALSE be emphasized as code here, since they're in reference to a boolean variable?

Coleeb · 2017-08-11T20:00:00Z

Docs/details/events.md

@@ -0,0 +1,154 @@
+# Events
+
+Events are a notion core to how Santa interacts with a sync-server. Events are generated when there is a blocked `exec()` while in lockdown or monitor mode. Events are also generated in monitor mode for an `exec()` that was allowed to run, but would have been blocked in lockdown mode. This allows an admin to roll out Santa to their macOS fleet in monitor mode, but still collect meaningful data. The events collected while in monitor can be used to build a fairly comprehensive whitelist of signing certificates and binaries before switching the fleet to lockdown mode.


notion core or core notion?

The events collected while in monitoring

or

The events collected while in monitor mode

replace fairly with reasonably or nearly?

Events are a defined set of data, core to how Santa interacts with a sync-server.

Coleeb · 2017-08-14T13:48:19Z

Docs/introduction/syncing-overview.md

+
+#### Flow of a full sync
+
+This is a high level overview of the syncing process end to end. For a more a more detailed account of each part, see the respective documents. The santaclt binary can be run in one of two modes, daemon and non-daemon. The non-daemon mode does one full sync and exits. This is the typical way a user will interact with Santa, mainly to force a full sync. The daemon mode is used by santad to schedule full syncs, listen for push notifications and upload events.


This is a high level overview of the syncing process. For a more a more detailed account of each part, see the respective documentation.

Coleeb · 2017-08-14T13:50:38Z

Docs/introduction/syncing-overview.md

+
+0. When the santad process starts up, it looks for a `SyncBaseURL` key/value in the config. If one exists it will `fork()` and `exec()` `santactl sync —-daemon`. Before the new process calls `exec()`, all privileges are dropped. All privileged actions are then restricted to the XPC interface made available to santactl by santad. Since this santactl process is running as a daemon it too exports an XPC interface so santad can interact with the process efficiently and securely. To ensure syncing reliability santad will restart the santactl daemon if it is killed or crashes.
+1. The santactl daemon process now schedules a full sync for 15 sec in the future. The 15 sec is used to let santad settle before santactl starts sending rules from the sync-server to process.
+2. The full sync starts. There are a number of stages to a full sync.


There are a number of stages to a full sync:

Coleeb · 2017-08-14T13:51:27Z

Docs/introduction/syncing-overview.md

+2. The full sync starts. There are a number of stages to a full sync.
+   1. preflight: The sync-server can set various settings for Santa.
+   2. logupload (optional): The sync-server can request that the Santa logs be uploaded to an endpoint.
+   3. eventupload (optional): If Santa has generated events it will upload them to the sync-server.


eventupload (optional): If Santa has generated events, it will upload them to the sync-server.

Coleeb · 2017-08-14T13:51:56Z

Docs/introduction/syncing-overview.md

+   3. eventupload (optional): If Santa has generated events it will upload them to the sync-server.
+   4. ruledownload: Download rules from the sync-server.
+   5. postflight: Updates timestamps for successful syncs.
+3. After the full sync completes a new full sync will be scheduled, by default this will be 10min. However there are a few ways to manipulate this.


However, there are a few ways to manipulate this:

Coleeb · 2017-08-14T13:53:48Z

Docs/introduction/syncing-overview.md

+
+#### santactl XPC interface
+
+When running as a daemon the santactl process makes available an XPC interface for use by santad. This allows santad to send blocked binary or bundle events directly to santactl for immediate upload to the sync-server. Doing so makes for a smoother user experience. The binary that was blocked on macOS is immediately available for viewing or handling on the sync-server.


When running as a daemon, the santactl process makes available an XPC interface for use by santad. This allows santad to send blocked binary or bundle events directly to santactl for immediate upload to the sync-server, enabling a smoother user experience. The binary that was blocked on macOS is immediately available for viewing or handling on the sync-server.

nguyen-phillip · 2017-08-14T19:27:36Z

Docs/details/mode.md

+
+##### Lockdown mode
+
+Running Santa in Lockdown mode will stop any unknown binaries from running. Meaning, if the binary has no rules or scopes that apply, it will be blocked.


Running Santa in Lockdown Mode will stop all unknown binaries from running. This means that if the binary has no rules or scopes that apply, then it will be blocked.

Q: Lockdown mode is more restrictive than monitor mode right? If this is the case, then I think it would be good to repeat that it still stops blacklisted binaries from running. e.g. Running Santa in Lockdown Mode will stop all blacklisted binaries and additionally will prevent all unknown binaries from running.

boom! I like it

nguyen-phillip · 2017-08-14T19:35:09Z

Docs/details/rules.md

+Whitelisted (Certificate)
+```
+
+##### Built in rules


nguyen-phillip · 2017-08-14T19:35:50Z

Docs/details/rules.md

+
+##### Built in rules
+
+To avoid blocking any Apple system binaries or Santa binaries, santad will create 2 immutable certificate rules at startup.


nguyen-phillip · 2017-08-14T19:37:08Z

Docs/details/santa-driver.md

+
+##### Kauth
+
+santa-driver utilizes two Kauth scopes `KAUTH_SCOPE_VNODE` and `KAUTH_SCOPE_FILEOP `. It registers itself with the Kauth API by calling `kauth_listen_scope()` for each scope. This function takes three arguments.


nguyen-phillip · 2017-08-14T19:53:45Z

Docs/details/santabs.md

+
+The santabs process is an XPC service for the santa-driver.kext bundle, meaning only binaries within that bundle can launch santabs. It will be launched with with whatever privileges the calling process is running as. Currently santad is the only caller of santabs, so santabs runs as root.
+
+#####Events


missing space between ##### and Events

nguyen-phillip · 2017-08-14T20:03:16Z

Docs/details/santactl.md

+
+The sync command is covered in the [syncing.md](syncing.md) document.
+
+#####Debug Commands


Missing space between ##### and Debug

nguyen-phillip · 2017-08-14T20:15:07Z

Docs/details/santactl.md

+
+This may be the most complex part of Santa. It really has two types of work that is does. Firstly it contains all of the code and functionality for syncing with a sync-server. The details of which are covered in the [syncing.md](syncing.md) document. This document will cover the status work that santactl performs.
+
+The santactl binary can be used to view the state and configuration of Santa as a whole. It can also inspect individual files. When running without a sync-server it also a supported method of managing the rules database. 


It does two types of work:

It contains all of the code and functionality for syncing with a sync-server.

It can be used to view the state and configuration of Santa as a whole. (...)

The details of santactl's syncing functionality are covered in the syncing.md document. This document will cover the status work that santactl performs.

nguyen-phillip · 2017-08-14T20:42:59Z

Docs/details/santad.md

+
+At this point santa-driver is loaded and running in the kernel but is allowing all executions and not sending any messages to santad. Before santad tells santa-driver it is ready to receive messages it needs to setup a few more things.
+
+The rule and event databases are now initialized. Followed by connection establishment to the Santa (GUI) and santactl sync daemon. The config file is processed and now santad knows what mode it is running in.


initialized, followed by

nguyen-phillip · 2017-08-14T20:51:23Z

Docs/development/building.md

@@ -0,0 +1,104 @@
+
+
+#Building


missing space between # and Building

nguyen-phillip · 2017-08-14T20:53:47Z

Docs/development/building.md

+
+#### 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 configured to allow non Apple KEXT signing certificates.


missing "be" and hyphen:
.. SIP will have to be configured to allow non-Apple KEXT signing certificates.

nguyen-phillip · 2017-08-14T20:56:55Z

Docs/development/building.md

+
+#### 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: santa-driver ...
or
Note that santa-driver ...

nguyen-phillip · 2017-08-14T20:58:55Z

Docs/development/building.md

+
+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 a XPC service that launchd scopes to hosting bundle. Thus the need for the `Attach to Process by PID or Name…` technique.  See the [ipc](../details/ipc.md) document for for details.


a XPC --> an XPC
to hosting bundle. --> to a hosting bundle.

nguyen-phillip · 2017-08-14T21:00:09Z

Docs/index.md

+
+For those who want even more details on how Santa works under the hood, this section is for you.
+
+######Binaries


Missing space between ###### and Binaries

nguyen-phillip · 2017-08-14T21:00:35Z

Docs/index.md

+* [santa-gui](details/santa-gui.md): A user-land GUI daemon that displays notifications when an `exec()` is blocked.
+* [santabs](details/santabs.md): A user-land root daemon that finds Mach-O binaries within a bundle and creates events for them. 
+
+######Concepts


Missing space between ###### and Concepts

nguyen-phillip · 2017-08-14T21:09:47Z

Docs/introduction/syncing-overview.md

+
+#### Flow of a full sync
+
+This is a high level overview of the syncing process end to end. For a more a more detailed account of each part, see the respective documents. The santaclt binary can be run in one of two modes, daemon and non-daemon. The non-daemon mode does one full sync and exits. This is the typical way a user will interact with Santa, mainly to force a full sync. The daemon mode is used by santad to schedule full syncs, listen for push notifications and upload events.


santaclt --> santactl
add oxford comma? --> .. push notifications, and upload events.

nguyen-phillip · 2017-08-14T21:14:14Z

Docs/introduction/syncing-overview.md

+
+This is a high level overview of the syncing process end to end. For a more a more detailed account of each part, see the respective documents. The santaclt binary can be run in one of two modes, daemon and non-daemon. The non-daemon mode does one full sync and exits. This is the typical way a user will interact with Santa, mainly to force a full sync. The daemon mode is used by santad to schedule full syncs, listen for push notifications and upload events.
+
+0. When the santad process starts up, it looks for a `SyncBaseURL` key/value in the config. If one exists it will `fork()` and `exec()` `santactl sync —-daemon`. Before the new process calls `exec()`, all privileges are dropped. All privileged actions are then restricted to the XPC interface made available to santactl by santad. Since this santactl process is running as a daemon it too exports an XPC interface so santad can interact with the process efficiently and securely. To ensure syncing reliability santad will restart the santactl daemon if it is killed or crashes.


insert comma: Since this santactl process is running as a daemon, it too exports ...

nguyen-phillip · 2017-08-14T21:15:46Z

Docs/introduction/syncing-overview.md

+   3. eventupload (optional): If Santa has generated events it will upload them to the sync-server.
+   4. ruledownload: Download rules from the sync-server.
+   5. postflight: Updates timestamps for successful syncs.
+3. After the full sync completes a new full sync will be scheduled, by default this will be 10min. However there are a few ways to manipulate this.


10min --> 10 minutes (here and in rest of document)

tburgin · 2017-08-14T22:34:40Z

@russellhancox PTAL for technical accuracy

russellhancox · 2017-08-15T00:33:03Z

.gitignore

@@ -1,6 +1,8 @@
 .DS_Store
 Build
 santa-*
+!santa-*.md


Any reason not to just exclude *.md?

not really, done

russellhancox · 2017-08-16T18:22:47Z

Docs/deployment/configuration.md

@@ -0,0 +1,118 @@
+# Configuration
+
+Two configuration methods can be used to control Santa: local configuration and a sync server controlled configuration.


I'm not entirely sure how to word it but this isn't 100% accurate - even with a sync server some configuration is only available locally (we don't sync down any of the GUI options, though maybe we should).

Added some clarification.

russellhancox · 2017-08-16T18:24:29Z

Docs/deployment/configuration.md

+| FileChangesRegex*             | String     | The regex of paths to log file changes. Regexes are specified in ICU format. |
+| WhitelistRegex*               | String     | A regex to whitelist if the binary or certificate scopes did not allow execution.  Regexes are specified in ICU format. |
+| BlacklistRegex*               | String     | A regex to blacklist if the binary or certificate scopes did not block an execution.  Regexes are specified in ICU format. |
+| EnablePageZeroProtection      | Bool       | Enable `__PAGEZERO` protection, defaults to YES.  If this flag is set to NO, 32-bit binaries that are missing  the `__PAGEZERO` segment will not be blocked. |


Reverse the description and mention that this can be over-riden by rules.

If this flag is set to YES, 32-bit binaries that are missing the __PAGEZERO segment will be blocked even in MONITOR mode, unless the binary is whitelisted by an explicit rule.

russellhancox · 2017-08-16T18:25:26Z

Docs/deployment/configuration.md

+| BlacklistRegex*               | String     | A regex to blacklist if the binary or certificate scopes did not block an execution.  Regexes are specified in ICU format. |
+| EnablePageZeroProtection      | Bool       | Enable `__PAGEZERO` protection, defaults to YES.  If this flag is set to NO, 32-bit binaries that are missing  the `__PAGEZERO` segment will not be blocked. |
+| MoreInfoURL                   | String     | The URL to open when the user clicks "More Info..." when opening Santa.app.  If unset, the button will not be displayed. |
+| EventDetailURL                | String     | See the Event URL Info section below.    |


See the EventDetailURL section below. Also link to the section (#eventdetailurl)

russellhancox · 2017-08-16T18:27:09Z

Docs/deployment/configuration.md

+| EventDetailURL                | String     | See the Event URL Info section below.    |
+| EventDetailText               | String     | Related to the above property, this string represents the text to show on the button. |
+| UnknownBlockMessage           | String     | In lockdown mode this is the message shown to the user when an unknown binary is blocked. If this message is not configured, a reasonable default is provided. |
+| BannedBlockMessage            | String     | This is the message shown to the user when a binary is blocked because of a rule, if that rule doesn't provide a custom message. If this is not configured, a reasonable  default is provided. |


Remove the comma before "if that rule doesn't" and after "if this is not configured"

russellhancox · 2017-08-16T18:58:37Z

Docs/development/building.md

+
+# Building
+
+Santa makes use of [rake](https://ruby.github.io/rake/) for building and testing Santa. All of the [releases](https://github.com/google/santa/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. macOS 10.13+ will most likely require user consent, even when signed with Google's KEXT signing certificate.


Remove the 10.13 note until we know more.

russellhancox · 2017-08-16T19:00:11Z

Docs/development/building.md

+
+#### 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.


If someone connects lldb to santad they'll deadlock their machine 😃

Added a note

russellhancox · 2017-08-16T19:01:13Z

Docs/introduction/binary-whitelisting-overview.md

+
+#### Background
+
+The decision flow starts in the kernel. The macOS kernel is extensible by way of a kernel extension (KEXT). macOS makes available kernel programming interfaces (KPIs) to be used by a KEXT. Santa utilizes of the Kernel Authorization (Kauth) KPI.. This is a very powerful and verbose interface that gives Santa the ability to listen in on most vnode and file systems operations and to take actions, directly or indirectly, on the operations being performed. Still, there are some limitations to Kauth which are pointed out in the santa-driver document. For more information on the santa-driver KEXT see the [santa-driver.md](../details/santa-driver.md) document.


Santa utilizes of the Kernel Authorization (Kauth) KPI..

to:

Santa utilizes the Kernel Authorization (Kauth) KPI.

russellhancox · 2017-08-16T19:01:52Z

Docs/introduction/binary-whitelisting-overview.md

+   * If Kauth receives a deny, it will stop the `execve()` from taking place. 
+   * If Kauth receives an allow, it will defer the decision. If there are other Kauth listeners, they also have a chance deny or defer.
+3. If there is no entry for the `vnode_id` in the cache a few actions occur:
+   * Santa-driver hands off the decision making to santad.


s/Santa-driver/santa-driver/

russellhancox · 2017-08-16T19:02:36Z

Docs/introduction/binary-whitelisting-overview.md

+   * If Kauth receives an allow, it will defer the decision. If there are other Kauth listeners, they also have a chance deny or defer.
+3. If there is no entry for the `vnode_id` in the cache a few actions occur:
+   * Santa-driver hands off the decision making to santad.
+   * A new entry is created in the cache for the `vnode_id` with a special value of `ACTION_REQUEST_BINARY`.  This is used as a placeholder until the decision from santad comes back. If another process tries to `execve()` the same `vnode_id`, santa-driver will have that thread wait for the in-flight decision from santad. All subsequent `execve()`s for the same `vnode_id` will use the decision in the cache as explained in #2, until the cache is invalidated. See the [santa-driver.md](../details/santa-driver.md) document for more details on the cache invalidation.


Probably also worth pointing out that if the file is written to while any of the threads are waiting for a response the request_binary entry is removed, forcing the decision-making process to be restarted

tburgin

PTAL

tburgin · 2017-08-17T16:36:57Z

.gitignore

@@ -1,6 +1,8 @@
 .DS_Store
 Build
 santa-*
+!santa-*.md


not really, done

tburgin · 2017-08-17T16:43:50Z

Docs/deployment/configuration.md

@@ -0,0 +1,118 @@
+# Configuration
+
+Two configuration methods can be used to control Santa: local configuration and a sync server controlled configuration.


Added some clarification.

tburgin · 2017-08-17T16:45:20Z

Docs/deployment/configuration.md

+| FileChangesRegex*             | String     | The regex of paths to log file changes. Regexes are specified in ICU format. |
+| WhitelistRegex*               | String     | A regex to whitelist if the binary or certificate scopes did not allow execution.  Regexes are specified in ICU format. |
+| BlacklistRegex*               | String     | A regex to blacklist if the binary or certificate scopes did not block an execution.  Regexes are specified in ICU format. |
+| EnablePageZeroProtection      | Bool       | Enable `__PAGEZERO` protection, defaults to YES.  If this flag is set to NO, 32-bit binaries that are missing  the `__PAGEZERO` segment will not be blocked. |


tburgin · 2017-08-17T16:46:22Z

Docs/deployment/configuration.md

+| BlacklistRegex*               | String     | A regex to blacklist if the binary or certificate scopes did not block an execution.  Regexes are specified in ICU format. |
+| EnablePageZeroProtection      | Bool       | Enable `__PAGEZERO` protection, defaults to YES.  If this flag is set to NO, 32-bit binaries that are missing  the `__PAGEZERO` segment will not be blocked. |
+| MoreInfoURL                   | String     | The URL to open when the user clicks "More Info..." when opening Santa.app.  If unset, the button will not be displayed. |
+| EventDetailURL                | String     | See the Event URL Info section below.    |


tburgin · 2017-08-17T16:47:43Z

Docs/deployment/configuration.md

+| EventDetailURL                | String     | See the Event URL Info section below.    |
+| EventDetailText               | String     | Related to the above property, this string represents the text to show on the button. |
+| UnknownBlockMessage           | String     | In lockdown mode this is the message shown to the user when an unknown binary is blocked. If this message is not configured, a reasonable default is provided. |
+| BannedBlockMessage            | String     | This is the message shown to the user when a binary is blocked because of a rule, if that rule doesn't provide a custom message. If this is not configured, a reasonable  default is provided. |


tburgin · 2017-08-17T17:20:25Z

Docs/development/building.md

+
+# Building
+
+Santa makes use of [rake](https://ruby.github.io/rake/) for building and testing Santa. All of the [releases](https://github.com/google/santa/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. macOS 10.13+ will most likely require user consent, even when signed with Google's KEXT signing certificate.


tburgin · 2017-08-17T17:23:38Z

Docs/development/building.md

+
+#### 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.


Added a note

tburgin · 2017-08-17T17:24:43Z

Docs/introduction/binary-whitelisting-overview.md

+
+#### Background
+
+The decision flow starts in the kernel. The macOS kernel is extensible by way of a kernel extension (KEXT). macOS makes available kernel programming interfaces (KPIs) to be used by a KEXT. Santa utilizes of the Kernel Authorization (Kauth) KPI.. This is a very powerful and verbose interface that gives Santa the ability to listen in on most vnode and file systems operations and to take actions, directly or indirectly, on the operations being performed. Still, there are some limitations to Kauth which are pointed out in the santa-driver document. For more information on the santa-driver KEXT see the [santa-driver.md](../details/santa-driver.md) document.


tburgin · 2017-08-17T17:25:11Z

Docs/introduction/binary-whitelisting-overview.md

+   * If Kauth receives a deny, it will stop the `execve()` from taking place. 
+   * If Kauth receives an allow, it will defer the decision. If there are other Kauth listeners, they also have a chance deny or defer.
+3. If there is no entry for the `vnode_id` in the cache a few actions occur:
+   * Santa-driver hands off the decision making to santad.


tburgin · 2017-08-17T17:28:12Z

Docs/introduction/binary-whitelisting-overview.md

+   * If Kauth receives an allow, it will defer the decision. If there are other Kauth listeners, they also have a chance deny or defer.
+3. If there is no entry for the `vnode_id` in the cache a few actions occur:
+   * Santa-driver hands off the decision making to santad.
+   * A new entry is created in the cache for the `vnode_id` with a special value of `ACTION_REQUEST_BINARY`.  This is used as a placeholder until the decision from santad comes back. If another process tries to `execve()` the same `vnode_id`, santa-driver will have that thread wait for the in-flight decision from santad. All subsequent `execve()`s for the same `vnode_id` will use the decision in the cache as explained in #2, until the cache is invalidated. See the [santa-driver.md](../details/santa-driver.md) document for more details on the cache invalidation.


russellhancox · 2017-08-17T18:23:48Z

Docs/details/rules.md

@@ -8,7 +8,7 @@ Binary rules use the SHA-256 hash of the entire binary as an identifier. This is

 ##### Certificate Rules

-Certificate rules are formed from the SHA-256 fingerprint of an x509 leaf signing certificate. This is a powerful rule type that has a much broader reach than an individual binary rule . A signing certificate can sign any number of binaries. Whitelisting or blacklisting just a few key signing certificates can cover the bulk of an average user's binaries. The leaf signing certificate is the only part of the chain that is evaluated. Though the whole chain is available for viewing.
+Certificate rules are formed from the SHA-256 fingerprint of an x.509 leaf signing certificate. This is a powerful rule type that has a much broader reach than an individual binary rule . A signing certificate can sign any number of binaries. Whitelisting or blacklisting just a few key signing certificates can cover the bulk of an average user's binaries. The leaf signing certificate is the only part of the chain that is evaluated. Though the whole chain is available for viewing.


s/x.509/X.509

russellhancox · 2017-08-17T18:26:12Z

Docs/details/ipc.md

+
+![Santa IPC](santa_ipc.png)
+
+#####SNTXPCConnection and two way communication 


Missing space after the ######

russellhancox · 2017-08-17T18:28:19Z

Docs/deployment/configuration.md

 | MoreInfoURL                   | String     | The URL to open when the user clicks "More Info..." when opening Santa.app.  If unset, the button will not be displayed. |
-| EventDetailURL                | String     | See the Event URL Info section below.    |
+| EventDetailURL                | String     | See the [EventDetailURL](#EventDetailURL) section below. |


The capitalization of the anchor matters, it's #eventdetailurl

russellhancox · 2017-08-17T18:29:46Z

Docs/development/building.md

+
+Note: santa-driver (the kernel extension) cannot be debugged by attaching with Xcode.
+
+Note: Attaching to santad with breakpoints in the decision making codepath will deadlock your machine.


Not even setting breakpoints, just attaching will deadlock. Attaching 'interrupts' the process, stopping all threads from proceeding and dropping you into interactive mode, but now now thing is processing, the terminal will freeze and you won't be able to resume.

Only when using lldb directly. When using Xcode to attach it let's the process continue and only stops threads with breakpoints.

tburgin

PTAL

tburgin · 2017-08-17T18:57:25Z

Docs/details/ipc.md

+
+![Santa IPC](santa_ipc.png)
+
+#####SNTXPCConnection and two way communication 


tburgin · 2017-08-17T18:58:44Z

Docs/development/building.md

+
+Note: santa-driver (the kernel extension) cannot be debugged by attaching with Xcode.
+
+Note: Attaching to santad with breakpoints in the decision making codepath will deadlock your machine.


Only when using lldb directly. When using Xcode to attach it let's the process continue and only stops threads with breakpoints.

* Docs: Start of Santa Docs * Docs: /exec()/execve()/ * Docs: /sync-server/sync server/ * Docs: review updates

Docs: Start of Santa Docs

eb49661

russellhancox reviewed Aug 11, 2017

View reviewed changes

Coleeb reviewed Aug 14, 2017

View reviewed changes

tburgin added 2 commits August 14, 2017 11:48

Docs: /exec()/execve()/

d46dfad

Docs: /sync-server/sync server/

a18c57d

nguyen-phillip reviewed Aug 14, 2017

View reviewed changes

Docs: review updates

7c867a7

russellhancox suggested changes Aug 16, 2017

View reviewed changes

Docs: review updates

98bde28

tburgin commented Aug 17, 2017

View reviewed changes

russellhancox suggested changes Aug 17, 2017

View reviewed changes

Docs: review updates

fbbea4c

tburgin commented Aug 17, 2017

View reviewed changes

Docs: review updates

dbf2005

russellhancox approved these changes Aug 17, 2017

View reviewed changes

tburgin merged commit 4238553 into google:master Aug 17, 2017

nguyen-phillip pushed a commit to nguyen-phillip/santa that referenced this pull request Aug 21, 2017

Docs: Start of Santa Docs (google#192)

002c644

* Docs: Start of Santa Docs * Docs: /exec()/execve()/ * Docs: /sync-server/sync server/ * Docs: review updates

nguyen-phillip pushed a commit to nguyen-phillip/santa that referenced this pull request Aug 21, 2017

Docs: Start of Santa Docs (google#192)

35df64a

* Docs: Start of Santa Docs * Docs: /exec()/execve()/ * Docs: /sync-server/sync server/ * Docs: review updates

dskfh pushed a commit to dskfh/santa that referenced this pull request Jul 17, 2020

Docs: Start of Santa Docs (google#192)

c3008c6

* Docs: Start of Santa Docs * Docs: /exec()/execve()/ * Docs: /sync-server/sync server/ * Docs: review updates

		@@ -0,0 +1,154 @@
		# Events

		Events are a notion core to how Santa interacts with a sync-server. Events are generated when there is a blocked `exec()` while in lockdown or monitor mode. Events are also generated in monitor mode for an `exec()` that was allowed to run, but would have been blocked in lockdown mode. This allows an admin to roll out Santa to their macOS fleet in monitor mode, but still collect meaningful data. The events collected while in monitor can be used to build a fairly comprehensive whitelist of signing certificates and binaries before switching the fleet to lockdown mode.

		@@ -0,0 +1,113 @@
		# Configuration

		There are two types of configurations that can be utilized to control Santa. The first is a local configuration. The second is a sync-server controlled configuration.


		###### Archived Object

		Events are temporarily stored in a sqlite3 database `/var/db/santa/events.db` until they uploaded to the sync server. They are stored in the [NSKeyedArchiver](https://developer.apple.com/documentation/foundation/nskeyedarchiver?language=objc) format. Here is an example of a Firefox event in the events.db awaiting upload.


		The santad and Santa (GUI) processes are both started and kept alive by launchd as LaunchDaemon and LaunchAgent respectively. This means santad runs as root, and Santa (GUI) runs as the console user. There can be multiple Santa (GUI) process running, one per logged in user.

		When using a sync-server the santactl process is started by santad with a `fork()` and `exec()` of `santactl sync —-daemon`. Before the new process starts, all privileged are dropped. So santactl runs as nobody.


		When using a sync-server the santactl process is started by santad with a `fork()` and `exec()` of `santactl sync —-daemon`. Before the new process starts, all privileged are dropped. So santactl runs as nobody.

		The santabs process is started by launchd by way of an XPC service connection from santad. XPC services inherit their initiator's privileges so santabs runs as root.


		#### Flow of a full sync

		This is a high level overview of the syncing process end to end. For a more a more detailed account of each part, see the respective documents. The santaclt binary can be run in one of two modes, daemon and non-daemon. The non-daemon mode does one full sync and exits. This is the typical way a user will interact with Santa, mainly to force a full sync. The daemon mode is used by santad to schedule full syncs, listen for push notifications and upload events.


		#### santactl XPC interface

		When running as a daemon the santactl process makes available an XPC interface for use by santad. This allows santad to send blocked binary or bundle events directly to santactl for immediate upload to the sync-server. Doing so makes for a smoother user experience. The binary that was blocked on macOS is immediately available for viewing or handling on the sync-server.


		##### Lockdown mode

		Running Santa in Lockdown mode will stop any unknown binaries from running. Meaning, if the binary has no rules or scopes that apply, it will be blocked.


		##### Built in rules

		To avoid blocking any Apple system binaries or Santa binaries, santad will create 2 immutable certificate rules at startup.


		##### Kauth

		santa-driver utilizes two Kauth scopes `KAUTH_SCOPE_VNODE` and `KAUTH_SCOPE_FILEOP `. It registers itself with the Kauth API by calling `kauth_listen_scope()` for each scope. This function takes three arguments.


		The santabs process is an XPC service for the santa-driver.kext bundle, meaning only binaries within that bundle can launch santabs. It will be launched with with whatever privileges the calling process is running as. Currently santad is the only caller of santabs, so santabs runs as root.

		#####Events


		The sync command is covered in the [syncing.md](syncing.md) document.

		#####Debug Commands


		This may be the most complex part of Santa. It really has two types of work that is does. Firstly it contains all of the code and functionality for syncing with a sync-server. The details of which are covered in the [syncing.md](syncing.md) document. This document will cover the status work that santactl performs.

		The santactl binary can be used to view the state and configuration of Santa as a whole. It can also inspect individual files. When running without a sync-server it also a supported method of managing the rules database.


		At this point santa-driver is loaded and running in the kernel but is allowing all executions and not sending any messages to santad. Before santad tells santa-driver it is ready to receive messages it needs to setup a few more things.

		The rule and event databases are now initialized. Followed by connection establishment to the Santa (GUI) and santactl sync daemon. The config file is processed and now santad knows what mode it is running in.


		#### 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 configured to allow non Apple KEXT signing certificates.


		#### 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.


		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 a XPC service that launchd scopes to hosting bundle. Thus the need for the `Attach to Process by PID or Name…` technique. See the [ipc](../details/ipc.md) document for for details.


		For those who want even more details on how Santa works under the hood, this section is for you.

		######Binaries


		This is a high level overview of the syncing process end to end. For a more a more detailed account of each part, see the respective documents. The santaclt binary can be run in one of two modes, daemon and non-daemon. The non-daemon mode does one full sync and exits. This is the typical way a user will interact with Santa, mainly to force a full sync. The daemon mode is used by santad to schedule full syncs, listen for push notifications and upload events.

		0. When the santad process starts up, it looks for a `SyncBaseURL` key/value in the config. If one exists it will `fork()` and `exec()` `santactl sync —-daemon`. Before the new process calls `exec()`, all privileges are dropped. All privileged actions are then restricted to the XPC interface made available to santactl by santad. Since this santactl process is running as a daemon it too exports an XPC interface so santad can interact with the process efficiently and securely. To ensure syncing reliability santad will restart the santactl daemon if it is killed or crashes.

		@@ -0,0 +1,118 @@
		# Configuration

		Two configuration methods can be used to control Santa: local configuration and a sync server controlled configuration.

Docs: Start of Santa Docs #192

Docs: Start of Santa Docs #192

Conversation

tburgin commented Aug 11, 2017

russellhancox left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment


		# Building

		Santa makes use of [rake](https://ruby.github.io/rake/) for building and testing Santa. All of the [releases](https://github.com/google/santa/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. macOS 10.13+ will most likely require user consent, even when signed with Google's KEXT signing certificate.


		#### Background

		The decision flow starts in the kernel. The macOS kernel is extensible by way of a kernel extension (KEXT). macOS makes available kernel programming interfaces (KPIs) to be used by a KEXT. Santa utilizes of the Kernel Authorization (Kauth) KPI.. This is a very powerful and verbose interface that gives Santa the ability to listen in on most vnode and file systems operations and to take actions, directly or indirectly, on the operations being performed. Still, there are some limitations to Kauth which are pointed out in the santa-driver document. For more information on the santa-driver KEXT see the [santa-driver.md](../details/santa-driver.md) document.


		![Santa IPC](santa_ipc.png)

		#####SNTXPCConnection and two way communication


		Note: santa-driver (the kernel extension) cannot be debugged by attaching with Xcode.

		Note: Attaching to santad with breakpoints in the decision making codepath will deadlock your machine.