express-prevoty

prevoty-express

Build simple, secure web applications with Prevoty and Express!

Overview

The Prevoty REST API is the easiest way for individuals and organizations to prevent Cross-Site Scripting (XSS) and SQL Injection (SQLi) attacks in their web applications. The API has been designed to provide simple access to the powerful content analysis systems and intelligence tools that Prevoty has developed.

This library is an easy way to plugin the Prevoty platform to your express applications.

Node.js bindings

This express-prevoty library depends on the underlying prevoty node.js.

Get Started

To get started:

1. Run "npm install express-prevoty" or add

"express-prevoty": ">=1.0.0"

OR

"express-prevoty": "*"

to your package.json file and run "npm install"

1. You will need to add this to the top of your server.js file:

var prevoty = require('express-prevoty');

1. Make sure you have a v1 API key (from the Security Policies page in Prevoty Manager Console, not to be confused with the keys from the Plugin Configurations page) as well as any other policy configuration keys (from the Security Policies page in Prevoty Manager Console, not to be confused with the keys from the Plugin Configurations page).

2. The Prevoty Content features provide a wrapper around the standard body-parser.js Express library to protect you from XSS attacks. In order to enable this, you should include the contentConfig sub object inside of the initPrevoty options.

YOU SHOULD NOT INVOKE THE body-parser middleware yourself. The prevoty initPrevoty function documented below will instantiate the body-parser middleware and add it to the middleware chain for you.

MAKE SURE YOU DO NOT HAVE THE FOLLOWING IN YOUR APPLICATION CODE:

var bodyParser = require('body-parser');
app.use(bodyParser.urlencoded({extended:true}));
router.use(bodyParser.urlencoded({extended:true}));

1. The Prevoty Query feature assumes that your application is backed by mysql and you are using the express-myconnection middleware.
   If you are not using the express-myconnection middleware you can not use the Query feature of our Express.js plugin. You will need to call out to the Prevoty NodeJS SDK directly. See https://www.npmjs.com/package/prevoty for more information.

YOU SHOULD NOT add the express-myconnection object to the middleware chain yourself. Just pass it into the prevoty initPrevoty function documented below and it will add it to the middleware chain for you.

1. After you've added your logging, session management, and express.static middleware to the middleware chain, you should invoke the initPrevoty which will instantiate all of the Prevoty middleware as well as the body-parser middleware and return a router which you can add to your middleware chain in the appropriate part of the your code. Be sure to replace the elements between < > with your appropriate definitions.

app.use(prevoty.initPrevoty(app,
    {
        'apiBase' : https://api.prevoty.com
        'apiKey' : <PREVOTY API KEY>,
        'sessionIDLookupCallback' : function(req) {return req.sessionID;}
        'logCallback' : function(req, logObj, logStr) {console.log(logStr)},
        'contentConfig' : {
            'contentConfigurationKey' : <PREVOTY CONTENT CONFIGURATION KEY>,
            'contentMinimalLogging' : true,
            'extended' : true,
            'bodySizeLimit' : '1mb'},
        },
        'queryConfig' : {
            'queryConfigurationKey' : <PREVOTY QUERY CONFIGURATION KEY>,
            'queryMinimalLogging' : true,
            'queryViolationMode' : 'block',
            'queryFailureMode' : 'continue',
            'blockOnComment' : true,
            'blockOnTautology' : true,
            'blockOnContradiction' : true,
            'blockOnStaticComparison' : false,
            'mysqlConnection' :
                connection(mysql,
                {
                    host     : <HOSTNAME>,
                    user     : <USERNAME>,
                    password : <PASSWORD>,
                    database : <DATABASE NAME>,
                    debug    : false //set true if you wanna see debug logger
                }, 'request')
        },
    }
));

The apiBase parameter is required. To use the Prevoty Cloud set it to 'https://api.prevoty.com'. To use an on-premise Prevoty Engine make sure to use the http protocol instead of https, so the value would be something like 'http://prevoty.domain.com:9090'.

The apiKey parameter is required and should be set to the appropriate API Key string from your application's Prevoty configuration.

The parameter sessionIDLookupCallback is required and is defined as a function which takes the Express.Request object as a parameter and returns a string which can be used to uniquely identify the current session. Since there are a range of possibilities for how an Express programmer might keep track of session information, it is necessary for the express-prevoty library to rely on the application programmer to provide a mechanism for accessing the session ID.

The logCallback parameter is required. The Prevoty plugin will write invoke this callback function with 3 parameters: the request object, an object representing the Prevoty Splunk Logging Data, and a string representation of that same Prevoty Splunk Logging Data object in JSON form. This allows you to use whatever internal logging mechanism your application may have to log the Prevoty information so that it can be forwarded to your Splunk indexer. The documentation above shows a simple default implementation which uses console.log(). You might wish to use your own logging object to log to a file which will be monitored by the Splunk Universal Forwarder, or to syslog, or to some other 3rd party logging mechanism.

The contentConfig.contentConfigurationKey parameter is required and should be set to the appropriate Content Configuration Key (from the Security Policies page in Prevoty Manager Console, not to be confused with the keys from the Plugin Configurations page).

The contentConfig.contentMinimalLogging parameter is optional and defaults to true, meaning only significant events will be logged. If you change this value to false, all content requests and results will be logged.

The contentConfig.extended parameter is required. If set to false the Prevoty middleware will use the simple query parser and if set to true it will use the extended query parser. This is equivalent to the express application setting "query parser" = <true|false>, or the extended option for the standard body-parser.

The contentConfig.bodySizeLimit parameter tells Prevoty how big of a body is allowed before it will give up and throw an error. The parameter is optional and defaults to '1mb', just like the standard body-parser middleware.

The queryConfig.queryConfigurationKey parameter is required and should be set to the appropriate Query Database Configuration Key (from the Security Policies page in Prevoty Manager Console, not to be confused with the keys from the Plugin Configurations page).

The contentConfig.contentMinimalLogging parameter is optional and defaults to true, meaning only significant events will be logged. If you change this value to false, all query requests and results will be logged.

The queryConfig parameters queryViolationMode, queryFailureMode, blockOnComment, blockOnTautology, blockOnContradiction, and blockOnStaticComparison are all required parameters and inform the plugin how to respond when SQL queries that meet those criteria are examined.

The queryConfig.mysqlConnection parameter is required and is an instance of the express-myconnection middleware with your appropriate mysql configuration parameters defined. See https://www.npmjs.com/package/express-myconnection for more information.

Issues

Feel free to file an issue or send us a pull request.