Exemples

Présentation

Nous avons préparé quelques exemples pour vous montrer comment utiliser Sandbox2 dans différents scénarios et comment rédiger des règles.

Vous les trouverez dans //sandboxed_api/sandbox2/examples. Vous trouverez des explications détaillées ci-dessous.

CRC4

L'exemple CRC4 est un calcul intentionnellement bogué d'une somme de contrôle CRC4, qui montre comment mettre en bac à sable un autre programme et comment communiquer avec lui.

  • crc4bin.cc : programme que nous voulons mettre en bac à sable (c'est-à-dire Sandboxee)
  • crc4sandbox.cc : programme de bac à sable qui l'exécutera (c'est-à-dire l'exécuteur).

Fonctionnement :

  1. L'exécuteur démarre Sandboxee à partir de son chemin d'accès au fichier à l'aide de ::sandbox2::GetDataDependencyFilePath().
  2. L'exécuteur envoie l'entrée à Sandboxee via le canal de communication Comms à l'aide de SendBytes().
  3. Sandboxee calcule le CRC4 et renvoie ses réponses à l'exécuteur via le canal de communication Comms, qui les reçoit avec RecvUint32().

Si le programme effectue un autre appel système que la communication (read() et write()), il est arrêté pour non-respect des règles.

static

L'exemple statique montre comment mettre en bac à sable un binaire lié statiquement, tel qu'un binaire tiers dont vous n'avez pas la source, ce qui signifie qu'il n'est pas conscient qu'il sera mis en bac à sable.

  • static_bin.cc : Sandboxee est un binaire C statique qui convertit le texte ASCII de l'entrée standard en majuscules.
  • static_sandbox.cc : exécuteur avec sa stratégie, ses limites et son descripteur de fichier pour l'entrée Sandboxee.

Fonctionnement :

  1. L'exécuteur démarre Sandboxee à partir de son chemin d'accès au fichier à l'aide de GetDataDependencyFilepath, comme pour CRC4.
  2. Il définit des limites, ouvre un descripteur de fichier sur /proc/version et le marque pour qu'il soit mappé dans Sandboxee avec MapFd.
  3. La règle autorise certains appels système (open) à renvoyer une erreur (ENOENT) plutôt qu'à être arrêtés en raison d'un non-respect des règles. Cela peut être utile lors de l'exécution d'un programme tiers dans un bac à sable, où nous ne pouvons pas modifier les appels système effectués. Nous pouvons donc faire en sorte qu'ils échouent de manière élégante.

outil

L'exemple d'outil est à la fois un outil permettant de développer vos propres règles et d'expérimenter les API Sandbox2, ainsi qu'une démonstration de ses fonctionnalités.

  • sandbox2tool.cc : exécuteur démontrant :
    • exécuter un autre binaire dans le bac à sable ;
    • comment configurer les vérifications du système de fichiers ;
    • comment l'exécuteur peut exécuter Sandboxee de manière asynchrone pour lire sa sortie de manière progressive.

Faites l'essai :

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

Options :

  • --sandbox2tool_resolve_and_add_libraries pour résoudre et monter les bibliothèques requises pour Sandboxee
  • --sandbox2tool_additional_bind_mounts <PATHS> pour mettre des répertoires supplémentaires à la disposition de Sandboxee
  • --sandbox2tool_keep_env, pour conserver les variables d'environnement actuelles
  • --sandbox2tool_redirect_fd1 pour recevoir le Sandboxee STDOUT_FILENO (1) et l'afficher localement
  • --sandbox2tool_cpu_timeout pour définir le délai avant expiration du processeur en secondes
  • --sandbox2tool_walltime_timeout pour définir le délai avant expiration du temps réel en secondes
  • --sandbox2tool_file_size_creation_limit pour définir la taille maximale des fichiers créés
  • --sandbox2tool_cwd pour définir le répertoire de travail actuel du bac à sable

custom_fork

L'exemple custom_fork montre comment créer un bac à sable qui initialisera le binaire, puis attendra les requêtes fork() provenant de l'exécuteur parent.

Ce mode offre des performances potentiellement améliorées par rapport aux autres types de bac à sable, car la création de nouvelles instances de Sandboxees ne nécessite pas l'exécution de nouveaux binaires, mais uniquement la duplication de ceux existants.

  • custom_fork_bin.cc : serveur fork personnalisé, recevant les requêtes à fork() (via Client::WaitAndFork) afin de générer de nouveaux Sandboxees.
  • custom_fork_sandbox.cc : exécuteur qui démarre un serveur fork personnalisé. Il envoie ensuite des requêtes à celui-ci (via de nouveaux exécuteurs) pour générer (via fork()) de nouveaux Sandboxees.

réseau

L'espace de noms réseau, activé par défaut, empêche le processus mis en bac à sable de se connecter au monde extérieur. Cet exemple montre comment résoudre ce problème.

Une connexion est initialisée dans l'exécuteur et le socket résultant est transmis via ::sandbox2::Comms::SendFD(). Sandboxee reçoit le socket à l'aide de ::sandbox2::Comms::RecvFD(), puis peut l'utiliser pour échanger des données comme d'habitude.

  • network_bin.cc : programme que nous souhaitons mettre en bac à sable (c'est-à-dire le Sandboxee).
  • network_sandbox.cc : programme de bac à sable qui l'exécutera (c'est-à-dire l'exécuteur).

network_proxy

Cet exemple montre une autre façon de gérer un espace de noms réseau. En interne, il fonctionne exactement de la même manière que l'exemple ci-dessus, mais il est exposé en tant qu'API plus pratique.

Sandboxee peut établir une connexion réseau de deux manières différentes :

  • Automatique : en installant un gestionnaire automatique, puis en émettant des appels de connexion réguliers.
  • Manuelle : en obtenant un NetworkProxyClient et en utilisant directement NetworkProxyClient::Connect.

Cet exemple montre les deux méthodes. Le mode automatique est utilisé lorsque l'indicateur connect_with_handler est défini. Sinon, le mode manuel est utilisé.

  • network_bin.cc : programme que nous souhaitons mettre en bac à sable (c'est-à-dire le Sandboxee).
  • network_sandbox.cc : programme de bac à sable qui l'exécutera (l'exécuteur).