# express-mongo-sanitize

> Sanitize your express payload to prevent MongoDB operator injection.

Latest version **2.2.0** (published 2022-01-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-mongo-sanitize
pnpm add express-mongo-sanitize
yarn add express-mongo-sanitize
bun add express-mongo-sanitize
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2022-01-14 |
| First published | 2015-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 0 |
| Unpacked size | 11.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Tom Spencer |
| Maintainers | fiznool |
| Keywords | mongodb, express, middleware, operator, injection, security |

## Links

- npm: https://www.npmjs.com/package/express-mongo-sanitize
- Repository: https://github.com/fiznool/express-mongo-sanitize
- Homepage: https://github.com/fiznool/express-mongo-sanitize#readme
- Issues: https://github.com/fiznool/express-mongo-sanitize/issues
- npm.io page: https://npm.io/package/express-mongo-sanitize

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 2.2.0 (latest) — 2022-01-14
- 2.1.0 — 2021-05-11
- 2.0.2 — 2021-01-07
- 2.0.1 — 2020-12-02
- 2.0.0 — 2020-03-25
- 1.3.2 — 2017-01-12
- 1.3.1 — 2017-01-12
- 1.3.0 — 2016-01-15
- 1.2.0 — 2016-01-13
- 1.1.0 — 2016-01-13
- 1.0.0 — 2015-11-11

## README

# Express Mongoose Sanitize

Express 4.x middleware which sanitizes user-supplied data to prevent MongoDB Operator Injection.

[![Build Status](https://github.com/fiznool/express-mongo-sanitize/workflows/Node.js%20CI/badge.svg)](https://github.com/fiznool/express-mongo-sanitize/workflows/Node.js%20CI/badge.svg)
[![npm version](https://img.shields.io/npm/v/express-mongo-sanitize)](https://img.shields.io/npm/v/express-mongo-sanitize)
[![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
npm install express-mongo-sanitize
```

## Usage

Add as a piece of express middleware, before defining your routes.

```js
const express = require('express');
const bodyParser = require('body-parser');
const mongoSanitize = require('express-mongo-sanitize');

const app = express();

app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());

// 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 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
// READ MORE: https://github.com/fiznool/express-mongo-sanitize/issues/36
app.use(
  mongoSanitize({
    allowDots: true,
  }),
);

// Both allowDots and replaceWith
app.use(
  mongoSanitize({
    allowDots: true,
    replaceWith: '_',
  }),
);
```

### `onSanitize`

`onSanitize` callback is called after the request's value was sanitized.

```js
app.use(
  mongoSanitize({
    onSanitize: ({ req, key }) => {
      console.warn(`This request[${key}] is sanitized`, req);
    },
  }),
);
```

### `dryRun`

You can run this middleware as dry run mode.

```js
app.use(
  mongoSanitize({
    dryRun: true,
    onSanitize: ({ req, key }) => {
      console.warn(`[DryRun] This request[${key}] will be sanitized`, req);
    },
  }),
);
```

### Node Modules API

You can also bypass the middleware and use the module directly:

```js
const mongoSanitize = require('express-mongo-sanitize');

const payload = {...};

// Remove any keys containing prohibited characters
mongoSanitize.sanitize(payload);

// Replace any prohibited characters in keys
mongoSanitize.sanitize(payload, {
  replaceWith: '_'
});

// 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
});

// Both allowDots and replaceWith
mongoSanitize.sanitize(payload, {
  allowDots: true,
  replaceWith: '_'
});

// 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).
// 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);
```

## 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.

## Credits

Inspired by [mongo-sanitize](https://github.com/vkarpov15/mongo-sanitize).

## License

MIT

---
_Source: https://npm.io/package/express-mongo-sanitize · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._