Views:
Retrieves quarantine events of the services that Cloud App Security protects.

HTTPS Request

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

Request Parameters

Important
Important
The request must contain the required parameters.
Parameter
Description
Required Parameter
service
Name of the protected service whose quarantine events you want to retrieve.
Currently, the value must be exchange.
Optional Parameter
start
end
Start and end time during which quarantine events 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 quarantine evens within a maximum of 7 days 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 quarantine events within one day before the point of time when the request is sent.
  • If both start and end are specified, the request retrieves quarantine events within the configured duration. Make sure the end time is no earlier than the start time.
  • If only start is specified, the request retrieves quarantine events within one day after the point of the configured start time.
  • If only end is specified, the request retrieves quarantine events within one day before the point of the configured end time.
limit
Number of quarantine events to display at a time. A maximum of 500 quarantine events are allowed.
If not specified, the value is set to 500 by default.
If the total quarantine events 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 quarantine events for the previous request. Repeat this until all quarantine events for the first request are obtained.

Request Example

Example 1: retrieve all quarantine events of Exchange Online within five minutes before the point of time when the request is sent
GET https://api.tmcas.trendmicro.com/v1/siem/quarantine_events?service=exchange
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafed4
Example 2: retrieve quarantine events of Exchange Online from 2018-09-23 03:35:07.000 to 2018-09-25 05:47:07:000 (UTC), with the number of events to display at a time being 10
  • GET https://api.tmcas.trendmicro.com/v1/siem/quarantine_events?service=exchange&
    start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=10
    Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafed4
  • If the total quarantine events 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/quarantine_events?service=exchange&
    start=2018-09-23T03:35:07.000Z&end=2018-09-25T05:47:07.000Z&limit=10&page_id=<randomly generated value>=
    Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafed4

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

{
  "traceId": "ff20f32e-3bb2-4102-84d1-62f92c415901",
  "current_link": "https://api.tmcas.trendmicro.com/v1/siem/quarantine_events?service=exchange",
  "next_link": "",
  "last_log_item_generation_time": "2021-10-26T01:48:36.687Z",
  "quarantine_events": [
    {
      "service": "Exchange Online",
      "message": {
        "affected_user": "username@example.com",
        "mailbox": "username@example.com",
        "detection_time": "2021-10-25T09:51:26.697Z",
        "mail_unique_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AJUMWJ_w_F0WJ1OxbHWzuuAABMEsyEwAA",
        "mail_log_id": "1d9f27ea-3579-11ec-8159-00224809f763",
        "mail_message_id": "<HK0PR02MB3698C584C7E6844016D0455C98839@HK0PR02MB3698.apcprd02.prod.outlook.com>",
        "mail_message_delivery_time": "2021-10-25T09:51:00.000Z",
        "mail_message_sender": "username@example.com",
        "mail_message_recipient": [
          "castest2@ewdevnew.onmicrosoft.com"
        ],
        "mail_message_subject": "FW: mitigation restore test  1025 1009",
        "mail_status": "Quarantined",
        "location": "username@example.com\\Sent Items",
        "mail_quarantine_type": "Quarantine",
        "triggered_security_filter": "File Blocking",
        "security_risk_name": "mitigation",
        "threat_type": "Phishing"
      }
    },
    {
      "service": "Exchange Online",
      "message": {
        "affected_user": "username@example.com",
        "mailbox": "username@example.com",
        "detection_time": "2021-10-26T01:48:36.687Z",
        "mail_unique_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AJUMWJ_w_F0WJ1OxbHWzuuAABMEt6hwAA",
        "mail_log_id": "d485296b-35fe-11ec-8159-00224803dc63",
        "mail_message_id": "<HK0PR02LK36982A5C844MD294E01BCFE198849@skzafjdshlmjdls.fdsafda.prod.outlook.com>",
        "mail_message_delivery_time": "2021-10-26T01:48:00.000Z",
        "mail_message_sender": "username@example.com",
        "mail_message_recipient": [
          "castest2@ewdevnew.onmicrosoft.com"
        ],
        "mail_message_subject": "FW: mitigation restore test  1026 0948",
        "mail_status": "Quarantined",
        "location": "username@example.com\\Sent Items",
        "mail_quarantine_type": "Quarantine",
        "triggered_security_filter": "File Blocking",
        "security_risk_name": "mitigation",
        "threat_type": "Phishing"
      }
    }
  ]
}

Response Fields

The following table describes the available fields for the response body. For more information about quarantine event related fields, see Quarantine 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 quarantine events exceed the specified limit to display at a time. Use this URL to form a second request to retrieve the remaining quarantine events for the previous request. Repeat this until all quarantine events for the first request are obtained.
last_log_item_generation_time
ISO 8601 timestamp
Date and time when the last quarantine event in the current request was generated, that is, the detection_time of the last quarantine event in the current request
quarantine_events
JSON array
Details of the requested quarantine event
quarantine_events/service
String
Name of the requested service
quarantine_events/message
JSON array
Details of one quarantine event
quarantine_events/message/affected_user
String
Mailbox that received an email message triggering the quarantine event, or user account that uploaded or modified a file triggering the quarantine event
quarantine_events/message/mailbox
String
Email address of an email message
quarantine_events/message/detection_time
ISO 8601 timestamp
Date and time when the quarantine event is detected
quarantine_events/message/mail_unique_id
String
Unique ID of an email message
quarantine_events/message/mail_log_id
String
ID that uniquely identifies a quarantine event
quarantine_events/message/mail_message_id
String
ID of the email message that triggered the quarantine event
quarantine_events/message/mail_message_delivery_time
ISO 8601 timestamp
Date and time when the email message was sent
quarantine_events/message/mail_message_sender
String
Email address of the sender
quarantine_events/message/mail_message_recipient
Array
Email address(es) of the recipient(s)
quarantine_events/message/mail_message_subject
String
Subject of the email message that triggered the quarantine event
quarantine_events/message/action_source
String
Indicates that the email message is quarantined through the Mitigation API. The value is API.
quarantine_events/message/mail_status
String
Email status
quarantine_events/message/location
String
Location where the quarantine event was detected
quarantine_events/message/triggered_security_filter
String
Name of the security filter that detected the security event
quarantine_events/message/security_risk_name
String
Name of the security risk detected
quarantine_events/message/mail_quarantine_type
String
The value is quarantine.
quarantine_events/message/threat_type
String
Threat type detected in the security event