RealityServer Features

Command Blacklist

Availability

RealityServer supports a command blacklist and whitelist system to reduce the attack surface of RealityServer servers. When configured, blacklisting only allows the running of commands that are configured to be acceptable. This prevents applications running commands which contain risky functionality such as writing directly to disk (e.g., \c export_scene).

  • If neither a blacklist or whitelist are configured then all commands are are allowed (this is the default state).
  • If a blacklist is configured alone then all commands will be allowed to run, except those listed in the blacklist.
  • If a whitelist is configured alone then only commands in the whitelist will be allowed to run.
  • If both blacklists and whitelists are configured then only commands which are in the whitelist and not in the blacklist will be allowed to run.
The command blacklisting systems is available in the following contexts:
  • JSON-RPC requests
  • WebSocket requests
  • Native C++ commands calling other commands
  • V8 JavaScript commands calling other commands

To allow for the sanctioning of safe commands, the concept of tainting is used. A \c tainted command context will enforce usage of the command blacklisting system. For many situations, this is the default. However when calling a subcommand from a C++ or V8 Javascript command, the command will need to enable the blacklisting system manually by setting its context as \c tainted. For V8 Javascript commands, this is done by setting \c RS.Tainted to \c true . For C++ commands, this is done by calling \c set_tainted(true) on the \c ICommand_context interface before subcommand execution. By doing this any disallowed commands will fail to execute.

When a command execution is rejected due to blacklisting or whitelisting it returns the equivalent response to the command not being found for which ever method is being used to access it. The response is identical to that type of error as to not reveal that the rejection was due to blacklisting or whitelisting.

Where the functionality of a disallowed command is needed it is expected that command would be wrapped in another command which performs the needed validation to make it safe.

Blacklist configuration is only available through realityserver.conf style configuration. See the Blacklist Directives section of the RealityServer Configuration documentation for how to set the \c command_blacklist , \command_whitelist , \c command_blacklist_file and \command_whitelist_file global directives.