Beispiele

Übersicht

Wir haben einige Beispiele vorbereitet, um zu zeigen, wie Sie Sandbox2 in verschiedenen Szenarien verwenden und Richtlinien schreiben.

Sie finden sie unter //sandboxed_api/sandbox2/examples. Eine detaillierte Erklärung finden Sie unten.

CRC4

Das CRC4-Beispiel ist eine absichtlich fehlerhafte Berechnung einer CRC4-Prüfsumme, die zeigt, wie Sie ein anderes Programm in einer Sandbox ausführen und damit kommunizieren.

  • crc4bin.cc: Das Programm, das in einer Sandbox ausgeführt werden soll (d.h. das Sandboxee)
  • crc4sandbox.cc: Das Sandbox-Programm, das es ausführt (d. h. der Executor)

Funktionsweise:

  1. Der Executor startet das Sandboxee über den Dateipfad mit ::sandbox2::GetDataDependencyFilePath().
  2. Der Executor sendet Eingaben über den Kommunikationskanal Comms mit SendBytes() an das Sandboxee.
  3. Das Sandboxee berechnet den CRC4-Wert und sendet die 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 Sie eine statisch verknüpfte Binärdatei in einer Sandbox ausführen, z. B. eine Binärdatei eines Drittanbieters, für die Sie nicht die Quelle haben. Das bedeutet, dass sie nicht weiß, dass sie in einer Sandbox ausgeführt wird.

  • static_bin.cc: Das 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 einem Dateideskriptor für die Sandboxee-Eingabe.

Funktionsweise:

  1. Der Executor startet das Sandboxee über den Dateipfad mit GetDataDependencyFilepath, genau wie bei CRC4.
  2. Er richtet Limits ein, öffnet einen Dateideskriptor für /proc/version und markiert ihn mit MapFd für die Zuordnung im Sandboxee.
  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 Sie ein Drittanbieterprogramm in einer Sandbox ausführen, bei dem Sie nicht ändern können, welche Systemaufrufe ausgeführt werden. Stattdessen können Sie dafür sorgen, dass sie ordnungsgemäß fehlschlagen.

Tool

Das Tool-Beispiel ist sowohl ein Tool zum Entwickeln eigener Richtlinien und zum Experimentieren mit Sandbox2-APIs als auch eine Demonstration der Funktionen.

  • sandbox2tool.cc: Der Executor zeigt:
    • wie Sie eine andere Binärdatei in einer Sandbox ausführen,
    • wie Sie Dateisystemprüfungen einrichten und
    • wie der Executor das 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 zum Auflösen und Einbinden der erforderlichen Bibliotheken für das Sandboxee
  • --sandbox2tool_additional_bind_mounts <PATHS> zum Bereitstellen zusätzlicher Verzeichnisse für das Sandboxee
  • --sandbox2tool_keep_env zum Beibehalten der aktuellen Umgebungsvariablen
  • --sandbox2tool_redirect_fd1 zum Empfangen von STDOUT_FILENO (1) des Sandboxee und zur lokalen Ausgabe
  • --sandbox2tool_cpu_timeout zum Festlegen des CPU-Time-outs in Sekunden
  • --sandbox2tool_walltime_timeout zum Festlegen des Wall-Time-Time-outs in Sekunden
  • --sandbox2tool_file_size_creation_limit zum Festlegen der maximalen Größe erstellter Dateien
  • --sandbox2tool_cwd zum Festlegen des aktuellen Arbeitsverzeichnisses der Sandbox

custom_fork

Das Beispiel custom_fork zeigt, wie Sie eine Sandbox erstellen, die die Binärdatei initialisiert und dann auf fork()-Anfragen vom übergeordneten Executor wartet.

Dieser Modus bietet möglicherweise eine höhere Leistung als andere Arten von Sandbox-Funktionen, da hier zum Erstellen neuer Instanzen von Sandboxees 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() empfängt (über ForkingClient::EnterForkLoop), um neue Sandboxees zu erstellen.
  • custom_fork_sandbox.cc: Der Executor, der einen benutzerdefinierten Fork-Server startet. Anschließend sendet er Anfragen an ihn (über neue Executors), um (über fork()) neue Sandboxees zu erstellen.

Netzwerk

Der standardmäßig aktivierte Netzwerk-Namespace verhindert, dass sich der in einer Sandbox ausgeführte Prozess mit der Außenwelt verbindet. Dieses Beispiel zeigt, wie Sie dieses Problem beheben.

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

  • network_bin.cc: Das Programm, das in einer Sandbox ausgeführt werden soll (d. h. das Sandboxee)
  • network_sandbox.cc: Das Sandbox-Programm, das es ausführt (d. h. der Executor)

network_proxy

Dieses Beispiel zeigt eine alternative Möglichkeit, mit einem Netzwerk-Namespace umzugehen. Intern funktioniert es genau wie das obige Beispiel, wird aber als bequemere API bereitgestellt.

Das Sandboxee kann auf zwei verschiedene Arten eine Netzwerkverbindung herstellen:

  • Automatisch : Installieren Sie einen automatischen Handler und führen Sie dann reguläre Verbindungsaufrufe aus.
  • Manuell : Rufen Sie einen NetworkProxyClient ab und verwenden Sie direkt NetworkProxyClient::Connect.

Dieses Beispiel zeigt beide Methoden. Der automatische Modus wird verwendet, wenn das Flag connect_with_handler festgelegt ist. Andernfalls wird der manuelle Modus verwendet.

  • network_bin.cc: Das Programm, das in einer Sandbox ausgeführt werden soll (d. h. das Sandboxee)
  • network_sandbox.cc: Das Sandbox-Programm, das es ausführt (der Executor)