Whitelist for SCM Packages
In the context of the ThingWorx SCM Edge Extension for the .NET SDK, a whitelist is a simple text file that provides a .NET SDK application with a list of executables on the device that should be allowed to process a script that has been downloaded in a package from the ThingWorx Platform. It is up to developers to create the whitelist. If you are downloading a script to devices, the whitelist must provide the extension for the script file and the path to the executable. The following table lists some scripting languages that you may want to use, their file extensions, and the default paths to the scripting executables on devices.
|
Scripting Language
|
File Extension
|
Default Path to Executable
|
|---|---|---|
|
Node.js
|
js
|
c:\Program Files\node\node.exe
|
|
Python
|
py
|
c:\Program Files\python\python.exe
|
|
BASIC (Windows)
|
bas
|
c:\Program Files\cscript.exe
|
|
Batch (Windows)
|
bat
|
CMD /C
|
For example, js is the extension for a node.js script and the complete path to the executable on a Windows device is c:\Program Files\node\node.exe. For the Windows Script Host, the file extension is bas, and the path to the executable is c:\Program Files\cscript.exe. Here is an example of a whitelist:
# This is a sample whitelist
# please review it before using it in production
js,C:\Program Files\node\node.exe
bas,C:\Program Files\cscript.exe
bat,CMD /C
py,C:\Program Files\python\python.exe
# please review it before using it in production
js,C:\Program Files\node\node.exe
bas,C:\Program Files\cscript.exe
bat,CMD /C
py,C:\Program Files\python\python.exe
In this example, the first entry shows the extension for node.js (js) and the path to the executable on a Windows device. The second entry shows the extension for BASIC (bas) and the path to the executable on a Windows computer. The third entry is for Windows batch (bat) file and the path for launching it. The fourth line provides the extension for Python (py) and the path to the Python executable on a Windows device.
SCM Security on Windows
To prevent malicious code from being downloaded and executed on your Windows devices, you can use the Windows user field to execute packages as a user specified in the whitelist. This field contains a "well-known security ID" string (SID), as described at https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/security-identifiers. The SID string corresponds to the lowest possible security level at which the installed script can successfully be executed. The installation occurs at the security level indicated by the generic security string in the user field of the whitelist.
Specifically, the SID should be one of the following:
• "S-1-16-0" for Untrusted Mandatory Level
• "S-1-16-4096" for Low Mandatory Level
• "S-1-16-8192" for Medium Mandatory Level
• "S-1-16-8448" for Medium Plus Mandatory Level
• "S-1-16-12288" for High Mandatory Level
 |
The user field can also be left empty, indicating that the install process should be run at the security level of the current user.
|
Adding Entries to the Whitelist
To add a new approved script executable, use the ScmThing.AddExecutionWhilteListEntry(ext,usr,path) function, where
• ext is the file extension for scripts, such as js, bas, or lua.
• usr is the name of a system user that SCM should try to use to run the script executable.
• path is the full path to the program that is expected to run the script that has the matching extension.
Reading the Whitelist
If you want to check that a particular extension is in the whitelist file, use the GetWhiteListEntry(ext) function, where ext is the file extension that you want to check. The function returns the matching entry for the extension specified.