https://github.com/analog-nico/hpp
Express middleware to protect against HTTP Parameter Pollution attacks
https://github.com/analog-nico/hpp
Last synced: 8 months ago
JSON representation
Express middleware to protect against HTTP Parameter Pollution attacks
- Host: GitHub
- URL: https://github.com/analog-nico/hpp
- Owner: analog-nico
- License: isc
- Created: 2015-03-05T22:37:03.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-02-06T09:53:21.000Z (almost 3 years ago)
- Last Synced: 2025-04-08T16:09:39.728Z (9 months ago)
- Language: JavaScript
- Homepage:
- Size: 164 KB
- Stars: 396
- Watchers: 9
- Forks: 13
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - hpp - nico | 343 | (JavaScript)
README
# HPP
[Express](http://expressjs.com) middleware to **protect against HTTP Parameter Pollution attacks**
[](https://travis-ci.org/analog-nico/hpp) [](https://coveralls.io/r/analog-nico/hpp?branch=master) [](https://david-dm.org/analog-nico/hpp)
## Why?
Let [Chetan Karande's slides](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=48) do the explaining:
[](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=48)
[](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=49)
[](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=50)
[](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=54)
...and exploits may allow [bypassing the input validation](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=57) or even result in [denial of service](https://speakerdeck.com/ckarande/top-overlooked-security-threats-to-node-dot-js-web-applications?slide=55).
## 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
[](https://npmjs.org/package/hpp)
This is a module for node.js and io.js and is installed via npm:
``` bash
npm install hpp --save
```
## Getting Started
Add the HPP middleware like this:
``` js
// ...
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:
``` js
// 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](test/spec/perf.js) 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](https://github.com/analog-nico/hpp/issues/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](https://github.com/analog-nico/hpp/pull/2))*
- Updated dependencies
*(Thanks to @maxrimue for [pull request #3](https://github.com/analog-nico/hpp/pull/3))*
- v0.1.2 (2015-05-18)
- Added [whitelist feature](#whitelisting-specific-parameters)
*(Thanks to @avaly for suggesting this in [issue #1](https://github.com/analog-nico/hpp/issues/1))*
- Updated dependencies
- 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](http://en.wikipedia.org/wiki/ISC_license) it is functionally equivalent to the MIT license.
See the [LICENSE file](LICENSE) for details.