diff --git a/README.md b/README.md index f7fd6e0b0..cf0c5aa7a 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,11 @@ Santa Icon

-Santa is a binary authorization system for macOS. It consists of a system or -kernel extension (depending on the macOS version) that monitors for executions, -a daemon that makes execution decisions based on the contents of a local -database, a GUI agent that notifies the user in case of a block decision -and a command-line utility for managing the system and synchronizing the -database with a server. +Santa is a binary authorization system for macOS. It consists of a system +extension that monitors for executions, a daemon that makes execution decisions +based on the contents of a local database, a GUI agent that notifies the user in +case of a block decision and a command-line utility for managing the system and +synchronizing the database with a server. It is named Santa because it keeps track of binaries that are naughty or nice. diff --git a/docs/details/ipc.md b/docs/details/ipc.md index f25b444b9..4452779c9 100644 --- a/docs/details/ipc.md +++ b/docs/details/ipc.md @@ -10,10 +10,6 @@ Most IPC within Santa is done by way of Apple's to provide client multiplexing, signature validation of connecting clients and forced connection establishment. This is called SNTXPCConnection. -Communication between santad and santa-driver (KEXT) is done with a -[IOUserClient](https://developer.apple.com/documentation/kernel/iouserclient?language=objc) -subclass and IOKit/IOKitLib.h functions. - ##### Who starts who? The santad and Santa (GUI) processes are both started and kept alive by launchd diff --git a/docs/details/logs.md b/docs/details/logs.md index 28daa6252..dfa55bd97 100644 --- a/docs/details/logs.md +++ b/docs/details/logs.md @@ -30,9 +30,3 @@ flight, including messages related to the system extension: ```sh /usr/bin/log show --info --debug --predicate 'senderImagePath CONTAINS[c] "santa"' ``` - -For those still using the kernel extension, you could use a more specific command: - -```sh -/usr/bin/log show --info --debug --predicate 'senderImagePath == "/Library/Extensions/santa-driver.kext/Contents/MacOS/santa-driver"' -```` \ No newline at end of file diff --git a/docs/details/santa-driver.md b/docs/details/santa-driver.md deleted file mode 100644 index 5d2859d28..000000000 --- a/docs/details/santa-driver.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -parent: Details ---- - -# santa-driver - -santa-driver is a macOS -[kernel extension](https://developer.apple.com/library/content/documentation/Darwin/Conceptual/KEXTConcept/KEXTConceptIntro/introduction.html) -(KEXT) that makes use of the -[Kernel Authorization](https://developer.apple.com/library/content/technotes/tn2127/_index.html) -(Kauth) KPI. This allows santa-driver to listen for events and either deny or -defer the decision of those events. The santa-driver acts as an intermediary -layer between Kauth and santad, with some caching to lower the overhead of -decision making. - -##### 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: - -* `const char *scope` -* `kauth_scope_callback_t _callback` -* `void *context` - -It returns a `kauth_listener_t` that is stored for later use, in Santa's case to -stop listening. - -###### KAUTH_SCOPE_VNODE - -Here is how santa-driver starts listening for `KAUTH_SCOPE_VNODE` events. - -```c++ -vnode_listener_ = kauth_listen_scope( - KAUTH_SCOPE_VNODE, vnode_scope_callback, reinterpret_cast(this)); -``` - -The function `vnode_scope_callback` is called for every vnode event. There are -many types of vnode events, they complete list can be viewed in the kauth.h. -There are many types of vnode events, the complete list can be viewed in -kauth.h. Santa is only concerned with regular files generating -`KAUTH_VNODE_EXECUTE` [1] and `KAUTH_VNODE_WRITE_DATA` events. All non-regular -files and unnecessary vnode events are filtered out. - -Here is how santa-driver stops listening for `KAUTH_SCOPE_VNODE` events: - -```c++ -kauth_unlisten_scope(vnode_listener_); -``` - -[1] `KAUTH_VNODE_EXECUTE` events that do not have the `KAUTH_VNODE_ACCESS` -advisory bit set. - -###### KAUTH_SCOPE_FILEOP - -Santa also listens for file operations, this is mainly used for logging [1] and -cache invalidation. - -* `KAUTH_FILEOP_DELETE`, `KAUTH_FILEOP_RENAME`, `KAUTH_FILEOP_EXCHANGE` and - `KAUTH_FILEOP_LINK` are logged -* `KAUTH_FILEOP_EXEC` is used to log `execve()`s. Since the - `KAUTH_VNODE_EXECUTE` is used to allow or deny an `execve()` the process - arguments have not been setup yet. Since `KAUTH_FILEOP_EXEC` is triggered - after an `execve()` it is used to log the `execve()`. - -[1] `KAUTH_FILEOP_CLOSE` is used to invalidate that file's representation in the -cache. If a file has changed it needs to be re-evalauted. This is particularly -necessary for files that were added to the cache with an action of allow. - -##### Driver Interface - -santa-driver implements an -[IOUserClient](https://developer.apple.com/documentation/kernel/iouserclient?language=objc) -subclass and santad interacts with it through IOKit/IOKitLib.h functions. - -[//]: # "TODO(bur, rah) Flesh out the details" - -##### Cache - -To aid in performance, santa-driver utilizes a caching system to hold the state -of all observed `execve()` events. - -###### Key - -The key is a `uint64_t`. The top 32 bits hold the filesystem ID, while the -bottom 32 bits hold the file unique ID. Together we call this the vnode_id. - -```c++ -uint64_t vnode_id = (((uint64_t)fsid << 32) | fileid); -``` - -###### Value - -The value is a `uint64_t` containing the action necessary, along with the -decision timestamp. The action is stored in the top 8 bits. The decision -timestamp is stored in the remaining 56 bits. - -```c++ -santa_action_t action = (santa_action_t)(cache_val >> 56); -uint64_t decision_time = (cache_val & ~(0xFF00000000000000)); -``` - -The possible actions are: - -| Actions | Expiry Time | Description | -| ----------------------- | ---------------- | ------------------------------ | -| `ACTION_REQUEST_BINARY` | None | Awaiting an allow or deny | -| | | decision from santad. | -| `ACTION_RESPOND_ALLOW` | None | Allow the `execve()` | -| `ACTION_RESPOND_DENY` | 500 milliseconds | Deny the `execve()`, but | -| | | re-evalaute after 500 | -| | | milliseconds. If someone is | -| | | trying to run a banned binary | -| | | continually every millisecond | -| | | for example, only 2 evaluation | -| | | requests to santad for would | -| | | occur per second. This | -| | | mitigates a denial of service | -| | | type attack on santad. | - -###### Invalidation - -Besides the expiry time for individual entries, the entire cache will be cleared -if any of the following events takes place: - -* Addition of a block rule -* Change to the blocked path regex -* Cache fills up. This defaults to `5000` entries for the root volume and - `500` for all other mounted volumes. - -To view the current kernel cache count see the "Kernel info" section of -`santactl status`: - -```sh -⇒ santactl status ->>> Kernel Info - Root cache count | 107 - Non-root cache count | 0 -``` diff --git a/docs/details/santabs.md b/docs/details/santabs.md index 6ffe01ba9..d5e6c1307 100644 --- a/docs/details/santabs.md +++ b/docs/details/santabs.md @@ -4,7 +4,7 @@ parent: Details # santabs -The santabs process is an XPC service for the santa-driver.kext bundle, meaning +The santabs process is an XPC service for the santad bundle, meaning only binaries within that bundle can launch santabs. It will be launched with the same privileges as its calling process. Currently, santad is the only caller of santabs, so santabs runs as root. diff --git a/docs/details/santactl.md b/docs/details/santactl.md index 5570f4691..62d97e950 100644 --- a/docs/details/santactl.md +++ b/docs/details/santactl.md @@ -80,7 +80,6 @@ To view all of the component versions `santactl version` ```sh ⇒ santactl version -santa-driver | 0.9.19 santad | 0.9.19 santactl | 0.9.19 SantaGUI | 0.9.19 @@ -91,7 +90,6 @@ Again, a JSON version is available `santactl version --json` ```sh ⇒ santactl version --json { - "santa-driver" : "0.9.19", "santad" : "0.9.19", "SantaGUI" : "0.9.19", "santactl" : "0.9.19" @@ -408,35 +406,3 @@ BundleID: com.ridiculousfish.HexFiend See the [santabs.md](santabs.md) document for more information on bundles and bundle hashes. - -##### checkcache - -This is used to check if a particular file is apart of santa-driver's kernel -cache. Mainly for debugging purposes. - -```sh -⇒ santactl checkcache /usr/bin/yes -File does not exist in cache -⇒ /usr/bin/yes -y -y -y -y -y -^C -⇒ santactl checkcache /usr/bin/yes -File exists in [allowlist] kernel cache -``` - -##### flushcache - -This can be used to flush santa-driver's kernel cache, as shown here. - -```sh -⇒ santactl checkcache /usr/bin/yes -File exists in [allowlist] kernel cache -⇒ sudo santactl flushcache -Cache flush requested -⇒ santactl checkcache /usr/bin/yes -File does not exist in cache -``` diff --git a/docs/index.md b/docs/index.md index d2f44f3db..a9d89d6f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,8 +35,7 @@ For those who want even more details on how Santa works under the hood, this sec There are five main components that make up Santa whose core functionality is described in snippets below. For additional detail on each component, visit their respective pages. These quick descriptions do not encompass all the jobs performed by each component, but do provide a quick look at the basic functionality utilized to achieve the goal of binary authorization. -* [santa-driver](details/santa-driver.md): A macOS kernel extension that participates in `execve()` decisions. -* [santad](details/santad.md): A user-land root daemon that makes decisions on behalf of santa-driver requests. +* [santad](details/santad.md): A user-land root daemon that makes decisions. * [santactl](details/santactl.md): A user-land anonymous daemon that communicates with a sync server for configurations and policies. santactl can also be used by a user to manually configure Santa when using the local configuration. * [santa-gui](details/santa-gui.md): A user-land GUI daemon that displays notifications when an `execve()` is blocked. * [santabs](details/santabs.md): A user-land root daemon that finds Mach-O binaries within a bundle and creates events for them.