Ejemplos

Descripción general

Preparamos algunos ejemplos para demostrar cómo usar Sandbox2 en diferentes situaciones y cómo escribir políticas.

Puedes encontrarlos en //sandboxed_api/sandbox2/examples. A continuación, encontrarás explicaciones detalladas.

CRC4

El ejemplo de CRC4 es un cálculo intencionalmente defectuoso de una suma de verificación CRC4, que demuestra cómo ejecutar otro programa en un entorno de pruebas y cómo comunicarse con él.

  • crc4bin.cc: Es el programa que queremos ejecutar en la zona de pruebas (es decir, el Sandboxee).
  • crc4sandbox.cc: Es el programa de zona de pruebas que lo ejecutará (es decir, el ejecutor).

Cómo funciona:

  1. El ejecutor inicia Sandboxee desde su ruta de acceso al archivo con ::sandbox2::GetDataDependencyFilePath().
  2. El ejecutor envía la entrada al Sandboxee a través del canal de comunicación Comms con SendBytes().
  3. Sandboxee calcula el CRC4 y envía sus respuestas al ejecutor a través del canal de comunicación Comms, que lo recibe con RecvUint32().

Si el programa realiza cualquier otra llamada al sistema que no sea de comunicación (read() y write()), se detiene debido a un incumplimiento de política.

static

El ejemplo estático muestra cómo aislar un objeto binario vinculado de forma estática, como un objeto binario de terceros para el que no tienes la fuente, lo que significa que no sabe que se aislará.

  • static_bin.cc: Sandboxee es un objeto binario estático de C que convierte el texto ASCII de la entrada estándar a mayúsculas.
  • static_sandbox.cc: Es el ejecutor con su política y límites, y que usa un descriptor de archivo para la entrada de Sandboxee.

Cómo funciona:

  1. El ejecutor inicia el Sandboxee desde su ruta de acceso al archivo con GetDataDependencyFilepath, al igual que para CRC4.
  2. Establece límites, abre un descriptor de archivo en /proc/version y lo marca para que se asigne en el Sandboxee con MapFd.
  3. La política permite que algunas llamadas al sistema (open) muestren un error (ENOENT) en lugar de que se interrumpan debido a un incumplimiento de política. Esto puede ser útil cuando se ejecuta en un entorno de pruebas un programa de terceros en el que no podemos modificar las llamadas al sistema que se realizan, por lo que, en cambio, podemos hacer que fallen de forma correcta.

herramienta

El ejemplo de herramienta es tanto una herramienta para desarrollar tus propias políticas y experimentar con las APIs de Sandbox2, como una demostración de sus funciones.

  • sandbox2tool.cc: Es el ejecutor que demuestra lo siguiente:
    • cómo ejecutar otro objeto binario en un entorno de pruebas aislado
    • cómo configurar las verificaciones del sistema de archivos
    • cómo el ejecutor puede ejecutar Sandboxee de forma asíncrona para leer su salida de forma progresiva.

Pruébalo:

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

Marcas:

  • --sandbox2tool_resolve_and_add_libraries para resolver y activar las bibliotecas requeridas para Sandboxee
  • --sandbox2tool_additional_bind_mounts <PATHS> para que haya directorios adicionales disponibles para el Sandboxee
  • --sandbox2tool_keep_env para conservar las variables de entorno actuales
  • --sandbox2tool_redirect_fd1 para recibir el STDOUT_FILENO (1) de Sandboxee y generarlo de forma local
  • --sandbox2tool_cpu_timeout para establecer el tiempo de espera de la CPU en segundos
  • --sandbox2tool_walltime_timeout para establecer el tiempo de espera de tiempo real en segundos
  • --sandbox2tool_file_size_creation_limit para establecer el tamaño máximo de los archivos creados
  • --sandbox2tool_cwd para establecer el directorio de trabajo actual de la zona de pruebas

custom_fork

En el ejemplo de custom_fork, se muestra cómo crear un entorno de pruebas que inicializará el archivo binario y, luego, esperará las solicitudes de fork() provenientes del ejecutor principal.

Este modo ofrece un rendimiento potencialmente mayor en comparación con otros tipos de zonas de pruebas, ya que, en este caso, la creación de nuevas instancias de Sandboxees no requiere la ejecución de nuevos archivos binarios, sino solo la bifurcación de los existentes.

  • custom_fork_bin.cc: Es el servidor de bifurcación personalizado que recibe solicitudes para fork() (a través de Client::WaitAndFork) con el objetivo de generar nuevos Sandboxees.
  • custom_fork_sandbox.cc: Es el ejecutor, que inicia un servidor de bifurcación personalizado. Luego, le envía solicitudes (a través de ejecutores nuevos) para generar (a través de fork()) nuevos Sandboxees.

red

El espacio de nombres de red, que está habilitado de forma predeterminada, impide que el proceso en zona de pruebas se conecte con el mundo exterior. En este ejemplo, se muestra cómo abordar este problema.

Se inicializa una conexión dentro del ejecutor y el socket resultante se pasa a través de ::sandbox2::Comms::SendFD(). Sandboxee recibe el socket con ::sandbox2::Comms::RecvFD() y, luego, puede usarlo para intercambiar los datos como de costumbre.

  • network_bin.cc: Es el programa que queremos ejecutar en la zona de pruebas (es decir, el Sandboxee).
  • network_sandbox.cc: Es el programa de zona de pruebas que lo ejecutará (es decir, el ejecutor).

network_proxy

En este ejemplo, se muestra una forma alternativa de controlar un espacio de nombres de red. Internamente, funciona exactamente igual que el ejemplo anterior, pero se expone como una API más conveniente.

El Sandboxee puede establecer una conexión de red de 2 maneras diferentes:

  • automático: Se instala un controlador automático y, luego, se emiten llamadas de conexión periódicas.
  • manual: Se obtiene un objeto NetworkProxyClient y se usa NetworkProxyClient::Connect directamente.

En este ejemplo, se muestran ambos métodos. El modo automático se usa cuando se establece la marca connect_with_handler; de lo contrario, se usa el modo manual.

  • network_bin.cc: Es el programa que queremos ejecutar en la zona de pruebas (es decir, el Sandboxee).
  • network_sandbox.cc: Es el programa de zona de pruebas que lo ejecutará (el ejecutor).