Security Logs Services

Article Overview

The following article describes EasySend's security logs services feature. It provides background, information about the API structure and how to use it.

Background

The Security Logs Services feature allows you to receive a pre-set payload (as a textual JSON or as a JSON file) based on the Elastic Common Schema (ECS) version 8.11 format containing various information regarding transactions at chosen security events that occur. The JSON is sent using a service.

The included events are:

• Authentication events for all auth providers:
  • CheckAuthResponseMissingCredentials
  • CheckAuthResponseAuthenticationSucceed
  • CheckAuthResponseAuthenticationError
  • CheckAuthResponseAuthenticationFailed

• Link Sent event
• Opened event
• Data Submitted event - When the user clicks the submit button
• Step Completed event - When a step is completed 
• Completed event - When the entire workflow is completed 

Security Logs by Service

for additional information see the Security Logs article.

Security Logs by API

To retrieve security logs via API, you must construct the request as follows:

Method

GET

URL

<PLAYER_URL>/player/api/get-security-logs

Headers

apiKey - the value will be the API key set in the EASYSEND_SECURITY_LOGS_API_KEY environment variable.

Parameters

• start_time - indicating when the security event occurred in YYYYMMDDHHMMSS format. This parameter is required.  
• end_type - indicating the time until the security event occurred in YYYYMMDDHHMMSS format. This parameter is optional, if missing, the default value will be until the current time.
• app_type - player. This parameter is optional, if missing, both Builder and Player security logs will be retrieved. 

Response

Error responses:

• 401 - Unauthorized - usually due to missing or wrong API key.
• 500 - Nonspecific error - this can happen due to various server-related issues.
• 400 - Bad request - this can happen due to missing start_time, bad time format, or invalid app_type.
• 408 - Request timeout - a request limited to 55 seconds. If reaching the timeout, an option is to change start_time and end_time to divide the request.

Success Response:

In case of success (200), the response will happen in streaming, returning chunks in each response divided into pages. 

Headers:

• Number-Of-Pages - the number of pages in the response. Each page will contain up to 10,000 security log entries.
• Number-Of-Results - the total number of results.

Response body example:

[
  {
    "pageNumber": <number of page>,
    "results": <number of results in page>,
    "securityLogs": [
      <securityLogJson>,
      <securityLogJson>,
      ...
    ]
  },
  {
    "pageNumber": <number of page>,
    "results": <number of results in page>,
    "securityLogs": [
      <securityLogJson>,
      <securityLogJson>,
      ...
    ]
  }
]

How to Use

Customer Settings Configuration:

• Choosing which events and which service to run

• Setting delivery method:
  • API Call Only - the Player will store the logs in a designated table and the logs can be retrieved through an API call.
  • API Call and Custom Service - the logs will be stored in the table and will be able to be retrieved through the API and also run a service each time a security log is stored.

Security Log Format - Player:

{
  "ecs": {
    "version": string
  },
  "@timestamp": string,
  "organization": {
    "name": string
  },
  "user_agent": {
    "os": {
      "browser_language": string,
      "browser_platform": string,
      "is_mobile_device": bool,
      "is_verified_bot": bool
    },
    "name": string,
    "device": {
      "name": string
    },
    "original": string
  },
  "os": {
    "family": string,
    "full": string
  },
  "client": {
    "ip": string
  },
  "event": {
    "action": string,
    "timezone": string
  },
  "geo": {
    "country_name": string,
    "region_name": string
  },
  "url": {
    "full": string,
    "domain": string
  },
  "service": {
    "environment": string
  },
  "label": {
    "app_type": string,
    "customer_id": string,
    "business_group": string,
    "business_group_id": string,
    "deploy_timestamp": string,
    "is_co_browsing_on": bool,
    "master_rid": string,
    "page_analytics_id": string,
    "page_index": string,
    "page_name": string,
    "process_id": string,
    "process_multi_language": string,
    "request_id": string,
    "rid": string,
    "role": string,
    "source_type": string,
    "source_value": string,
    "step_id": string,
    "step_index": string,
    "web_flow_name": string,
    "webflow_id": string,
    "player_version": string,
    "authentication_method": string,
    "authentication_status": string,
    "auth_action": string,
    "auth_page": string,
  }
}