Beispiele

Überblick

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

Sie finden sie unter //sandboxed_api/sandbox2/examples. Eine ausführliche Erläuterung finden Sie weiter unten.

CRC4

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

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

So gehts:

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

Wenn das Programm andere Systemaufrufe als die Kommunikation durchführt (read() und write()), 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, z. B. ein Binärprogramm eines Drittanbieters, für das Sie die Quelle nicht haben. Das bedeutet, dass nicht bewusst ist, dass sie in einer Sandbox ausgeführt wird.

  • static_bin.cc: Sandboxee ist ein statisches C-Binärprogramm, das ASCII-Text von der Standardeingabe in Großbuchstaben konvertiert.
  • static_sandbox.cc: Der Executor mit seiner Richtlinie, Beschränkungen und Verwendung eines Dateideskriptors für die Sandboxee-Eingabe.

So gehts:

  1. Das Executor startet das Sandboxee-Objekt aus seinem Dateipfad mit GetDataDependencyFilepath, genau wie für CRC4.
  2. Er legt Limits fest, öffnet einen Dateideskriptor auf /proc/version und markiert die Datei mit MapFd, damit sie in der Sandboxee zugeordnet werden kann.
  3. Gemäß der Richtlinie können einige Systemaufrufe (open) einen Fehler (ENOENT) zurückgeben, anstatt aufgrund eines Richtlinienverstoßes gelöscht zu werden. Dies kann nützlich sein, wenn ein Drittanbieterprogramm in einer Sandbox ausgeführt wird, bei der wir nicht ändern können, welche Systemaufrufe erfolgen. Stattdessen können sie ordnungsgemäß fehlschlagen.

Tool

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

  • sandbox2tool.cc: Der Executor, der Folgendes zeigt:
    • wie eine weitere binäre Sandbox ausgeführt wird,
    • wie Dateisystemprüfungen eingerichtet werden
    • wie der Executor die Sandboxee asynchron ausführen kann, um seine 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 und 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

Meldungen:

  • --sandbox2tool_resolve_and_add_libraries, um die erforderlichen Bibliotheken für die Sandboxee aufzulösen und bereitzustellen
  • --sandbox2tool_additional_bind_mounts <PATHS>, um zusätzliche Verzeichnisse für Sandboxee verfügbar zu machen
  • --sandbox2tool_keep_env, um die aktuellen Umgebungsvariablen beizubehalten
  • --sandbox2tool_redirect_fd1, um die Sandboxee-STDOUT_FILENO (1) zu erhalten und sie lokal auszugeben
  • --sandbox2tool_cpu_timeout, um das CPU-Zeitlimit in Sekunden festzulegen
  • --sandbox2tool_walltime_timeout, um das Zeitlimit in Sekunden festzulegen
  • --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 custom_fork-Beispiel zeigt, wie Sie eine Sandbox erstellen, die die Binärdatei initialisiert und dann auf fork()-Anfragen vom übergeordneten Executor wartet.

Dieser Modus bietet potenziell eine höhere Leistung im Vergleich zu anderen Sandbox-Arten, da zum Erstellen neuer Instanzen von Sandboxees keine neuen Binärprogramme ausgeführt werden müssen, sondern nur die vorhandenen abgespalten werden müssen.

  • custom_fork_bin.cc: Der benutzerdefinierte Fork-Server, der Anfragen an fork() (über Client::WaitAndFork) empfängt, um neue Sandboxees zu erzeugen.
  • custom_fork_sandbox.cc: Das Executor-Element, das einen benutzerdefinierten Fork-Server startet. Dann sendet er Anfragen (über neue Executors) an ihn, um (über fork()) neue Sandboxees zu erzeugen.

Netzwerk

Der standardmäßig aktivierte Netzwerk-Namespace verhindert, dass der in der Sandbox ausgeführte Prozess eine Verbindung zur Außenwelt herstellt. Dieses Beispiel zeigt, wie Sie mit diesem Problem umgehen.

Eine Verbindung wird innerhalb des Executors initialisiert und der resultierende Socket wird über ::sandbox2::Comms::SendFD() übergeben. Die Sandboxee empfängt den Socket mithilfe von ::sandbox2::Comms::RecvFD() und kann dann mit diesem Socket die Daten wie gewohnt austauschen.

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

network_proxy

Dieses Beispiel zeigt eine alternative Art und Weise, mit einem Netzwerk-Namespace umzugehen. Intern funktioniert sie genauso wie das obige Beispiel, wird jedoch als eine komfortablere API bereitgestellt.

Der Sandboxee kann auf zwei verschiedene Arten eine Netzwerkverbindung herstellen:

  • automatic: Durch Installieren eines automatischen Handlers und durch anschließendes Ausführen regelmäßiger Verbindungsaufrufe.
  • manual: Durch Abrufen einer NetworkProxyClient und direkt über NetworkProxyClient::Connect.

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

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