Skip to content
This repository was archived by the owner on Feb 5, 2025. It is now read-only.

Doc improvements #1431

Open
lid wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Doc improvements #1431

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2ee3079
Update file-access-auth.md
lid Aug 27, 2024
aafd7fc
Fix typo
lid Aug 28, 2024
e0a0d0b
EnableSilentMode & EnableSilentTTYMode are boolean
lid Sep 5, 2024
cfe147a
Add platform binary example
lid Sep 6, 2024
80b0b0b
Add more FAA examples
lid Sep 6, 2024
d52167e
Update file-access-auth.md
lid Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/deployment/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ also known as mobileconfig files, which are in an Apple-specific XML format.
| FileChangesRegex\* | String | The regex of paths to log file changes. Regexes are specified in ICU format. |
| AllowedPathRegex\* | String | A regex to allow if the binary, certificate, or Team ID scopes did not allow/block execution. Regexes are specified in ICU format. |
| BlockedPathRegex\* | String | A regex to block if the binary, certificate, or Team ID scopes did not allow/block an execution. Regexes are specified in ICU format. |
| FileChangesPrefixFilters | Array | Array of path prefix strings. When an event is logged, if the target path (e.g. the file being written/removed/etc ) matches a prefix it will not be loggged. |
| FileChangesPrefixFilters | Array | Array of path prefix strings. When an event is logged, if the target path (e.g. the file being written/removed/etc ) matches a prefix it will not be logged. |
| EnableBadSignatureProtection | Bool | If true, binaries with a bad signing chain will be blocked even in MONITOR mode, **unless** the binary is allowed by an explicit rule. Defaults to false. |
| EnablePageZeroProtection | Bool | If true, 32-bit binaries that are missing the `__PAGEZERO` segment will be blocked even in MONITOR mode, **unless** the binary is allowed by an explicit rule. Defaults to true. |
| EnableSilentMode | Bool | If true, Santa will not post any GUI notifications. This can be a very confusing experience for users, use with caution. Defaults to false. |
Expand Down
33 changes: 29 additions & 4 deletions docs/deployment/file-access-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,16 @@ To enable this feature, the `FileAccessPolicyPlist` key in the main [Santa confi
| `AllowReadAccess` | `Options` | Boolean | No | v2023.1+ | If true, indicates the rule will **not** be applied to actions that are read-only access (e.g., opening a watched path for reading, or cloning a watched path). If false, the rule will apply both to read-only access and access that could modify the watched path. (Default = `false`) |
| `AuditOnly` | `Options` | Boolean | No | v2023.1+ | If true, operations violating the rule will only be logged. If false, operations violating the rule will be denied and logged. (Default = `true`) |
| `InvertProcessExceptions` | `Options` | Boolean | No | v2023.5+ | If true, logic is inverted for the list of processes defined by the `Processes` key such that the list becomes the set of processes that will be denied or allowed but audited. (Default = `false`) |
| `EnableSilentMode` | `Options` | String | No | v2023.7+ | If true, Santa will not display a GUI dialog when this rule is violated. |
| `EnableSilentTTYMode` | `Options` | String | No | v2023.7+ | If true, Santa will not post a message to the controlling TTY when this rule is violated. |
| `EnableSilentMode` | `Options` | Boolean | No | v2023.7+ | If true, Santa will not display a GUI dialog when this rule is violated. |
| `EnableSilentTTYMode` | `Options` | Boolean | No | v2023.7+ | If true, Santa will not post a message to the controlling TTY when this rule is violated. |
| `EventDetailURL` | `Options` | String | No | v2023.8+ | Rule-specific URL that overrides the top-level `EventDetailURL`. |
| `EventDetailText` | `Options` | String | No | v2023.8+ | Rule-specific button text that overrides the top-level `EventDetailText`. |
| `Processes` | `<Name>` | Array | No | v2023.1+ | A list of dictionaries defining processes that are allowed to access paths matching the globs defined with the `Paths` key. For a process performing the operation to be considered a match, it must match all defined attributes of at least one entry in the list. |
| `BinaryPath` | `Processes` | String | No | v2023.1+ | A path literal that an instigating process must be executed from. |
| `TeamID` | `Processes` | String | No | v2023.1+ | Team ID of the instigating process. |
| `CertificateSha256` | `Processes` | String | No | v2023.1+ | SHA256 of the leaf certificate of the instigating process. |
| `CDHash` | `Processes` | String | No | v2023.1+ | CDHash of the instigating process. |
| `SigningID` | `Processes` | String | No | v2023.1+ | Signing ID of the instigating process. |
| `SigningID` | `Processes` | String | No | v2023.1+ | Signing ID of the instigating process. Note that unlike in binary authorization, the Signing ID for file access authorization is specified separately from the Team ID; see the example below. |
| `PlatformBinary` | `Processes` | Boolean | No | v2023.2+ | Whether or not the instigating process is a platform binary. |

### EventDetailURL
Expand Down Expand Up @@ -77,7 +77,10 @@ This is an example configuration conforming to the specification outlined above:
<dict>
<key>Paths</key>
<array>
<!-- restrict access to foo in all user directories -->
<string>/Users/*/foo</string>

<!-- restrict access to ~/tmp/foo, ~/tmp/foo2, ~/tmp/foo/bar, for all user directories -->
<dict>
<key>Path</key>
<string>/Users/*/tmp/foo</string>
Expand All @@ -96,7 +99,27 @@ This is an example configuration conforming to the specification outlined above:
</dict>
<key>Processes</key>
<array>
<dict>
<!-- Platform binaries use a separate key that, rather than the `platform:com.apple.ls` format used in binary authorization rules -->
<key>PlatformBinary</key>
<true/>
<key>SigningID</key>
<string>com.apple.ls</string>
</dict>
<dict>
<!-- Signing IDs are specified differently than in binary authorization rules, note the separate TeamID key -->
<key>TeamID</key>
<string>EQHXZ8M8AV</string>
<key>SigningID</key>
<string>com.google.Chrome</string>
</dict>
<dict>
<!-- Allow the Slack Team ID -->
<key>TeamID</key>
<string>BQR82RBBHL</string>
</dict>
<dict>
<!-- Allow the binary at the path, AND require the TeamID specified -->
<key>BinaryPath</key>
<string>/usr/local/bin/my_foo_writer</string>
<key>TeamID</key>
Expand Down Expand Up @@ -138,7 +161,9 @@ The following table demonstrates which rule will be applied for operations on a

Configured path globs represent a point in time. That is, path globs are expanded when a configuration is applied to generate the set of monitored paths. This is not a "live" representation of the filesystem. For instance, if a new file or directory is added that would match a glob after the configuration is applied, it is not immediately monitored.

Within the main Santa configuration, the `FileAccessPolicyUpdateIntervalSec` key controls how often any changes to the configuration are applied as well as re-evaluating configured path globs to match the current state of the filesystem.
Within the main Santa configuration, the `FileAccessPolicyUpdateIntervalSec` key controls how often any changes to the configuration are applied as well as re-evaluating configured path globs to match the current state of the filesystem. This has a minimum value of 15 seconds.

`**` syntax is not supported, only `*` is supported for wildcards.

### Prefix and Glob Path Evaluation

Expand Down