Sign In with your
Trend Micro Account
Need Help?
Need More Help?

Create a technical support case if you need further support.

Trend Micro Cloud App Security SIEM API Solution

    • Updated:
    • 15 Oct 2018
    • Product/Version:
    • Cloud App Security All.All
    • Platform:
    • N/A N/A
Summary

Cloud App Security provides access to certain product service data through Cloud App Security Representational State Transfer (REST) Integration APIs allowing customers to integrate third-party applications and systems. Using these APIs may potentially expose sensitive information. Therefore, to ensure that only trusted applications can use the APIs, generate an authentication token that the trusted applications send with API requests. Cloud App Security verifies the validity of all API requests from third-party applications and systems using the token information and sends the requested data to them.

In this release, Cloud App Security supports only the SIEM API.

Details
Public

The SIEM API Features are listed below:

The SIEM API Transport level are:

  • HTTPS
  • Token Based Authentication
  • All request and response body are JSON formatted
  • All timestamps in the returned events and requests are in UTC
  • The maximum interval is three days.
  • Requests to the service may be throttled to prevent abuse

Cloud App Security get the information via: GET https://<hostname>/siem/v1/security_events

The hostname is subject to the site where your Cloud App Security service is hosted:

  • US site: api.tmcas.trendmicro.com
  • EU site: api-eu.tmcas.trendmicro.com
  • Japan site: api.tmcas.trendmicro.co.jp

Refer to the URL of your Cloud App Security management console to determine the applicable hostname.

Authentication Method

You should get the authentication token from the register API by CLP account and password. Every request will contain the authentication key. Below are the details:

  1. Manage Authentication Tokens.

    Manage Authentication Tokens

    Click image to enlarge.

    Customer can get the authenticate_token from the UI page. The Bearer token will belong to the OAuth 2.0 Authorization.

  2. Authentication

    Server will authenticate the identity by "Authorization".

    Set the header.

    Authentication

  3. Throttle.

    Each customer just have 10 queries in 1 minute, and a total of 14400 queries in one day.

Standard Responses

The table below provides the list of standard responses.

CodeMessageScenarios
200SuccessThe request has been handled and returned in the response body. Inthe case of a JSON format, the structure is always returned, even if empty.
400BadRequest The request is missing a mandatory "request" parameter, a parameter contains data which is incorrectly formatted.
401UnauthorizedThere is no authorization information included in the request, the authorization information is incorrect, or the user is not authorized.
404Not FoundThe request API is not supported.
405Method Not AllowedThe request API method is not supported.
429Too Many RequestsThe user has made too many requests over the past 1 minute or 24 hours and has been throttled.
500Internal Server ErrorThe service has encountered an unexpected situation and is unable to give a better response to the request.

If the response is not 200, the detailed reason for the error message will be listed in json format.

Example response

HTTP/1.1 400 Bad Request

Content-Type: application/json

{

"code": -4000001,

"traceId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",

"msg": "error message for debugging"

}

Request Parameters

The table below provides the description for each request parameters

FieldDescription
service[must] The service which you want to select (exchange, sharepoint, onedrive, dropbox, googledrive, box, huntingplatform and so on). The service parameter just support one service type per request.
event[must] The event type which you want to (dlp, virtualanalyzer, securityrisk, ransomware, Intelligencealert and so on). The event parameter just support parameterone event type per request.
start[optional] .DateTime(ISO8601 Timestamp). If you don't set the start and end time, it will return the last 5 mintues events.
end[optional] .DateTime(ISO8601 Timestamp). If you don't set the start and end time, it will return the last 5 mintues events.
limit[optional] The page size (default is 200). The maximum value is 200

Response Data Structure

Below is an example of the response data structure:

{

"selfLink": "https://api.tmcas.trendmicro.com/siem/v1/security_events?

service=exchange&event=dlp&start=XXXXX",

"nextLink": "",

"securityEvents": [

{

"service": "exchange",

"event": "dlp",

"message": {

"file_name": "Mail Body",

"location":

"username1@example1.onmicrosoft.com\\Inbox", "mail_message_id": "

<XXXXXXX.outlook.com>",

"mail_message_sender": ["

<username1@example1.onmicrosoft.com.onmicrosoft.com>"], "mail_message_recipient": [

"\" username2\"< username2@example2.onmicrosoft.com >"

],

"mail_message_subject": "test dlp ",

"mail_message_delivery_time": "2016-07-22T01:51:28",

"mail_message_submit_time": "2016-07-22T01:51:31",

"triggered_policy_name": "Default Exchange Policy DLP",

"triggered_security_filter": "Data Loss Prevention",

"detection_time": "2016-07-22T01:51:31",

"violator": " username2@example2.onmicrosoft.com ",

"triggered_dlp_template": [],

"violating_content": "",

"action": "Pass",

"action_result": "Successful"

}

}

]

}

Response Description

The table below provides information about the different field and data types.

FieldData TypeDescription
data/serviceStringthe security_event message service. (exchange, sharepoint, onedrive, dropbox, googledrive, box, huntingplatform and so on)
data/eventStringthe security_event message event. (dlp, virtualanalyzer, securityrisk, ransomware, intelligence alert and so on)
data/messageJSON Structurethesecurity_event message content.
data/message/file_nameStringfile name triggered security policy in the security_event message
data/message/locationStringfile path for this file. It can be used to find the message location.
data/message/mail_message_idStringmessage id in the security_event message for mail. It can be used to find the mail which triggered security policy.
data/message/mail_message_senderArraymail senders in the message.
data/message/mail_message_recipientArraymail recipients in the message.
data/message/mail_message_subjectStringmail subject in the message.
data/message/mail_message_delivery_timeDateTime(ISO8601 Timestamp)mail delivery time in the message.
data/message/mail_message_submit_timeDateTime(ISO8601Timestamp)mail submit time in the message.
data/message/triggered_policy_nameStringtriggered policy name in Cloud App Security configuration
data/message/triggered_security_filterStringtriggered security filter in Cloud App Security configuration
data/message/detection_timeDateTime(ISO8601Timestamp)triggered security filter in Cloud App Security configuration
data/message/violatorStringviolator in the message.
data/message/triggered_dlp_templateArraythe Data Loss Prevention template this event triggered.
data/message/violating_contentStringthe violating content in this event.
data/message/actionStringaction for this event.
data/message/action_resultStringaction result for this event.
Premium
Internal
Rating:
Category:
SPEC
Solution Id:
1121249
Feedback
Did this article help you?

Thank you for your feedback!

To help us improve the quality of this article, please leave your email here so we can clarify further your feedback, if neccessary:
We will not send you spam or share your email address.

*This form is automated system. General questions, technical, sales, and product-related issues submitted through this form will not be answered.

If you need additional help, you may try to contact the support team. Contact Support

To help us improve the quality of this article, please leave your email here so we can clarify further your feedback, if neccessary:
We will not send you spam or share your email address.

*This form is automated system. General questions, technical, sales, and product-related issues submitted through this form will not be answered.