The Contrast Node agent analyzes the behavior of Node.js web applications using established techniques, such as source-to-source compilation, to add Contrast sensors to an application prior to execution. Just as tools such as Istanbul and CoffeeScript use this technique to weave new features into JavaScript, Contrast uses it to help you keep your applications secure.

About the Agent

There are two primary source code transformations that the Contrast Node agent employs to monitor the behavior of your application:

Function hooks take over the execution of a given function like, child_process.exec, to collect data about its arguments and its return value, and send this data to the parts of the agent responsible for analysis. As a result, the agent enables certain functions to be self reporting.

AST transformation is the process by which the agent creates an abstract syntax tree of a body of code, manipulates the tree and then creates new source code based on this syntax tree. The agent goes through this process to handle scenarios in which function hooks won't work. For example, rewrites allow Contrast to add operator overloading to JavaScript so that it can properly track the flow of untrusted data.

Use the Agent

To start analyzing an application, download the Node.js agent and create a configuration file. The process is outlined in the Node Agent Installation article. Just like you would run your application with node <app-main.js>, the Contrast Node agent allows you to run your application with node ./node_modules/node_contrast <app-main>.js.

Supported Technologies

Node.js Version Support

Contrast supports Node.js Long-Term Support (LTS) versions 6, 8 and 10. Contrast shifts its support for Node.js versions as the working group shifts its LTS windows. For the schedule, see the Node.js Long-Term Support Release Schedule.

Note: The Node.js agent currently doesn't support HTTP2, and generally doesn't support Node.js features classified as Experimental (Stability: 1).

Web Framework Support

While the agent can still run on web frameworks that aren't officially supported, Contrast may produce less-specific findings than it would for supported frameworks. Instead of reporting that a vulnerability occurs in your application code, Contrast may need to report it within the framework code where it interfaces directly with Node.js's built-in http module.

Third-Party Module Support

Contrast doesn't guarantee support for old or deprecated versions of third-party modules.

OS Support

The agent runs in the Node.js application layer with some C++ dependencies. As a result, it works on the same operating systems as Node.js, including Linux, Windows, macOS and other Unix-like systems, assuming there is a C++ compiler toolchain installed.

Testing Environments

When changes are made, Contrast runs a battery of automated tests to ensure that it detects findings in supported technologies across all supported versions of Node. This includes tests that exercise the agent against Contrast's Node Test Bench, Hapi 16 Test Bench, Hapi 17 Test Bench and Hapi 18 Test Bench applications. Each of these applications is updated as Contrast adds more third-party library support to the agent.

If you want to add test cases, let Contrast know by clicking on the link of your chosen application and submitting a pull request.

Additional Technology

Contrast runs with a range of third-party technology, including options that aren't listed here. If you want to confirm that Contrast supports your preferred technology, or you'd like to make a case for Contrast to support it, let Contrast know.

More Information

Working with Transpilers

Contrast supports applications written in languages that compile to JavaScript, such as CoffeeScript and TypeScript. While Contrast only instruments JavaScript, you can tell Contrast how to get to the compiled code; whether the JavaScript is precompiled or compiled at runtime determines your method.

Note: Although Contrast functions with languages that compile to JavaScript, the source may not correspond directly with the resulting JavaScript. As a result, reported metadata - such as vulnerability line-of-code and filename - references the compiled result, not the original source.

Runtime Compilers

Languages like CoffeeScript run via a command line utility, which acts as a runner and compiles your application to JavaScript at runtime. It's possible to have Contrast's Node.js agent act as a runner for the runtime transpiler, which acts as a runner for your application.

To set up Contrast as a runner, you must provide the entrypoint to the transpiler instead of providing the entrypoint to your application as an argument. (You're essentially telling Contrast that your application is the transpiler.) Next, you must use the --appArgs setting to tell Contrast to pass this argument along.

Please refer to the following example script setup for running Contrast with a CoffeeScript application:

scripts: {
    "test": "...",
    "start": "...",
    "contrast": "node-contrast /path/to/coffee/transpiler --application.args '/path/to/app/entrypoint.cofee'"


Some languages, like TypeScript, require you to precompile your code before runtime. In these cases, Contrast must simply point to the compiled entrypoint for your application:

scripts: {
    "test": "...",
    "start": "...",
    "contrast": "node-contrast /path/to/compiled/entrypoint.js"