Esempi

Panoramica

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

Per una spiegazione dettagliata, consulta la sezione //sandboxed_api/sandbox2/examples.

CRC4

L'esempio di CRC4 è un calcolo intenzionalmente con bug di un checksum CRC4, che mostra come eseguire il sandbox di un altro programma e come comunicare con questo.

  • crc4bin.cc: il programma a cui vogliamo applicare la sandbox (ovvero Sandboxee)
  • crc4sandbox.cc: il programma sandbox che lo eseguirà (ovvero l'esecutore).

Come funziona:

  1. L'esecutore avvia Sandboxee dal relativo percorso file utilizzando ::sandbox2::GetDataDependencyFilePath().
  2. L'esecutore invia un input a Sandboxee sul canale di comunicazione Comms utilizzando SendBytes().
  3. Sandboxee calcola il CRC4 e invia le sue risposte all'esecutore tramite il canale di comunicazione Comms che lo riceve con RecvUint32().

Se il programma effettua chiamate di sistema diverse dalla comunicazione (read() e write()), viene interrotta a causa di una violazione delle norme.

static

L'esempio statico mostra come eseguire il sandboxing di un programma binario collegato in modo statico, ad esempio un programma binario di terze parti per il quale non disponi dell'origine, ovvero che non è consapevole del fatto che verrà limitato tramite sandbox.

  • static_bin.cc: Sandboxee è un programma binario C statico che converte il testo ASCII da input standard a testo maiuscolo.
  • static_sandbox.cc: l'esecutore con i relativi criteri, limiti e l'utilizzo di un descrittore di file per l'input di Sandboxee.

Come funziona:

  1. L'esecutore avvia Sandboxee dal relativo percorso file utilizzando GetDataDependencyFilepath, proprio come per CRC4.
  2. Imposta i limiti, apre un descrittore di file su /proc/version e lo contrassegna per la mappatura nel Sandboxee con MapFd.
  3. Il criterio consente ad alcune chiamate di sistema (open) di restituire un errore (ENOENT) anziché essere terminate a causa di una violazione delle norme. Questo può essere utile quando si esegue il sandboxing di un programma di terze parti in cui non possiamo modificare le chiamate di sistema che vengono effettuate, ma possiamo fare in modo che non vengano eseguite correttamente.

strumento

L'esempio dello strumento è sia uno strumento per sviluppare criteri personalizzati che sperimentare con le API Sandbox2, nonché una dimostrazione delle sue funzionalità.

  • sandbox2tool.cc: l'esecutore che dimostra quanto segue:
    • come eseguire un altro programma binario con sandbox,
    • come configurare i controlli del file system e
    • il modo in cui l'esecutore può eseguire Sandboxee in modo asincrono per leggerne l'output progressivamente.

Fai una prova:

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

Contrassegni:

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

custom_fork

L'esempio custom_fork mostra come creare una sandbox che inizializza il programma binario, quindi attende le richieste fork() provenienti dall'esecutore principale.

Questa modalità offre prestazioni potenzialmente maggiori rispetto ad altri tipi di sandboxing, come in questo caso la creazione di nuove istanze di sandbox non richiede l'esecuzione di nuovi programmi binari, ma solo il forking di quelli esistenti

  • custom_fork_bin.cc: il fork-server personalizzato che riceve richieste a fork() (tramite Client::WaitAndFork) per creare nuovi sandbox.
  • custom_fork_sandbox.cc: esecutore che avvia un server fork personalizzato. Quindi invia le richieste (tramite nuovi esecutori) per generare (tramite fork()) nuovi sandbox.

emittente

Lo spazio dei nomi di rete, abilitato per impostazione predefinita, impedisce al processo con sandbox di connettersi al mondo esterno. Questo esempio mostra come affrontare questo problema.

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

  • network_bin.cc: il programma a cui vogliamo applicare la sandbox (ovvero Sandboxee).
  • network_sandbox.cc: il programma sandbox che lo eseguirà (ovvero l'esecutore).

network_proxy

Questo esempio mostra un modo alternativo per gestire uno spazio dei nomi di rete. Internamente, funziona esattamente allo stesso modo dell'esempio precedente, ma viene mostrato come un'API più comoda.

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

  • automatico – Installando un gestore automatico e quindi inviando chiamate Connect regolari.
  • manual – Ottenendo NetworkProxyClient e utilizzando direttamente NetworkProxyClient::Connect.

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