Docs: Switch themes, update config, fix redirect (#583)

google · Aug 18, 2021 · 256836d · 256836d
1 parent b117d81
commit 256836d
Show file tree

Hide file tree

Showing 23 changed files with 132 additions and 21 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,4 +1,15 @@
-theme: jekyll-theme-cayman
+title: Santa
+remote_theme: pmarsceill/just-the-docs
+
+nav_sort: case_insensitive
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/google/santa"
+gh_edit_branch: "main"
 
 plugins:
     - jekyll-redirect-from

diff --git a/docs/deployment/configuration.md b/docs/deployment/configuration.md
@@ -1,10 +1,19 @@
-# Important
-
-Santa v0.9.21 has moved to using an Apple [Configuration Profile](https://developer.apple.com/library/content/featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html) to manage the local configuration. The old config file (`/var/db/santa/config.plist`) is no longer used.
+---
+title: Configuration
+parent: Deployment
+---
 
 # Configuration
 
-Two configuration methods can be used to control Santa: a local configuration profile and a sync server controlled configuration. There are certain options that can only be controlled with a local configuration profile and others that can only be controlled with a sync server controlled configuration. Additionally, there are options that can be controlled by both.
+Santa is configured using Apple
+[Configuration Profiles](https://developer.apple.com/library/content/featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html)
+to manage the local configuration.
+
+Two configuration methods can be used to control Santa: a local configuration
+profile and a sync server controlled configuration. There are certain options
+that can only be controlled with a local configuration profile and others that
+can only be controlled with a sync server controlled configuration.
+Additionally, there are options that can be controlled by both.
 
 ## Local Configuration Profile
 
@@ -39,13 +48,16 @@ Two configuration methods can be used to control Santa: a local configuration pr
 | EventLogPath                  | String     | If EventLogType is set to filelog, EventLogPath will provide the path to save logs. Defaults to /var/db/santa/santa.log. If you change this value ensure you also update com.google.santa.newsyslog.conf with the new path.        |
 | EnableMachineIDDecoration     | Bool       | If YES, this appends the MachineID to the end of each log line. Defaults to NO.       |
 
-*overridable by the sync server: run `santactl status` to check the current running config
+*overridable by the sync server: run `santactl status` to check the current
+running config
 
 ##### EventDetailURL
 
-When the user gets a block notification, a button can be displayed which will take them to a web page with more information about that event.
+When the user gets a block notification, a button can be displayed which will
+take them to a web page with more information about that event.
 
-This property contains a kind of format string to be turned into the URL to send them to. The following sequences will be replaced in the final URL:
+This property contains a kind of format string to be turned into the URL to send
+them to. The following sequences will be replaced in the final URL:
 
 | Key          | Description                              |
 | ------------ | ---------------------------------------- |
@@ -60,7 +72,10 @@ For example: `https://sync-server-hostname/%machine_id%/%file_sha%`
 
 ##### Example Configuration Profile
 
-Here is an example of a configuration profile that could be set. It was generated with Tim Sutton's great [mcxToProfile](https://github.com/timsutton/mcxToProfile) tool. A copy is also available [here](com.google.santa.example.mobileconfig).
+Here is an example of a configuration profile that could be set. It was
+generated with Tim Sutton's great
+[mcxToProfile](https://github.com/timsutton/mcxToProfile) tool. A copy is also
+available [here](com.google.santa.example.mobileconfig).
 
 A few key points to when creating your configuration profile:
 
@@ -154,10 +169,10 @@ A few key points to when creating your configuration profile:
 
 ```
 
-Configuration profiles have a `.mobileconfig` file extension. There are many ways to install configuration profiles:
+Configuration profiles have a `.mobileconfig` file extension. There are a couple
+ways to install configuration profiles:
 
 * Double click them in Finder
-* Use the `/usr/bin/profiles` tool
 * Use an MDM
 
 ## Sync server Provided Configuration

diff --git a/docs/deployment/index.md b/docs/deployment/index.md
@@ -0,0 +1,6 @@
+---
+title: Deployment
+has_children: true
+nav_order: 3
+---
+
diff --git a/docs/details/events.md b/docs/details/events.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Events
 
 Events are a defined set of data, core to how Santa interacts with a sync

diff --git a/docs/details/index.md b/docs/details/index.md
@@ -0,0 +1,5 @@
+---
+title: Details
+has_children: true
+nav_order: 4
+---
diff --git a/docs/details/ipc.md b/docs/details/ipc.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Interprocess Communication (IPC)
 
 Most IPC within Santa is done by way of Apple's

diff --git a/docs/details/logs.md b/docs/details/logs.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Logs
 
 Santa currently logs to `/var/db/santa/santa.log` by default. All executions and

diff --git a/docs/details/mode.md b/docs/details/mode.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Mode
 
 Santa can run in one of two modes, Lockdown or Monitor. To check the current

diff --git a/docs/details/rules.md b/docs/details/rules.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Rules
 
 Rules provide the primary evaluation mechanism for allowing and blocking

diff --git a/docs/details/santa-driver.md b/docs/details/santa-driver.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # santa-driver
 
 santa-driver is a macOS

diff --git a/docs/details/santa-gui.md b/docs/details/santa-gui.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Santa GUI
 
 The Santa GUI process is pretty simple. It's only job is the display user GUI

diff --git a/docs/details/santabs.md b/docs/details/santabs.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # santabs
 
 The santabs process is an XPC service for the santa-driver.kext bundle, meaning

diff --git a/docs/details/santactl.md b/docs/details/santactl.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # santactl
 
 This may be the most complex part of Santa. It does two types of work:

diff --git a/docs/details/santad.md b/docs/details/santad.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # santad
 
 The santad process does the heavy lifting when it comes to making decisions

diff --git a/docs/details/scopes.md b/docs/details/scopes.md
@@ -1,3 +1,7 @@
+---
+parent: Details
+---
+
 # Scopes
 
 In addition to rules, Santa can allow or block based on scopes. Currently, only

diff --git a/docs/development/building.md b/docs/development/building.md
@@ -1,7 +1,12 @@
+---
+title: Building
+parent: Development
+---
+
 # Building
 
 Santa uses [Bazel](https://bazel.build) for building, testing and releases. The
-`master` branch on GitHub is the source-of-truth with features developed in
+`main` branch on GitHub is the source-of-truth with features developed in
 personal forks.
 
 #### Cloning
@@ -13,7 +18,7 @@ git clone https://github.com/google/santa
 cd santa
 ```
 
-The above command will default to using the `master` branch. All releases are
+The above command will default to using the `main` branch. All releases are
 built from tagged commits, so if you wanted to build, run or test a specific
 release you can checkout that tag:
 

diff --git a/docs/development/contributing.md b/docs/development/contributing.md
@@ -1,3 +1,8 @@
+---
+title: Contributing
+parent: Development
+---
+
 Want to contribute? Great! First, read this page (including the small print at the end).
 
 ### Before you contribute

diff --git a/docs/development/index.md b/docs/development/index.md
@@ -0,0 +1,5 @@
+---
+title: Development
+has_children: true
+nav_order: 5
+---
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,9 @@
-# Welcome to the Santa Docs
+---
+title: Home
+nav_order: 1
+---
+
+# Welcome
 
 Santa is a binary authorization system for macOS. Here you will find the
 documentation for understanding how Santa works, how to deploy it and how to
@@ -33,7 +38,7 @@ There are five main components that make up Santa whose core functionality is de
 * [santad](details/santad.md): A user-land root daemon that makes decisions on behalf of santa-driver requests.
 * [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. 
+* [santabs](details/santabs.md): A user-land root daemon that finds Mach-O binaries within a bundle and creates events for them.
 
 ###### Concepts
 

diff --git a/docs/introduction/binary-authorization-overview.md b/docs/introduction/binary-authorization-overview.md
@@ -1,6 +1,9 @@
---------------------------------------------------------------------------------
-
-## redirect_from: "/introduction/binary-whitelisting-overview.md"
+---
+title: Binary Authorization
+parent: Intro
+redirect_from:
+  - /introduction/binary-whitelisting-overview
+---
 
 # Binary Authorization Overview
 

diff --git a/docs/introduction/index.md b/docs/introduction/index.md
@@ -0,0 +1,5 @@
+---
+title: Intro
+has_children: true
+nav_order: 2
+---
diff --git a/docs/introduction/syncing-overview.md b/docs/introduction/syncing-overview.md
@@ -1,3 +1,8 @@
+---
+title: Syncing
+parent: Intro
+---
+
 # Syncing Overview
 
 #### Background

diff --git a/docs/theme/Santa.css b/docs/theme/Santa.css