PR add-code branch

.gitignore

@@ -0,0 +1,18 @@
+# Binaries
+matching-core/build
+
+# Logs
+logs
+
+# Object files
+*.o
+*.dylib
+
+# Python files
+__pycache__
+
+# ccls files
+.ccls-cache
+
+# Debug symbols
+*.dSYM

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "maap"]
+	path = maap
+	url = https://github.com/0xbf00/maap
+[submodule "matching-core/simbple"]
+	path = matching-core/simbple
+	url = https://github.com/0xbf00/simbple

README.md

@@ -1,2 +1,68 @@
 # iShrink
 Minimization of  Apple sandbox profiles
+
+## Dependencies
+
+The project requires the following dependencies in order to run:
+* `cmake`
+* `nlohmann/json`
+
+To install these dependencies use homebrew likewise:
+```sh
+$ brew tap nlohmann/json
+$ brew install cmake nlohmann_json
+```
+
+## Installation
+```sh
+git clone --recursive https://github.com/malus-security/iShrink.git
+# Install submodule
+# - maap: For the installation guide check Jakob Rieck's repo at https://github.com/0xbf00/maap
+
+# Build matching-core
+$ mkdir matching-core/build
+$ cd matching-core/build
+$ cmake ..
+$ make
+```
+
+## Usage
+
+To minimize a profile, follow these steps:
+
+1. Use the analysis script from Jakob Rieck's macos-sandbox-coverage solution.
+2. Use the minimization script to obtain the minimized `rules.sb` sandbox profile in SBPL.
+3. Compile using `compile_sb` from Stefan Esser's sandbox\_toolkit.
+4. Use the test script to apply the compiled minimized profile to the app.
+
+## Using macos-sandbox-coverage
+
+The program only supports two switches:
+
+1. Use `--app` to specify the path to the application you want to collect sandbox coverage data for
+2. Use `--timeout` to specify the number of seconds for the app to run. If you do not specify a timeout, the app will run indefinitely or until it is closed by the user.
+
+```sh
+$ ./sandbox_coverage.py --app /Applications/Calculator.app > output.json
+```
+## Obtaining the minimized sandbox profile
+
+```sh
+$ ./minimize.py output.json
+```
+
+## Compiling the resulted profile
+
+```sh
+$ ./maap/extern/compile_sb rules.sb rules.bin
+```
+
+## Applying the compiled profile
+The test script has three switches:
+1. `--app` to provide the path to the application
+2. `--timeout` to specify the amount of time in seconds for the app to be tested. This is an optional argument, the application will run until is terminated by the user unless a timeout is specified.
+3. `--m` to provide the path to the compiled minimized profile.
+
+```sh
+$ ./test.py --app /System/Applications/Calendar.app/ --timeout 60 --m rules.bin
+```

data/README.md

@@ -0,0 +1,44 @@
+# Complementary Data
+
+The `data/` subdirectory contains generic profiles, templates, examples, and other stuff we might want to keep an archive of.
+
+## Generic Sandbox Profiles
+
+The `data/` subdirectory contains the general sandboxing profile that is used as the ultimate matching target.
+
+It is generated from a reduced, _generalised_ `Container.plist` file. Compared to for example `Calculator.app`'s metadata file, the following changes were made:
+
+1. Removes `Identity` data
+2. Removes `SandboxProfileData` data
+3. Removes all entitlements except for the `com.apple.security.app-sandbox` entitlement, as this entitlement is shared by all sandboxed apps.
+4. Under `Parameters`, replaces all concrete paths with placeholder values such as `$_HOME$`
+5. Under `RedirectablePaths`, replaces the user portion of the path with `$_HOME$`
+6. Turn `SystemImages` into an empty array.
+
+Use [`simbple`](https://github.com/0xbf00/simbple) to do this:
+
+```sh
+cd data/generic_profiles/
+export PLATFORM="$(sw_vers -productVersion)-$(sw_vers -buildVersion)"
+simbple "$PLATFORM.plist" --scheme > "$PLATFORM.sb"
+simbple "$PLATFORM.plist" --JSON > "$PLATFORM.sb"
+```
+
+Note: depending on your version of macOS you might need to generate your own generic profiles!
+
+## Templates
+
+The templates are used for generating reports. They are created with the [Jinja](http://jinja.palletsprojects.com) template language.
+
+## IOKit Mappings
+
+The `iomap/` subdirectory contains platform-specific mappings from IOKit services to clients. The mappings in this directory are not directly used by the matcher. The mappings the matcher actually uses are defined in `matching-core/sandbox_utils/iokit.c`.
+
+The mapping files can be generated with the `iomap.py` script:
+
+```sh
+export PLATFORM="$(sw_vers -productVersion)-$(sw_vers -buildVersion)"
+./matching-core/sandbox_utils/iomap.py --json > "data/iomap/$PLATFORM.json"
+```
+
+Note: you need to have `ioscan` in your `PATH`, which is part of [iokit-utils](https://github.com/Siguza/iokit-utils).