beuterei / nestjs-chatter-patrol Goto Github PK

Shared NestJS communication sanitation functionality

· Report Bug · Request Feature ·

A collection of sanitation functionality for NestJS.

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

Another important design decision is to crash loudly, this avoid sanitation errors and issues happening unnoticed and posing a threat to your app´s integrity.

npm i @beuluis/nestjs-chatter-patrol

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

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 }),
        },
    ],
})

⚠️ 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

• 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',
  }]});

• Apply whitelist to /example url path.

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

• Apply whitelist to url paths matching /example/.

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

• Apply whitelist to GET and POST methods.

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

• Apply whitelist to all methods.

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

• To allow all b tags everywhere.

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

• Whitelist every content for matching urlPath and methods.

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

• 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

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

• 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

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

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

• whitelistAllContent Defines if you want to whitelist all content.

• 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

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 too much, but hey much helps much. Right? RIGHT?