Skip to content

Home

Jump to bottom
Anthony Trummer edited this page Jan 6, 2022 · 43 revisions

Welcome to the 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's 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.

Getting Started

While installing and using Electronegativity is fairly easy, the following section covers some of the details around the tool's 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 package manager:

$ npm install @doyensec/electronegativity -g

At this stage, the tool can be invoked by using the following command line:

$ electronegativity -i [TARGET]

Where [TARGET] is either the application source code directory, a single JavaScript file (.js), a single HTML file (.html), or an application ASAR package (.asar). In case of single files, the tool will only invoke checks that are relevant for the target. Please note that it is also possible to use wildcard * characters.

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:

Output selection

-o, --output

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 (--relative). It is also possible to provide the -v flag to also display a short informative description for each issue encountered.

Checks selection

-l, --checks

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.

Check Typologies

Electronegativity was designed 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:

  • JS
  • HTML
  • JSON

Checks can be either "atomic" or "global":

  • Atomic: Defines a simple check type, where the check is executed 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 line of JS/HTML in 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 Checks

Electronegativity currently implements the following checks:

  1. AffinityGlobalCheck.js - AFFINITY_GLOBAL_CHECK
  2. AllowPopupCheck.js - ALLOWPOPUPS_HTML_CHECK
  3. AuxclickJSCheck.js - AUXCLICK_JS_CHECK
  4. AuxclickHTMLCheck.js - AUXCLICK_HTML_CHECK
  5. AvailableSecurityFixesGlobalCheck.js - AVAILABLE_SECURITY_FIXES_GLOBAL_CHECK
  6. BlinkFeaturesJSCheck.js - BLINK_FEATURES_JS_CHECK
  7. BlinkFeaturesHTMLCheck.js - BLINK_FEATURES_HTML_CHECK
  8. CertificateErrorEventJSCheck.js - CERTIFICATE_ERROR_EVENT_JS_CHECK
  9. CertificateVerifyProcJSCheck.js - CERTIFICATE_VERIFY_PROC_JS_CHECK
  10. ContextIsolationJSCheck.js - CONTEXT_ISOLATION_JS_CHECK
  11. CustomArgumentsJSCheck.js - CUSTOM_ARGUMENTS_JS_CHECK
  12. CustomArgumentsJSONCheck.js - CUSTOM_ARGUMENTS_JSON_CHECK
  13. CSPGlobalCheck.js - CSP_GLOBAL_CHECK
  14. DangerousFunctionsJSCheck.js - DANGEROUS_FUNCTIONS_JS_CHECK
  15. ElectronVersionJSONCheck.js - ELECTRON_VERSION_JSON_CHECK
  16. ExperimentalFeaturesHTMLCheck.js - EXPERIMENTAL_FEATURES_HTML_CHECK
  17. ExperimentalFeaturesJSCheck.js - EXPERIMENTAL_FEATURES_JS_CHECK
  18. HTTPResourcesJSCheck.js - HTTP_RESOURCES_JS_CHECK
  19. HTTPResourcesHTMLCheck.js - HTTP_RESOURCES_HTML_CHECK
  20. HTTPResourcesAndNodeIntegrationGlobalCheck - HTTP_RESOURCES_WITH_NODE_INTEGRATION_GLOBAL_CHECK
  21. InsecureContentHTMLCheck.js - INSECURE_CONTENT_HTML_CHECK
  22. InsecureContentJSCheck.js - INSECURE_CONTENT_JS_CHECK
  23. LimitNavigationJSCheck.js - LIMIT_NAVIGATION_JS_CHECK
  24. LimitNavigationGlobalCheck.js - LIMIT_NAVIGATION_GLOBAL_CHECK
  25. NodeIntegrationHTMLCheck.js - NODE_INTEGRATION_HTML_CHECK
  26. NodeIntegrationAttachEventJSCheck.js - NODE_INTEGRATION_ATTACH_EVENT_JS_CHECK
  27. NodeIntegrationJSCheck.js - NODE_INTEGRATION_JS_CHECK
  28. OpenExternalJSCheck.js - OPEN_EXTERNAL_JS_CHECK
  29. PermissionRequestHandlerJSCheck.js - PERMISSION_REQUEST_HANDLER_JS_CHECK
  30. PermissionRequestHandlerGlobalCheck.js - PERMISSION_REQUEST_HANDLER_GLOBAL_CHECK
  31. PreloadJSCheck.js - PRELOAD_JS_CHECK
  32. ProtocolHandlersJSCheck.js - PROTOCOL_HANDLER_JS_CHECK
  33. RemoteModuleJSCheck.js - REMOTE_MODULE_JS_CHECK
  34. SandboxJSCheck.js - SANDBOX_JS_CHECK
  35. SecurityWarningsDisabledJSCheck.js - SECURITY_WARNINGS_DISABLED_JS_CHECK
  36. SecurityWarningsDisabledJSONCheck.js - SECURITY_WARNINGS_DISABLED_JSON_CHECK
  37. WebSecurityHTMLCheck.js - WEB_SECURITY_HTML_CHECK
  38. WebSecurityJSCheck.js - WEB_SECURITY_JS_CHECK
Clone this wiki locally