Install the Node.js agent

Install the Node.js agent on your system.


Quickstart

Installing the Sqreen Node.js agent allows you to monitor the security of your application and block attacks in realtime. The installation process is the same as adding any new module:

Standard Node.js application

From a terminal, install the Sqreen module and save it into your project:

npm install --save sqreen

You must require the Sqreen Node.js module first at the top of your main script:

require('sqreen');

Why must the Sqreen module be required first?

If the Sqreen agent is not required as the first module at the top of your main script, the following applies:

  • Modules required before the Sqreen agent cannot be instrumented. For example, the database driver is not protected with Sqreen logic.
  • Request context lost: the agent might not be able to determine to which HTTP request the code relates to.
  • Protection on file access or command executions from Node.js core modules is not available.

To help you troubleshoot your setup, the agent informs you if it's not the first module included. It lists all the modules required before it. Please note that it does not detect and list Node.js core modules.

Then, from a terminal, set up your Sqreen token (provided from the user interface) in your home directory:

cat > sqreen.json <<EOF
{
  "app_name": "YOUR_APPLICATION_NAME",
  "token": "SQREEN_TOKEN"
}
EOF

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or (https://my.sqreen.com/profile/organization/tokens). Your token has the prefix org_.

To help Sqreen identify the application when you use an organization token, you also need to set a unique application name.

Application tokens deprecated

Application tokens are unique to an application. Organization tokens are available throughout the organization your account belongs to.

While Sqreen will continue to support application tokens for backward compatibility in the short term, they are now deprecated, and we encourage you to convert your applications to use organization tokens as soon as possible.

Follow this how-to to migrate applications using an application token.

Install the agent in a non-production environment

Typically you install the Sqreen agent in your production environment, but you can create several applications by specifying the environment in the application name.

# Set the Sqreen token and the app name, including the environment
cat > sqreen.json <<EOF
{
    "app_name": "foobar (production)",
    "token": "SQREEN_TOKEN"
}
EOF

Basic configuration

The Sqreen agent stores your configuration in the sqreen.json file.

Instead of using the Sqreen configuration file, you can also use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables to set up your token and the application name.

export SQREEN_APP_NAME="YOUR_APPLICATION_NAME"
export SQREEN_TOKEN="SQREEN_TOKEN"

The Sqreen Node.js agent provides flexible configuration settings. Refer to Configuration for Node.js for more detailed information.

Uninstall the agent

To uninstall the Sqreen agent, remove the sqreen module from your application.

Notes

The Sqreen Node.js agent is available on npm.

Use different Sqreen applications for different environments

We recommend you to use different Sqreen applications on your different environments: production, staging and development.

sq-native module

Starting version 1.33.0, Sqreen for Node.js introduces an optional dependency on module sq-native.

This module is used to provide in-app WAF capabilities. It relies on a native addon downloaded from S3 at install time. Therefore if the post-install script are disabled or if a firewall prevents accessing S3, installation of this optional module can fail.