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 Audited Services [1]	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.
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.

[1]

The Notification Gateway service is not audited.

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 Broker service 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

Tip

See also ESS’ Kafka Configuration.

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.

Additional Information

See also https://quarkus.io/guides/all-config.