Nimble Polyglot Microcosm

    hpp
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/hpp package

    0.2.3 • Public • Published

    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.

    Install

    npm i hpp

    DownloadsWeekly Downloads

    52,294

    Version

    0.2.3

    License

    ISC

    Unpacked Size

    13.1 kB

    Total Files

    5

    Last publish

    Collaborators

    • analog-nico