| Robert Sesek | 1f23918 | 2020-09-21 22:00:41 | [diff] [blame] | 1 | # Sandbox Debugging |
| 2 | |
| 3 | The [macOS sandbox](../../sandbox/mac/seatbelt_sandbox_design.md) confines |
| 4 | Chrome processes that handle untrustworthy data or code (or both). It works by |
| 5 | blocking the process from accessing OS resources, which can have unintended side |
| 6 | effects that cause compatibility issues or crashes. This document provides |
| 7 | instructions for debugging such issues. |
| 8 | |
| 9 | ## Determining if the Sandbox is Responsible |
| 10 | |
| 11 | The easiest way to test if the sandbox is causing a compatibility issue is to |
| 12 | **temporarily** disable it. This can be done like so: |
| 13 | |
| 14 | open -a 'Google Chrome' --args --no-sandbox |
| 15 | |
| 16 | > Running with `--no-sandbox` is an insecure configuration. After performing the |
| 17 | > test, you should quit Chrome and re-launch normally. |
| 18 | |
| 19 | If the issue still persists, then the issue is not caused by the sandbox. If the |
| 20 | issue no longer occurs, continue to help provide further debugging information. |
| 21 | |
| 22 | ## Debugging the Sandbox |
| 23 | |
| 24 | If you have determined that the sandbox is responsible for the issue, the next |
| 25 | step is to determine what the sandbox is blocking. Sandbox violations are |
| 26 | written to the system log (rather than Chrome's standard output/error), so a |
| 27 | separate command is needed to access the data. |
| 28 | |
| 29 | Start the `log` command to show sandbox violation errors: |
| 30 | |
| 31 | log stream --predicate '((processID == 0) AND (senderImagePath CONTAINS "/Sandbox")) OR (subsystem == "com.apple.sandbox.reporting")' |
| 32 | |
| 33 | Then launch Chrome with with the `--enable-sandbox-logging` argument: |
| 34 | |
| 35 | open -a 'Google Chrome' --args --enable-sandbox-logging |
| 36 | |
| 37 | After you reproduce the issue, quit Chrome and `Ctrl-C` the `log` command to |
| 38 | stop it. Copy and paste the entire output of the log command to a text file and |
| 39 | attach it to the bug tracker. |
| 40 | |
| 41 | You can also access historical sandbox violations using the `log` command like |
| 42 | so: |
| 43 | |
| 44 | log show --start '2020-09-21 17:45:00' --predicate '((processID == 0) AND (senderImagePath CONTAINS "/Sandbox")) OR (subsystem == "com.apple.sandbox.reporting")' |
| 45 | |
| 46 | Adjust the `--start` (and potentially add an `--end` date/time in the same |
| 47 | format) to limit the amount of output. |
| Robert Sesek | 3b731b1 | 2021-04-14 21:54:03 | [diff] [blame] | 48 | |
| 49 | ## Breaking on Sandbox Violations |
| 50 | |
| 51 | In order to determine what is causing a sandbox violation, it can be helpful to |
| 52 | use the `send-signal` action on a sandbox rule, like so: |
| 53 | |
| 54 | (deny file-write (path "/foo/bar") (with send-signal SIGSTOP)) |
| 55 | |
| 56 | That will cause the process to stop until a debugger is attached or *SIGCONT* is |
| 57 | sent to the process. |
