sandbox/mac: add README.md

This doc is heavily inspired by the now-very-outdated writeup on the
website
(https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design/)
which I will shortly delete and replace with a reference to this doc in
the git repo.

Fixed: 40271620
Change-Id: I66568f2348d747691f489dce12f0c6e8309544c7
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5585392
Reviewed-by: Mark Rowe <markrowe@chromium.org>
Commit-Queue: Elly FJ <ellyjones@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1309622}

sandbox/mac/README.md

@@ -0,0 +1,84 @@
+# The Mac Sandbox
+
+The Mac sandbox provides an API for restricting the capabilities of a process.
+The overall design philosophy of the sandbox is documented
+[elsewhere](../docs/design/sandbox.md); this document explains the interface and
+implementation of the Chromium sandbox on macOS.
+
+## Seatbelt
+
+On macOS, the sandbox uses the `sandbox(7)` API, sometimes referred to as
+"Seatbelt". Note that this is different from the "App Sandbox", which is a
+concept that applies to apps installed from the macOS App Store. The sandbox(7)
+sandbox allows for a process to confine itself using a sandbox policy, which is
+a declarative program describing what resources and APIs the process and its
+children are allowed to use.
+
+Those programs look like this:
+
+```
+(allow user-preference-read)
+(allow file-data-read
+  (path (user-homedir-path "/foo")))
+(allow syscall-unix
+  (syscall-number SYS_read)
+  ...)
+```
+
+They are structured as a series of rules that either allow or deny access to
+specific resources. The default stance for sandboxed processes is to give them
+access only to resources they need access to, and so all our sandboxes use:
+
+```
+(deny default)
+```
+
+You can find the production sandbox policies in [../policy/mac](../policy/mac),
+generally named after the process type they are applied to. [The "common"
+policy](../policy/mac/common.sb) contains primitives and variables shared by all
+process types.
+
+Note that processes can still use any file descriptors they already had open,
+even if the sandbox policy would deny them access to those resources now, so a
+common pattern is to first open any needed resources, then apply the sandbox
+policy.
+
+## Writing A Sandbox Policy
+
+Start with a default-deny sandbox, then run your new process type with
+`--enable-sandbox-logging` (from common.sb), which will cause the sandbox to log
+to `syslog(3)` whenever it denies a request. This will give you an empirical
+idea of what resources your process needs to work. With that list in hand, you
+will then need to assess whether:
+
+* The process does need access to that resource, in which case you should grant
+  it in your sandbox policy, or
+* The process does need access to that resource but in a controlled way, in
+  which case you should have it ask the browser process for the access it needs
+  at runtime ("brokering"), or
+* The process doesn't need access to it but is trying to use it anyway, in which
+  case you should fix your code to not do that
+
+Be especially careful if you're calling any Cocoa or AppKit APIs, since these
+sometimes require access to certain resources to work. You should ensure you
+have tested code paths leading to these very thoroughly **with the sandbox
+enabled** - unit tests are not run in the sandbox!
+
+Once you're all done, send your policy to a mamber of
+[//sandbox/policy/mac/OWNERS](../policy/mac/OWNERS) for review.
+
+## Applying The Sandbox
+
+The `--process-type` argument to your subprocess declares what process type it
+is, which dictates what type of sandbox it gets. The full list of types are in
+[sandbox.mojom](../policy/mojom/sandbox.mojom).
+
+Internally, the .sb policy files are compiled via `Seatbelt::Compile`, producing
+a binary representation of the sandbox policy. This is passed over Mojo to
+newly-created processes via `SeatbeltExecClient`; the newly-created process
+receives it using `SeatbeltExecServer`, then applies it in
+`SeatbeltExecServer::ApplySandboxProfile`.
+
+## Debugging The Sandbox
+
+See [//docs/mac/sandbox_debugging.md](../../docs/mac/sandbox_debugging.md).