Get Security Logs

Retrieves security event logs of the services that Cloud App Security protects.

HTTPS Request

GET https://<serviceURL>/v1/siem/security_events

Request Parameters

Important:

The request must contain the required parameters.

Parameter

Description

Required Parameter

service

Name of the protected service whose logs you want to retrieve.

Important:

Specify one service at a time.

Options include:

  • exchange

    Note:

    This option covers only Exchange Online related logs.

  • sharepoint

  • onedrive

  • dropbox

  • box

  • googledrive

  • gmail

  • teams

  • exchangeserver

    Note:

    This option covers Exchange Server related logs from ScanMail for Microsoft Exchange after your ScanMail server is registered to Cloud App Security.

  • salesforce_sandbox

  • salesforce_production

  • teams_chat

event

Type of the security event whose logs you want to retrieve. Options include:

  • securityrisk

  • virtualanalyzer

  • ransomware

  • dlp

Important:

Specify one event type at a time.

Optional Parameter

start

end

Start and end time during which logs are to retrieve. Format: ISO 8601 timestamp to the second or millisecond in UTC, yyyy-mm-ddThh:mm:ss[.mmm]Z. For example, 2016-07-22T01:51:31Z or 2016-07-22T01:51:31.001Z.

The request retrieves logs within a maximum of 72 hours before the point of time when the request is sent according to the start and end settings:

  • If both start and end are not specified, the request retrieves logs within five minutes before the point of time when the request is sent.

  • If both start and end are specified, the request retrieves logs within the configured duration. Make sure the end time is no earlier than the start time.

  • If only start is specified, the request retrieves logs within five minutes after the point of the configured start time.

  • If only end is specified, the request retrieves logs within five minutes before the point of the configured end time.

limit

Number of log items to display at a time. A maximum of 500 log items are allowed.

If not specified, the value is set to 500 by default.

If the total log items requested exceed the specified limit, a URL is provided in the next_link field in the response. Use this URL to form a second request to retrieve the remaining log items for the previous request. Repeat this until all log items for the first request are obtained.

Request Example

Example 1: retrieve all Data Loss Prevention logs of Exchange Online within five minutes before the point of time when the request is sent
GET https://api.tmcas.trendmicro.com/v1/siem/security_events?service=exchange&event=dlp
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Example 2: retrieve Security Risk Scan logs of Exchange Online from 2018-09-23 03:35:07.000 to 2018-09-25 05:47:07:000 (UTC), with the number of log items to display at a time being 10

  • GET https://api.tmcas.trendmicro.com/v1/siem/security_events?service=exchange&event=securityrisk&
    start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=10
    Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77
  • If the total log items requested exceed 10, use the URL in the next_link field in the response to form a second request as:
    GET https://api.tmcas.trendmicro.com/v1/siem/security_events?service=exchange&event=securityrisk&
    start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=10&page_id=<randomly generated value>=
    Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Response

On success, the service sends back an HTTP 200 response and returns a response body in JSON format; otherwise, the service sends back an error message in JSON format with error details. For more information about errors, see API Responses.

Response Example

HTTP/1.1 200
Content-Type: application/json

{
    "current_link": "https://api.tmcas.trendmicro.com/v1/siem/security_events?service=exchange&event=securityrisk&
     start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=1",
    "next_link": "https://api.tmcas.trendmicro.com/v1/siem/security_events?service=exchange&event=securityrisk&
     start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=1&page_id=<randomly generated value>=",
    "last_log_item_generation_time": "2018-09-25T02:14:40Z",
    "security_events": [
        {
            "log_item_id": "NdGBDmYBWu4z8GKN0Jhl",
            "service": "exchange",
            "event": "security_risk_scan",
            "message": {
                "scan_type": "Real-time scan",
                "affected_user": "username1@example1.onmicrosoft.com",
                "location": "username1@example1.onmicrosoft.com\\Junk Email",
                "detection_time": "2018-09-25T02:14:40Z",
                "triggered_policy_name": "phishing test from jimmy",
                "triggered_security_filter": "Web Reputation",
                "action": "Quarantine",
                "action_result": "success",
                "mail_message_id": "<0ee59974fb7c48538b3e077f5c40b877@trendmicro.com>",
                "mail_message_sender": "<username2@example2.com>",
                "mail_message_recipient": [
                    "\"username1\"<username1@example1.onmicrosoft.com>"
                ],
                "mail_message_submit_time": "2018-09-25T02:14:25.818Z",
                "mail_message_delivery_time": "2018-09-25T02:14:24",
                "mail_message_subject": "aaaa",
                "mail_message_file_name": "filename.exe",
                "security_risk_name": "Spyware: http://wrs21.winshipway.com",
                "detected_by": "Web Reputation",
                "risk_level": "Dangerous"
            }
        }
    ]
}

Response Fields

The following table describes the available fields for the response body. For more information about security event related fields, see Logs and Reports in the Cloud App Security Online Help.

Note:

All time-related fields in the table are set to Coordinated Universal Time (UTC).

Field

Data Type

Description

current_link

String

URL in the current request

next_link

String

URL for the follow-up request if the requested logs exceed the specified limit to display at a time. Use this URL to form a second request to retrieve the remaining log items for the previous request. Repeat this until all log items for the first request are obtained.

last_log_item_generation_time

ISO 8601 timestamp

Date and time when the last log item in the current request was generated, that is, the detection_time of the last log item in the current request

security_events

JSON array

Details of the requested security event log items

security_events/log_item_id

String

ID that uniquely identifies a log item

security_events/service

String

Name of the requested service

security_events/event

String

Type of the requested security event

security_events/message

JSON object

Details of one security event log item

Common fields in "message"

security_events/message/scan_type

String

Whether it is a real-time scan or manual scan that detected the security event

security_events/message/affected_user

String

Mailbox that received an email message triggering the security event, or user account that uploaded or modified a file triggering the security event

security_events/message/location

String

Location where the security event was detected

security_events/message/detection_time

ISO 8601 timestamp

Date and time when the security event was detected

security_events/message/triggered_policy_name

String

Name of a configured policy that was violated

security_events/message/triggered_security_filter

String

Name of the security filter that detected the security event

security_events/message/action

String

Action that Cloud App Security took after detecting the security event

security_events/message/action_result

String

Whether the action was successfully taken or not

Email related fields in "message"

security_events/message/mail_message_id

String

ID of the email message that triggered the security event

security_events/message/mail_message_sender

String

Email address of the sender

security_events/message/mail_message_recipient

Array

Email address(es) of the recipient(s)

security_events/message/mail_message_submit_time

ISO 8601 timestamp

Date and time when the email message triggering the security event was received

security_events/message/mail_message_delivery_time

ISO 8601 timestamp

Date and time when the email message triggering the security event was sent

security_events/message/mail_message_subject

String

Subject of the email message that triggered the security event

security_events/message/mail_message_file_name

String

Name of the email attachment that triggered the security event

File related fields in "message"

security_events/message/file_name

String

Name of the file that triggered the security event

security_events/message/file_upload_time

ISO 8601 timestamp

Date and time when the file triggering the security event was uploaded

Log type related fields in "message"

Security Risk Scan

security_events/message/security_risk_name

String

Name of the security risk detected

security_events/message/detected_by

String

Technology or method through which the email message or file triggering the security event was detected

security_events/message/risk_level

String

Web Reputation risk level assigned to the analyzed URL that triggered the security event

security_events/message/file_sha1

String

SHA-1 hash value of the file that triggered the security event

security_events/message/file_sha256

String

SHA-256 hash value of the file that triggered the security event

Virtual Analyzer

security_events/message/virus_name

String

Name of the virus detected

security_events/message/file_sha1

String

SHA-1 hash value of the file that triggered the security event

security_events/message/risk_level

String

Virtual Analyzer risk level assigned to the analyzed object that triggered the security event

security_events/message/detection_type

String

Type of the suspicious object that triggered the security event

security_events/message/file_sha256

String

SHA-256 hash value of the file that triggered the security event

security_events/message/va_report_link

String

Link for the summary report generated by Virtual Analyzer.

This field is returned only when the value of the risk_level field is High Risk, Medium Risk, or Low Risk.

To get the report, you need to use the report ID in this link to invoke the Get Virtual Analyzer Report API. For details, see Get Virtual Analyzer Report.

Ransomware

security_events/message/ransomware_name

String

Name of the ransomware detected

Data Loss Prevention

security_events/message/triggered_dlp_template

Array

Details of the compliance template that was violated to trigger the security event