README.md
1# Guetzli Sandbox
2This is an example implementation of a sandbox for the [Guetzli](https://github.com/google/guetzli) library using [Sandboxed API](https://github.com/google/sandboxed-api).
3Please read Guetzli's [documentation](https://github.com/google/guetzli#introduction) to learn more about it.
4
5## Implementation details
6Because Guetzli provides a C++ API and SAPI requires functions to be `extern "C"`, a wrapper library has been written for the compatibility. SAPI provides a Transaction class, which is a convenient way to create a wrapper for your sandboxed API that handles internal errors. The original Guetzli has a command-line utility to encode images, so a fully compatible utility that uses sandboxed Guetzli is provided.
7
8The wrapper around Guetzli uses file descriptors to pass data to the sandbox. This approach restricts the sandbox from using the `open()` syscall and also helps to prevent making copies of data, because you need to synchronize it between processes.
9
10## Build Guetzli Sandboxed
11Right now Sandboxed API support only Linux systems, so you need one to build it. Guetzli sandboxed uses [Bazel](https://bazel.build/) as a build system so you need to [install it](https://docs.bazel.build/versions/3.4.0/install.html) before building.
12
13To build Guetzli sandboxed encoding utility you can use this command:
14`bazel build //:guetzli_sandboxed`
15
16Then you can use it in this way:
17```
18guetzli_sandboxed [--quality Q] [--verbose] original.png output.jpg
19guetzli_sandboxed [--quality Q] [--verbose] original.jpg output.jpg
20```
21Refer to Guetzli's [documentation](https://github.com/google/guetzli#using) to read more about usage.
22
23## Examples
24There are two different sets of unit tests which demonstrate how to use different parts of Guetzli sandboxed:
25* `tests/guetzli_sapi_test.cc` - example usage of Guetzli sandboxed API.
26* `tests/guetzli_transaction_test.cc` - example usage of Guetzli transaction.
27
28To run tests use the following command:
29`bazel test ...`
30
31Also, there is an example of custom security policy for your sandbox in
32`guetzli_sandbox.h`
33
