Takes two parameters Command, Options

Description:

Shell$ is a Top Query function that runs another program on the host operating system.

This function is not available by default due to the increased security risks described below. To enable this function, the Moxie.cfg value of AllowShell must be set to the word Yes.

By default, when Moxie.Build is running as an app instead of a service, the window of the program started by Shell$ will start with focus at a normal size. Various Options values can change that behaviour. When Moxie.Build is run as a service, unless the service is running as a user who is currently logged in as a desktop user (not recommended), the window will not be visible to any accessible user regardless of the Options.

Parameters:

• Command: My contain one of the following
  
  • The path of the program to run, along with any command line parameters
  • A handle returned by Shell$ when the Async Option was used, for use with Status and Close
• Options: This optional second parameter will control the behaviour using the following space-separated options:
  
  • Async: Instead of the default behaviour that executes the command synchronously (MOX code will wait until Shell$ completes), the command will execute asynchronously (MOX code will continue after starting the command)
  • Status: Using the handle returned by Async as the Command, returns the Exit Code or a value of STILL_ACTIVE
  • Close: Using the handle returned by Async as the Command, returns the Exit Code or a value of STILL_ACTIVE, and closes the handle
  • Hide: Hide the window of the program started by Shell$
  • Minimize: Minimize the window of the program started by Shell$ and without focus
  • Maximize: Maximize the window of the program started by Shell$ and with focus

Function Return:

By default, this command will return the process exit code, which is the return value of the WinMain function of the program that was run.

When the Async Option is used, the return value is a handle to the Windows process that was started. This handle value may be used with subsequent Shell$ calls with the Command parameter set to this value with an Option of either Status or Close to get the exit code of that process if it has completed, or it will return the text value of "STILL_ACTIVE" if the process has not yet completed. When using Async, the handle must be closed when access to the Status is no longer needed, or else a memory leak will occur.

Exit codes are returned as a signed 32-bit integer if not 0, or are blank/false if 0. Typically, negative values are error codes, 0 (returned as blank/false) is success without a specific value, and positive values other than 259 are output numbers. The internal Windows integer value for STILL_ACTIVE is 259, so be careful that the programs you call do not use that value as an exit code.

Security Risks:

When this command is enabled, even when not used, its opens up an entirely new threat landscape. Moxie.Build's web safety content filtering and safety framework do not provide protection against command injection into external programs. Therefore, user data should never be included as part of the command parameter; instead, some unique identifier should be used to facilitate inter-process communication.

Furthermore, when this command is enabled, an attacker who has otherwise gained access to a Moxie.Build system can run commands on the host operating system that would otherwise not be possible to run from Moxie.Build, likely resulting in the attacker gaining access to the host operating system via exploit chaining. Consider having any instances of Moxie.Build that use Shell$ to not be user or public facing, but instead use Remote methods to communicate between a public facing instance and the private instance that uses Shell$.

Examples: