Welcome to Electronegativity Official Documentation
Electronegativity is a tool to identify misconfigurations and security anti-patterns in Electron-based applications. It leverages AST and DOM parsing to look for security-relevant configurations, as described in our Electron Security Checklist - A Guide for Developers and Auditors white-paper.
The Electron security white-paper introduces a checklist of security anti-patterns and must-have features to illustrate misconfigurations and vulnerabilities in Electron-based applications. Software developers and security auditors can benefit from this document as it provides a concise, yet comprehensive, summary of potential weaknesses and implementation bugs when developing applications using Electron. Based on this study, we developed Electronegativity to automate the discovery of those security anti-patterns.
Besides Application Vulnerabilities...
It is important to remember that the security of your Electron application is the result of the overall security of the framework foundation (Chromium, Node.js), Electron itself, all NPM dependencies and your code. In addition to all application code vulnerabilities likely discovered by this tool, it is your responsibility to follow a few important best practices:
- Keep your application up-to-date with the latest Electron framework release
When releasing your product, you’re also shipping a bundle composed of Electron, Chromium shared library and Node.js. Vulnerabilities affecting these components may impact the security of your application. By updating Electron to the latest version, you ensure that critical vulnerabilities (such as nodeIntegration bypasses) are already patched and cannot be exploited in your application
- Evaluate your dependencies
While NPM provides half a million reusable packages, it is your responsibility to choose trusted 3rd-party libraries. If you use outdated libraries affected by known vulnerabilities or rely on poorly maintained code, your application security could be in jeopardy
- Adopt secure coding practices
The first line of defense for your application is your own code. Common web vulnerabilities, such as Cross-Site Scripting (XSS), have a higher security impact on Electron applications hence it is highly recommended to adopt secure software development best practices and perform security testing
While installing and using Electronegativity is fairly easy, the following section covers some of the details around the tool command line arguments and internal heuristics.
To get Electronegativity up and running, it's possible to use NPM since major releases are pushed to the repository:
$ npm install @doyensec/electronegativity -g
At this stage, the tool can be invoked by using the following command line:
$ electronegativity -i [TARGET]
Since the tool can be used on both source code and application packages, it is easy to perform testing on both open-source and commercial applications.
On macOS (and potentially other platforms), it is possible to leverage the Command (or Cmd) ⌘ key to highlight file paths within terminal output and files in order to quickly open resources that require manual validation.
In addition to the mandatory
-i [TARGET] command line argument, the user can also specify the following options:
This is used for selecting a different output type. By default, the application uses standard terminal output to display results in a compact table. The user can select Comma-Separate file (CSV) or Sarif (SARIF) to obtain a more detailed description of the findings. SARIF stands for Static Analysis Results Interchange Format and it defines a standard format for the output of static analysis tools.
$ electronegativity -i [TARGET] -o output.csv
will return the output in standard output as well as generating "output.csv". The following fields will be included in the comma-separated file: issue, filename, location, sample, description, url
$ electronegativity -i [TARGET] -o output.sarif
will return the output in standard output as well as generating "output.sarif". Sarif is a json-based format following the http://json.schemastore.org/sarif-2.0.0 schema.
By default the file locations are provided in their absolute path notation. If you wish to display only their project-relative path, you can do so by providing the
-r flag (
By default, the tool will run all checks on the target file(s). However, the user may be interested in specific classes of vulnerabilities only, thus it is possible to select a list of checks (comma-separated). Checks are defined by their names (e.g. CSPGlobalCheck)
$ electronegativity -i [TARGET] -l CSPGlobalCheck
will return the output for the CSPGlobalCheck only.
Electronegativity is build in such a way to easily allow the development of new security checks.
There are three different check types that work respectively on three types of application resources:
Checks can be either "atomic" or "global":
Atomic: Defines a simple check type, where the check is execute on each branch of the AST/DOM and a single pass of the execution is sufficient to identify vulnerabilities. For example, checks in this category can verify whether a specific flag has value 'true' or 'false'
Global: This class of checks is executed after the first round of atomic checks and they work on the array of issues generated by the atomic checks to determine further vulnerabilities or discard false positives. Global checks provide an improved decisional process, which comes in handy for checks that need to scan every JS/HTML of the target application before determining the presence or absence of a vulnerability. Global checks can specify their dependence on other atomic checks (e.g. "CSPJSCheck" and "CSPHTMLCheck" need to be executed before "CSPGlobalCheck").
Depending on the specific heuristics used by the check and the type of vulnerability that we're trying to detect, the tool may mark findings as
*Review Required* meaning that the user is required to manually review the affected resources. Going forward, we plan to introduce the concept of Severity and Confidence to help screening between false positives and real issues.
Electronegativity currently implements the following checks:
- AffinityGlobalCheck.js - AFFINITY_GLOBAL_CHECK
- AllowPopupCheck.js - ALLOWPOPUPS_HTML_CHECK
- AuxclickJSCheck.js - AUXCLICK_JS_CHECK
- AuxclickHTMLCheck.js - AUXCLICK_HTML_CHECK
- AvailableSecurityFixesGlobalCheck.js - AVAILABLE_SECURITY_FIXES_GLOBAL_CHECK
- BlinkFeaturesJSCheck.js - BLINK_FEATURES_JS_CHECK
- BlinkFeaturesHTMLCheck.js - BLINK_FEATURES_HTML_CHECK
- CertificateErrorEventJSCheck.js - CERTIFICATE_ERROR_EVENT_JS_CHECK
- CertificateVerifyProcJSCheck.js - CERTIFICATE_VERIFY_PROC_JS_CHECK
- ContextIsolationJSCheck.js - CONTEXT_ISOLATION_JS_CHECK
- CustomArgumentsJSCheck.js - CUSTOM_ARGUMENTS_JS_CHECK
- CustomArgumentsJSONCheck.js - CUSTOM_ARGUMENTS_JSON_CHECK
- CSPGlobalCheck.js - CSP_GLOBAL_CHECK
- DangerousFunctionsJSCheck.js - DANGEROUS_FUNCTIONS_JS_CHECK
- ElectronVersionJSONCheck.js - ELECTRON_VERSION_JSON_CHECK
- ExperimentalFeaturesHTMLCheck.js - EXPERIMENTAL_FEATURES_HTML_CHECK
- ExperimentalFeaturesJSCheck.js - EXPERIMENTAL_FEATURES_JS_CHECK
- HTTPResourcesJSCheck.js - HTTP_RESOURCES_JS_CHECK
- HTTPResourcesHTMLCheck.js - HTTP_RESOURCES_HTML_CHECK
- InsecureContentHTMLCheck.js - INSECURE_CONTENT_HTML_CHECK
- InsecureContentJSCheck.js - INSECURE_CONTENT_JS_CHECK
- LimitNavigationJSCheck.js - LIMIT_NAVIGATION_JS_CHECK
- LimitNavigationGlobalCheck.js - LIMIT_NAVIGATION_GLOBAL_CHECK
- NodeIntegrationHTMLCheck.js - NODE_INTEGRATION_HTML_CHECK
- NodeIntegrationAttachEventJSCheck.js - NODE_INTEGRATION_ATTACH_EVENT_JS_CHECK
- NodeIntegrationJSCheck.js - NODE_INTEGRATION_JS_CHECK
- OpenExternalJSCheck.js - OPEN_EXTERNAL_JS_CHECK
- PermissionRequestHandlerJSCheck.js - PERMISSION_REQUEST_HANDLER_JS_CHECK
- PermissionRequestHandlerGlobalCheck.js - PERMISSION_REQUEST_HANDLER_GLOBAL_CHECK
- PreloadJSCheck.js - PRELOAD_JS_CHECK
- ProtocolHandlersJSCheck.js - PROTOCOL_HANDLER_JS_CHECK
- SandboxJSCheck.js - SANDBOX_JS_CHECK
- SecurityWarningsDisabledJSCheck.js - SECURITY_WARNINGS_DISABLED_JS_CHECK
- SecurityWarningsDisabledJSONCheck.js - SECURITY_WARNINGS_DISABLED_JSON_CHECK
- WebSecurityHTMLCheck.js - WEB_SECURITY_HTML_CHECK
- WebSecurityJSCheck.js - WEB_SECURITY_JS_CHECK