@janus-idp/backstage-plugin-audit-log-node

This package contains common types and utility functions for audit logging the backend

Installation

To install this plugin in a package/plugin, run the following command:

yarn workspace <package/plugin> add @janus-idp/backstage-plugin-audit-log-node

Usage

The audit logging node package contains a helper class for generating audit logs with a common structure, as well as logging them.

The auditLog function can be used to log out an audit log using the backstage LoggerService. You can provide a log level to the auditLog function. The supported levels are: info, debug, warn, and error. If no log level is provided, it defaults to the info level.

Alternatively, if you want to generate the audit log object (does not contain message) without it being logged out for you, the createAuditLogDetails helper function of the DefaultAuditLogger can be used.

The DefaultAuditLogger.createAuditLogDetails will generate the actorId of the actor with the following priority (highest to lowest):

The actorId provided in the arguments
The actor id generated from the express.Request object provided in the arguments
null if neither of the above fields were provided in the arguments

Event Naming Convention

It is recommended that you prefix the eventName value with the name of the component you are audit logging. This will help with searchability in the central log collector.

For example, "ScaffolderTaskRead", "CatalogEntityFetch", etc.

IMPORTANT

Any fields containing secrets provided to these helper functions should have secrets redacted or else they will be logged as is.

For the DefaultAuditLogger, these fields would include:

The metadata field
The following fields in the request:
- request.body
- request.params
- request.query
The response.body field

The getActorId helper function grabs the specified entityRef of the user or service associated with the provided credentials in the provided express Request object. If no request is provided or no user/service was associated to the request, undefined is returned.

Example

Audit Log Example

In the following example, we add a simple audit log for the /health endpoint of a plugin's router to the debug log level.

import {
  AuthService,
  HttpAuthService,
  LoggerService,
} from '@backstage/backend-plugin-api';
import { Config } from '@backstage/config';

/* highlight-add-start */
import { DefaultAuditLogger } from '@janus-idp/backstage-plugin-audit-log-node';

/* highlight-add-end */

export interface RouterOptions {
  logger: LoggerService;
  config: Config;
  auth: AuthService;
  httpAuth: HttpAuthService;
}

export async function createRouter(
  options: RouterOptions,
): Promise<express.Router> {
  const { logger, config, auth, httpAuth } = options;

  /* highlight-add-start */
  const auditLogger = new DefaultAuditLogger({
    logger,
    auth,
    httpAuth,
  });
  /* highlight-add-end */

  const router = Router();
  router.use(express.json());

  router.get('/health', async (request, response) => {
    logger.info('PONG!');
    response.json({ status: 'ok' });

    /* highlight-add-start */
    // Note: if `level` is not provided, it defaults to `info`
    auditLogger.auditLog({
      eventName: 'HealthEndpointHit',
      stage: 'completion',
      status: 'succeeded',
      level: 'debug',
      request,
      response: {
        status: 200,
        body: { status: 'ok' },
      },
      message: `The Health Endpoint was hit by ${await auditLogger.getActorId(
        request,
      )}`,
    });
    /* highlight-add-end */
  });

  const middleware = MiddlewareFactory.create({ logger, config });

  router.use(middleware.error());
  return router;
}

Assuming the user:default/tester user hit requested this endpoint, something similar to the following would be outputted if the logger format is JSON:

{"actor":{"actorId":"user:default/tester","hostname":"localhost","ip":"::1","userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"},"eventName":"HealthEndpointHit","isAuditLog":true,"level":"debug","message":"The Health Endpoint was hit by user:default/tester","meta":{},"plugin":"test","request":{"body": "","method":"GET","params":{},"query":{},"url":"/api/test/health"},"service":"backstage","stage":"completion","status":"succeeded","timestamp":"2024-05-17 11:17:07","type":"plugin"}

Audit Log Error Example

In the following example, we utilize the auditLog utility function to generate and output an error log to the error log level:

import {
  AuthService,
  HttpAuthService,
  LoggerService,
} from '@backstage/backend-plugin-api';

/* highlight-add-start */
import { DefaultAuditLogger } from '@janus-idp/backstage-plugin-audit-log-node';

/* highlight-add-end */

export interface RouterOptions {
  logger: LoggerService;
  auth: AuthService;
  httpAuth: HttpAuthService;
}

export async function createRouter(
  options: RouterOptions,
): Promise<express.Router> {
  const { logger, auth, httpAuth } = options;

  /* highlight-add-start */
  const auditLogger = new DefaultAuditLogger({
    logger,
    auth,
    httpAuth,
  });
  /* highlight-add-end */

  const router = Router();
  router.use(express.json());

  router.get('/error', async (request, response) => {
    try {
      const customErr = new Error('Custom Error Occurred');
      customErr.name = 'CustomError';

      throw customErr;

      response.json({
        status: 'ok',
      });
    } catch (err) {
      /* highlight-add-start */
      auditLogger.auditLog({
        eventName: 'ErrorEndpointHit',
        stage: 'completion',
        status: 'failed',
        level: 'error',
        request,
        response: {
          status: 501,
          body: {
            errors: [
              {
                name: (err as Error).name,
                message: (err as Error).message,
              },
            ],
          },
        },
        errors: [customErr],
        message: `An error occurred when querying the '/errors' endpoint`,
      });
      /* highlight-add-end */
      // Do something with the caught error
      response.status(501).json({
        errors: [
          {
            name: (err as Error).name,
            message: (err as Error).message,
          },
        ],
      });
    }
  });
  router.use(errorHandler());
  return router;
}

An example error audit log would be in the following form: Note: the stack trace was removed redacted in this example due to its size.

{"actor":{"actorId":"user:development/guest","hostname":"localhost","ip":"::1","userAgent":"curl/8.2.1"},"errors":[{"message":"Custom Error Occurred","name":"CustomError","stack":"CustomError: Custom Error Occurred\n    at STACK_TRACE]"}],"eventName":"ErrorEndpointHit","isAuditLog":true,"level":"error","message":"An error occurred when querying the '/errors' endpoint","meta":{},"plugin":"test","request":{"body":{},"method":"GET","params":{},"query":{},"url":"/api/test/error"},"response":{"body":{"errors":[{"name":"CustomError","message":"Custom Error Occurred"}]},"status":501},"service":"backstage","stage":"completion","status":"failed","timestamp":"2024-05-23 10:09:04"}