1. Welcome to the NSR Physiome Project!
  2. Physiome JSim
  3. The JSim Documentation Set
  4. The JSim Sandbox

The JSim Sandbox

Introduction

JSim models allow for embedding of source code in Java, C and (eventually) other languages using a feature called Functions and Procedures (F&P). F&P give modelers great flexibility in how they formulate model calculations, at the cost of opening a potential security hole. Using these same constructs, an unscrupulous person could embed malicious code into a JSim model or project file and pass it on to an unsuspecting JSim user. The user's account and/or computer system might then be harmed by running such a model under JSim. The JSim sandbox is a mechanism for safely running untrusted model code.

Prerequisites:

Contents:

  • Sandbox Overview
  • Activating the Sandbox
  • Usage Recommendations
  • Technical Details
  • Comments or Questions?

Give feedback

Sandbox Overview

The JSim sandbox is a protected environment for running Java F&P that prevents potentially dangerous operations (such as deleting arbitrary files). Complete details on prohibited operations are found in the technical details section of this document.

The sandbox has two user-configurable parameters:

  1. READPATH - readable directories available to the application;
  2. WRITEPATH - writeable/deletable directories available to the application.

The default sandbox is very restrictive, prohibiting, for instance, saving project files in their normal locations. The user may augment the default READPATH and WRITEPATH on the command line in jsim or jsbatch.

Activating the Sandbox

The sandbox is activated in the -sandbox switch::

-sandbox [ WRITEPATH [ READPATH ] ]

Each PATH is a list of files or directories separated by your operating system's path separation character (colon on MacOS and Linux, semi-colon on Windows). User may specify no paths, the WRITEPATH only or both paths. READPATH automatically contains WRITEPATH so path elements need not be entered twice.

The sandbox switch is available in the jsim, jsbatch and jsserver programs. jsserver behaves slightly differently that the others in that:

  • the sandbox is active by default. It may be disabled (NOT RECOMMENDED) via the -nosandbox switch;
  • READPATH and WRITEPATH may not be specified on the command line.

Usage Recommendations

NSR recommends the following safety practices as standard:

  1. Running models developed by yourself or trusted collaborators does not require the sandbox.
  2. If you receive a model or project file from an untrusted source, it should be run in the sandbox. If working in the sandbox is inconvenient, you should examine the code to make sure there is nothing malicious in it before running it outside the sandbox.
  3. It is always a poor idea to run JSim (or any other complex user program) from a privileged account (that is, Administrator or root).

Technical Details

Activating the sandbox causes the following changes in program behaviour:

  • The default JSIMPATH does not contains the program launch directory (.);
  • The default READPATH in command-line applications (jsbatch, jsserver) contains JAVAHOME, JSIMHOME and JSIMPATH;
  • The default READPATH in GUI applications (jsim) contains all files;
  • The default WRITEPATH is the work directory for the session;
  • The default READPATH and WRITEPATH may be augmented via the -sandbox switch in jsim and jsbatch;
  • reading files outside READPATH is prohibited;
  • writing or deleting files outside WRITEPATH is prohibited;
  • C language source F&P is prohibited;
  • Loading native libraries from the session work directory is prohibited;
  • Executing system commands (such as "rm -Rf /") is prohibited;
  • Opening network connections is allowed only to the local host, a remote RMI server/client host (if any), and the -userurl host (if any).

If you have particular concerns about JSim security issues, contact us.

Comments or Questions?

Give feedback

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.