Log Security Event

The logSecurityEvent operation allows you to submit application-generated events to be sent to your tenants’ logging and SIEM systems, along with the events generated by encrypt and decrypt operations. You provide an event type, along with a set of metadata associated with the event. TSC sends this request to the TSP, which routes it to the SIEM configured by the specified tenant.

The EventMetadata provided with the event includes the following fields:

tenantId: A unique ID specifying the tenant to which the event is associated - this will allow the TSP to route all of a tenant’s security events to that tenant’s SIEM system.

requestingUserOrServiceId: A unique ID that denotes which user or service is making the request to encrypt data. This will be used to log access of the Tenant Security Proxy.

dataLabel: An optional label that can be used to add additional classification for the event being logged.

timestampMillis: An optional time, in milliseconds since the epoch, that indicates when the event occurred. If this is omitted, the current time on the system is used.

sourceIp: An optional string containing the IP address of the event’s initiator.

objectId: An optional string specifying the identifier of the object being acted on by the event.

requestId: An optional string specifying a unique ID that ties host application request ID to Tenant Security Proxy logs.

otherData: Any other string key/value pairs to apply to the encrypted data. This data will be sent to the Tenant Security Proxy for logging. In Java, this is a Map.

Java

Date date = new Date();
Map<String, String> customFields = new HashMap<>();
customFields.put("field1", "value1");
customFields.put("field2", "value2");
EventMetadata metadata =
    new EventMetadata("TENANT_ID", "serviceOrUserId", "data label", customFields, "Rq8675309", "127.0.0.1", "userId1", date.getTime());

JavaScript

const metadata = new EventMetadata("TENANT_ID", "serviceOrUserId", "data label", Data.now(), "127.0.0.1", "userId1", "Rq8675309", {
    field1: "value1",
    field2: "value2",
});

PHP

$metadata = new EventMetadata("TENANT_ID", new IclFields("serviceOrUserId", "data label", "127.0.0.1", "userId1", "Rq8675309"), [], time() * 1000);

Go

requestMetadata := tsc.RequestMetadata{TenantID: "TENANT_ID",
    IclFields: tsc.IclFields{RequestingID: "serviceOrUserId",
        DataLabel: "data label",
        SourceIP:  "127.0.0.1",
        ObjectID:  "userId1",
        RequestID: "Rq8675309"},
    CustomFields: nil}
metadata := tsc.EventMetadata{RequestMetadata: requestMetadata, TimestampMillis: time.Now()}

It is also possible to provide undefined for the optional values in the Javascript TSC:

JavaScript

const metadata = new EventMetadata("TENANT_ID", "serviceOrUserId");

or

JavaScript

const metadata = new EventMetadata("TENANT_ID", "serviceOrUserId", undefined, undefined, undefined, "userId1");

The Java TSC provides several constructors that allow you to specify a subset of the parameters. All of them require the tenantId and requestingUserOrServiceId.

The caller must specify the event type; we predefine a number of types, grouped into different categories. The complete list can be found here. In addition to the predefined event types, there is an additional custom event type that allows you to add new event type names that are unique to your application.

Java

CompletableFuture<Void> logEvent = client.logSecurityEvent(UserEvent.LOGIN, metadata));
try {
    logEvent.get();
} catch (Exception e) {
    fail("Security Event logging failed.");
}

JavaScript

client.logSecurityEvent(UserEvent.LOGIN, metadata).then(
    (queuedEvent) => console.log("Successfully logged user login event."),
    (error) => console.log("Error logging user login event: ${error}.");
);

PHP

$client->logSecurityEvent(UserEvent::login(), $metadata);

Go

err := client.LogSecurityEvent(ctx, tsc.UserLoginEvent, &metadata)

Based on the provided tenant ID, the provided information will be formatted into an event and sent via the TSP to the tenant’s SIEM.