> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/security/auditing.md). # Auditing ESS auditing provides comprehensive activity monitoring to manage risks. ESS services support the auditing of their activities. {% hint style="info" %} For information on the ESS Auditing Service, see [https://docs.inrupt.com/ess/latest/services/service-auditing/](https://docs.inrupt.com/ess/latest/services/service-auditing/ "mention") {% endhint %} ## Audit Events The following events are audited: ### Purgeable Services Applies to Access Grant, Authorization, Broker, Pod Provision, and WebID services. | Event Name | Notes | | ----------------- | --------------- | | `purge-init` | Purge start. | | `purge-completed` | Purge complete. | ### Access Grant Service Access Request/Grant/Denial lifecycle events. | Event Name | Notes | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access-grant-created` | Access Grant has been created. | | `access-grant-read` | Access Grant has been read. | | `access-grant-deleted` | Access Grant has been deleted. | | `access-grant-revoked` | Access Grant status has been revoked. | | `access-grant-activated` | A revoked Access Grant has been re-activated. | | `access-grant-verified` | Access Grant has been verified. Disabled by default; see [`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-access-grant/#inrupt_vc_audit_read_operations_enabled). | | `access-request-created` | Access Request has been created. | | `access-request-read` | Access Request has been read. | | `access-request-deleted` | Access Request has been deleted. | | `access-request-revoked` | Access Request status has been revoked. | | `access-request-verified` | Access Request has been verified. Disabled by default; see [`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-access-grant/#inrupt_vc_audit_read_operations_enabled). | | `access-denial-created` | Access Denial has been created. | | `access-denial-read` | Access Denial has been read. | | `access-denial-deleted` | Access Denial has been deleted. | | `access-denial-verified` | Access Denial has been verified. Disabled by default; see [`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-access-grant/#inrupt_vc_audit_read_operations_enabled). | | `access-credential-queried` | Access Credentials have been queried (previously `access-grant-queried`). Disabled by default; see [`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-access-grant/#inrupt_vc_audit_read_operations_enabled). | | `request-authorized` | Request has been authorized. For the `/query` and `/verify` endpoints, disabled by default; see [`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-access-grant/#inrupt_vc_audit_read_operations_enabled). | | `revocation-status-read` | Revocation status has been read. | {% hint style="info" %} Access Grant audit events now include the grantee as a structured **`target`** field. **`request-authorized`** events contain additional information (such as the Access Grant service endpoint, the WebID, client id, etc.) for **authenticated** access requests/grants/denial events. For these events, you can find the corresponding **`request-authorized`** event using the instrument field. However, other than the service endpoint, the same information may be found in the **`access-*`** event messages themselves. As part of the Access Grant to UMA access token exchange (which is an **unauthenticated** event), **`revocation-status-read`** events occur. These **`revocation-status-read`** events, which are also *unauthenticated*, do not have an associated **`request-authorized`** event. {% endhint %} ### Authorization Service ACR lifecycle events. | Event Name | Notes | | ---------------------------------- | ---------------------------------- | | `acr-created` | ACR has been created. | | `acr-updated` | ACR has been updated. | | `acr-deleted` | ACR has been deleted. | | `provisioned-pod-access-control` | Provisioned Pod access control. | | `deprovisioned-pod-access-control` | De-provisioned Pod access control. | ### Pod Storage Service Resource lifecycle events. | Event Name | Notes | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resource-created` | Resource has been created. | | `resource-updated` | Resource has been updated. | | `resource-deleted` | Resource has been deleted. | | `resource-touched` | Container timestamp has been updated due to changes in child resources. | | `resource-read` | Resource has been read. Disabled by default; see [`INRUPT_STORAGE_AUDIT_RESOURCE_READ_ENABLED`](https://docs.inrupt.com/ess/latest/services/service-pod-management/service-pod-storage.md#inrupt_storage_audit_resource_read_enabled). | | `storage-provisioned` | Storage provisioned (internal). | | `storage-deprovisioned` | Storage deprovisioned (internal). | | `storage-discovery-by-agent` | Storages discovered for agent (internal). | | `resource-discovery` | Non-container resources discovered for storage (internal). | | `view-definition-created` | View definition has been created. | | `view-definition-deleted` | View definition has been deleted. | | `view-binding-created` | View binding has been created. | {% hint style="info" %} Starting in ESS 3.3, resource lifecycle events include the canonical storage URI (`storageUri`) and the external path-based URI (`url`) in the event object. See the [examples](/security/auditing/appendix-audit-events-examples.md) for the updated event format. {% endhint %} ### Pod Provision Service | Event Name | Notes | | ----------------- | ---------------- | | `pod-provisioned` | Pod provisioned. | ### Purger Application | Event Name | Notes | | ----------------- | -------------------------- | | `purge-started` | Purge operation started. | | `purge-completed` | Purge operation completed. | | `purge-failed` | Purge operation failed. | ### Ingest Service | Event Name | Notes | | ------------------------ | ---------------------------------------------- | | `resource-reindexed` | Agent triggered re-index of a single resource. | | `bulk-reindex-started` | Agent triggered bulk reindex of all resources. | | `bulk-reindex-completed` | Bulk reindex completed. | | `bulk-reindex-failed` | Bulk reindex failed. | | `bulk-reindex-cancelled` | Bulk reindex cancelled. | ### Search Service | Event Name | Notes | | -------------------------------- | ------------------------------------------ | | `search-query-executed` | Agent executed a search query. | | `search-resource-lookup` | Agent looked up indexed resource metadata. | | `search-facet-query` | Agent queried search facets. | | `metadata-query-executed` | Agent executed a metadata query. | | `search-content-deleted` | Agent deleted indexed search content. | | `search-content-deletion-failed` | Agent's content deletion failed. | ### Solid OIDC Broker Service Authentication/Authorization flow events. | Event Name | Notes | | ---------------------------------- | ---------------------------------------- | | `openid-backend-idp-login` | Agent has logged in through backend IdP. | | `openid-token-requested` | A new token was requested. | | `openid-authorization-initialized` | Initialized an authorization code flow. | ### WebID Service WebID Profile events. | Event Name | Notes | | --------------------- | --------------------------------------------------- | | `webid-provisioned` | WebID was provisioned (previously `webid-created`). | | `webid-updated` | WebID was updated. | | `webid-deleted` | WebID was deleted. | | `webid-deprovisioned` | WebID was deprovisioned. | ### Platform Management Service Account lifecycle events. | Event Name | Notes | | ----------------------------- | ----------------------------------------------------------------------------------- | | `account-created` | Account has been created. | | `account-updated` | Account has been updated (e.g. WebID has been created or Storage has been created). | | `admin-account-created` | Admin created account on behalf of user. | | `admin-account-activated` | Admin activated account. | | `admin-account-deprovisioned` | Admin deprovisioned account. | | `token-exchange` | Token exchanged for ESS agent. | ### Notification Service Notification subscription lifecycle events. | Event Name | Notes | | ---------------------- | -------------------------------------------- | | `subscription-created` | Subscription has been created. | | `subscription-deleted` | Subscription has been deleted. | | `reprocess-init` | Reprocessing of failed deliveries started. | | `reprocess-completed` | Reprocessing of failed deliveries completed. | ### Services Without Audit Events The following services do not produce audit events: * WebSocket Notification service * Start service {% hint style="info" %} ESS uses asynchronous messaging for auditing. {% endhint %} {% hint style="info" %} **Audit Event Delivery** In ESS 3.3 and later, audit events are published using a transactional outbox: the audit event is written in the same database transaction as the change it records, then delivered to Kafka. Delivery is at-least-once, so an audit message may be delivered more than once with the same **`id`** — consumers should deduplicate on **`id`**. See [Reliable Event Delivery](https://docs.inrupt.com/ess/latest/administration/reliable-event-delivery/) for configuration and monitoring. {% endhint %} #### Audit Event Message Internal Format Internally, ESS’ audit event messages are in RDF and serialized as [ActivityStreams 2.0](https://www.w3.org/TR/activitystreams-core/) JSON-LD documents: {% hint style="info" %} Although the following document shows all possible fields for an event message, the specific events determine which fields appear. Pod-related event messages include: * the actor information ([WebID](/reference/glossary.md#webid)) * the application information ([Client ID](/reference/glossary.md#client-identifier)) * the Pod information (Pod root URL and Pod data subject) {% endhint %} ```json { "@context":[ "https://www.w3.org/ns/activitystreams", "https://schema.inrupt.com/audit/v1.jsonld" ], "id":"", "type": [ "Activity", ,... ], "name":"", "summary": "", "generator": , "actor": [ , ... ], "object": [ , ... ], "instrument": [ , , , , ... ], "result": [ ], "published": "", "identifier":"" } ``` #### `@context` Specifies the JSON-LD contexts. #### `id` Universally Unique IDentifier (UUID) for the event. #### `type` An array of event types; e.g., `[ "Activity", "Create" ]`. #### `name` Name that denotes the event; e.g., `openid-backend-idp-login`, `resource-created`, `access-grant-created`, etc. #### `summary` Short description associated with the message `name`. #### `generator` JSON document identifying the software (e.g., service) producing the event. For example, the `generator` for a Pod provision event: ```json "generator": { "id": "", "type": ["SoftwareApplication"], "name": "", "qualifiedAssociation": "", "wasAssociatedWith": "" } ``` #### `actor` An array of JSON documents that identify the agents, if any, associated with the event. The actor’s identity can be denoted by various combination of fields, such as (list below is not exhaustive): * `id` and `type` fields * `name` and `type` fields The field can also be empty `[]` for events not initiated by a user. For example, for an Access Request/Grant event: ```json "actor": [ { "id": "urn:ess:agent:01JXYZ1234ABCDEF5678GHIJ90", "type": ["Agent"] } ] ``` For IdP login events: ```json "actor": [ { "name": "someusername", "type": ["Agent"] } ] ``` #### `object` An array of JSON documents that identify the objects associated with the event; that is, the objects against which the action is performed. The object can be denoted by various combination of fields, such as (list below is not exhaustive): * `id` and `name` fields * `id` and `type` fields * `name` and `qualifiedAssociation` fields **Pod provisioned event:** ```json "object": [ { "type": ["Storage"], "id": "" } ] ``` **Access Request/Grant/Denial creation events:** The `object` contains the created Request/Grant/Denial in a document with the [content](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-content) field (the credential as a string) and the [mediaType](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype) field, plus an element that identifies the Pod resource: ```json "object": [ { "context": ["https://www.w3.org/2018/credentials/v1", "https://schema.inrupt.com/credentials/v2.jsonld"], "id": "https://vc.example.com/vc/79288a3...", "type": ["VerifiableCredential", "SolidAccessRequest"], "vcId": "79288a3...", "content": "{\"id\":\"https://vc.example.com/vc/79288a3 ... }", "mediaType": "application/ld+json" }, { "type": ["Resource"], "id": "https://storage.example.com/ad3b.../sc/a1b2c3d4..." } ] ``` **Pod resource CRUD events** (`resource-created`, `resource-read`, `resource-updated`, `resource-deleted`): The `object` field includes an object that identifies the Pod resource: ```json "object": [ { "id": "https://storage.example.com/ad3b.../sc/a1b2c3d4...", "url": "https://storage.example.com/ad3b.../sp/some/resource", "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "storageId": "ad3b...", "storageUri": "https://storage.example.com/ad3b.../", "parentId": "f0e1d2c3-b4a5-6789-0fed-cba987654321", "version": 1, "generated": "6cba8240-9f79-40db-a129-c6b8edddb840", "invalidated": "4e12ed06-c4e5-41bc-bcd3-0f6a821c08ca", "type": ["Resource"] } ] ``` Starting in ESS 3.3, resource lifecycle events include additional fields: * `id` — the canonical resource URI * `url` — the external path-based URI * `storageUri` — the canonical storage URI * `resourceId` and `storageId` — internal identifiers * `parentId` — the parent resource identifier * `version` — the resource version number The `generated` and `invalidated` fields are internal references to the content that appear in some combination depending on whether it’s a create/read/update/delete event. The object may also include additional fields, such as `accessControl` for `resource-created` events. #### `instrument` An array of JSON documents that identify: **Client information:** ```json "instrument": [ { "id": "https://start.example.com/app/id", "summary": "Client identifier" } ] ``` Instrument objects that identify the clients have an associated `summary` field with the value `"Client identifier"`. Some events do not have associated clients, and thus may have an empty `instrument` array. [**OpenTelemetry**](https://opentelemetry.io/docs/what-is-opentelemetry/) **info:** ```json "instrument": [ { "traceId": "7decd3657a9efffc010a4b6a4b3da586", "spanId": "91123fce3c668451", "isSampled": true, "name": "OpenTelemetry Span Context", "type": ["SpanContext"] } ] ``` The OpenTelemetry `traceId` field can be used to correlate messages associated with a request. See [appendix-audit-event-correlation.md](/security/auditing/appendix-audit-event-correlation.md) for more information. **Pod information:** * `hasDataSubject` — the Pod data subject (the agent who created the Pod) * `hasStorage` — the Pod root URL ```json "instrument": [ { "hasDataSubject": { "id": "urn:ess:agent:01JXYZ1234ABCDEF5678GHIJ90", "type": ["https://w3id.org/dpv#DataSubject"] }, "hasStorage": "https://storage.example.com/root/", "type": ["http://www.w3.org/2004/02/skos/core#Concept"] } ] ``` [**Application-defined metadata**](https://docs.inrupt.com/ess/latest/administration/application-defined-metadata)**:** ```json "instrument": [ { "name": "Application-Defined Request Metadata", "items": [ { "mediaType": "text/plain", "name": "x-correlation-id", "content": "2049875809728750827498245084" }, { "mediaType": "text/plain", "name": "my-client-version", "content": "1.0.3" } ], "type": ["urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"] } ] ``` See [Application-Defined Metadata](https://docs.inrupt.com/ess/latest/administration/application-defined-metadata) for the configuration needed to include in audit events. #### `result` An array of JSON documents that contains associated results. For example: * An `access-request-verified` event includes the results of the verification. * An `access-grant-revoked` event includes the updated status. #### `published` The timestamp of the event. #### `identifier` Identifier to use for correlated events from a **single** service that have occurred within the same request. To correlate events across services for a request, use the OpenTelemetry `traceId` in the `instrument` field. For examples, see [Appendix: Audit Events Examples](/security/auditing/appendix-audit-events-examples.md) ### Integration with External Logging Systems The ESS [Auditing Service](https://docs.inrupt.com/ess/latest/services/service-auditing/) can log to: * **`sysout`** (default) * Syslog * [Microsoft Sentinel](https://azure.microsoft.com/en-us/services/microsoft-sentinel/#overview) For more information, see [Integration with Syslog](https://docs.inrupt.com/ess/latest/services/service-auditing#integration-with-syslog) and [Integration with Sentinel](https://docs.inrupt.com/ess/latest/services/service-auditing#integration-with-sentinel).