Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pre-commit #14

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add pre-commit #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fe51df
Add config file (with hooks)
radudum10 Sep 11, 2022
ed969a1
Update README
radudum10 Sep 11, 2022
6480ed6
Run pre-commit on all files
radudum10 Sep 11, 2022
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
15 changes: 15 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/psf/black
rev: 22.8.0
hooks:
- id: black
- repo: https://github.com/igorshubovych/markdownlint-cli
rev: v0.32.2
hooks:
- id: markdownlint
199 changes: 154 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,88 +1,197 @@
# SandBlaster: Reversing the Apple Sandbox

SandBlaster is a tool for reversing (decompiling) binary Apple sandbox profiles. Apple sandbox profiles are written in SBPL (*Sandbox Profile Language*), a Scheme-like language, and are then compiled into an undocumented binary format and shipped. Primarily used on iOS, sandbox profiles are present on macOS as well. SandBlaster is, to our knowledge, the first tool that reverses binary sandbox profiles to their original SBPL format. SandBlaster works on iOS from version 7 onwards including iOS 11.

The technical report [SandBlaster: Reversing the Apple Sandbox](https://arxiv.org/abs/1608.04303) presents extensive (though a bit outdated) information on SandBlaster internals.

SandBlaster relied on previous work by [Dionysus Blazakis](https://github.com/dionthegod/XNUSandbox) and Stefan Esser's [code](https://github.com/sektioneins/sandbox_toolkit) and [slides](https://www.slideshare.net/i0n1c/ruxcon-2014-stefan-esser-ios8-containers-sandboxes-and-entitlements).

The reverser (in the `reverse-sandbox/` folder) and the helper tool (in the `helpers/` folder) run on any Python running platform.

SandBlaster may be installed and run standalone, though we recommend installing and running it from within [iExtractor](https://github.com/malus-security/iExtractor). Check the [iExtractor documentation](https://github.com/malus-security/iExtractor/blob/master/README.md) for information.
# [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

## SandBlaster: Reversing the Apple Sandbox

SandBlaster is a tool for reversing (decompiling) binary Apple sandbox profiles.
Apple sandbox profiles are written in
SBPL (*Sandbox Profile Language*), a Scheme-like language, and are then compiled
into an undocumented binary format and
shipped. Primarily used on iOS, sandbox profiles are present on macOS as well.
SandBlaster is, to our knowledge, the
first tool that reverses binary sandbox profiles to their original SBPL format.
SandBlaster works on iOS from version 7
onwards including iOS 11.

The technical
report [SandBlaster: Reversing the Apple Sandbox](https://arxiv.org/abs/1608.04303)
presents extensive (
though a bit outdated) information on SandBlaster internals.

SandBlaster relied on previous work
by [Dionysus Blazakis](https://github.com/dionthegod/XNUSandbox) and Stefan
Esser's [code](https://github.com/sektioneins/sandbox_toolkit)
and [slides](https://www.slideshare.net/i0n1c/ruxcon-2014-stefan-esser-ios8-containers-sandboxes-and-entitlements)
.

The reverser (in the `reverse-sandbox/` folder) and the helper tool (in
the `helpers/` folder) run on any Python running
platform.

SandBlaster may be installed and run standalone, though we recommend installing
and running it from
within [iExtractor](https://github.com/malus-security/iExtractor). Check
the [iExtractor documentation](https://github.com/malus-security/iExtractor/blob/master/README.md)
for information.

iExtractor is open source software released under the 3-clause BSD license.

## Installation

SandBlaster requires Python2 for the reverser (in `reverse-sandbox/`), Python3 with `lief` library for helper script (in `helpers/`).
SandBlaster requires Python2 for the reverser (in `reverse-sandbox/`), Python3
with `lief` library for helper script (
in `helpers/`).

After cloning the SandBlaster repository, you have to install `lief` for Python3:
```
After cloning the SandBlaster repository, you have to install `lief` for
Python3:

```bash
pip3 install lief
```

If the installation of `lief` fails you need compile to it. More information about how to compile it can be found on the [wiki page](https://lief.quarkslab.com/doc/stable/compilation.html).
If the installation of `lief` fails you need compile to it. More information
about how to compile it can be found on
the [wiki page](https://lief.quarkslab.com/doc/stable/compilation.html).

## Usage

In order to use SandBlaster you need access to the binary sandbox profiles and the sandbox operations, a set of strings that define sandbox-specific actions. Sandbox operations and sandbox profiles are extracted using the `helpers/extract_sandbox_data.py` script. Sandbox profiles are extracted from the kernel sandbox extension (as a bundle for iOS 4 and 9-11) or from kernel cache (as a bundle for iOS 12) or from the `sandboxd` file in the iOS filesystem (for iOS 5-8). Sandbox operations are extracted either from kernel extension (for iOS 4-11) or from kernel cache (for iOS 12).

So, as input data, SandBlaster requires the kernelcache, the kernel sandbox extension and the `sandboxd` file. Information and scripts on extracting them from a publicly available IPSW (*iPhone Software*) file is presented by [iExtractor](https://github.com/malus-security/iExtractor).

Below are the steps and commands to reverse the sandbox profiles for iOS 8.4.1, assuming the sandbox kernel extension (`com.apple.security.sandbox.kext`) and the `sandboxd` file are available:

```
In order to use SandBlaster you need access to the binary sandbox profiles and
the sandbox operations, a set of strings
that define sandbox-specific actions. Sandbox operations and sandbox profiles
are extracted using
the `helpers/extract_sandbox_data.py` script. Sandbox profiles are extracted
from the kernel sandbox extension (as a
bundle for iOS 4 and 9-11) or from kernel cache (as a bundle for iOS 12) or from
the `sandboxd` file in the iOS
filesystem (for iOS 5-8). Sandbox operations are extracted either from kernel
extension (for iOS 4-11) or from kernel
cache (for iOS 12).

So, as input data, SandBlaster requires the kernelcache, the kernel sandbox
extension and the `sandboxd` file.
Information and scripts on extracting them from a publicly available IPSW (*
iPhone Software*) file is presented
by [iExtractor](https://github.com/malus-security/iExtractor).

Below are the steps and commands to reverse the sandbox profiles for iOS 8.4.1,
assuming the sandbox kernel
extension (`com.apple.security.sandbox.kext`) and the `sandboxd` file are
available:

```bash
# Extract sandbox operations from kernelcache.
cd helpers/
./extract_sandbox_data.py -o iPad2,1_8.4.1_12H321.sb_ops iPad2,1_8.4.1_12H321.com.apple.security.sandox.kext 8.4.1
./extract_sandbox_data.py -o iPad2,1_8.4.1_12H321.sb_ops iPad2,1_8.4.1_12H321.
com.apple.security.sandox.kext 8.4.1
# Extract binary sandbox profile files from sandboxd.
mkdir iPad2,1_8.4.1_12H321.sandbox_profiles
./extract_sandbox_data.py -O iPad2,1_8.4.1_12H321.sandbox_profiles/ iPad2,1_8.4.1_12H321.sandboxd 8.4.1
./extract_sandbox_data.py -O iPad2,1_8.4.1_12H321.sandbox_profiles/ iPad2,1_8.4
.1_12H321.sandboxd 8.4.1
# Reverse all binary sandbox profiles.
cd ../reverse-sandbox/
mkdir iPad2,1_8.4.1_12H321.reversed_profiles
for i in ../helpers/iPad2,1_8.4.1_12H321.sandbox_profiles/*; do python reverse_sandbox.py -r 8.4.1 -o ../helpers/iPad2,1_8.4.1_12H321.sb_ops -d iPad2,1_8.4.1_12H321.reversed_profiles/ "$i"; done
for i in ../helpers/iPad2,1_8.4.1_12H321.sandbox_profiles/*; do python
reverse_sandbox.py -r 8.4.1 -o ../helpers/iPad2,1_8.4.1_12H321.sb_ops -d iPad2
,1_8.4.1_12H321.reversed_profiles/ "$i"; done
```

Below are the steps and commands to reverse the sandbox profiles for iOS 9.3, assuming the sandbox kernel extension (`com.apple.security.sandbox.kext`) is available:
Below are the steps and commands to reverse the sandbox profiles for iOS 9.3,
assuming the sandbox kernel
extension (`com.apple.security.sandbox.kext`) is available:

```
```bash
# Extract sandbox operations from kernelcache.
cd helpers/
./extract_sandbox_data.py -o iPhone5,1_9.3_13E237.sb_ops iPhone5,1_9.3_13E237.com.apple.security.sandox.kext 9.3
./extract_sandbox_data.py -o iPhone5,1_9.3_13E237.sb_ops iPhone5,1_9.3_13E237.
com.apple.security.sandox.kext 9.3
# Extract sandbox profile bundle from kernel sandbox extension.
./extract_sandbox_data.py -O . iPhone5,1_9.3_13E237.com.apple.security.sandox.kext 9.3
./extract_sandbox_data.py -O . iPhone5,1_9.3_13E237.com.apple.security.sandox.
kext 9.3
cd ../reverse-sandbox/
# Reverse all binary sandbox profiles in sandbox bundle.
mkdir iPhone5,1_9.3_13E237.reversed_profiles
# Print all sandbox profiles in bundle.
python reverse_sandbox.py -r 9.3 -o ../helpers/iPhone5,1_9.3_13E237.sb_ops -d iPhone5,1_9.3_13E237.reversed_profiles/ ../helpers/sandbox_bundle -psb
python reverse_sandbox.py -r 9.3 -o ../helpers/iPhone5,1_9.3_13E237.sb_ops -d
iPhone5,1_9.3_13E237.reversed_profiles/ ../helpers/sandbox_bundle -psb
# Do actual reversing.
python reverse_sandbox.py -r 9.3 -o ../helpers/iPhone5,1_9.3_13E237.sb_ops -d iPhone5,1_9.3_13E237.reversed_profiles/ ../helpers/sandbox_bundle
python reverse_sandbox.py -r 9.3 -o ../helpers/iPhone5,1_9.3_13E237.sb_ops -d
iPhone5,1_9.3_13E237.reversed_profiles/ ../helpers/sandbox_bundle
```

The extraction of the binary sandbox profiles differs between iOS <= 8 and iOS >= 9. Since iOS >= 9 the binary sandbox profiles are stored in a sandbox bundle in the kernel sandbox extension. The `helpers/extract_sandbox_data.py` script extracts them appropriately depending on the iOS version.
The extraction of the binary sandbox profiles differs between iOS <= 8 and iOS >
= 9. Since iOS >= 9 the binary sandbox
profiles are stored in a sandbox bundle in the kernel sandbox extension.
The `helpers/extract_sandbox_data.py` script
extracts them appropriately depending on the iOS version.

The `-psb` option for `reverse_sandbox.py` prints out the sandbox profiles part of a sandbox bundle without doing the actual reversing.
The `-psb` option for `reverse_sandbox.py` prints out the sandbox profiles part
of a sandbox bundle without doing the
actual reversing.

The `reverse_sandbox.py` script needs to be run in its directory (`reverse-sandbox/`) since it needs the other Python modules and the `logger.config` file.
The `reverse_sandbox.py` script needs to be run in its
directory (`reverse-sandbox/`) since it needs the other Python
modules and the `logger.config` file.

## Internals

The `helpers/` subfolder contains helper scripts that provide a nicer interface for the external tools.

The actual reverser is part of the `reverse-sandbox/` folder. Files here can be categorized as follows:

* The main script is `reverse_sandbox.py`. It parses the command line arguments, does basic parsing of the input binary file (extracts sections) and calls the appropriate functions from the other modules.
* The core of the implementation is `operation_node.py`. It provides functions to build the rules graph corresponding to the sandbox profile and to convert the graph to SBPL. It is called by `reverse_sandbox.py`.
* Sandbox filters (i.e. match rules inside sandbox profiles) are handled by the implementation in `sandbox_filter.py` and the configuration in `filters.json`, `filter_list.py` and `filters.py`. Filter specific functions are called by `operation_node.py`.
* Regular expression reversing is handled by `sandbox_regex.py` and `regex_parse.py`. `regex_parse.py` is the back end parser that converts the binary representation to a basic graph. `sandbox_regex.py` converts the graph representation (an automaton) to an actual regular expression (i.e. a string of characters and metacharacters). It is called by `reverse_sandbox.py` for parsing regular expressions, with the resulting regular expression list being passed to the functions exposed by `operation_node.py`; `operation_node.py` passes them on to sandbox filter handling files.
* The new format for storing strings since iOS 10 is handled by `reverse_string.py`. The primary `SandboxString` class in `reverse_string.py` is used in `sandbox_filter.py`.
* Logging is configured in the `logger.config` file. By default, `INFO` and higher level messages are printed to the console, while `DEBUG` and higher level messages are printed to the `reverse.log` file.
The `helpers/` subfolder contains helper scripts that provide a nicer interface
for the external tools.

The actual reverser is part of the `reverse-sandbox/` folder. Files here can be
categorized as follows:

* The main script is `reverse_sandbox.py`. It parses the command line arguments,
does basic parsing of the input binary
file (extracts sections) and calls the appropriate functions from the other
modules.
* The core of the implementation is `operation_node.py`. It provides functions
to build the rules graph corresponding to
the sandbox profile and to convert the graph to SBPL. It is called
by `reverse_sandbox.py`.
* Sandbox filters (i.e. match rules inside sandbox profiles) are handled by the
implementation in `sandbox_filter.py`
and the configuration in `filters.json`, `filter_list.py` and `filters.py`.
Filter specific functions are called
by `operation_node.py`.
* Regular expression reversing is handled by `sandbox_regex.py`
and `regex_parse.py`. `regex_parse.py` is the back end
parser that converts the binary representation to a basic
graph. `sandbox_regex.py` converts the graph
representation (an automaton) to an actual regular expression (i.e. a string
of characters and metacharacters). It is
called by `reverse_sandbox.py` for parsing regular expressions, with the
resulting regular expression list being
passed to the functions exposed by `operation_node.py`; `operation_node.py`
passes them on to sandbox filter handling
files.
* The new format for storing strings since iOS 10 is handled
by `reverse_string.py`. The primary `SandboxString` class
in `reverse_string.py` is used in `sandbox_filter.py`.
* Logging is configured in the `logger.config` file. By default, `INFO` and
higher level messages are printed to the
console, while `DEBUG` and higher level messages are printed to
the `reverse.log` file.

## Supported iOS Versions

SandBlaster works for iOS version 4 onwards including iOS 12. Apple has been making updates to the binary format of the sandbox profiles: since iOS 9 sandbox profiles are stored in a bundle, since iOS 10 strings are aggregated together in a specialied binary format. iOS 11 didn't bring any change to the format.
SandBlaster works for iOS version 4 onwards including iOS 12. Apple has been
making updates to the binary format of the
sandbox profiles: since iOS 9 sandbox profiles are stored in a bundle, since iOS
10 strings are aggregated together in a
specialied binary format. iOS 11 didn't bring any change to the format.

## Pre-commit

```bash
pip install pre-commit
```

* For documentation check the [official site](https://pre-commit.com/).
* Active hooks:
1. [black](https://github.com/psf/black)
2. [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)
* For adding more hooks, check
the [supported hooks](https://pre-commit.com/hooks.html)
or [create a new one](https://pre-commit.com/index.html#new-hooks).

## Community

Expand Down
Loading