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 11 months ago