Auditing Service#

Changed in version 2.0.

ESS Auditing service audits various activities from the ESS services, including itself.

By default, auditing is enabled and logs the audit events to sysout.

Note

Auditing service continues to run when auditing is disabled; instead, disabling auditing stops the ESS services from publishing audit events.

Audit Events#

The following events are audited:

Services

Event Name

Notes

All Services

  • service-started

  • service-shutdown

Service Startup/Shutdown.

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.

Pod Provision Service

  • pod-provisioned

Pod Provisioning.

OpenID Provider

  • 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.

Audit Event Message Internal Format#

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

Note

Although the following document shows all possible fields for an event message, the specific events determine which fields appear.

{
   "@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>, ... ],
   "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, etc.

See Audit Events for a list of audited events names.

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": "urn:ess:<service hostname>#<processId>"
   "type": ["SoftwareApplication"],
   "name": "<application name>",
   "qualifiedAssociation": "<processId>",
   "wasAssociatedWith": "<service hostname>"
}

actor

An array of JSON documents that identify the agents associated with the event. For example, for a Pod provision event:

"actor": [
   { "id": "https://id.example.com/someusername" }
]

object

An array of JSON documents that identify the objects associated with the event. For example, for a Pod provision event:

"object": [
   { "type": "Storage", "id": "<PodURL>" }
]

instrument

An array of JSON documents that identify the clients associated with the event, such as the client identifier for a token request event.

"instrument": [ {
   "id": "<Client Identifier>"
} ]

published

The timestamp of the event.

identifier

Identifier to use for correlated events.

For example, the following is an audit event fired by the OpenID Provider for a new token request:

The openid-token-requested occurs for both new and refresh token requests. The summary field specifies whether the event is for a new or a refresh token.

{
   "@context":[
     "https://www.w3.org/ns/activitystreams",
     "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id":"urn:uuid:f8a16c67-4229-4295-9b81-0000000003",
   "type":["Activity", "Delegation", "AuthorizationCodeFlow"],
   "name":"openid-token-requested",
   "summary":"A new token was requested via the authorization code flow",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-openid-postgres",
      "qualifiedAssociation":"process-id:45",
      "wasAssociatedWith":"ess-openid-postgres-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser"
   }],
   "object": [{
      "name": "authorization_code",
      "scope": "openid webid"
   }],
   "instrument": [{
      "id": "1UqavEk9vYmx7BXq-rXFrJ6JfetldosysS9gJMTaecE"
   }],
   "published":"2022-01-27T09:40:40.466021Z",
   "identifier":"108bc9cdf0c2781ed143f2de22020d83"
}

For more information, see Audit Event Examples.

Integration with Syslog#

The ESS Auditing service can integrate with Syslog. When integrating with Syslog, ESS audit events are converted to Syslog message format:

<priority>version timestamp hostname service processId messageId message

Where:

  • hostname, service, processId and messageId values are taken extracted from the audit event agent field.

  • message is the full ESS audit event in JSON.

For example:

<110>1 2022-01-12T20:17:08.387Z ess-pod-storage-84648cfc95-qs865 inrupt-storage-postgres-s3 85 urn:uuid:579668c1-4e14-4fad-aea3-0000000005 { "@context": [ "https://www.w3.org/ns/activitystreams", "https://schema.inrupt.com/audit/v1.jsonld" ], "id": "urn:uuid:579668c1-4e14-4fad-aea3-0000000005", "type": ["Activity", "Create"], "name": "resource-created", "summary": "Resource has been created", "generator": { "type":["SoftwareApplication"], "name":"inrupt-storage-postgres-s3", "qualifiedAssociation":"process-id:22", "wasAssociatedWith":"ess-pod-storage-84648cfc95-qs865" }, "actor": [{ "id": "https://id.example.com/someuser" }], "object": [{ "type": "Resource", "id": "https://storage.example.com/51defe94/foo", "generated": "93b242492865407sa4d30247b2d64d00", "accessControl": "https://authorization.example.com/83b242392" }], "published": "2022-01-26T08:37:05.863044Z", "identifier": "14bce501481a67fbf0383f3f4359085a" }

By default, the Auditing service logs to sysout. To have the service output to Syslog instead, see Manage Auditing.

See also Syslog configuration options.

For more information on Syslog, see RFC 5424.

Integration with Sentinel#

The ESS Audit service can integrate with Microsoft Sentinel

When integrating with Microsoft Sentinel, the ESS audit events are converted into a Sentinel-specific format and POST’ed to the Sentinel service.

By default, the Auditing service logs to sysout. To have the service output to Sentinel instead, see Manage Auditing.

See also Sentinel configuration options.

Configuration#

As part of the installation process, Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.

The following configuration options are available for the service and may be set as part of updating the inputs for your deployment. The Inrupt-provided base Kustomize overlays may be using updated configuration values that differ from the default values.

Auditing Service: General Configuration#

QUARKUS_HTTP_PORT#

Default: 8080

The HTTP port the audit service runs on.

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

Audit Service: Kafka#

KAFKA_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers for use by ESS services, including this service.

Setting KAFKA_BOOTSTRAP_SERVERS configures ESS to use the same Kafka instance(s) for all its Kafka message channels (e.g., solidresource and auditv1out message channels). This service uses the auditv1in and auditv1out channels.

Note

Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

To use a different Kafka instance for the auditv1in and auditv1out channels, use specific message channel configuration.

See also ESS’ Kafka Configuration.

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD#

The strong cipher key to use when running auditing with encrypted messages.

Auditing Service: Syslog Configuration#

By default, the Auditing service logs to sysout. To have the service output to Syslog instead:

  • Customize your deployment to output to Syslog. See Manage Auditing for details.

  • Update configuration for Syslog integration. The following configuration options are available for integration with Syslog.

INRUPT_AUDIT_SYSLOG_HOST#

Default: localhost

The syslog server hostname that the audit service will connect to.

INRUPT_AUDIT_SYSLOG_PORT#

Default: 514

The syslog server port that the audit service will connect to.

INRUPT_AUDIT_SYSLOG_PROTOCOL#

Default: TCP

The protocol used to connect to the syslog server. Valid values are:

  • TCP

  • SSL_TCP

Auditing Service: Sentinel Configuration#

By default, the Auditing service logs to sysout. To have the service output to Microsoft Sentinel instead:

  • Customize your deployment to output to Sentinel. See Manage Auditing for details.

  • Update configuration for Sentinel integration. The following configuration options are available for integration with Microsoft Sentinel.

INRUPT_AUDIT_SENTINEL_WORKSPACE_ID#

Workspace ID used to access the Sentinel API.

INRUPT_AUDIT_SENTINEL_SHARED_KEY#

Shared key used to access the Sentinel API.

INRUPT_AUDIT_SENTINEL_API_VERSION#

The Sentinel API version.

INRUPT_AUDIT_SENTINEL_LOG_TYPE#

Default: Audit

The Sentinel Log-Type of the message.

QUARKUS_REST_CLIENT_SENTINEL_API_URL#

The Sentinel base URL that the audit service will connect to.