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

HTTPS Request

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

Request Parameters

Important
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
Important
Specify one service at a time.
Options include:
  • exchange
    Note
    Note
    This option covers logs related to both Exchange Online and Exchange Online (Inline Mode).
  • sharepoint
  • onedrive
  • dropbox
  • box
  • googledrive
  • gmail
  • teams
  • exchangeserver
    Note
    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
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 Online",
            "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",
                "threat_type": "Phishing",
                "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
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
The value options are as follows:
  • Exchange Online
  • Exchange Online (Inline Mode)
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
security_events/message/threat_type
String
Threat type detected in the security event
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
Array
Email address(es) of the recipient(s)
security_events/message/mail_message_recipientsecurity_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
Note
Note
This field is not available for Exchange Online (Inline Mode).
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
security_events/message/mail_message_envelope_sender
String
Message envelope sender
Note
Note
This field is available only for Exchange Online (Inline Mode).
security_events/message/mail_message_direction
String
Mail direction, indicating whether the email is inbound or outbound message
Note
Note
This field is available only for Exchange Online (Inline Mode).
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
Related information