github/santa
1
1
Fork 0
mirror of https://github.com/google/santa.git synced 2026-04-24 03:00:12 -04:00
Code Issues Packages Projects Releases Wiki Activity

Remove references to santa-driver and the kernel extension from parts of the docs (#762)

Browse Source
This commit is contained in:
Kent Ma
2022-03-21 11:33:45 -04:00
committed by GitHub
parent aadc961429
commit 16f74cb85c
7 changed files with 7 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@@ -4,12 +4,11 @@
<img src="./Source/santa/Resources/Images.xcassets/AppIcon.appiconset/santa-hat-icon-128.png" alt="Santa Icon" />
</p>
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.

4
docs/details/ipc.md
View File

@@ -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

6
docs/details/logs.md
View File

@@ -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"'
````

139
docs/details/santa-driver.md
View File

@@ -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<void *>(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
```

2
docs/details/santabs.md
View File

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

34
docs/details/santactl.md
View File

@@ -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
```

3
docs/index.md
View File

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