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:
- 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.
- Authentication
Server will authenticate the identity by "Authorization".
Set the header.
- 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.
| Code | Message | Scenarios |
|---|---|---|
| 200 | Success | The request has been handled and returned in the response body. Inthe case of a JSON format, the structure is always returned, even if empty. |
| 400 | Bad | Request The request is missing a mandatory "request" parameter, a parameter contains data which is incorrectly formatted. |
| 401 | Unauthorized | There is no authorization information included in the request, the authorization information is incorrect, or the user is not authorized. |
| 404 | Not Found | The request API is not supported. |
| 405 | Method Not Allowed | The request API method is not supported. |
| 429 | Too Many Requests | The user has made too many requests over the past 1 minute or 24 hours and has been throttled. |
| 500 | Internal Server Error | The 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
| Field | Description |
|---|---|
| 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.
| Field | Data Type | Description |
|---|---|---|
| data/service | String | the security_event message service. (exchange, sharepoint, onedrive, dropbox, googledrive, box, huntingplatform and so on) |
| data/event | String | the security_event message event. (dlp, virtualanalyzer, securityrisk, ransomware, intelligence alert and so on) |
| data/message | JSON Structure | thesecurity_event message content. |
| data/message/file_name | String | file name triggered security policy in the security_event message |
| data/message/location | String | file path for this file. It can be used to find the message location. |
| data/message/mail_message_id | String | message id in the security_event message for mail. It can be used to find the mail which triggered security policy. |
| data/message/mail_message_sender | Array | mail senders in the message. |
| data/message/mail_message_recipient | Array | mail recipients in the message. |
| data/message/mail_message_subject | String | mail subject in the message. |
| data/message/mail_message_delivery_time | DateTime(ISO8601 Timestamp) | mail delivery time in the message. |
| data/message/mail_message_submit_time | DateTime(ISO8601Timestamp) | mail submit time in the message. |
| data/message/triggered_policy_name | String | triggered policy name in Cloud App Security configuration |
| data/message/triggered_security_filter | String | triggered security filter in Cloud App Security configuration |
| data/message/detection_time | DateTime(ISO8601Timestamp) | triggered security filter in Cloud App Security configuration |
| data/message/violator | String | violator in the message. |
| data/message/triggered_dlp_template | Array | the Data Loss Prevention template this event triggered. |
| data/message/violating_content | String | the violating content in this event. |
| data/message/action | String | action for this event. |
| data/message/action_result | String | action result for this event. |