DOCSEARCHbyAlgolia
Submit Docs

Sandboxed API (SAPI)

repository·main·Indexed 23 days ago

https://github.com/google/sandboxed-api

A framework for sandboxing individual C/C++ libraries using Google's Sandbox2 technology. SAPI provides reusable library-level isolation and includes integrations for various external libraries such as Jsonnet, libtiff, LodePNG, PFFFT, libcurl, and others, primarily utilizing CMake and Bazel for configuration.

Tokens
9.8K
Snippets
35
Records
72
Agent score
83%

What's inside Sandboxed API

  1. Overview of Sandboxed API Integrations

    main
    The contrib/ directory contains reusable Sandboxed API integrations for various external libraries. These integrations allow external libraries to run within a sandboxed environment. Most integrations listed use CMake for the integration process, while some projects use Bazel.

  2. Overview of Sandboxed API (SAPI)

    main

    Sandboxed API (SAPI) is an open-source project built on top of Google's Sandbox2. It is designed to simplify the sandboxing of individual C/C++ libraries rather than entire programs.

    Key benefits include:

    • Library-level Isolation: Individual C/C++ libraries can be sandboxed, isolating the main program from vulnerabilities within that specific library.
    • Reusability: Libraries sandboxed with SAPI follow a "Sandbox once, use anywhere" model, allowing them to be reused across different projects without reimplementing security policies or data exchange mechanisms.
    • Granular Security Policies: Each SAPI library uses a tightly defined security policy focused on the specific syscall/resource footprint of that library, rather than a broad policy covering all utilized libraries.

    Note: Sandbox2 is also open-sourced as part of this project and can be used independently.

  3. Overview of Sandbox2

    main
    Sandbox2 is a C++ security sandbox designed for Linux. It allows developers to run untrusted programs or specific portions of a program within highly restricted, confined environments. The primary security goal is to ensure that even if a security vulnerability (such as a buffer overflow) occurs within the protected region, it cannot cause harm to the rest of the system due to the extreme restrictions placed on the runtime environment.

  5. Explore LibUV Sandbox examples

    main

    The examples/ directory contains sandboxed versions of code snippets from the official LibUV User Guide. These examples are designed to demonstrate how to perform basic LibUV tasks within a sandboxed environment and provide a comparison between regular LibUV code and sandboxed LibUV code.

    Available examples include:

    • helloworld.cc: A minimal example that starts a loop and exits immediately. Use this to understand how to initialize and run a simple loop in the sandbox.
    • idle-basic.cc: Demonstrates using an idle watcher. It shows how to implement and use simple callbacks within the sandboxed environment to control loop execution (e.g., stopping the loop after a specific number of iterations).
    • uvcat.cc: A simplified version of the cat command-line tool. It takes an absolute path to a file as an argument and prints its contents. Use this to learn how to manage complex asynchronous callbacks for filesystem operations like opening, reading, and writing files in the sandbox.

  6. Explore LibCurl Sandbox Examples

    main

    The oss-internship-2020/curl/examples directory contains sandboxed versions of standard libcurl code snippets. These examples are designed to help developers understand how to use the LibCurl Sandbox API and how sandboxed code differs from regular libcurl code.

    Available examples include:

    • example1: A simple HTTP request that downloads and prints a page (based on simple.c).
    • example2: An HTTP request that uses a callback to save the page directly in memory (based on getinmemory.c).
    • example3: An HTTPS request using SSL authentication. This example requires 4 arguments: SSL certificates file, SSL keys file, SSL keys password, and CA certificates files (based on simplessl.c).
    • example4: An HTTP request using a polling method to track request status (based on multi-poll.c).
    • example5: Multiple simultaneous HTTP requests using libcurl's multithreading methods (based on multithread.c).
    • example6: A simple HTTP request that demonstrates the use of Sandbox API Transactions (based on simple.c).

  7. Understand LodePNG sandboxing limitations

    main

    While many LodePNG functions can be sandboxed, certain functions are not supported by the Sandboxed API. Specifically, functions that use std::vector parameters or use function overloading cannot be sandboxed directly.

    If you require these unsupported functions, you must implement a custom wrapper library that encapsulates them to make them compatible with the sandboxing requirements.

  8. How the Sandboxed API (SAPI) works

    main

    The project implements a sandboxing mechanism to limit the permissions and capabilities of library methods. This secures the usage of GDAL by controlling operations, system calls, or namespace access.

    Once a sandbox is obtained, functions are called through a Sandbox API (referred to as api in current tests). Useful functions from the gdal.h header are integrated into the SAPI library built with CMake.

  9. How the GDAL raster process works

    main

    The rastering workflow follows these steps using GDAL functionalities:

    1. Open File: A .tiff file is manipulated using the GDALOpen functionality, which extracts a pointer to a dataset containing raster bands.
    2. Metadata Extraction: The dataset contains metadata, coordinate systems, georeferencing transforms, and raster size information.
    3. Dimension Extraction: Image dimensions are extracted using specific GDAL(X/Y)Size functions applied to the block.
    4. Data Conversion and Loading: The GDALRasterBand function handles data type conversion, and the RasterIO method is used to place the converted data into an allocated structure.

  10. SAPI Clang tool header generator

    main
    SAPI provides a clang tool header generator based on LLVM Libtooling (located in tools/clang_generator/BUILD). The project aims to support at least the latest three LLVM releases and is tested on Debian stable.

  11. Implement and link callbacks for LibCurl Sandbox

    main

    Callbacks (function pointers passed to the library) cannot be implemented in the same files that use the library. They must reside in separate files that are compiled together with the library.

    Linking Callbacks

    To include your callback implementations, add the absolute path of the source files to the CMake variable CURL_SAPI_CALLBACKS.

    Accessing Callbacks

    Once linked, you can obtain the function pointers using an RPCChannel object.

  12. Explore Guetzli sandboxed API and Transaction usage examples

    main

    The repository includes unit tests that serve as practical examples for integrating the sandboxed API:

    • API Usage: See tests/guetzli_sapi_test.cc for examples of how to use the Guetzli sandboxed API.
    • Transaction Usage: See tests/guetzli_transaction_test.cc for examples of how to use the Sandboxed API Transaction class, which simplifies error handling.
    • Security Policy: See guetzli_sandbox.h for an example of a custom security policy implementation.

    To run these tests, use:

    bazel test ...