Beispiele

Übersicht

Wir haben einige Beispiele vorbereitet, um zu zeigen, wie Sandbox2 in verschiedenen Szenarien verwendet wird und wie Richtlinien geschrieben werden.

Sie finden sie unter //sandboxed_api/sandbox2/examples. Unten finden Sie detaillierte Erklärungen.

CRC4

Das CRC4-Beispiel ist eine absichtlich fehlerhafte Berechnung einer CRC4-Prüfsumme, die zeigt, wie ein anderes Programm in einer Sandbox ausgeführt und wie mit ihm kommuniziert wird.

  • crc4bin.cc: Das Programm, das wir in der Sandbox ausführen möchten (d.h. das Sandboxee)
  • crc4sandbox.cc: Das Sandbox-Programm, in dem es ausgeführt wird (d.h. der Executor).

Funktionsweise:

  1. Der Executor startet die Sandboxee über ihren Dateipfad mit ::sandbox2::GetDataDependencyFilePath().
  2. Der Executor sendet Eingaben über den Kommunikationskanal Comms mithilfe von SendBytes() an den Sandboxee.
  3. Der Sandboxee berechnet den CRC4 und sendet seine Antworten über den Kommunikationskanal Comms zurück an den Executor, der sie mit RecvUint32() empfängt.

Wenn das Programm einen anderen Systemaufruf als die Kommunikation (read() und write()) ausführt, wird es aufgrund eines Richtlinienverstoßes beendet.

Statisch

Das statische Beispiel zeigt, wie eine statisch verknüpfte Binärdatei in einer Sandbox ausgeführt wird. Das ist z. B. bei Binärdateien von Drittanbietern der Fall, für die Sie den Quellcode nicht haben und die daher nicht wissen, dass sie in einer Sandbox ausgeführt werden.

  • static_bin.cc: Die Sandboxee ist eine statische C-Binärdatei, die ASCII-Text aus der Standardeingabe in Großbuchstaben umwandelt.
  • static_sandbox.cc: Der Executor mit seiner Richtlinie, seinen Limits und der Verwendung eines Dateideskriptors für die Sandboxee-Eingabe.

Funktionsweise:

  1. Der Executor startet das Sandboxee über seinen Dateipfad mit GetDataDependencyFilepath, genau wie bei CRC4.
  2. Es werden Limits festgelegt, ein Dateideskriptor für /proc/version geöffnet und er wird mit MapFd für die Zuordnung in Sandboxee markiert.
  3. Die Richtlinie erlaubt, dass einige Systemaufrufe (open) einen Fehler (ENOENT) zurückgeben, anstatt aufgrund eines Richtlinienverstoßes beendet zu werden. Das kann nützlich sein, wenn ein Drittanbieterprogramm in einer Sandbox ausgeführt wird und wir nicht ändern können, welche Systemaufrufe erfolgen. Stattdessen können wir dafür sorgen, dass sie ordnungsgemäß fehlschlagen.

Tool

Das Toolbeispiel ist sowohl ein Tool zum Entwickeln eigener Richtlinien und zum Testen von Sandbox2-APIs als auch eine Demonstration der Funktionen.

  • sandbox2tool.cc: Der Executor demonstriert Folgendes:
    • wie Sie eine weitere Binärdatei in der Sandbox ausführen,
    • wie Sie Dateisystemprüfungen einrichten.
    • wie der Executor die Sandboxee asynchron ausführen kann, um die Ausgabe schrittweise zu lesen.

Probieren Sie es selbst aus:

Bazel

bazel run //sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

CMake + Ninja

cd build-dir
ninja sandbox2_sandbox2tool && \
./sandbox2_sandbox2tool \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

Google3 (Blaze)

blaze run //third_party/sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
 --sandbox2tool_resolve_and_add_libraries \
 --sandbox2tool_additional_bind_mounts /etc \
 /bin/cat /etc/hostname

Flags:

  • --sandbox2tool_resolve_and_add_libraries, um die erforderlichen Bibliotheken für die Sandboxee aufzulösen und einzubinden
  • --sandbox2tool_additional_bind_mounts <PATHS>, um dem Sandboxee zusätzliche Verzeichnisse zur Verfügung zu stellen
  • --sandbox2tool_keep_env zum Beibehalten der aktuellen Umgebungsvariablen
  • --sandbox2tool_redirect_fd1, um die Sandboxee STDOUT_FILENO (1) zu empfangen und lokal auszugeben
  • --sandbox2tool_cpu_timeout, um das CPU-Zeitlimit in Sekunden festzulegen
  • --sandbox2tool_walltime_timeout zum Festlegen des Wanduhr-Zeitlimits in Sekunden
  • --sandbox2tool_file_size_creation_limit, um die maximale Größe der erstellten Dateien festzulegen
  • --sandbox2tool_cwd, um das aktuelle Arbeitsverzeichnis der Sandbox festzulegen

custom_fork

Das Beispiel custom_fork zeigt, wie eine Sandbox erstellt wird, in der das Binärprogramm initialisiert wird. Anschließend wird auf fork()-Anfragen vom übergeordneten Executor gewartet.

Dieser Modus bietet potenziell eine höhere Leistung als andere Arten von Sandboxing, da hier zum Erstellen neuer Sandboxee-Instanzen keine neuen Binärdateien ausgeführt werden müssen, sondern nur die vorhandenen verzweigt werden.

  • custom_fork_bin.cc: Der benutzerdefinierte Fork-Server, der Anfragen an fork() (über Client::WaitAndFork) empfängt, um neue Sandboxees zu starten.
  • custom_fork_sandbox.cc: Der Executor, der einen benutzerdefinierten Fork-Server startet. Anschließend werden Anfragen (über neue Executors) gesendet, um (über fork()) neue Sandboxees zu erstellen.

Netzwerk

Der Netzwerk-Namespace, der standardmäßig aktiviert ist, verhindert, dass der Sandbox-Prozess eine Verbindung zur Außenwelt herstellt. In diesem Beispiel wird gezeigt, wie Sie dieses Problem beheben können.

Eine Verbindung wird im Executor initialisiert und der resultierende Socket wird über ::sandbox2::Comms::SendFD() übergeben. Die Sandboxee empfängt den Socket über ::sandbox2::Comms::RecvFD() und kann ihn dann wie gewohnt zum Austausch der Daten verwenden.

  • network_bin.cc: Das Programm, das wir in einer Sandbox ausführen möchten (d.h. das Sandboxee).
  • network_sandbox.cc: Das Sandbox-Programm, das ausgeführt wird (d.h. der Executor).

network_proxy

In diesem Beispiel wird eine alternative Methode für den Umgang mit einem Netzwerk-Namespace gezeigt. Intern funktioniert es genau wie im obigen Beispiel, wird aber als komfortablere API bereitgestellt.

Die Sandboxee kann auf zwei verschiedene Arten eine Netzwerkverbindung herstellen:

  • Automatisch: Durch die Installation eines automatischen Handlers und das regelmäßige Ausführen von Connect-Aufrufen.
  • Manuell: Sie rufen ein NetworkProxyClient ab und verwenden NetworkProxyClient::Connect direkt.

In diesem Beispiel werden beide Methoden gezeigt. Der automatische Modus wird verwendet, wenn das Flag connect_with_handler gesetzt ist. Andernfalls wird der manuelle Modus verwendet.

  • network_bin.cc: Das Programm, das wir in einer Sandbox ausführen möchten (d.h. das Sandboxee).
  • network_sandbox.cc: Das Sandbox-Programm, in dem es ausgeführt wird (der Executor).