Node.js module install
Last updated 2023-06-27
IMPORTANT
This guide only applies to Next-Gen WAF customers with access to the Next-Gen WAF control panel. If you have access to the Next-Gen WAF product in the Fastly control panel, you can only deploy the Next-Gen WAF with the Edge WAF deployment method.
The Next-Gen WAF Node.js module is compatible with Node 0.10 through 18.X. All dependencies are specified in the npm-shrinkwrap.json
file.
Installation
Install the latest version from npmjs.com:
$ npm install sigsci-module-nodejs
For specific releases prior to 1.5.3, installation can be performed from the release archive. Replace <VERSION>
with the specific version number:
$ npm install https://dl.signalsciences.net/sigsci-module-nodejs/<VERSION>/sigsci-module-nodejs-<VERSION>.tgz
See the package archive for a list of available versions.
Usage
How to incorporate the Next-Gen WAF Node.js module will depend on your application.
Native applications
If your application invokes http.createServer
directly, use the native API.
Above your application code, import the Next-Gen WAF Node.js module by adding the following lines:
1var Sigsci = require('sigsci-module-nodejs')23// Your application codeBelow your application code, create a
Sigsci
object:1// Your application code23var sigsci = new Sigsci({4 path: '/var/run/sigsci.sock'5 // Other parameters here6})Wrap the dispatcher with
sigsci.wrap
. Replace thehttp.createServer(dispatcher).listen(8085, '127.0.0.1')
line with:http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')
Example
1var Sigsci = require('sigsci-module-nodejs')2
3// Your application code4
5var sigsci = new Sigsci({6 path: '/var/run/sigsci.sock'7 // Other parameters here8})9
10http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')
Node.js Express
The Node.js Express module is exposed as Express middleware and is typically inserted as the first middleware, immediately below the var app = express()
statement. See the Express Using Middleware documentation for more details.
Above your application code, import the Next-Gen WAF Node.js module by adding the following lines:
1var Sigsci = require('sigsci-module-nodejs')23// Your application codeBelow your application code, create a
Sigsci
object:1// Your application code23var sigsci = new Sigsci({4path: '/var/run/sigsci.sock'5// other parameters here6})Below the
var app = express()
line, insert the Node.js module middleware:1var app = express()2app.use(sigsci.express())34// You can still call other middleware and routes5app.use(...)6app.get('/route', ...)
Example
1var Sigsci = require('sigsci-module-nodejs')2
3// Your application code4
5var sigsci = new Sigsci({6path: '/var/run/sigsci.sock'7// other parameters here8})9
10var app = express()11app.use(sigsci.express())12
13// You can still call other middleware and routes14app.use(...)15app.get('/route', ...)
Node.js Restify
Installing the Next-Gen WAF module for Restify is similar to Node.js, except that 404 errors are handled differently in Restify. For best results, Signal Sciences should hook into the NotFound
event. See the Restify node server api for more details.
Node.js Hapi v17 & v18
At the top of your application, add the following:
1var Sigsci = require('sigsci-module-nodejs')2const Hapi = require('@hapi/hapi')3
4var sigsci = new Sigsci({5 path: '/var/run/sigsci.sock'6 // see other options below7})8const init = async() => {9 // Creating a server10 const server = Hapi.Server({11 port: 808512 });13
14 server.ext('onRequest', sigsci.hapi17())15 server.events.on('response', sigsci.hapiEnding())16 // Add SigSci request lifecycle methods, e.g.17 // server.route({18 // method: ['POST', 'PUT', 'PATCH', 'DELETE'],19 // config: {20 // payload: {21 // parse: false,22 // maxBytes: 10 * 1024 * 1024,23 // output: 'data'24 // }25 // },26 // path: '/response',27 // handler: responseHandler28 // })29};30init();
Node.js Hapi v14
At the top of your application, add the following:
1var Sigsci = require('sigsci-module-nodejs')2
3var sigsci = new Sigsci({4 path: '/var/run/sigsci.sock'5 // see other options below6})7// Creating a Server8const Hapi = require('hapi')9const server = Hapi.Server({10 port: 808511});12// Add SigSci request lifecycle methods, e.g.13// server.route({14// method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],15// path: '/dynamic/response',16// handler: responseHandler17// })18
19server.ext('onRequest', sigsci.hapi14())20server.on('response', sigsci.hapiEnding())21server.start((err) => {22 if (err) {23 throw err24 }25 console.log('Server running at:', server.info.uri)26})
Node.js KOA
At the top of your application, add the following:
1const Koa = require('koa');2const Router = require('koa-router');3var Sigsci = require('sigsci-module-nodejs')4const server = new Koa();5const router = new Router();6var sigsci = new Sigsci({7 path: '/var/run/sigsci.sock'8// see other options below9})10
11// add lifecycle methods here12// var dispatcher = async function (ctx) {13// let req = ctx.req14// let res = ctx.res15 // add your code here16// }17
18// setup your endpoints here19// router.all('/response', dispatcher)20
21server.use(sigsci.koa())22server.use(router.routes())23
24server.listen(8085);
Configuration
You can module configuration options directly in the Sigsci
object:
1var sigsci = new Sigsci({2path: '/var/run/sigsci.sock'3...4})
Name | Description |
---|---|
port | Specifies the port to connect to the agent via TCP. If this is set, the path parameter is ignored. |
host | Specifies the IP address to connect to the agent via TCP (optional). Default: localhost |
path | Specifies the Unix Domain Socket to connect to the agent via UDS. |
socketTimeout | Number of milliseconds to wait for a response from the agent. After this time the module allows the original request to pass (i.e. fail open). |
maxPostSize | Controls the maximum size in bytes of a POST body that is sent to the agent. If the body is larger than this value, the post body is not sent to the agent. This allows control over performance (larger POST bodies take longer to process) and to prevent DoS attacks. |
log | The function to use to log error messages. By default it will be something to the effect of: function (msg) { console.log(util.format('SIGSCI %s', msg)) |
anomalySize | Threshold between calculated and reported context response size. Default: 524288 |
anomalyDurationMillis | Internal post processing duration limit. Default: 1000 |
timeoutMillis | Fail open timeout for Agent decision engine. Default: 200 |
expectedContentTypes | A space delimited list of custom content-types to support. |
extendContentTypes | A boolean, enables extended content inspection. Default: false |
Additional details and default values are available in the SigSci.js
file.
Next Steps
Verify the agent and module installation and explore module options.
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.