Auditing

ESS auditing provides comprehensive activity monitoring to manage risks. ESS services support the auditing of their activities.

For information on the ESS Auditing Service, see https://docs.inrupt.com/ess/latest/services/service-auditing/

Audit Events

The following events are audited:

Services	Event Name	Notes
Most Services	service-started service-shutdown	Service Startup/Shutdown.
Purgeable services (i.e. Access Grant, Authorization, Broker, Pod Provision, and WebID)	purge-init purge-completed	Purge start/complete.
Access Grant Service	access-grant-created access-grant-queried access-grant-read access-grant-revoked access-grant-verified access-request-created access-request-read access-request-revoked access-request-verified access-denial-created access-denial-read access-denial-revoked access-denial-verified request-authorized revocation-status-read	Access Request/Grant/Denial lifecycle events. 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.
Authorization Service	acr-created acr-updated acr-deleted provisioned-pod-access-control deprovisioned-pod-access-control	ACR Lifecycle events.
Pod Storage Service	resource-created resource-updated resource-deleted	Resource Lifecycle events.
	resource-read	Successful resource read events (GET and HEAD operations). To enable, see INRUPT_STORAGE_AUDIT_RESOURCE_READ_ENABLED configuration for Pod Storage Service.
Pod Provision Service	pod-provisioned	Pod Provisioned event.
Purger application	purge-started purge-completed purge-failed	Purge start/end (successful or not).
Query Service	query-succeeded	Query events.
Query Indexer	ingest-succeeded ingest-failed	Query Indexer events.
Solid OIDC Broker Service	openid-backend-idp-login openid-token-requested openid-authorization-initialized	Authentication/Authorization flow.
UMA Service	uma-token-created	UMA Grant Flow.
WebID Service	webid-created webid-updated webid-deleted	WebID Profile events.

The following services do not produce audit events:

• Notification Gateway service

• WebSocket Notification service

• Start service

ESS uses asynchronous messaging for auditing.

Audit Event Message Internal Format

Internally, ESS’ audit event messages are in RDF and serialized as ActivityStreams 2.0 JSON-LD documents:

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)

• the application information (Client ID)

• the Pod information (Pod root URL and Pod data subject)

{
   "@context":[
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id":"<UUID of the event>",
   "type": [ "Activity", <type2>,... ],
   "name":"<event name>",
   "summary": "<event description>",
   "generator": <JSON document identifying the software producing the event>,
   "actor": [ <JSON document identifying the actor associated with the event>, ... ],
   "object": [ <JSON document identifying the object associated with the event>, ... ],
   "instrument": [ <JSON document identifying the client/application associated with the event>,
                   <JSON document with associated OpenTelemetry data>,
                   <JSON document with associated application-defined metadata>,
                   <JSON document identifying the Pod root and data subject>, ... ],
   "result": [ <JSON document containing associated results for the event, if any> ],
   "published": "<datetime>",
   "identifier":"<identifier to use for correlated events>"
}

@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., service-started, 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: "generator": { "id": "<service URL>" "type": ["SoftwareApplication"], "name": "<application name>", "qualifiedAssociation": "<processId>", "wasAssociatedWith": "<Kubernetes pod name>" }
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 (such as service start events, etc.). id and name fields are associated with a type field. For example: For an Access Request/Grant event, which include the id and the type: "actor" : [ { "id" : "https://id.example.com/someusername", "type" : [ "Agent" ] } ], For IdP login events: "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; For example: A Pod provisioned event: "object": [ { "type": [ "Storage" ], "id": "<Pod Root URL>" } ] For Access Request/Grant/Denial creation events, the object field contains the created Access Request/Grant/Denial: The object for the create Access Request/Grant/Denial events contains the created Request/Grant/Denial in a document with: the content field that contains the Access Request/Grant/Denial as string and the mediaType field. Previously, the object contained the created Access Request/Grant/Denial directly as an element. The object contains an element that identifies the Pod resource. "object": [ { "content" : "{\"id\":\"https://vc.example.com/vc/79288a3 ... }", "mediaType": "application/ld+json" }, { "type" : [ "Resource" ], "id" : "https://storage.example.com/ad3b.../some/resource" } ] For Pod resource CRUD events ( resource-created, resource-read, resource-updated, and resource-deleted) events, the object field include an object that identifies the Pod resource. For example: "object": [ { "generated" : "6cba8240-9f79-40db-a129-c6b8edddb840", "invalidated" : "4e12ed06-c4e5-41bc-bcd3-0f6a821c08ca", "type" : [ "Resource" ], "id" : "https://storage.example.com/ad3b.../some/resource" } ] 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: The clients associated with the event, if any. For example: "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 such as service-started do not have associated clients, and thus may have empty instrument array. The associated OpenTelemetry instrument info For example: "instrument" : [ // ... { "traceId" : "7decd3657a9efffc010a4b6a4b3da586", "spanId" : "91123fce3c668451", "isSampled" : true, "name" : "OpenTelemetry Span Context", "type" : [ "SpanContext" ] }, // ... ], OpenTelemetry traceId field can be used to correlate messages associated with a request. See Appendix: Audit Event Correlation for more information. The associated Pod information: hasDataSubject contains the Pod data subject information (Pod Data Subject refers to the agent who created the Pod. ) hasStorage contains the Pod root URL. For example: "instrument" : [ // ... { "hasDataSubject" : { "id" : "https://id.example.com/someusername", "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 sent in client requests For example: "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 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, or 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

Integration with External Logging Systems

The ESS Auditing Service can log to:

• sysout (default)

• Syslog

• Microsoft Sentinel

For more information, see Integration with Syslog and Integration with Sentinel.