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 isolare un altro programma e come comunicare con esso.

• crc4bin.cc: il programma che vogliamo inserire nella sandbox (ovvero Sandboxee)
• crc4sandbox.cc: il programma sandbox che lo eseguirà (ovvero l'executor).

Come funziona:

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

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

static

L'esempio statico mostra come eseguire il sandboxing di un binario collegato staticamente, ad esempio un binario di terze parti di cui non disponi dell'origine, il che significa che non è a conoscenza del fatto che verrà sottoposto a sandboxing.

• static_bin.cc: Sandboxee è un 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 di file per l'input di Sandboxee.

Come funziona:

1. L'esecutore avvia Sandboxee dal percorso del file utilizzando GetDataDependencyFilepath, proprio come per CRC4.
2. Imposta i limiti, apre un descrittore di file su /proc/version e lo contrassegna per essere mappato in Sandboxee con MapFd.
3. Le norme consentono ad alcune chiamate di sistema (open) di restituire un errore (ENOENT) anziché essere interrotte a causa di una violazione delle norme. Ciò può essere utile quando viene eseguito il sandboxing di un programma di terze parti in cui non è possibile modificare le chiamate di sistema effettuate, quindi possiamo farle non riuscire in modo controllato.

strumento

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 binario in modalità sandbox,
  • come configurare i controlli del file system e
  • in che modo l'executor può eseguire Sandboxee in modo asincrono per leggere progressivamente il suo output.

Prova anche tu:

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 Sandboxee
• --sandbox2tool_additional_bind_mounts <PATHS> per rendere disponibili directory aggiuntive al sandboxee
• --sandbox2tool_keep_env per mantenere le variabili di ambiente correnti
• --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 di wall-time in secondi
• --sandbox2tool_file_size_creation_limit per impostare la dimensione massima dei file creati
• --sandbox2tool_cwd per impostare la directory di lavoro attuale del sandbox

custom_fork

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

Questa modalità offre prestazioni potenzialmente migliori rispetto ad altri tipi di sandbox, in quanto la creazione di nuove istanze di Sandboxee non richiede l'esecuzione di nuovi binari, ma solo la creazione di una copia di quelli esistenti.

• custom_fork_bin.cc: il server fork personalizzato, che riceve richieste di fork() (tramite Client::WaitAndFork) 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.

rete

Lo spazio dei nomi di rete, abilitato per impostazione predefinita, impedisce al processo in sandbox di connettersi al mondo esterno. Questo esempio mostra come risolvere il 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ò utilizzarlo per scambiare i dati come di consueto.

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

network_proxy

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

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

• Automatico: installando un gestore automatico ed emettendo poi chiamate di connessione regolari.
• 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 nella sandbox (ovvero il Sandboxee).
• network_sandbox.cc: il programma sandbox che lo eseguirà (l'executor).