v2.2.0

CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.2.0] - 2022-01-14
+
+### Added
+
+- New `config` option:
+  - `allowDots` boolean: if set, allows dots in the user-supplied data #41
+
+### Fixed
+
+- Prevent null pointer exception when using `dryRun` option #88
+
 ## [2.1.0] - 2021-05-11
 
 ### Added
@@ -81,6 +92,7 @@ Note that if you weren't previously expecting headers to be sanitized, this is c
 
 Initial Release.
 
+[2.2.0]: https://github.com/fiznool/express-mongo-sanitize/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/fiznool/express-mongo-sanitize/compare/v2.0.2...v2.1.0
 [2.0.2]: https://github.com/fiznool/express-mongo-sanitize/compare/v2.0.1...v2.0.2
 [2.0.1]: https://github.com/fiznool/express-mongo-sanitize/compare/v2.0.0...v2.0.1

README.md

@@ -7,6 +7,25 @@ Express 4.x middleware which sanitizes user-supplied data to prevent MongoDB Ope
 [![npm downloads per week](https://img.shields.io/npm/dw/express-mongo-sanitize?color=blue)](https://img.shields.io/npm/dw/express-mongo-sanitize?color=blue)
 [![Dependency Status](https://img.shields.io/librariesio/release/npm/express-mongo-sanitize)](https://img.shields.io/librariesio/release/npm/express-mongo-sanitize)
 
+## What is this module for?
+
+This module searches for any keys in objects that begin with a `$` sign or contain a `.`, from `req.body`, `req.query` or `req.params`. It can then either:
+
+- completely remove these keys and associated data from the object, or
+- replace the prohibited characters with another allowed character.
+
+The behaviour is governed by the passed option, `replaceWith`. Set this option to have the sanitizer replace the prohibited characters with the character passed in.
+
+The config option `allowDots` can be used to allow dots in the user-supplied data. In this case, only instances of `$` will be sanitized.
+
+See the spec file for more examples.
+
+## Why is it needed?
+
+Object keys starting with a `$` or containing a `.` are _reserved_ for use by MongoDB as operators. Without this sanitization, malicious users could send an object containing a `$` operator, or including a `.`, which could change the context of a database operation. Most notorious is the `$where` operator, which can execute arbitrary JavaScript on the database.
+
+The best way to prevent this is to sanitize the received data, and remove any offending keys, or replace the characters with a 'safe' one.
+
 ## Installation
 
 ```bash
@@ -27,18 +46,25 @@ const app = express();
 app.use(bodyParser.urlencoded({ extended: true }));
 app.use(bodyParser.json());
 
-// To remove data, use:
+// By default, $ and . characters are removed completely from user-supplied input in the following places:
+// - req.body
+// - req.params
+// - req.headers
+// - req.query
+
+// To remove data using these defaults:
 app.use(mongoSanitize());
 
-// Or, to replace prohibited characters with _, use:
+// Or, to replace these prohibited characters with _, use:
 app.use(
   mongoSanitize({
     replaceWith: '_',
   }),
 );
 
 // Or, to sanitize data that only contains $, without .(dot)
-// Can be useful for letting data pass that is meant for querying nested documents. NOTE: This may cause some problems on older versions of MongoDb
+// Can be useful for letting data pass that is meant for querying nested documents.
+// NOTE: This may cause some problems on older versions of MongoDb
 // READ MORE: https://github.com/fiznool/express-mongo-sanitize/issues/36
 app.use(
   mongoSanitize({
@@ -101,7 +127,9 @@ mongoSanitize.sanitize(payload, {
   replaceWith: '_'
 });
 
-// Exclude sanitization of . (dot), only sanitize data that contains $. This may cause some problems on older versions of mongo db
+// Exclude sanitization of . (dot), only sanitize data that contains $.
+// NOTE: This may cause some problems on older versions of MongoDb
+// READ MORE: https://github.com/fiznool/express-mongo-sanitize/issues/36
 mongoSanitize.sanitize(payload, {
   allowDots: true
 });
@@ -115,27 +143,11 @@ mongoSanitize.sanitize(payload, {
 // Check if the payload has keys with prohibited characters
 const hasProhibited = mongoSanitize.has(payload);
 
-// Check if the payload has keys with prohibited characters (`.` is excluded). So if the payload only has `.` it will return false (since it doesn't see the data with `.` as a malicious data)
+// Check if the payload has keys with prohibited characters (`.` is excluded).
+// If the payload only has `.` it will return false (since it doesn't see the data with `.` as malicious)
 const hasProhibited = mongoSanitize.has(payload, true);
 ```
 
-## What?
-
-This module searches for any keys in objects that begin with a `$` sign or contain a `.`, from `req.body`, `req.query` or `req.params`. It can then either:
-
-- completely remove these keys and associated data from the object, or
-- replace the prohibited characters with another allowed character.
-
-The behaviour is governed by the passed option, `replaceWith`. Set this option to have the sanitizer replace the prohibited characters with the character passed in.
-
-See the spec file for more examples.
-
-## Why?
-
-Object keys starting with a `$` or containing a `.` are _reserved_ for use by MongoDB as operators. Without this sanitization, malicious users could send an object containing a `$` operator, or including a `.`, which could change the context of a database operation. Most notorious is the `$where` operator, which can execute arbitrary JavaScript on the database.
-
-The best way to prevent this is to sanitize the received data, and remove any offending keys, or replace the characters with a 'safe' one.
-
 ## Contributing
 
 PRs are welcome! Please add test coverage for any new features or bugfixes, and make sure to run `npm run prettier` before submitting a PR to ensure code consistency.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-mongo-sanitize",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Sanitize your express payload to prevent MongoDB operator injection.",
   "main": "index.js",
   "types": "index.d.ts",