Install the Node.js agent

Install the Node.js agent on your system.


Quickstart

Installing the Sqreen Node.js agent enables 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 is not the first module included. It lists all the modules required before it. Please note that Node.js core modules are not detected and thus won't be listed.

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 is prefixed with org_.

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

Application tokens depreciated

Appplication tokens are dedicated to an application, and 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 depreciated, and we encourage you to convert your applications to use organization tokens as soon as possible.

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.