README
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 Numberusername
,login
orname
: Stringemail
: Stringreason
: 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);
});