Migrate Sandboxed API docs to developer.google.com/sandboxed-api
This change removes the in-tree documentation in favor of the one hosted on the Google's Developer site. This makes it easier to maintain for the sandbox team, as there is now only a single source of truth for both internal and external documentation. If you find errors/bugs in the documentation, please file regular GitHub issues. PiperOrigin-RevId: 267132623 Change-Id: I4c950fcef77da0b361cb35b99aa2f187efe6f320pull/30/head
Christian Blichmann
Copybara-Service
parent
daa3defac0
commit
ea1a934d51
80
README.md
80
README.md
|
|
@ -9,84 +9,22 @@ Copyright 2019 Google LLC
|
|||
|
||||
The Sandboxed API project (**SAPI**) aims to make sandboxing of C/C++ libraries
|
||||
less burdensome: after initial setup of security policies and generation of
|
||||
library interfaces, an almost-identical stub API is generated (using a
|
||||
[template-based programming variable hierarchy system](sandboxed_api/docs/variables.md)),
|
||||
transparently forwarding calls using a custom RPC layer to the real library
|
||||
running inside a sandboxed environment.
|
||||
library interfaces, an almost-identical stub API is generated, transparently
|
||||
forwarding calls using a custom RPC layer to the real library running inside a
|
||||
sandboxed environment.
|
||||
|
||||
Additionally, each SAPI library utilizes a tightly defined security policy, in
|
||||
contrast to the typical sandboxed project, where security policies must cover the total
|
||||
syscall/resource footprint of all utilized libraries.
|
||||
|
||||
## Documentation
|
||||
|
||||
## Intended audience
|
||||
|
||||
SAPI is designed to help you sandbox only a part of binary. That is, a library
|
||||
or some other code with an unknown security posture.
|
||||
|
||||
See [Sandboxing Code](sandboxed_api/docs/sandbox-overview.md) to make sure this is the type of
|
||||
sandboxing you are looking for.
|
||||
|
||||
## How does it work?
|
||||
|
||||
Navigate to our [How it works](sandboxed_api/docs/howitworks.md) page.
|
||||
|
||||
|
||||
## Motivation
|
||||
|
||||
Sandboxes available for use in Google required additional implementation work
|
||||
with each new instance of project which was intended to be sandboxed, even if
|
||||
it reused the same software library. Sandbox security policies and other
|
||||
restrictions applied to the sandboxed process had to be reimplemented each
|
||||
time, and data exchange mechanisms between trusted and untrusted parts of
|
||||
the code had to be designed from the scratch.
|
||||
|
||||
While designing the Sandboxed API project, our goal was to make this process
|
||||
easy and straightforward. Our working motto is: **Sandbox once, use anywhere**.
|
||||
|
||||
|
||||
## Is it proven technology?
|
||||
|
||||
The project has been designed, developed and is maintained by members of
|
||||
the Google Sandbox Team. It also uses our field-tested
|
||||
[Sandbox 2](sandboxed_api/sandbox2/README.md).
|
||||
|
||||
Currently, many internal projects are already using SAPI to isolate
|
||||
their production workloads. You can read more about them in the
|
||||
[Examples](sandboxed_api/docs/examples.md) section.
|
||||
|
||||
We've also prepared some more example SAPI implementations for your reference.
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
Install the required dependencies, this assumes you are running Debian 10
|
||||
"Buster":
|
||||
|
||||
```bash
|
||||
echo "deb http://storage.googleapis.com/bazel-apt stable jdk1.8" | \
|
||||
sudo tee /etc/apt/sources.list.d/bazel.list
|
||||
wget -qO - https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
|
||||
sudo apt-get update
|
||||
sudo apt-get install -qy build-essential linux-libc-dev bazel python3 \
|
||||
python3-pip libclang-7-dev
|
||||
pip3 install clang
|
||||
```
|
||||
|
||||
Clone and run the build:
|
||||
```bash
|
||||
git clone https://github.com/google/sandboxed-api && cd sandboxed-api
|
||||
bazel build ...
|
||||
```
|
||||
|
||||
Try out one of the [examples](sandboxed_api/docs/examples.md):
|
||||
```bash
|
||||
bazel run //sandboxed_api/examples/stringop:main_stringop
|
||||
```
|
||||
|
||||
There are also a more detailed instructions that should help you
|
||||
**[getting started with SAPI](sandboxed_api/docs/getting-started.md)**.
|
||||
Detailed developer documentation is available on the Google Developers site for
|
||||
[Sandboxed API](https://developers.google.com/sandboxed-api).
|
||||
|
||||
There is also a
|
||||
[Getting Started](https://developers.google.com/sandboxed-api/docs/getting-started)
|
||||
guide.
|
||||
|
||||
## Getting Involved
|
||||
|
||||
|
|
|
|||
|
|
@ -1,87 +1,9 @@
|
|||
# Getting started with SAPI
|
||||
|
||||
## Build Dependencies
|
||||
Detailed developer documentation is available on the Google Developers site for
|
||||
[Sandboxed API](https://developers.google.com/sandboxed-api).
|
||||
|
||||
To build and run code with SAPI, the following dependencies must be installed
|
||||
on the system:
|
||||
Visit the
|
||||
[Getting Started](https://developers.google.com/sandboxed-api/docs/getting-started)
|
||||
guide.
|
||||
|
||||
* To compile your code: GCC 6 (version 7 or higher preferred) or Clang 7 (or
|
||||
higher)
|
||||
* For auto-generating header files: Clang Python Bindings
|
||||
* [Bazel](https://bazel.build/) version 0.23.0
|
||||
* Python 2.7 with type annotations
|
||||
* Linux userspace API headers
|
||||
* Linux kernel with support for UTS, IPC, user, PID and network namespaces
|
||||
|
||||
Please refer to the
|
||||
[Bazel documentation](https://docs.bazel.build/versions/master/bazel-overview.html)
|
||||
for information on how to change the default compiler toolchain.
|
||||
|
||||
### Debian 10 "Buster"
|
||||
Build dependencies:
|
||||
```bash
|
||||
echo "deb http://storage.googleapis.com/bazel-apt stable jdk1.8" | \
|
||||
sudo tee /etc/apt/sources.list.d/bazel.list
|
||||
wget -qO - https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
|
||||
sudo apt-get install -qy python-typing python-clang-7 libclang-7-dev
|
||||
sudo apt-get install -qy build-essential linux-libc-dev bazel
|
||||
```
|
||||
|
||||
### Gentoo
|
||||
Kernel options required:
|
||||
```
|
||||
General setup --->
|
||||
-*- Namespaces support
|
||||
[*] UTS namespace
|
||||
[*] IPC namespace
|
||||
[*] User namespace (EXPERIMENTAL)
|
||||
[*] PID Namespaces
|
||||
[*] Network namespace
|
||||
```
|
||||
|
||||
Build dependencies:
|
||||
```bash
|
||||
emerge dev-util/bazel dev-python/typing dev-python/clang-python
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Under [Examples](examples.md) you can find a few libraries, previously prepared
|
||||
by the SAPI team.
|
||||
|
||||
|
||||
## Development Process
|
||||
|
||||
You will have to prepare two parts of your a sandbox library project. The
|
||||
sandboxed library part (**SAPI library**), and the **host code**
|
||||
which will make use of functionality exposed by your sandboxed library.
|
||||
|
||||
|
||||
## SAPI Library
|
||||
|
||||
The *SAPI library* is a sandboxed process, which exposes required functionality
|
||||
to the *host code*.
|
||||
|
||||
In order to create it, you'll need your C/C++ library, for example another open
|
||||
source project on GitHub. You will also have to create some supporting code
|
||||
(part of it will be automatically generated). This code will describe which
|
||||
functionality exactly you would like to contain (which library functions), and
|
||||
the [sandbox policies](../sandbox2/docs/getting-started.md#policy) you would
|
||||
like your library to run under.
|
||||
|
||||
All those steps are described in details under [Library](library.md).
|
||||
|
||||
|
||||
## Host Code
|
||||
|
||||
The *host code* is making use of functions exported by your *SAPI Library*.
|
||||
|
||||
It makes calls to sandboxed functions, receives results, and can access memory
|
||||
of a *SAPI library* in order to make copies of remote variables and memory
|
||||
blocks (arrays, structures, protocol buffers, etc.). Those memory blocks
|
||||
can then be accessed by the local process.
|
||||
|
||||
The host code can also copy contents of local memory to the remote process if
|
||||
needed.
|
||||
|
||||
Read about writing host code [here](host-code.md).
|
||||
|
|
|
|||
|
|
@ -5,15 +5,12 @@ programs or portions of programs in confined environments. The idea is that the
|
|||
runtime environment is so restricted that security bugs such as buffer overflows
|
||||
in the protected region cause no harm.
|
||||
|
||||
## Who is it for?
|
||||
## Documentation
|
||||
|
||||
Sandbox2 is aimed to sandbox C/C++ code or whole binaries in production.
|
||||
Detailed developer documentation is available on the Google Developers site for Sandboxed API under
|
||||
[Sandbox2](hhttps://developers.google.com/sandboxed-api/docs/sandbox2/overview).
|
||||
|
||||
See the sandboxing options [overview page](../docs/sandbox-overview.md) to make
|
||||
sure this is the type of sandboxing you are looking for.
|
||||
|
||||
## How does it work?
|
||||
|
||||
Read our [How it works](docs/howitworks.md) page to learn everything about this
|
||||
technology.
|
||||
There is also a
|
||||
[Getting Started](https://developers.google.com/sandboxed-api/docs/sandbox2/getting-started)
|
||||
guide for Sandbox2.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue