Launch assets by using a secured API
OpenFin allows programs to launch a variety of files, such as application assets, files that are downloaded during the application's lifetime, and existing executable files on the user's local hard drive. As convenient as this capability is, it can also be a risk to security. These risks can include ransomware, spyware, remote control software, corrupted and vandalized files, computer viruses, or other problems.
OpenFin provides security measures for downloaded files in the launchExternalProcess
function. The launchExternalProcess
function is itself a secured API which the developer must explicitly allow in the application manifest or the desktop owner settings, and the user must explicitly allow at runtime. To learn more about this, see the API security article.
The launchExternalProcess
function controls permissions for three processes: Application assets, downloaded files, and executable files.
In its simplified form, the launchExternalProcess
function gives full permission or full denial for each process type by the use of the boolean enabled
field.
Starting in 29.108.73, the launchExternalProcess
function has a rules-based system to allow or deny running specific assets and executable files.
How to use launchExternalProcess
The settings for launching external processes are stored in either the application manifest or the desktop owner settings. The launchExternalProcess
property exists within the System
property which exists within the permissions
property.
Launch application assets
With the launchExternalProcess
function, application assets can all be allowed or blocked, or selectively allowed or blocked.
Application assets are defined in the appAssets
array in the application manifest. These assets can be images, icons, fonts, executable files, or other files used by your application.
For example, this appAssets
array defines two assets which have the alias
of myapp
and myapp2
.
"appAssets": [
{
"src": "http://filesamples.com/exe.zip",
"alias": "myApp",
"version": "4.12.8",
"target": "myApp.exe",
"args": "a b c d"
},
{
"src": "http://examples.com/exe.zip",
"alias": "myApp2",
"version": "5.12.8",
"target": "myApp2.exe",
"args": "a b c"
}
]
Simplified method
To allow all assets to be launched, assets.enabled
must be set to true
. To block the launch of all assets, assets.enabled
must be set to false
.
In this example, all assets are allowed to launch:
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"assets": {
"enabled": true
}
}
}
}
Rules-based method
To allow specific assets to be launched or blocked, add a srcRules
array. Each element in the srcRules
array defines a match pattern rule to allow or block a set of assets that match specific criteria.
If there is nothing in the srcRules
array, all defined assets are allowed.
If there are elements in the srcRules
array, the matching engine iterates over the srcRules
array from top to bottom, stopping at the first match. If there is no match, the default behavior is used. To change the default behavior, include this as the last element in the srcRules
array: {match:['<all_urls>']}
It is recommended that specific cases be at the top of the array (for example, "https://mywebsite.com/assets/myasset.zip"
) and generic cases at the bottom of the array (for example, "*://*.google.com/*"
).
In this example, myapp
matches the first match
element because the src
for myapp
is http://filesamples.com/exe.zip, and is allowed to run because the rule has a "behavior": "allow"
. The second "match" rule ensures that all assets are blocked if they are from sources that don't match the first rule.
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"assets": {
"enabled": true,
"srcRules": [
{
"match": [
"*://filesamples.com/*"
],
"behavior": "allow"
},
{
"match": [
"<all_urls>"
],
"behavior": "block"
}
]
}
}
}
}
Launch downloaded files
With the launchExternalProcess
function, you can allow or block the launch of files downloaded by the user during the lifecycle of an OpenFin Application. This permission is allowed or blocked. Downloads do not have rules-based permissions.
Simplified method
To allow all downloaded files to be launched, downloads.enabled
must be set to true
. To block the launch of all downloaded files, downloads.enabled
must be set to false
.
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"downloads": {
"enabled": true
}
}
}
}
This is how to launch a downloaded file:
// Get the window ID.
const win = fin.Window.getCurrentSync();
// Add an event listener for the file-download-completed event.
win.addListener('file-download-completed', (evt) => {
// If the file download completed successfully ...
if (evt.state === 'completed') {
// Launch the downloaded file.
fin.System.launchExternalProcess({
// Save the UUID of the file so the file can be launched.
fileUuid: evt.fileUuid,
arguments: '',
listener: (result) => {
console.log('the exit code', result.exitCode);
}
}).then(processIdentity => {
console.log(processIdentity);
}).catch(error => {
console.logerror;
});
}
});
Launch executable files
With the launchExternalProcess
function, executable files can be all allowed or blocked, or selectively allowed or blocked.
Executable files that can be launched are programs and batch files which already exist on the user's computer, such as notepad.exe
and EXCEL.EXE
.
Simplified method
To allow all executable files to be launched, executables.enabled
must be set to true
. To block the launch of all assets, executables.enabled
must be set to false
.
In this example, all executable files are allowed to launch without restriction:
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"executables": {
"enabled": true
}
}
}
}
Rules-based method
To allow specific executable files to be launched or blocked, add a pathRules
array. Each element in the pathRules
array defines a match pattern rule to allow or block a set of executable files that match specific criteria.
If there is nothing in the pathRules
array, all defined executable files are allowed.
If there are elements in the pathRules
array, the matching engine iterates over the pathRules
array from top to bottom, stopping at the first match. If there is no match, the default behavior is allowed. To change the default behavior, include this as the last element in the pathRules
array: {match:['*.exe']}
It is recommended that specific cases be at the top of the array (for example, "C:\Program Files\Microsoft Office\root\Office16\EXCEL.EXE"
) and generic cases at the bottom of the array (for example, "*\Program Files*\Microsoft*"
).
In this example, C:\Windows\System32\xcopy.exe
matches the first match
element and is allowed to run because the rule has "behavior": "allow"
, but C:\Windows\notepad.exe
is not allowed to run because it matches the second match
element which has "behavior": "block"
.
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"executables": {
"enabled": true
"pathRules": [
{
"match": [
"*/System32/*.exe"
],
"behavior": "allow"
},
{
"match": [
"*.exe"
],
"behavior": "block"
}
]
}
}
}
}
Updated 12 months ago