Installation Issues

Scenario: I've started my application with the Node agent, but I'm not seeing any results.

Here are a few things you can do:

  • Exercise the application. Many findings will not be reported until the affected code paths have been executed.
  • Make sure the application is unarchived. Agents reporting on behalf of an archived application will be told by the Contrast application to temporarily pause reporting. Unarchiving the application should allow the agent to resume reporting within a couple of minutes.
  • Make sure that the agent is connected to the Contrast application. When the agent fails to establish a connection with the Contrast application, it will log the failure and run the application without instrumentation or reporting. Even if the application appears to be up and running, it doesn't mean the agent was successful!
  • Make sure that credentials in contrast_security.yaml belong to an account with permission to view findings for the application you're attempting to run with Contrast. You may need to check with your Contrast administrator.

Scenario: I'm seeing messages like "could not rewrite [filename]."

Part of our instrumentation process involves rewriting source as it's loaded into the module cache. The agent may fail to rewrite some files for a number of reasons: unexpected syntax, weird character encodings, etc. When this happens, the agent will log its failure and load the original, unmodified source into the module cache. While we may have difficulty following dataflow through these files, everything else should work as normal. Simply, if you are seeing these messages: please let us know!

Scenario: Contrast causes my application to misbehave.

While very uncommon, our instrumentation can introduce some errors. These types of problems are very high priority for us and are usually quickly escalated to one of our engineers; any information you can provide about the bug is very helpful to us in getting it fixed as fast as possible. When this happens, it's usually in one of three ways.

Contrast itself throws an error. This usually results in a clear error message. If there isn't one, run the agent with the agent.logger.level option set to debug, which will enable more verbose logging. The error message and stack trace is often enough for us to fix the issue, since it occurred in our code.

Contrast has changed data in a way that causes the application to throw an error. This will also probably result in an error message. Again, use the agent.logger.level option to enable more verbose logging from the agent. When we cause an error to be thrown in your code, it's almost always because we've manipulated the type of an argument being passed to a function. In this case, any information you can provide about the types the function expects, and what the function does with its arguments, can help us more quickly reproduce and patch the issue.

Contrast has changed data in a way that changes the behavior of the application. For example, data has been malformed by the agent and may break some business logic or cause conditional statements to pass or fail incorrectly. This is very rare, as Contrast tries to avoid ever modifying the meaning of the data. This is often the hardest type of problem to pin down, as on the surface it may seem like the application is fully functional. If you suspect the agent is doing this somewhere, please try to track down what behavior is changing and how it is changing from when the application is run without Contrast. With a known behavior, it becomes easier to track which data is being incorrectly changed. If it is possible to cause a stack trace once you know where this is happening, this information can make it much easier for us to figure out what we're breaking.

More Information

Node.js Agent Configuration

Application Performance

As you might expect, Contrast's analysis does make your app run a little slower. The good news is it's generally not enough for anyone to complain about, and the results are definitely worth it.

Startup Time

When you start your server with Contrast, you'll notice a delay in startup time. This is first caused by the agent attempting to establish a connection with TeamServer. High latency between the server and TeamServer, or a TeamServer which is under heavy load, may exacerbate the startup time. Where startup time is critical, this cost can be reduced as follows:

  • Run Contrast with the --skipAutoUpdate flag
  • Run Contrast with the --skipLibs flag. The agent will not collect information about the application's dependencies.
  • Run Contrast with the --localonly flag (we don't recommend this, as the agent will subsequently not attempt communication with TeamServer)

For most applications, the bulk of the startup time the agents adds is caused by the source code rewrites it performs for instrumentation. This delay scales directly with the amount of source code in the application - dependencies included. Where startup time is critical, this cost can be reduced by running Contrast with the --norewrite flag. This option is a last resort and should be avoided, as it will drastically reduce the accuracy of our dataflow.

Request Processing Time

It's probably more important to think about how Contrast affects the round-trip time. In typical applications, Contrast may noticeably impact the round-trip time of requests that contain a lot of business logic. Round-trip times for static resources typically don't get measurably worse. In requests where the total round-trip time is dominated by database or Web Service calls, Contrast's effect will be less noticeable.

If better performance is really important to your environment, consider the following options:

  • Turn off data flow rules (add --nopropagation)
  • Run Contrast nightly during integration tests
  • Run Contrast in an alternate environment (QA system or DEV environment)
  • Run Contrast on a single node in a load-balanced environment

More Information

Node.js Agent Configuration

Contrast Connectivity

Common Errors

Unable to register server with TeamServer. Contrast will not report findings. (302).

Check the credentials in contrast_security.yaml. This message is typically a result of incorrect credentials. If you're sure the credentials are correct, contact your account administrator and ensure that your account has the correct permissions.

Contrast was unable to connect to TeamServer. Continuing without instrumentation.

This occurs if the agent couldn't communicate with the Contrast application at all. Check to make sure that the contrast.url field in contrast_security.yaml is correct. It should be in the format There is no need to specify the /Contrast/ route.

This application is unwanted by TeamServer and no findings will be reported. Make sure the application is unarchived.

As is evident from the warning message, this typically occurs when the application you're using has been archived in the Contrast UI. If the application is unarchived, or you think the archived application should register differently in the Contrast application, there may simply be a name conflict. Try running with <name> to specify a unique name, which will resolve the conflict.

Set Up Proxies

Sometimes it's necessary to proxy all communication between the agent and the Contrast application. To do this, run the agent with --contrast.proxy.enable true and --contrast.proxy.url <proxy_url>. Any communication to Contrast will be sent via the proxy server specified in the URL.