Esempi

Panoramica

Abbiamo preparato alcuni esempi per mostrare come utilizzare Sandbox2 in diversi scenari e come scrivere le norme.

Puoi trovarli in //sandboxed_api/sandbox2/examples. Di seguito sono riportate spiegazioni dettagliate.

CRC4

L'esempio CRC4 è un calcolo intenzionalmente difettoso di un checksum CRC4, che mostra come inserire un altro programma in una sandbox e come comunicare con esso.

  • crc4bin.cc: il programma che vogliamo inserire in una sandbox (ovvero il Sandboxee)
  • crc4sandbox.cc: il programma sandbox che ne eseguirà l'esecuzione (ovvero l'executor).

Come funziona:

  1. L'executor avvia il Sandboxee dal relativo percorso file utilizzando ::sandbox2::GetDataDependencyFilePath().
  2. L'executor invia l'input al Sandboxee tramite il canale di comunicazione Comms utilizzando SendBytes().
  3. Il Sandboxee calcola il CRC4 e invia le risposte all'executor tramite il canale di comunicazione Comms, che le riceve con RecvUint32().

Se il programma effettua una syscall diversa dalla comunicazione (read() e write()), viene terminato a causa di una violazione delle norme.

static

L'esempio statico mostra come inserire in una sandbox un file binario collegato staticamente, ad esempio un file binario di terze parti di cui non hai l'origine, il che significa che non sa che verrà inserito in una sandbox.

  • static_bin.cc: il Sandboxee è un file binario C statico che converte il testo ASCII dall'input standard in maiuscolo.
  • static_sandbox.cc: l'executor con le relative norme, i limiti e l'utilizzo di un descrittore del file per l'input di Sandboxee.

Come funziona:

  1. L'executor avvia il Sandboxee dal relativo percorso file utilizzando GetDataDependencyFilepath, proprio come per CRC4.
  2. Configura i limiti, apre un descrittore del file su /proc/version e lo contrassegna per essere mappato nel Sandboxee con MapFd.
  3. Le norme consentono ad alcune syscall (open) di restituire un errore (ENOENT) anziché essere terminate a causa di una violazione delle norme. Questa opzione può essere utile quando si inserisce in una sandbox un programma di terze parti in cui non è possibile modificare le syscall effettuate, quindi possiamo farle fallire in modo controllato.

tool

L'esempio di strumento è sia uno strumento per sviluppare le tue norme e sperimentare le API Sandbox2, sia una dimostrazione delle sue funzionalità.

  • sandbox2tool.cc: l'executor che mostra:
    • come eseguire un altro file binario in una sandbox,
    • come configurare i controlli del file system e
    • come l'executor può eseguire il Sandboxee in modo asincrono per leggerne progressivamente l'output.

Prova tu stesso:

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

Flag:

  • --sandbox2tool_resolve_and_add_libraries per risolvere e montare le librerie richieste per il Sandboxee
  • --sandbox2tool_additional_bind_mounts <PATHS> per rendere disponibili directory aggiuntive per il Sandboxee
  • --sandbox2tool_keep_env per mantenere le variabili di ambiente attuali
  • --sandbox2tool_redirect_fd1 per ricevere il Sandboxee STDOUT_FILENO (1) e generarlo localmente
  • --sandbox2tool_cpu_timeout per impostare il timeout della CPU in secondi
  • --sandbox2tool_walltime_timeout per impostare il timeout del tempo reale in secondi
  • --sandbox2tool_file_size_creation_limit per impostare la dimensione massima dei file creati
  • --sandbox2tool_cwd per impostare la directory di lavoro attuale della sandbox

custom_fork

L'esempio custom_fork mostra come creare una sandbox che inizializzerà il file binario e poi attenderà le richieste fork() provenienti dall'executor principale.

Questa modalità offre un potenziale aumento delle prestazioni rispetto ad altri tipi di sandbox, poiché in questo caso la creazione di nuove istanze di Sandboxee non richiede l'esecuzione di nuovi file binari, ma solo la creazione di fork di quelli esistenti.

  • custom_fork_bin.cc: il server fork personalizzato, che riceve richieste di fork() (tramite ForkingClient::EnterForkLoop) per generare nuovi Sandboxee.
  • custom_fork_sandbox.cc: l'executor, che avvia un server fork personalizzato. Poi invia richieste (tramite nuovi executor) per generare (tramite fork()) nuovi Sandboxee.

network

Lo spazio dei nomi di rete, che è attivato per impostazione predefinita, impedisce al processo in sandbox di connettersi al mondo esterno. Questo esempio mostra come risolvere questo problema.

Una connessione viene inizializzata all'interno dell'executor e il socket risultante viene passato tramite ::sandbox2::Comms::SendFD(). Il Sandboxee riceve il socket utilizzando ::sandbox2::Comms::RecvFD() e poi può utilizzare questo socket per scambiare i dati come di consueto.

  • network_bin.cc: il programma che vogliamo inserire in una sandbox (ovvero il Sandboxee).
  • network_sandbox.cc: il programma sandbox che lo eseguirà (ovvero l'executor).

network_proxy

Questo esempio mostra un modo alternativo per gestire uno spazio dei nomi di rete. Internamente, funziona esattamente come l'esempio precedente, ma viene esposto come un'API più pratica.

Il Sandboxee può stabilire una connessione di rete in due modi diversi:

  • Automatico : installando un gestore automatico e poi emettendo normali chiamate di connessione.
  • Manuale : ottenendo un NetworkProxyClient e utilizzando direttamente NetworkProxyClient::Connect.

Questo esempio mostra entrambi i metodi. La modalità automatica viene utilizzata quando è impostato il flag connect_with_handler, altrimenti viene utilizzata la modalità manuale.

  • network_bin.cc: il programma che vogliamo inserire in una sandbox (ovvero il Sandboxee).
  • network_sandbox.cc: il programma sandbox che lo eseguirà (l'executor).