From 948908f0f74f02c60b8452f89cde1775daa45de7 Mon Sep 17 00:00:00 2001 From: Paul Schultz Date: Tue, 18 Mar 2025 09:59:57 -0500 Subject: [PATCH] docs: update auditor naming conventions Signed-off-by: Paul Schultz --- docs/backend-system/core-services/auditor.md | 87 +++++++++++++++++--- 1 file changed, 76 insertions(+), 11 deletions(-) diff --git a/docs/backend-system/core-services/auditor.md b/docs/backend-system/core-services/auditor.md index d4cbf70325..53242500ae 100644 --- a/docs/backend-system/core-services/auditor.md +++ b/docs/backend-system/core-services/auditor.md @@ -7,7 +7,7 @@ description: Documentation for the Auditor service ## Overview -This document describes the Auditor Service, a software service designed to record and report on security-relevant events within an application. This service utilizes the `winston` library for logging and provides a flexible way to capture and format audit events. +This document describes the Auditor Service, a core service designed to record and report on security-relevant events within an application. By default, this service utilizes the `rootLogger` core service for logging. ## Key Features @@ -16,15 +16,13 @@ This document describes the Auditor Service, a software service designed to reco - Supports detailed metadata for each event. - Offers success/failure reporting for events. - Integrates with authentication and plugin services for enhanced context. -- Uses `winston` for flexible log formatting and transport. - Provides a service factory for easy integration with Backstage plugins. -- Supports configurable log transports (console, file). ## How it Works -The Auditor Service defines a core class, `Auditor`, which implements the `AuditorService` interface. This class uses `winston` to log audit events with varying levels of severity and associated metadata. It also integrates with authentication and plugin services to capture actor details and plugin context. +The Auditor Service defines a class, `Auditor`, which implements the `AuditorService` interface. This class uses a `logFn` to log audit events with varying levels of severity and associated metadata. It also integrates with authentication and plugin services to capture actor details and plugin context. -The `auditorServiceFactory` creates an `Auditor` instance for the root context and provides a factory function for creating child loggers for individual plugins. This allows each plugin to have its own logger with inherited and additional metadata. +The `auditorServiceFactory` wraps the `rootLogger` core service and provides a factory function for creating child loggers for individual plugins. This allows each plugin to have its own logger with inherited and additional metadata. ## Usage Guidance @@ -78,10 +76,77 @@ In this example, an audit event is created for each request to `/my-endpoint`. T ## Naming Conventions -When defining `eventId` and `subEventId` for your audit events, follow these guidelines: +When defining audit events, follow these guidelines to ensure consistency and clarity: -- Use kebab-case (e.g., `user-login`, `file-download`, `fetch`, `entity-create`, `entity-update`). -- The `eventId` represents a logical group of similar events or operations. For example, "fetch" could be used as an `eventId` encompassing various fetch methods like `by-id` or `by-location`. -- Use `subEventId` to further categorize events within a logical group. For example, if the `eventId` is "fetch", the `subEventId` could be "by-id" or "by-location" to specify the method used for fetching. -- Avoid redundant prefixes related to the plugin ID, as that context is already provided. -- Choose names that clearly and concisely describe the event being audited. +- **Use kebab-case:** Event IDs should be in kebab-case (e.g., `user-session`, `file-download`, `entity-fetch`). +- **`eventId` for Logical Grouping:** The `eventId` represents a broad category or logical group of related operations. For example, `entity-fetch` would group all entity retrieval events. `location-mutate` would group all actions that mutate a location. +- **`meta.queryType` (or related field) for Specific Actions within a Group:** Use a `meta` field (like `queryType`, `actionType` or similar) to specify the particular action or query that occurred within the broader `eventId` group. + - For instance, with `eventId: entity-fetch`, use `meta: { queryType: 'by-id' }` to represent fetching an entity by its ID. Other examples could be: + - `meta: { queryType: 'all' }` for fetching all entities. + - `meta: { queryType: 'by-query' }` for fetching entities by a query. + - `meta: { actionType: 'delete' }` for `eventId: entity-mutate` when an entity was deleted. + - `meta: { actionType: 'create' }` for `eventId: location-mutate` when a location was added. + - Use `meta` fields to add more context to the event being tracked. +- **Avoid Redundant Prefixes:** Do not include redundant prefixes related to the plugin ID in your event names. The plugin context is already provided separately. +- **Clear and Concise:** Choose names that clearly and concisely describe the event being audited. + +## Common Meta Keys and Values + +The following table details common keys found within the `meta` object of audit events and their formats: + +| Key | Description | Format | Example(s) | +| ------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------- | +| `queryType` | Specifies the type of query performed when fetching data. | A kebab-case string | `all`, `by-id`, `by-name`, `by-query`, `by-refs`, `ancestry`, `by-entity` | +| `actionType` | Specifies the type of action performed when modifying data. | A kebab-case string | `create`, `delete`, `refresh` | +| `entityRef` | The full reference of an entity, including kind, namespace, and name. | `[kind]:[namespace]/[name]` | `component:default/my-component`, `group:my-org/team-a` | +| `locationRef` | A specific reference to a location being operated on. | Any string representing the location. | `Url:https://example.com/catalog-info.yaml`, `custom:default/my-location` | +| `uid` | The unique identifier of a location or other object involved in the operation. | Any valid unique ID string | `9a4e740b-e557-427f-b9f2-0d4f092b1c1e` | + +By following these conventions, you create a more structured and informative audit trail that is easier to search, filter, and understand. This allows you to better group and understand the events being logged. + +## Audit Event Examples + +To illustrate how these naming conventions and the meta field are used in practice, the following examples demonstrate typical audit events for common operations. + +**Typical Read Operation Example:** + +For an operation that fetches all entities, a typical audit event would look like this: + +```json +{ + "eventId": "entity-fetch", + "meta": { + "queryType": "all" + } + ... +} +``` + +**Typical Write Operation Example:** + +For an operation that deletes an entity, a typical audit event would look like this: + +```json +{ + "eventId": "entity-mutate", + "meta": { + "actionType": "delete", + "uid": "some-entity-uid" + }, + "severityLevel": "medium" + ... +} +``` + +## Practical Examples for Auditor Implementation + +To clarify how to utilize the Auditor feature effectively, we recommend exploring the Catalog Backend. It offers two valuable resources: + +- **Code Implementation Example (createRouter.ts):** + - The [`createRouter.ts`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/createRouter.ts) file within the Catalog Backend showcases a practical integration of the `AuditorService` within a Backstage backend plugin. + - Specifically, the lines that demonstrate the creation of an audit event. This includes setting critical parameters such as `eventId` and `severityLevel`, as well as incorporating relevant metadata like `queryType` and `entityRef`. +- **Documentation Example (README.md):** + - The "Audit Events" section of the Catalog Backend's [`README.md`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md#audit-events) provides a well-structured example of documenting emitted audit events. + - It illustrates how to detail various `eventId` values and their corresponding `meta` fields (e.g., `queryType`, `actionType`) for different plugin operations. + +These examples provide both a code-level demonstration and a documentation guideline for effectively utilizing the `AuditorService` to manage audit events within your Backstage plugins.