# 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: | Services | Event Name | Notes | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Most Services | | Service Startup/Shutdown. | | Purgeable services (i.e. Access Grant, Authorization, Broker, Pod Provision, and WebID) | | Purge start/complete. | | Access Grant Service | |

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 Lifecycle events. | | Pod Storage Service | | Resource Lifecycle events. | | | |

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 event. | | Purger application | | Purge start/end (successful or not). | | Query Service | | Query events. | | Query Indexer | | Query Indexer events. | | Solid OIDC Broker Service | | Authentication/Authorization flow. | | UMA Service | | UMA Grant Flow. | | WebID Service | | WebID Profile events. | The following services do not produce audit events: * Notification Gateway service * WebSocket Notification service * Start service {% hint style="info" %} ESS uses asynchronous messaging for auditing. {% 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](https://docs.inrupt.com/reference/glossary#webid)) * the application information ([Client ID](https://docs.inrupt.com/reference/glossary#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":"" } ```
@contextSpecifies the JSON-LD contexts.
idUniversally Unique IDentifier (UUID) for the event.
typeAn array of event types; e.g., [ "Activity", "Create" ].
nameName that denotes the event; e.g., service-started, openid-backend-idp-login, resource-created, access-grant-created, etc.
summaryShort 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.
publishedThe timestamp of the event.
identifierIdentifier 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](https://docs.inrupt.com/security/auditing/appendix-audit-events-examples "mention") ### 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).