sandbox/README.md

<!--* freshness: { owner: 'ise-sandboxing-members' reviewed: '2024-10-28' } *-->

# Sandboxed hunspell API

As part of ISE-Sandboxing's Sandboxing Enforcement Program
(go/ise-sandboxing-enforcement), we have identified the `hunspell` library
as a target that requires sandboxing if processing data originating from outside
of Alphabet. This is in accordance with our guideline go/untrusted-workloads.

This package contains a sandboxed version of the **spellcheck APIs** of
[//third_party/hunspell:hunspell](http:///BUILD).

Sandboxing `hunspell` provides an additional security boundary that requires
a malicious actor to successfully exploit two vulnerabilities before they are
able to laterally move away from the initial entry point.

TODO: Update the next paragraph depending on the `sapi_library` target in BUILD.

The `sandboxed_hunspell`
([//third_party/hunspell/sandbox:sandboxed_hunspell](http:///sandbox/BUILD))
library provides only a subset of the unsandboxed read/decode
APIs. This subset is listed in the `functions` argument of the `sapi_library`
BUILD rule. If more functions are needed, reach out to ISE Sandboxing
(go/ise-sandboxing) for guidance.

## sandboxed_hunspell

This is the SAPI implementation of `//third_party/hunspell:hunspell` and provides
users of the sandboxed API with the most control with regards to the sandbox's
life-time and the possibility to implement additional customizations. This comes
at the cost of simplicity.

### Getting started

Follow these steps:

1. In your BUILD file, add the target to your `deps` list:

   ```
   "//third_party/hunspell/sandbox:sandboxed_hunspell",
   ```

1. Add the library headers in your source files:

   ```
   #include "third_party/hunspell/sandbox/sandbox.h"
   #include "third_party/hunspell/sandbox/sandboxed_hunspell.sapi.h"
   ```

1. Create and then initialize the sandbox.

   ```
   sandboxed_hunspell::LibHunspellSapiSandbox sbx;
   SAPI_RETURN_IF_ERROR(sbx.Init());
   ```

1. Create the API object with the initialized sandbox:

   ```
   sandboxed_hunspell::LibHunspellApi api(&sbx);
   ```

1. Prepare the SAPI variables for the sandboxed API function call. For an
   explanation of SAPI variables, please consult go/sapi/variables.

   ```
    std::string s_afn = "utf8.aff";
    std::string s_dfn = "utf8.dic";

    sapi::v::ConstCStr c_afn(s_afn.c_str());
    sapi::v::ConstCStr c_dfn(s_dfn.c_str());

    SAPI_ASSERT_OK_AND_ASSIGN(
        sandboxed_hunspell::Hunhandle * hunspell,
        api.Hunspell_create(c_afn.PtrBefore(), c_dfn.PtrBefore()));
   ```

### sandboxed_hunspell_test

This tests the basic functionality of the `sandboxed_hunspell` and compares
the output to the `unsandboxed hunspell`. It is also a good source to
understand how the SAPI variables need to be prepared.