Retrieves security event logs of the services that Cloud App Security protects.
GET https://<serviceURL>/v1/siem/security_events
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:
|
event |
Type of the security event whose logs you want to retrieve. Options include:
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:
|
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. |
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
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
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.
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" } } ] }
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.
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 |