@beuluis/nestjs-chatter-patrol NPM

About The Project

A collection of sanitation functionality for NestJS.

Most functionality follows the opt-out principle. So you need to specifically whitelist stuff.

Another important design is that it crashed loud. This is done to not fail silently since sanitation is an important part of the app that should not fail.

Installation

npm i @beuluis/nestjs-chatter-patrol

Unstable installation

The next dist-tag is kept in sync with the latest commit on main. So this contains always the latest changes but is highly unstable.

npm i @beuluis/nestjs-chatter-patrol@next

Usage

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new SanitizeInterceptor());

With custom logger:

@Module({
    providers: [
        {
            provide: APP_INTERCEPTOR,
            inject: ['OtherLogger'],
            useFactory: (logger: OtherLogger) => new SanitizeInterceptor({ logger: logger }),
        },
    ],
})

Whitelisting

:warning: Whitelists get applied based on what the find methods matches first.

As example we use this config:

new SanitizeInterceptor({
    whitelists: [
        {
            urlPath: '/exampleUrl',
            methods: 'all',
            scope: 'both',
            fields: ['exampleField', { fieldPath: /example/, allowedTags: ['b'] }],
        },
        {
            urlPath: /example/,
            methods: 'all',
            scope: 'both',
            whitelistAllContent: true,
        },
    ],
});

curl -X POST -H "Content-Type: application/json" -d '{"exampleField": "value"}' http://example.com/exampleUrl matches the first whitelist and exampleField gets not sanitized
curl -X POST -H "Content-Type: application/json" -d '{"exampleOtherField": "value"}' http://example.com/exampleUrl matches the first whitelist and exampleOtherField gets sanitized but b tags are allowed
curl -X POST -H "Content-Type: text/plain" -d 'Hello' http://example.com/exampleOtherUrl matches the second whitelist and nothing gets sanitized

Scope

Apply whitelist to request. See interceptors.

new SanitizeInterceptor({ whitelists: [{
    ...,
    scope: 'request',
}]});

Apply whitelist to response. See interceptors.

new SanitizeInterceptor({ whitelists: [{
    ...,
    scope: 'response',
}]});

Apply whitelist to both. See interceptors.

new SanitizeInterceptor({ whitelists: [{
    ...,
    scope: 'both',
}]});

URL path

Apply whitelist to /example url path.

new SanitizeInterceptor({ whitelists: [{
    ...,
    urlPath: '/example',
}]});

Apply whitelist to url paths matching /example/.

new SanitizeInterceptor({ whitelists: [{
    ...,
    urlPath: /example/,
}]});

Methods

Apply whitelist to GET and POST methods.

new SanitizeInterceptor({ whitelists: [{
    ...,
    methods: ['GET', 'POST'],
}]});

Apply whitelist to all methods.

new SanitizeInterceptor({ whitelists: [{
    ...,
    methods: 'all',
}]});

sanitizeOptions. See also Whitelist with general sanitization configuration

To allow all b tags everywhere.

new SanitizeInterceptor({ whitelists: [{
    ...,
    sanitizeOptions: {
        allowedTags: ['b'],
    },
}]});

whitelistAllContent. See also Whitelist with general sanitization configuration

Whitelist every content for matching urlPath and methods.

new SanitizeInterceptor({ whitelists: [{
    ...,
    whitelistAllContent: true,
}]});

fields. See also Whitelist with additional field configuration

Whitelist the path example.example.

new SanitizeInterceptor({ whitelists: [{
    ...,
    fields: ['example.example'],
}]});

Whitelist the path matching /example/.

new SanitizeInterceptor({ whitelists: [{
    ...,
    fields: [/example/],
}]});

Apply sanitizeOptions to field path example.example

new SanitizeInterceptor({ whitelists: [{
    ...,
    fields: [{
        fieldsPath: 'example.example',
        allowedTags: ['b'],
    }],
}]});

Apply sanitizeOptions to field path matching /example/

new SanitizeInterceptor({ whitelists: [{
    ...,
    fields: ['example.[].example'],
}]});

Whitelist field path in array element

Interfaces

SanitizeFieldOptions

fieldPath Defines which fields should not be sanitized.
... This interface also extends the option interface of sanitize-html.

Whitelist

urlPath Defines which url paths should not be sanitized. You can also use a regex here.
methods Defines which http methods should not be sanitized. Use 'all' to whitelist all methods.
scope Defines if the whitelist should be applied to the request, response or both

Whitelist with additional field configuration

fields Defines which fields should not be sanitized. Can be a string, regex or SanitizeFieldOptions

Whitelist with general sanitization configuration

sanitizeOptions Defines which options to be used for sanitization. Uses option interface of sanitize-html.

Whitelist to ignore all content

whitelistAllContent Defines if you want to whitelist all content.

SanitizeInterceptorOptions

logger Instance of the logger to be used. Defaults to @nestjs/common´s logger
logLevel Log level to be used when something unexpected fails. Defaults to 'warn'
whitelist Whitelist of paths, methods and fields to be ignored by the interceptor. Uses array of Whitelist

Testing

Normally I would not test third party libs, but since this is such an important building block I follow a different approach to testing.

The test run the interceptor against multiple payloads compiled from known XSS payloads from github. Generally there are test that are probably to much, but hey much helps much. Right? RIGHT?

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.