From 948908f0f74f02c60b8452f89cde1775daa45de7 Mon Sep 17 00:00:00 2001 From: Paul Schultz Date: Tue, 18 Mar 2025 09:59:57 -0500 Subject: [PATCH 1/3] 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. From 726734002914bbf2486d6f275d3a228adb38924e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Mar 2025 16:04:40 +0100 Subject: [PATCH 2/3] Update docs/backend-system/core-services/auditor.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- docs/backend-system/core-services/auditor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend-system/core-services/auditor.md b/docs/backend-system/core-services/auditor.md index 53242500ae..4daaa8d0bb 100644 --- a/docs/backend-system/core-services/auditor.md +++ b/docs/backend-system/core-services/auditor.md @@ -99,7 +99,7 @@ The following table details common keys found within the `meta` object of audit | `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` | +| `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. From b9e82880947d17c0425330ffef0824e5444719c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Mar 2025 16:04:50 +0100 Subject: [PATCH 3/3] Update docs/backend-system/core-services/auditor.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- docs/backend-system/core-services/auditor.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/backend-system/core-services/auditor.md b/docs/backend-system/core-services/auditor.md index 4daaa8d0bb..43e789a70f 100644 --- a/docs/backend-system/core-services/auditor.md +++ b/docs/backend-system/core-services/auditor.md @@ -131,7 +131,8 @@ For an operation that deletes an entity, a typical audit event would look like t "eventId": "entity-mutate", "meta": { "actionType": "delete", - "uid": "some-entity-uid" + "uid": "some-entity-uid", + "entityRef": "component:default/petstore" }, "severityLevel": "medium" ...