Audit & Forensics Logs

The Keyavi Audit & Forensics Logs API provides read-only access to forensics and audit data that Keyavi nodes collect. These APIs provide the ability to integrate Keyavi with external applications, such as SIEM solutions like Microsoft Sentinel.

The Audit and Forensics logs API includes two resources: logs/payload and logs/full-payload. The primary difference between the two is logs/payload does not return Personally Identifiable Information (PII), while logs/full-payload does.

Full Payload

The endpoint for the Full Payload resource is logs/full-payload. It contains all the files' associated events, including protect, open, and audit events. The Full Payload resource includes PII and sensitive information. If you don't want to return PII, use the Payload resource instead.

Full Payload Resource Description

{
    "pagination": {
        "totalRecords": 26381,
        "pageSize": 100,
        "itemsInPage": 100,
        "page": 1
    },
    "data": [
        {
            "userLastNameFirstName": "Attree,Bevin",
            "userEmailAddress": "[email protected]",
            "currentOwnerLastNameFirstName": "Tant,Caddric",
            "currentOwnerEmailAddress": "[email protected]",
            "logId": 30088,
            "userId": "43634e36-a996-4b3b-beba-733f55bec760",
            "payloadId": "97b49357-9f02-468e-a70c-a4a5a180588b",
            "payloadName": "IdNullaUltrices.txt",
            "currentPayloadOwnerId": "bbbd4c14-a844-43f6-8afb-0352c2c4aea0",
            "actionAttempted": "Decrypt",
            "result": "AccessDenied",
            "resultReason": "UserPayloadNoAccess",
            "logTimestamp": "2023-05-05T15:54:22.5071276",
            "userNetwork": {
                "ipAddress": "60.254.90.254",
                "networkName": "Three Faces East    ",
                "networkId": "7dd47255-8751-4e16-8f82-2ec428ec75b2",
                "domainName": "AzureAD",
                "deviceType": "Microsoft Windows 10 Enterprise",
                "machineName": "17bqaDnu9",
                "mac": "9SCOO7ZEKL",
                "uuid": "86349ada-f414-4a86-9c73-430f451e85f9",
                "serviceProvider": "",
                "latLong": "84.9183,-09.7229",
                "address": "56 Nobel Terrace, New York, NY 10029, USA"
            }
        },
    ]
}

Attributes

The following table lists the attributes of this resource.

note

What's included in the JSON object depends on the permissions assigned to the API user. Work with your administrator to ensure that you have the right permissions.

Attribute	Description
`pagination`	Provides pagination details. You can pass `page` and `pageSize` query parameters to control the amount of data you receive.
`data`	Contains the information about the Keyavi-protected files returned by the resource.
`logID`	The unique identifier of the logged event.
`userLastNameFirstName`	The first and last name of the user performing the logged event. Note: `userLastNameFirstName` is PII.
`userEmailAddress`	The email address of the user performing the logged event. Note: `userEmailAddress` is PII.
`currentOwnerLastNameFirstName`	The first and last name of the owner of the Keyavi-protected file. Note: `currentOwnerLastNameFirstName` is PII.
`currentOwnerEmailAddress`	The first and last name of the owner of the Keyavi-protected file. Note: `currentOwnerEmailAddress` is PII.
`userId`	The user ID of the user performing the logged event. This is a Keyavi-generated internal user identifier unique to a Keyavi node.
`payloadId`	The ID associated with the Keyavi-protected file. This is a Keyavi-generated internal payload identifier unique to a Keyavi node.
`payloadName`	The name of the Keyavi-protected file.
`currentPayloadOwnerId`	The user ID of the owner of the Keyavi-protected file.
`actionAttempted`	The type of logged action (e.g., `Decrypt`, `Audit`, `Encrypt`, or `EncryptionRequest`). The `actionAttempted` always includes a related `result` and `resultReason`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`result`	How Keyavi responded to the `actionAttempted`. Possible values include `AccessGranted`, `AccessDenied`, `AccessWindow`, `RevokeAccess`, `AuthorisedGroupAccess`, `AuthorisedUserAccess`, and `AuthorChanged`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`resultReason`	Why Keyavi returned the `result` of the `actionAttempted`. Possible values include `Changed`, `Created`, `Success`, `TimeEmbargoFailed`, `UserPayloadNoAccess`, or `GeoValidationFailed`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`logTimestamp`	The UTC date and time when the action happened.
`userNetwork`	The network information used to identify geolocation information for the user's network, including IP address, network name, network ID, domain name, device type, machine name, MAC address, UUID, service provider, latitude and longitude, and address. Note: Access to geolocation information requires elevated privileges.

Retrieve Full Payload

Use a GET /logs/full-payload request to retrieve the list of logged events, based on the authentication used to make the request.

curl --location 'https://<Custom API URL>/api/logs/full-payload' \
--header 'Authorization: Bearer <Your Token>'

Parameters

The following table shows the query parameters available to tailor and filter the response for this resource.

Attribute	Description
`actionAttempted`	Filter by `Decrypt`, `Audit`, or `Encrypt`
`currentPayloadOwnerId`	Filter by the ID of the owner of the Keyavi-protected file.
`endTime`	The end time of the query formatted in ISO 8601 format, such as `YYYY-MM-DDTHH:MM:SS.ss`. This represents the latest timestamp for any file contained in the query.
`page`	Filter by the specific page number.
`pageSize`	Define the number of objects to include in the results. The default `pageSize` is 100.
`payloadId`	Filter by the ID of the Keyavi-protected file.
`payloadName`	Filter by the name of the Keyavi-protected file.
`result`	Filter by `AccessGranted`, `AccessDenied`,`AccessWindow`, `RevokeAccess`, `AuthorisedGroupAccess` or `AuthorisedUserAccess`.
`resultReason`	Filter by `Success`, `GeoValidationCountryExclusionFailed`, `TimeEmbargoFailed`, `UserPayloadNoAccess`, `GeoValidationFailed`, `Changed`, or `Created`.
`userId`	Filter by the ID of the user who performed the tracked action.
`sort`	Sort the results by `logTimestamp`, `userLastNameFirstName`, `result`, `resultReason`, `actionAttempted`, `payloadName`. To order ascending, prepend with `+`; to order descending, prepend with `-`. For example, `?sort=-logTimestamp` returns a descending list sorted by `logTimestamp`.
`startTime`	The start time of the query formatted in ISO 8601 format, such as `YYYY-MM-DDTHH:MM:SS.ss`. This represents the earliest timestamp for any file contained in the query.

Payload

The endpoint for the Payload resource is logs/payload. It contains all the files' associated events, including protect, open, and audit events. The Payload resource does not include PII or sensitive information like names and email addresses. If you want to return PII, use the Full Payload resource instead.

Payload Resource Description

{
    "pagination": {
        "totalRecords": 26381,
        "pageSize": 100,
        "itemsInPage": 100,
        "page": 1
    },
    "data": [
        {
            "logId": 30088,
            "userId": "43634e36-a996-4b3b-beba-733f55bec760",
            "payloadId": "97b49357-9f02-468e-a70c-a4a5a180588b",
            "payloadName": "IdNullaUltrices.txt",
            "currentPayloadOwnerId": "bbbd4c14-a844-43f6-8afb-0352c2c4aea0",
            "actionAttempted": "Decrypt",
            "result": "AccessDenied",
            "resultReason": "UserPayloadNoAccess",
            "logTimestamp": "2023-05-05T15:54:22.5071276",
            "userNetwork": {
                "ipAddress": "60.254.90.254",
                "networkName": "Three Faces East    ",
                "networkId": "7dd47255-8751-4e16-8f82-2ec428ec75b2",
                "domainName": "AzureAD",
                "deviceType": "Microsoft Windows 10 Enterprise",
                "machineName": "17bqaDnu9",
                "mac": "9SCOO7ZEKL",
                "uuid": "86349ada-f414-4a86-9c73-430f451e85f9",
                "serviceProvider": "",
                "latLong": "84.9183,-09.7229",
                "address": "56 Nobel Terrace, New York, NY 10029, USA"
            }
        },
    ]
}

Attributes

The following table lists the attributes of this resource.

note

What's included in the JSON object depends on the permissions assigned to the API user. Work with your administrator to ensure that you have the right permissions.

Attribute	Description
`pagination`	Provides pagination details. You can pass `page` and `pageSize` query parameters to control the amount of data you receive.
`data`	Contains the information about the Keyavi-protected files returned by the resource.
`logID`	The unique identifier of the logged event.
`userId`	The user ID of the user performing the logged event. This is a Keyavi-generated internal user identifier unique to a Keyavi node.
`payloadId`	The ID associated with the Keyavi-protected file. This is a Keyavi-generated internal payload identifier unique to a Keyavi node.
`payloadName`	The name of the Keyavi-protected file.
`currentPayloadOwnerId`	The user ID of the owner of the Keyavi-protected file.
`actionAttempted`	The type of logged action (e.g., `Decrypt`, `Audit`, `Encrypt`, or `EncryptionRequest`). The `actionAttempted` always includes a related `result` and `resultReason`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`result`	How Keyavi responded to the `actionAttempted`. Possible values include `AccessGranted`, `AccessDenied`, `AccessWindow`, `RevokeAccess`, `AuthorisedGroupAccess`, `AuthorisedUserAccess`, and `AuthorChanged`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`resultReason`	Why Keyavi returned the `result` of the `actionAttempted`. Possible values include `Changed`, `Created`, `Success`, `TimeEmbargoFailed`, `UserPayloadNoAccess`, or `GeoValidationFailed`. See Audit & Forensics Logs Actions, Results, and Reasons for details.
`logTimestamp`	The UTC date and time when the action happened.
`userNetwork`	The network information used to identify geolocation information for the user's network, including IP address, network name, network ID, domain name, device type, machine name, MAC address, UUID, service provider, latitude and longitude, and address. Note: Access to geolocation information requires elevated privileges.

Retrieve Payload

Use a GET /logs/payload request to retrieve the list of logged events, based on the authentication used to make the request.

curl --location 'https://<Custom API URL>/api/logs/full-payload' \
--header 'Authorization: Bearer <Your Token>'

Parameters

The following table shows the query parameters available to tailor and filter the response for this resource.

Attribute	Description
`actionAttempted`	Filter by `Decrypt`, `Audit`, or `Encrypt`
`currentPayloadOwnerId`	Filter by the ID of the owner of the Keyavi-protected file.
`endTime`	The end time of the query formatted in ISO 8601 format, such as `YYYY-MM-DDTHH:MM:SS.ss`. This represents the latest timestamp for any file contained in the query.
`page`	Filter by the specific page number.
`pageSize`	Define the number of objects to include in the results. The default `pageSize` is 100.
`payloadId`	Filter by the ID of the Keyavi-protected file.
`payloadName`	Filter by the name of the Keyavi-protected file.
`result`	Filter by `AccessGranted`, `AccessDenied`,`AccessWindow`, `RevokeAccess`, `AuthorisedGroupAccess` or `AuthorisedUserAccess`.
`resultReason`	Filter by `Success`, `GeoValidationCountryExclusionFailed`, `TimeEmbargoFailed`, `UserPayloadNoAccess`, `GeoValidationFailed`, `Changed`, or `Created`.
`userId`	Filter by the ID of the user who performed the tracked action.
`sort`	Sort the results by `logTimestamp`, `userLastNameFirstName`, `result`, `resultReason`, `actionAttempted`, `payloadName`. To order ascending, prepend with `+`; to order descending, prepend with `-`. For example, `?sort=-logTimestamp` returns a descending list sorted by `logTimestamp`.
`startTime`	The start time of the query formatted in ISO 8601 format, such as `YYYY-MM-DDTHH:MM:SS.ss`. This represents the earliest timestamp for any file contained in the query.

Audit & Forensics Logs

Full Payload​

Full Payload Resource Description​

Attributes​

note

Retrieve Full Payload​

Parameters​

Payload​

Payload Resource Description​

Attributes​

note

Retrieve Payload​

Parameters​

Full Payload

Full Payload Resource Description

Attributes

Retrieve Full Payload

Parameters

Payload

Payload Resource Description

Attributes

Retrieve Payload

Parameters