Nestjs-auditlog NPM

Description

Audit logging is the process of documenting activity within the software systems used across your organization. Audit logs record the occurrence of an event, the time at which it occurred, the responsible user or service, and the impacted entity. All of the devices in your network, your cloud services, and your applications emit logs that may be used for auditing purposes.

API document

You can visit the full API documents in here

Installation

You can install the library using npm:

npm install nestjs-auditlog

Example

To integrate nestjs-auditlog into your NestJS application, follow these steps:

First, import the module with AuditLogModule.forRoot(...) or AuditLogModule.forRootAsync(...) into your root AppModule. (refer to the module configuration documentation below).

import { AuditLogModule } from 'nestjs-auditlog';

@Module({
  imports: [AuditLogModule.forRoot({
    exporter: new OpenTelemetryHttpExporter('service1', 'user', '127.0.0.1:4318')
  })],
  ...
})
class AppModule {}

Please note that that AuditLogModule is global module.

Next, put the decorator @AuditLog to every api you want to send audit log.

import { Controller, Get, Query, Body, Post } from '@nestjs/common';
import { AuditLog } from 'nestjs-auditlog';

@Controller('/')
export class CatsController {
  @AuditLog({
    resource: {
      type: 'Cat',
    },
    operation: {
      id: 'findTheCat',
      type: 'Query',
    },
    resource_id_field_map: 'query.id',
  })
  @Get()
  findTheCat(@Query('id') id: string): any {
    return `Congratulations! You have found the cat ${id}!`;
  }

  @AuditLog({
    resource: {
      type: 'Cat',
    },
    operation: {
      type: 'Create',
      // if you ignore the id, we will get method name createTheCat as operation id
    },
    actor: {
      id: 'daniel',
      type: 'admin'
    }
    resource_id_field_map: 'body.id',
  })
  @Post()
  createTheCat(@Body() body: any): any {
    return `Congratulations! You created the cat ${body.id}!`;
  }
}

Please note that the above code snippets demonstrate the basic setup of nestjs-auditlog in your NestJS application. Make sure to adjust the code based on your specific application requirements and configuration.

We have many similar decorators for default defined operation type Create, Update, Remove, Query. You can check them on folder decorators:

AuditLogCreate: decorator with default operation.type = 'Create'
AuditLogUpdate: decorator with default operation.type = 'Update'
AuditLogRemove: decorator with default operation.type = 'Remove'
AuditLogQuery: decorator with default operation.type = 'Query'

Another way, we can use the service AuditLogService to send audit log

import { Controller, Get, Query, Body, Post } from '@nestjs/common';
import { AuditLog } from 'nestjs-auditlog';

@Controller('/')
export class CatsController {
  constructor(private readonly auditLogService: AuditLogService) {}

  @Get()
  async findTheCat(@Query('id') id: string) {
    await this.auditLogService.sendAuditLog({
      resource: {
        id,
        type: 'Cat',
      },
      operation: {
        id: 'findTheCat',
        type: 'Query',
      },
      actor: {
        id: 'daniel',
        type: 'admin',
      },
    });
    return `Congratulations! You have found the cat ${id}!`;
  }
}

Configuration

Configuration interface

The following interface is used for AuditLogModule configuration:

export interface IAuditLogConfigOptions {
  /**
   * setup audit log exporter
   */
  exporter: IAuditLogExporter;
}

Zero configuration

Just import AuditLogModule to AppModule:

import { AuditLogModule } from 'nestjs-auditlog';

@Module({
  imports: [AuditLogModule.forRoot()],
  ...
})
class AppModule {}

With Zero configuration, we will use default AuditLoggerDefaultExporter that print auditlog to stdout by using default Logger

Asynchronous configuration

With AuditLogModule.forRootAsync you can, for example, import your ConfigModule and inject ConfigService to use it in useFactory method.

useFactory should return object with Configuration interface

Here's an example:

import { AuditLogModule } from 'nestjs-auditlog';

@Injectable()
class ConfigService {
  public readonly timeout = 10000;
}

@Module({
  providers: [ConfigService],
  exports: [ConfigService]
})
class ConfigModule {}

@Module({
  imports: [
    AuditLogModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        await somePromise();
        return {
          exporter: new AuditLoggerDefaultExporter(),
        };
      }
    })
  ],
  ...
})
class AppModule {}

Exporters

We have many Auditlog Exporter, please check the folder exporters. Some examples:

AuditLoggerDefaultExporter: the default exporter for Zero configuration
OpenTelemetryGrpcExporter: the exporter that will emit the audit log to Opentelemetry host by GRPC method
OpenTelemetryHttpExporter: the exporter that will emit the audit log to Opentelemetry host by HTTP method