1. Docs

SaaS Shield Real Time Security Events

If you are using SaaS Shield and a tenant has configured a KMS, each request by your application to encrypt or decrypt sensitive data will cause the TSP to make a wrap or unwrap call to the tenant’s KMS. The tenant’s KMS should generate events that the tenant can extract to create a rudimentary security event stream. However, if the tenant enables key leasing, the KMS is no longer involved in each key wrap and unwrap action in the TSP, so the tenant will lose this source of information. To allow tenants to retain transparency around all access to their data, even with key leasing enabled, SaaS Shield provides a security event logging subsystem. Tenant administrators can configure connection information for their own logging / SIEM system in the Configuration Broker, similar to the way they configure their KMS information. The logging configuration is encrypted and protected the same way the KMS configuration is, using the end-to-end encryption provided by the Data Control Platform.

The TSP will generate a security event for each key wrap and unwrap operation. The APIs the TSC provides to encrypt and decrypt data allow the application to specify additional metadata, including the ID of the user or service requesting the action, a label for the data, and a request ID. This information is passed along to the TSP and is included in the events that are generated by the TSP and pushed to the tenant’s logging / SIEM system via the Real Time Security Event process, which is installed along with the Logdriver in your infrastructure. If a tenant has not provided a logging configuration, Logdriver will send their events to stdout instead.

This provides a significantly richer audit trail than the event stream that can be extracted from the tenant’s KMS. (More information is available on the metadata included with TSC calls to encrypt and decrypt.)

In addition to the events generated by the TSP, the TSCs provide an API so that your application can generate additional security events and feed them into the same stream. You can record logins, logouts, password changes, admin permission changes, and other events using the TSC and have them delivered to the appropriate tenant’s SIEM. This push of events happens in near-real time, so you don’t need to set up a process to periodically pull security events, and you don’t need to open up ports so your tenants can pull their events.

The following are benefits your tenants can realize by enabling real time security events:

  • a rich stream of wrap and unwrap action details, even if key leasing is enabled
  • additional metadata on each event if that is attached by the vendor’s application
  • unique vendor and TSP request IDs that can be used to correlate with server application and TSP logs to investigate individual events
  • application-generated security events give the tenant deeper insight into actions take by their users or by vendor processes

More information is available on the TSC call logSecurityEvent.

Logged Events

The TSP generates the following events and pushes them to tenant logging systems:

Standard Events

  • EDEK decrypted via {KMS}
  • DEK encrypted via {KMS}

Key Leasing Enabled

  • Leased a new key via {KMS}
  • Decrypted a leased key via {KMS}
  • Encrypted a DEK using a leased key
  • Decrypted an EDEK using a leased key


If you have a tenant that is configured to log to Stackdriver and make a call like the following (using the NodeJS TSC):

const metadata = new DocumentMetadata(TENANT_ID, "serviceOrUserId", "PII"); // Create a map containing your data const custRecord = { ssn: Buffer.from("000-12-2345", "utf-8"), address: Buffer.from("2825-519 Stone Creek Rd, Bozeman, MT 59715", "utf-8"), name: Buffer.from("Jim Bridger", "utf-8"), }; // Request a key from the KMS and use it to encrypt the document client.encryptDocument(custRecord, metadata)

then go to that tenant’s Stackdriver instance, set the resource to Global, and search, you can see the event that Logdriver pushed to the Stackdriver system. The above call logged the following event:

{ "insertId": "9g39qeg3bqb16a", "jsonPayload": { "tenantId": "tenant-gcp-l", "customFields": {}, "iclFields": { "tspRayId": "0AdZUx4R3UDLUjIi", "dataLabel": "PII", "requestingId": "serviceOrUserId", "logdriverRayId": "Chj4b1jXeId10ssx", "logMsg": "Decrypted a leased key via KMS." }, "timestamp": "2020-11-16T23:13:36.993Z" }, "resource": { "type": "global", "labels": { "project_id": "discrete-log-2" } }, "timestamp": "2020-11-16T23:13:36.993Z", "logName": "projects/discrete-log-2/logs/cmk-demo-logging", "receiveTimestamp": "2020-11-16T23:13:39.444272217Z" }

Application-Generated Events

The TSC logSecurityEvent method allows an application to log a number of different events. Each event has a category and an event name within that category. Except for the custom events, all the event names are predefined for each category.

Event Type Event names

The Custom event type allows you to provide your own name for the event, if you want to log an event that isn’t predefined.

Each event includes metadata that is passed with the event as it is processed. The metadata fields include the following:

  • tenantId: string specifying the tenant
  • timestampMillis: number specifying the time when the event occurred, in milliseconds since the epoch. Defaults to the current date/time if the caller does not provide a value
  • requestingUserOrServiceId: string specifying the unique ID of the user or service that triggered the event
  • datalabel: optional string providing an additional classification for the event
  • sourceIp: optional string containing the IP address that originated the action that triggered the event
  • objectId: optional string containing the ID of the object that was being affected when the event was triggered
  • requestId: optional string that the application can provide to tie the event together with requests to the TSP
  • otherData: optional list of key-value pairs that allow you to specify arbitrary names and values for additional metadata


If you have a tenant that is configured to log to Stackdriver and make a call like the following (using the NodeJS TSC):

const otherData = { "field1": "gumby", "field2": "pokey" }; const metadata1 = new EventMetadata(TENANT_ID, "userId1", "PII", Date.now() - 5000, "", "userId1", "Rq8675309", otherData); client.logSecurityEvent(UserEvent.LOGIN, metadata1)

the following event will be logged in Stackdriver:

{ "insertId": "1ha9seeg2bv3av7", "jsonPayload": { "customFields": { "field2": "pokey", "field1": "gumby" }, "timestamp": "2020-11-16T22:43:25.754Z", "iclFields": { "requestingId": "userId1", "dataLabel": "PII", "sourceIp": "", "objectId": "userId1", "event": "USER_LOGIN", "logdriverRayId": "0G4Y10UpHvaZA9V3", "requestId": "Rq8675309", "tspRayId": "G3nphyPNTcOv1l6W" }, "tenantId": "tenant-gcp-l" }, "resource": { "type": "global", "labels": { "project_id": "discrete-log-2" } }, "timestamp": "2020-11-16T22:43:25.754Z", "logName": "projects/discrete-log-2/logs/cmk-demo-logging", "receiveTimestamp": "2020-11-16T22:43:32.772011897Z" }

Supported SIEMs

SaaS Shield Real Time Security Events currently supports logging to Google Compute Platform’s Stackdriver and to Splunk (both the enterprise and cloud versions), with more options on the way. For a complete list of supported logging systems, check here.

If a tenant has not provided a logging configuration, Logdriver will send their events to stdout instead.

Was this page helpful?