Immunio Node Agent

Support Matrix

| Feature | Required package & version * | Note | | ----------------------------- | -------------------------------- | ---- | | All features | Node >= 0.12 || | SQLi | Sequelize >= 2.1, pg 4.x, pg-native, mysql 2.x, sqlite3 3.x || | NoSQLi | Mongoose 4.x, mongodb 2.x | | | XSS | Jade >= 1.3, Mustache >= 2.1 || | Session, Redirect | express-session, cookie-session || | Authentication | Passport 0.3 || | CSRF | csrf 3.x || | Cookie Tampering | cookie-parser 1.4 with Express ||

* Tested versions. Other versions might also work.

Installation

From the root of your Node app:

$ npm install --save immunio

Installation from source

From the root of your Node app:

$ npm link /path/to/agent-node

Usage

To active Immunio, add the following as the first line of your app setup code:

var immunio = require('immunio');

Configuration

The agent key and secret can be configured via the IMMUNIO_KEY and IMMUNIO_SECRET environment variables.

If you are using a configuration file instead of using environment variables, it needs to be called immunio.json be in the application root folder and needs to contain the follow immunio.json:

{
  "key": "my-key",
  "secret": "my-secret"
}

Note: The environment variables will take precedence over the configuration file.

Authentication API

If you're using Passport, Immunio will automatically hook into your authentication system to protect you against attacks.

If you're not using the above framework, you will need to manually tell Immunio when authentication occurs. Use the following methods to do so.

• After a user logs in: immunio.authentication.login(user, req)
• After a failed login attempt: immunio.authentication.failedLogin(user, req)
• After a user logs out: immunio.authentication.logout(user)
• After the current user is changed (or set): immunio.authentication.setUser(user, req)
• After a user requests a password reset: immunio.authentication.passwordReset(user, req)
• After a failed requests for resetting a password: immunio.authentication.failedPasswordReset(user, req)

Note: immunio.authentication.setUser(user, req) should be called for every request where user data is available, not just when authentication mechanisms are used.

These methods take a user object with the following properties their first argument:

• user_id: String or Number
• username, login or name: String
• email: String
• reason: String (for failures)

The second argument should be the Node HTTP request (req) or response (res) object, if available.

Here's an example:

var immunio = require('immunio');

// ...

app.use(function(req, res, next) {
  // Assuming req.user is populated with the current user in a previous middleware.
  if (req.user) {
    immunio.authentication.setUser(req.user, req);
  }
});

app.post('/login', function(req, res) {
  var username = req.body.username;
  var password = req.body.password;

  db.findUser(username, password, function(err, user) {
    if (err) {
      // On failed login
      // ...
      immunio.authentication.failedLogin({ username: username }, req);
    } else {
      // On successful login
      // ...
      immunio.authentication.login({
        user_id: user.id,
        username: user.name,
        email: user.email
      }, req);
    }
  });
});

app.get('/logout', function(req, res) {
  // Get the current user
  var user = req.user;

  immunio.authentication.logout({
    user_id: user.id,
    username: user.name,
    email: user.email
  }, req);

  // Your logout code ...
});

Waiting for Agent readiness

By default your app will start before Immunio is ready to protect it. If you want to prevent this behavior and wait for Immunio to be fully active before starting your app, use the following:

var immunio = require('immunio');

// ...

immunio.on('ready', function() {
  // Start your web server here.
  server.listen(port);
});