Installation of the Node.js agent


TL;DR

Installing the Sqreen Node.js agent enables you to monitor the security of your application and block attacks in real-time. Installing Sqreen in your Node.js application takes less than a minute:

  • Sign up to Sqreen to create your account
  • Pick up your first application name and language. The name of the application can be the name of the repository, or anything that will help you identify the app in your Sqreen dashboard
  • Follow the procedure detailed below

Standard Node.js Application

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

npm install --save sqreen

Sqreen NodeJS module must be required first at the top of your main script to work in optimal conditions:

require('sqreen');

Why Sqreen module must be required first?

If the Sqreen agent isn't required as the first module at the top of your main script, you may experience unexpected behaviours:

  • Modules required before Sqreen agent cannot be instrumented (e.g. database driver cannot be protected with Sqreen logic).
  • Request context lost: the agent might not be able to determine to which HTTP request the code is related to.
  • Protection on file access or command executions from NodeJS core modules will not be available.

To help you troubleshoot your setup, the agent will inform you that it hasn't been required first and list all the modules required before. Please note that NodeJS core modules are not detected thus won't be listed.

In case the agent isn't required as the first module, you may experiment unexpected behaviours: Modules required before Sqreen agent cannot be instrumented (e.g. database cannot be patched and protected). Request context lost: the agent might not be able to determine to which HTTP request the code is related to. * Protection on file access or command executions from NodeJS core modules will not be available.

Then, from a terminal, set up your Sqreen token (provided from your User Interface) in your home directory:

echo '{ "token": "mysecrettoken" }' > sqreen.json

Install the agent outside production environment

Typically you will install the Sqreen Node.js agent in your production environment, but you can create several applications using your Sqreen dashboard, and specifying the environment (development, staging, production). A unique Sqreen token will be provided for each of your applications.

Basic configuration

After installing the agent, your configuration will be stored in the configuration file sqreen.json. It basically contains your Sqreen token.

Instead of using the Sqreen configuration file sqreen.json, you can also use SQREEN_TOKEN environment variable to set up your token from a terminal:

export SQREEN_TOKEN=mysecrettoken 

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

Uninstall the agent

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

Notes

The Sqreen Node.js agent's gem is available on NPM repository.

Use different Sqreen Applications for different environments

We recommend you to use different Sqreen applications on your different environments: Production, Staging and Development.

Usage with Heroku

Do not forget to push the sqreen.json file if or to set the environment variable holding the token.