Audit Log API

Overview

The SendSafely Audit Log API captures metadata about events occurring in the SendSafely platform. Customers who opt in to this feature can access audit logs via the SendSafely Rest API and can optionally set up an automated export feed to an Amazon S3 bucket. 

Every Audit Log entry includes a standard set of fields that are captured for every event, as well as a LogDetails entry (in JSON format) that captures data specific to the event. The standard fields are searchable using the REST API.

Standard Fields

• eventId - Unique identifier for the event
• timestamp - Timestamp of when the event occurred in ISO 8601 format (UTC)
• eventType  - The event that triggered the log entry. The following event types are supported:
  • PACKAGE_EVENT - Logged each time a file action (e.g. upload, download etc.) is performed on a SendSafely package* 
  • ADMIN_EVENT - Logged each time an admin action is carried out by a SendSafely Admin user.
  • USER_EVENT - Logged each time a user action (e.g. login, reset password etc.) is carried out by an end-user. Includes both guests and registered users. 
• action** - The specific action performed as part of the logged event. Actions are more granular than events. Each eventType has a defined list of valid actions, described further below.
• ipAddress - The source IP address of the device that triggered the event
• authenticatedUser - The identity (email) of the logged in user who performed the event. Can have values of "Anonymous Recipient" or "Unverified Sender" if users are not authenticated. Includes both guests and registered users.
• impersonatedUser - If the authenticated user was an admin impersonating another user, then this is the person they were impersonating. If impersonation was not being performed this value will be null.
• LogDetails** - Additional data elements specific to the eventType and action. LogDetails are in JSON format.
  • The LogDetails field packageOwner field (logged for all PACKAGE_EVENTS) is also searchable via the REST_API.

 

* A SendSafely package is either a Transfer (includes Send, Reply or Personal URL upload), Dropzone or Workspace. The owner is either the person who created the package, or is the owner of the personal URL or Dropzone used by a guest to create a package.

** A complete list of actions and LogDetails for each event type are listed at the end of this article. 

Example Record

For reference, here is an example record for the PACKAGE_EVENT eventType and PACKAGE_FILE_DOWNLOAD action. In this example, [e-mail] downloaded a file named example.pdf from Package Id JEPT-YZ7X, which was sent by [e-mail]. 

{
   "eventId": "643ff796b9eb7544f4008724",       
   "timestamp": "2023-04-14T19:29:15.898Z"      
   "eventType": "PACKAGE_EVENT",
   "Action": "PACKAGE_FILE_DOWNLOAD",
   "ipAddress": "127.0.0.1",
   "authenticatedUser": "[e-mail]",
   "impersonatedUser": null,
   "logDetails": {
      "packageId": "JEPT-YZ7X",
      "packageType": "TRANSFER",
      "fileName": "example.pdf",
      "fileSize": "19924",
      "packageOwner": "[e-mail]"
   },
}

Data Retention

All Audit Logs are accessible through the API for 90 days. Customers that wish to retain log access for extended periods of time should use the S3 Export Feed, as the export files can be retained in S3 indefinitely.

Accessing Audit Log Data 

In order to access the Audit Log API, this feature must be enabled for your organization. Please contact [e-mail] for information regarding opting in to Audit Logging. In addition to the feature being enabled, you must also have Administrative rights in your SendSafely portal in order to access the Audit Log.

There are two options for accessing the Audit Log data: 

1. Direct queries using the SendSafely Rest API
2. Automated feed export to an S3 bucket in your AWS environment

1. Using the REST API

A SendSafely Administrator can access Audit Log data by making a request to the SendSafely REST API. An overview of the SendSafely Rest API can be found here. Tips for using the REST API for accessing the SendSafely Audit Log are noted below:

• Postman Collection

The SendSafely Rest API postman collection (Get AuditLog Post request) is located here: https://rest-api-docs.sendsafely.com/#39d41346-f4e1-40f5-b062-16d8157f8342

• Pagination 

The SendSafely Rest API uses the "pageSize" and “rowIndex" parameters for pagination. 

• • The pageSize value represents the number of records you want returned in each page (can be from 1 to 100). 
  • At the end of each response, a nextRowIndex value is returned if there are additional records. To request the next page, use the nextRowIndex value from the response as the rowIndex in your next request to fetch the next page. You should not specify a rowIndex (or alternatively use rowIndex=0) when requesting the first page of results. 

• Searching by Date/Time Range

When searching on date range, (minTimestamp and maxTimestamp) you must specify a date and optionally a time. Either of the following formats are accepted: 

• •  yyyy-MM-dd HH:mm:ss 
  • yyyy-MM-dd

• Request Examples:

  All user events for a specific user ([e-mail]) between two dates:
  • {"eventType":"USER_EVENT","ipAddress":"","authenticatedUser":"[e-mail]","impersonatedUser":"","packageOwner":"","minTimestamp":"2023-04-01","maxTimestamp":"2023-04-20","pageSize":100,"rowIndex":0}

All downloads by a user ([e-mail]):

• • {"eventType":"PACKAGE_EVENT","action":"PACKAGE_FILE_DOWNLOAD","ipAddress":"","authenticatedUser":"[e-mail]","impersonatedUser":"","packageOwner":"","minTimestamp":"","maxTimestamp":"","pageSize":100,"rowIndex":0}

2. S3 Export Feed

When the Audit Log S3 export feed is enabled, SendSafely will write all Audit Log records to a JSON file within your S3 bucket every 5 minutes. The file names generated by the export feed use the following format:

bucket[/prefix]/sendsafely-audit-export/portal-hostname/yyyy/mm/dd/sendsafely-audit-export_portal-hostname_end-time.json

• bucket - The name of the S3 bucket.
• prefix - The prefix (logical hierarchy) in the bucket. If you don't specify a prefix, the logs are placed at the root level of the bucket.
• portal-hostname- Your SendSafely portal hostname (ie acme.sendsafely.com) 
• yyyy/mm/dd - The date that the log was delivered.
• end-time- The date and time that the logging interval ended. For example, an end time of 20230414T234000Z contains entries for requests made between 23:35 and 23:40.

To enable S3 logging, your organization must already have access to the Audit Log API. Steps to configure your S3 bucket are documented here. 

Actions and LogDetails

Below is a complete list of all Audit Log eventTypes, associated actions, and a list of attributes logged within the LogDetails field. 

PACKAGE_EVENT

This event captures all file upload and download actions on a package.

Actions:

• PACKAGE_FILE_DOWNLOAD - captures all file downloads from either Transfer or Dropzone packages. (Workspace downloads are captured in the WORKSPACE_FILE_DOWNLOAD action.)
  
  • In-browser views of secure messages, images or PDF files are captured in this action as well as downloads to local drives. 
  • File downloads are logged individually even if there are multiple files in a package and the user chose the "download all" option"
  • LogDetails (in addition to standard fields):
    
    • packageId - Unique Package ID
    • packageType - Specifies whether the package containing the file is a DROPZONE or TRANSFER package.
    • fileName - Name of the file downloaded or "securemessage.txt" if a secure message.
    • fileSize - File size in bytes
    • packageOwner - The user (email address) who owns the package. The owner is either the person who created the package, or is the owner of the personal URL or Dropzone used by a guest to create a package.
    • uploader - The email address of the user who uploaded the file. "Unverified" is appended to the email address on unauthenticated Dropzones (i.e. the user’s email has not been validated by pin code)

• FINALIZE_PACKAGE - captures metadata on all "finalized" SendSafely packages. A finalized package has completed the package creation process (i.e. files have been uploaded, recipients added and settings configured) and has been successfully sent via SendSafely. 
  • Draft packages (i.e. those not yet sent) are not included in this action.
  • LogDetails (in addition to standard fields):
    • packageId - Unique Package Id
    • packageOwner - The user (email address) who owns the package. The owner is either the person who created the package, or is the owner of the personal URL or Dropzone used by a guest to create a package.
    • packageType - Specifies whether the package is a DROPZONE or TRANSFER package.
    • uploader - The email address of the user who uploaded the file. "Unverified" is appended to the email address on unauthenticated Dropzones (i.e. the user’s email has not been validated by pin code)
    • hasMessage - Whether the package includes a secure message (true/false)
    • files - Nested JSON object with file name and file size for each file in the package
    • recipients - Nested JSON object with the recipient email for each recipient. If the package has no recipients added (i.e. anyone with the link can access) this field will say "Anonymous Recipient"
    • contactGroups - Nested JSON object with the name and id of each contact group on the package
    • life - The number of days before the page expires and can no longer be accessed by recipients
    • recipientAccessLimit - The number of times a package can be opened by a recipient
    • restrictFileSaveAndPrint - View only status - i.e. whether PDF and Image files in the package can be downloaded and/or printed. This feature only applies to image or PDF files (true/false).
    • watermarking- whether PDF and Image files in the package are watermarked with the recipient's email address. This feature only applies to image or PDF files (true/false).

•  

• WORKSPACE_FILE_UPLOAD- captures metadata on every file uploaded to a Workspace.
  • LogDetails (in addition to standard fields):
    • packageId - Unique Package Id
    • workspaceName - The name of the Workspace
    • fileName - The name of the file
    • fileVersion - The version of the file
    • fileSize - The size of the file in bytes
    • packageOwner - The user who owns the Workspace
    • uploader - The email address of the user who uploaded the file.

• WORKSPACE_FILE_DOWNLOAD -  captures metadata on every file downloaded from a Workspace.
  • In-browser views of images or PDF files are captured in this action as well as downloads to local drives. 
  • File downloads are logged individually even if the user chose to download multiple files at one time.
  • LogDetails (in addition to standard fields):
    • packageIdUnique - Package Id
    • workspaceName - The name of the Workspace
    • fileName - The name of the file
    • fileVersion - The version of the file
    • fileSize - The size of the file in bytes
    • uploader - The email address of the user who uploaded the file
    • packageOwner - The user who owns the Workspace

ADMIN_EVENT

This event captures actions performed by an Admin user on a target user.

Actions:

• INVITE_USER -  Captures when an Admin has sent a registration invite to the target user 
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• ACTIVATE_USER -  Captures when the target user has been activated by SCIM, or the Admin has activated a Service Account (No Login) for the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• DEACTIVATE_USER - Captures when an Admin has deactivated the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• RESTORE_USER - Captures when an Admin has restored the target user from the Deactivated User listing (user is restored to No Login status)
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• GRANT_ADMIN_ROLE - Captures when an Admin has granted the target user Admin privileges
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• REVOKE_ADMIN_ROLE - Captures when an Admin has removed Admin privileges from the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• GRANT_APPROVER_ROLE - Captures when an Admin has granted the target user Approver privileges
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• REVOKE_APPROVER_ROLE - Captures when an Admin has removed Approver privileges from the target user.
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• ENABLE_USER_2FA_SMS - Captures when an Admin has turned on SMS 2FA for the target user. 
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• DISABLE_USER_2FA_SMS - Captures when an Admin has turned off SMS 2FA for the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• DISABLE_USER_2FA_TOTP - Captures when an Admin has turned off TOTP 2FA for the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• UPDATE_USER_SECURITY_QUESTION - Captures when an Admin has updated the security question and answer for the target user
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action
• UPDATE_USER_2FA_PHONE_NUMBER - Captures when an Admin has changed the target user’s phone number
  • LogDetails (in addition to standard fields):
    • targetUser - Email address of the user who was the target of the action

USER_EVENT

This event captures user actions and updates users have made to their own user profile. 

Actions:

• ACTIVATE - Captures when a user has completed the registration processDEACTIVATECaptures when a user has deactivated their own account from the Edit Profile screen
• BEGIN_REGISTRATION - Captures when a user has clicked on the Register Now button on the login screen
• ENABLE_2FA_SMS - Captures when a user has configured SMS 2FA
• DISABLE_2FA_SMS - Captures when a user has disabled SMS 2FA
• ENABLE_2FA_TOTP - Captures when a user has configured TOTP 2FA
• DISABLE_2FA_TOTP - Captures when a user has disabled TOTP 2FA
• UPDATE_SECURITY_QUESTION - Captures when a user has updated their security question and answer
• UPDATE_PASSWORD - Captures when a user has changed their password
• UPDATE_2FA_PHONENUMBER - Captures when a user has changed their phone number for SMS 2FA
• RESET_PASSWORD - Captures when a user has changed their password
• LOGIN - Captures when a user has successfully logged in
  • LogDetails (in addition to standard fields): 
    • isGuest - (true/false) Indicates if the user is a guest or a registered user
• GENERATE_API_KEY - Captures when a user has set up an API Key
• DEACTIVATE_API_KEY - Captures when a user has added a trusted browser / trusted device
• GENERATE_DEVICE_KEY - Captures when a user has added a trusted browser / trusted device
• DEACTIVATE_DEVICE_KEY - Captures when a user had deleted a trusted browser / trusted device

•