Skip to content

Latest commit

 

History

History
184 lines (132 loc) · 6.85 KB

README.md

File metadata and controls

184 lines (132 loc) · 6.85 KB
Raw

HPP

Express middleware to protect against HTTP Parameter Pollution attacks

Build Status Coverage Status Dependency Status

Why?

Let Chetan Karande's slides do the explaining:

Slide 48 Slide 49 Slide 50 Slide 54

...and exploits may allow bypassing the input validation or even result in denial of service.

And HPP solves this how exactly?

HPP puts array parameters in req.query and/or req.body aside and just selects the last parameter value. You add the middleware and you are done.

Installation

NPM Stats

This is a module for node.js and io.js and is installed via npm:

npm install hpp --save

Getting Started

Add the HPP middleware like this:

// ...
var hpp = require('hpp');

// ...
app.use(bodyParser.urlencoded()); // Make sure the body is parsed beforehand.

app.use(hpp()); // <- THIS IS THE NEW LINE

// Add your own middlewares afterwards, e.g.:
app.get('/search', function (req, res, next) { /* ... */ });
// They are safe from HTTP Parameter Pollution now.

Details about req.query

By default all top-level parameters in req.query are checked for being an array. If a parameter is an array the array is moved to req.queryPolluted and req.query is assigned the last value of the array:

GET /search?firstname=John&firstname=Alice&lastname=Doe

=>

req: {
    query: {
        firstname: 'Alice',
        lastname: 'Doe',
    },
    queryPolluted: {
        firstname: [ 'John', 'Alice' ]
    }
}

Checking req.query may be turned off by using app.use(hpp({ checkQuery: false })).

Details about req.body

Checking req.body is only done for requests with an urlencoded body. Not for json nor multipart bodies.

By default all top-level parameters in req.body are checked for being an array. If a parameter is an array the array is moved to req.bodyPolluted and req.body is assigned the last value of the array:

POST firstname=John&firstname=Alice&lastname=Doe

=>

req: {
    body: {
        firstname: 'Alice',
        lastname: 'Doe',
    },
    bodyPolluted: {
        firstname: [ 'John', 'Alice' ]
    }
}

Checking req.body may be turned off by using app.use(hpp({ checkBody: false })).

Whitelisting Specific Parameters

The whitelist option allows to specify parameters that shall not be touched by HPP. Usually specific parameters of a certain route are intentionally used as arrays. For that use the following approach that involves multiple HPP middlewares:

// Secure all routes at first.
// You could add separate HPP middlewares to each route individually but the day will come when you forget to secure a new route.
app.use(hpp());

// Add a second HPP middleware to apply the whitelist only to this route.
app.use('/search', hpp({ whitelist: [ 'filter' ] }));
GET /search?package=Helmet&package=HPP&filter=nodejs&filter=iojs

=>

req: {
    query: {
        package: 'HPP',
        filter:  [ 'nodejs', 'iojs' ], // Still an array
    },
    queryPolluted: {
        package: [ 'Helmet', 'HPP' ]
    }
}

The whitelist works for both req.query and req.body.

Performance

HPP was written with performance in mind since it eats CPU cycles for each request.

A performance test that includes two HPP middlewares plus a whitelist simulates an already demanding use case. On my Mac Book Air it measures 0.002ms to process a single request.

Contributing

To set up your development environment for HPP:

  1. Clone this repo to your desktop,
  2. in the shell cd to the main folder,
  3. hit npm install,
  4. hit npm install gulp -g if you haven't installed gulp globally yet, and
  5. run gulp dev. (Or run node ./node_modules/.bin/gulp dev if you don't want to install gulp globally.)

gulp dev watches all source files and if you save some changes it will lint the code and execute all tests. The test coverage report can be viewed from ./coverage/lcov-report/index.html.

If you want to debug a test you should use gulp test-without-coverage to run all tests without obscuring the code by the test coverage instrumentation.

Change History

  • v0.2.3 (2020-01-07)
    • Updated lodash dependency because of vulnerability
    • Added node v6, v8, v10 to CI build
    • Removed node v5 from CI build
  • v0.2.2 (2017-04-11)
    • Requiring individual lodash functions for faster boot time and lower memory footprint (Thanks to @mschipperheyn for suggesting this in issue #6)
  • v0.2.1 (2016-04-03)
    • Added node v4 and v5 to CI build
    • Removed node v0.11 from CI build
    • Updated dependencies
  • v0.2.0 (2015-05-25)
    • Bumped version to 0.2 to properly follow semver since the whitelist was added in v0.1.2
    • For better intuitiveness the last instead of the first value of an array is selected
    • Refactoring to improve readability and performance (Thanks to @le0nik for pull request #2)
    • Updated dependencies (Thanks to @maxrimue for pull request #3)
  • v0.1.2 (2015-05-18)
  • v0.1.1 (2015-04-16)
    • Removed two closures
    • Updated lodash
  • v0.1.0 (2015-04-12)
    • Updated dependencies
    • Use in production satisfactory
  • v0.0.1 (2015-03-05)
    • Initial version

License (ISC)

In case you never heard about the ISC license it is functionally equivalent to the MIT license.

See the LICENSE file for details.