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