Sandbox configuration file

For security reasons, you must have a security sandbox definition file for any server where:
 an adxd daemon or service runs,
 an sadfsq software is installed to allow access to files in the file system through the
Sage X3 engine.
**Security rules have been reinforced from version 7.2: a clear distinction is done between Cloud
based and on-premise environments.** This file is called configRuntime.json: * It is installed in
the cfg subfolder of the Sage X3 runtime folder. * Ideally, it should be write protected, but readable
by the Sage X3 runtime engine. * It includes a set of parameters in JSON format, and especially the
list of folders where the Sage X3 engine is allowed to access (sandbox definition).

Cloud security: trusted and untrusted mode

When an installation is done on the Cloud, the code executed by the engine can run in `trusted` or
`untrusted` mode:
 an execution instance of a standard code provided by Sage is trusted when called directly
or when called from a trusted execution instance.
 an execution instance of specific or vertical code is untrusted.
 any standard code called from a specific or vertical code executes in untrusted mode as
well.
Some limitations apply on trusted code execution:
* the sandbox limitation applies for files accessed from the server.
* restrictions exist on the order executed by the System command as explained below.

On untrusted code execution, the limitations are more severe:

* only the sandbox location with secured flag set to true can be accessed.
* no execution of a System command is possible.

Configuration file description

The format of the file is the following:
{
"sandbox": {
"directories": [
{
"path": "...",
"extensions": ["...", "..." ]
"pattern": ["...", "..." ]
"writable": true,
"secured": true,
"volume": "A"
}
…
],
"spawn": [
{
"path": "…",
"pattern": "…"
"params": […],
 "modes": […]
}
…
],
"allowConsole" : false

In the sandbox section, the directories section is a collection of entries that define the
sandbox as a whitelist of locations that can be accessed. If there is no match, the access is denied.
The following rules apply:
 The volume property is not mandatory, but when defined, it indicates a logical volume
previously defined in the adxvolume configuration file. For more information, see the
filpath documentation.
 writable defines if files can be created or modified in the corresponding directory. Its
value is false by default.
 The longest matching path has priority. If you have rule1 for '/a' and rule2 for '/a/b/c', rule1
applies to '/a/foo.bar' and rule2 applies to '/a/b/c/foo.bar'.
 Paths are always normalized (elimination of components) before being checked against the
sandbox rules.
 secured defines if the directory can be accessed by in untrusted execution mode. Its value
is false by default.

In the sandbox section, the spawn section is a collection of entries that define the system
commands usable in trusted mode as a whitelist. If there is no match with the command to be
executed, the execution is denied. The following rules apply:
 path is the directory where the command can be found. This path must of course be
included in the sandbox whitelist.
 pattern defines the command pattern to be executed (as a regular expression). See the
section above to know the syntaxes usable for regular expressions.
 params is an optional collection of numbers that give the list of parameters of the
command that are files.
 modes is a collection of strings associated to the previous params collection, that defines
if the corresponding files need read and/or write access (the strings in the collection will
include "r" and/or "w" for this purpose).
 when a shellscript or a window script is executed, all the lines of the script are analyzed
against the spawn rules before execution of the script.

The allowConsole parameter must be set to true to allow the console to operate. The console
operation implies access to all the folders of the server and not only to the whitelist. To ensure this,
the adxadmin software, used by the console, is not concerned by the sandbox restrictions. It is
therefore important to deactivate the console during normal operations, because there is a security
flaw if the flag remains set to true. This must only be the case during the short installation and
configuration period, or when an evolution of the configuration has to be piloted by the console.
In normal exploitation conditions, allowConsole must be set to false.
As there is no exception on folders that can be accessed, the following folders must be present
in the whitelist table. The engine will not work properly otherwise. The paths of these folders
start with xxxx/runtime, which is supposed to be the path where the runtime is installed:
{ "path": "xxxx/runtime/cfg",
This folder stores the configuration file and "extensions": [ "json" ]
should be available for the other runtimes that }
access the server from the network.
{ "path": "xxx/V7.1/runtime/sem",
This folder stores a semaphore file that needs "writable": true,
to be accessed by the process monitoring "extensions": [ "map", "dat" ]
}
function (psadx).
{ "path": "xxxx/runtime/tmp",
This folder stores log files of the engine and "extensions": [ "*" ]
must therefore be accessible in write mode. }

Control process
Every time an engine function uses file access in read or write mode (with functions such as Delfile,
Renamefile, Openi, Openo, and Openio) on a given Sage X3 server, the check is done against the
configuration file installed on the right server. If the configuration file denies access to the
corresponding file, the error code 27 (no access) appears.
It is possible to check the fact that a file is readable and/or writeable using the checkpath function.
Every time a System command is executed in a secured Cloud environment, the rules defined in the
spawn section are tested if the execution mode is trusted. If the result is unsuccessful, the error
code 27 (no access) is returned. In untrusted mode, the error is raised anyway.

Special characters usable in regular expressions

Characters Definition Example
Escape character (must be
\ C:\\Sage\\bin
doubled in path definitions)
[character_li One of the characters in the
[ABC] defines one of the characters A, B, C
st] list
One character in the range
[A-Z0-9] defines a character that can be either an
[f-l] defined by the first (f) and
upper case letter or a digit.
last (l) character.
(SUB|CNS|X|Y|Z)[A-Z]* defines a name composed of
One of the patterns given in
(p1|p2|p2) uppercase characters starting either with SUB, CNS,
the list (here p1, p2 or p3)
X, Y or Z.
[A-Z][A-Z0-9]* defines a name starting with an upper
repeats the previous pattern
* case letter followed by a variable number of characters
N times (N can be 0)
that can be upper case letters and/or digits.
. Any character .* defines N characters (N can be 0).
Optional marker for the
^ ^.*A defines a name that ends with an A.
beginning of the pattern
Optional marker for the end
$ .*A$ defines a name that ends with an A.
of the pattern
Sandbox file examples
The first example here is a sandbox description that allows any system command execution. It
works well but doesn't prevent execution of any harmful system command that would be allowed to
the user executing the X3 process.
{
"sandbox": {
"directories": [{
"path": "c:\\program files\\Sage X3\\runtime\\log",
"writable": true,

"extensions": ["log","tra"]
}, {
"path": "D:\\Sage_X3\\Folders",
"extensions": ["*"]
}, {
"others" : "D:\\Sage_X3\\\Tmp",
"writable": true,
"extensions": ["*"]
}, {
"path": "D:\\Othervolumes",
"volume": "A",
"extensions": ["*"]
}]},
"spawn": [
{
"pattern": ".*",
"path": "*"
}
], {
"allowConsole" : false
}

A second more realistic example shows a complete list of possible restrictions. Here, the database
used is SQL server, the operating system is Windows, and the corresponding administration
commands are allowed by the whitelist filtering:
{
"allowConsole": false,
"secured": false,
"sandbox": {
"directories": [
{
"path": "D:\\Sage\Sage X3\\runtime\\cfg",
"extensions": [
"json"
]
},
{
"path": "D:\\Sage\Sage X3\\runtime\\sem",
"writable": true,
"extensions": [
"map",
"dat"
]
},
{
"path": "D:\\Sage\Sage X3\\runtime",
"volume": "0",
"writable": true,
 "extensions": [
"*"
]
},
{
"path": "D:\\Sage\Sage X3\\folders",
"writable": true,
"volume": "A",
"extensions": [
"*"
]
},
{
"path": "D:\\Sage\Sage X3\\folders",
"pattern": [
"^[A-Z1-9]*/TRT/[YZ][A-Z1-9_]*\\.src$",
"^[A-Z1-9]*/TRT/(SPE|SPV|SUBY|SUBZ|CNSY|CNSZ)[A-Z1-9_]*\\.src$",
"^[A-Z1-9]*/TRT/[A-Z1-9_]*(_CSPE|_CSPV|_CVER)\\.src$",
"^[A-Z1-9]*/TRT/CNS[A-Z1-9_]*SPE\\.src$",
"^[A-Z1-9]*/STC/(C_Y|C_Z|R_Y|R_Z)[A-Z1-9_]*\\.stc$"
],
"writable": "true",
"secured": "true"
},
{
"path": "D:\\Sage\Sage X3\\folders\\",
"pattern": [
"^[A-Z1-9]*\\\\TRA\\\\.*",
"^[A-Z1-9]*\\\\tmp\\\\.*",
"^[A-Z1-9]*\\\\TRT\\\\[YZ][A-Z1-9_]*\\.src$",
"^[A-Z1-9]*\\\\TRT\\\\(SPE|SPV|SUBY|SUBZ|CNSY|CNSZ)[A-Z1-9_]*\\.src$",
"^[A-Z1-9]*\\\\TRT\\\\[A-Z1-9_]*(_CSPE|_CSPV|_CVER)\\.src$",
"^[A-Z1-9]*\\\\TRT\\\\CNS[A-Z1-9_]*SPE\\.src$",
"^[A-Z1-9]*\\\\STC\\\\(C_Y|C_Z|R_Y|R_Z)[A-Z1-9_]*\\.stc$"
],
"writable": true,
"secured": true
},
{
"path": "D:\\Sage\Sage X3\\runtime\\tmp",
"writable": true,
"extensions": [
"*",
""
]
}
],
"spawn": [
{
"pattern": "^ae_echo [A-Z0-9\\.\\\\_:\\\"\\-&%]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^ae_cat [ A-Z0-9\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
1
],
"modes": "r"
},
{
"pattern": "^ae_cp [ A-Z0-9\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
 1,
2
],
"modes": "rw"
},
{
"pattern": "^ae_mv [ A-Z0-9\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
1,
2
],
"modes": "ww"
},
{
"pattern": "^ae_parse [ A-Z0-9\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
2
],
"modes": "r"
},
{
"pattern": "^lsadx [ A-Z0-9>\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^valfil [ A-Z0-9>/\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^valtrt [ A-Z0-9>\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^valstc [ A-Z0-9>\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^archive [ A-Z0-9>\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^ae_logname$",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^ae_os$",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^ae_mkdir [ A-Z0-9\\.\\\\_:\"\\-\\/]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^lsadx.*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^adonix -v [A-Z0-9_]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^killadx [0-9]*",
 "path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^killadx [0-9]* >> [ A-Z0-9\\.\\\\_:\\\"\\-\\/]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^killadx.exe -e [0-9]* > [ A-Z0-9\\.\\\\_:\\\"\\-\\/]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^BREAK OFF$"
},
{
"pattern": "^BREAK ON$"
},
{
"pattern": "^@ECHO OFF$"
},
{
"pattern": "^ae_rm [ A-Z0-9\\.\\*\\\\_:\\\"\\-]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
1
],
"modes": "w"
},
{
"pattern": "^EXIT$"
},
{
"pattern": "^psadx [ A-Z0-9\\-]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^adxdwhat [ A-Z0-9>\\.\\\\_:\\\"\\-&]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^ae_rmdir [ A-Z0-9\\.\\*\\\\_:\\\"]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin",
"params": [
1
],
"modes": "w"
},
{
"pattern": "^[ A-Z0-9>\\.\\\\_:\\\"\\-\\/]*adcrapora\\.bat [ A-Z0-
9>\\.\\\\_:\\\"\\-\\/]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^adonix -a [ 0-9A-Z\\-:]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^set USER_ENTREP=[A-Z0-9~]*"
},
{
"pattern": "^set EXEC_ENTREP=[A-Z0-9~]*"
},
{
"pattern": "^set TRA_ENTREP=[A-Z0-9~]*"
},
 {
"pattern": "^set RQT_ENTREP=[A-Z0-9~]*"
},
{
"pattern": "^sqlplus /NOLOG [A-Z0-9\\.\\\\:\\\"\\-@/]*",
"path": "D:\\Sage\Sage X3\\runtime\\instantclient_12_1\\bin"
},
{
"pattern": "^ae_parsevt [ A-Z0-9\\.\\*\\\\_:]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^adcrapss7[ A-Z0-9>\\.\\\\_:\\\"\\-@#!\\$%&'\\(\\)\\*\\
+/;<=?\\[\\]\\^`{\\|}~]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^SET OSQL_EXE=osql"
},
{
"pattern": "IF EXIST \\\"%SQLS7_OSQL%\\\\BINN\\\\osql.EXE\\\" SET
OSQL_EXE=\\\"%SQLS7_OSQL%\\\\BINN\\\\osql.EXE\\\""
},
{
"pattern": "%OSQL_EXE% -D [ A-Z0-9>\\.\\\\_:\\\"\\-@#!\\$%&'\\(\\)\\*\\
+/;<=?\\[\\]\\^`{\\|}~]*"
},
{
"pattern": "^meladx[ A-Z0-9>\\.\\\\_:\\\"\\-@#!\\$%&'\\(\\)\\*\\+/;<=?\\
[\\]\\^`{\\|}~]*",
"path": "D:\\Sage\Sage X3\\runtime\\bin"
},
{
"pattern": "^ae_sort [ A-Z0-9\\.\\\\_:\\\"\\-]*",
"path": "D:\\Sage\Sage X3\\runtime\\ebin"
},
{
"pattern": "^dir /a:d /b [ 0-9A-Z\\\\:\\\"]*",
"modes": "r",
"params": [3]
}
]
}
}