Sweeping für E-Mail-Nachrichten | Trend Micro Service Central

Ansichten:

Durchsucht E-Mail-Nachrichten in geschützten Cloud App Security-Postfächern für diejenigen, die Suchkriterien für Meta-Informationen erfüllen.

HTTPS-Anforderung

GET https://<serviceURL>/v1/sweeping/mails

Anforderungsparameter

Parameter	Beschreibung
`mailbox`	E-Mail-Adresse des Postfachs, in dem gesucht werden soll Geben Sie eine vollständige E-Mail-Adresse ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel: user@example.com or user@example.com
`lastndays`	Anzahl der Tage (n × 24 Stunden) vor dem Zeitpunkt des Absendens der Anforderung, in denen E-Mail-Nachrichten gesucht werden sollen Cloud App Security speichert die Meta-Informationen von E-Mail-Nachrichten in jedem Postfach für 90 Tage. Konfigurieren Sie `lastndays` und `start`/`end` nicht gleichzeitig.
`start` `end`	Start- und Endzeit, während der die E-Mail-Nachricht durchsucht werden soll. Format: ISO 8601-Zeitstempel auf die Sekunde oder Millisekunde in UTC, yyyy-mm-ddThh: mm: SS[.MMM] Z. Zum Beispiel `2016-07-22T01:51:31Z` oder `2016-07-22T01:51:31.001Z`. Cloud App Security speichert die Meta-Informationen von E-Mail-Nachrichten 90 Tage lang. Die Anforderung durchsucht E-Mail-Nachrichten gemäß den `start`- und `end`-Einstellungen: Wenn sowohl `start` als auch `end` nicht angegeben sind, werden E-Mail-Nachrichten innerhalb von sieben Tagen (7 × 24 Stunden) vor dem Zeitpunkt des Absendens der Anforderung durchsucht. Wenn sowohl `start` als auch `end` angegeben sind, durchsucht die Anforderung E-Mail-Nachrichten innerhalb der konfigurierten Dauer. Stellen Sie sicher, dass die Endzeit (end) nicht vor der Startzeit (start) liegt. Wenn nur `start` angegeben ist, durchsucht die Anforderung E-Mail-Nachrichten innerhalb von sieben Tagen (7 × 24 Stunden) nach dem Zeitpunkt der konfigurierten start-Zeit. Wenn nur `end` angegeben wird, durchsucht die Anforderung E-Mail-Nachrichten innerhalb von sieben Tagen (7 × 24 Stunden) vor dem Zeitpunkt des konfigurierten Werts für end. Konfigurieren Sie `lastndays` und `start`/`end` nicht gleichzeitig.
`subject`	Betreff von E-Mail-Nachrichten, nach denen gesucht werden soll Um nach einem genauen Ausdruck zu suchen, z. B. `example1 example2`, schließen Sie den Wert in doppelte Anführungszeichen "example1 example2" ein. Andernfalls führt Cloud App Security einen partiellen Abgleich auf Grundlage des Ausdrucks durch. Beispiel 1: Wenn Sie den Wert auf `example1 example2` festlegen, sucht Cloud App Security nach E-Mail-Nachrichten, deren Betreff `example1`, `example2` oder `example1 example2` enthält. Beispiel 2: Wenn Sie den Wert auf `example1_example2-example3.txt_as_body` festlegen, sucht Cloud App Security nach E-Mail-Nachrichten, deren Betreff `example1_example2`, `example3`, `txt_as_body` oder `example1_example2-example3.txt_as_body` enthält.
`file_sha1`	SHA-1-Hash-Wert des zu suchenden Dateianhangs Cloud App Security verwendet die exakte Übereinstimmung. Geben Sie einen vollständigen und gültigen SHA-1-Hash-Wert ein.
`file_sha256`	SHA-256-Hash-Wert des zu suchenden Dateianhangs Cloud App Security verwendet die exakte Übereinstimmung. Geben Sie einen vollständigen und gültigen SHA-256-Hash-Wert ein.
`file_name`	Name des zu suchenden Dateianhangs Geben Sie den Dateinamen für die Suche mit oder ohne Dateierweiterung ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel: Be*ispiel
`file_extension`	Dateinamenerweiterung der zu suchenden Dateianhänge Geben Sie die Dateinamenerweiterung ein, nach der Sie suchen möchten, ohne einen Punkt "." ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel: do*
`url`	URL im E-Mail-Text oder in Anhängen, nach der gesucht werden soll Geben Sie die genaue URL ein, nach der Sie suchen möchten. Cloud App Security extrahiert den normalisierten URL-Teil aus der URL, d. h. Hostname + Pfad, um E-Mail-Nachrichten zu suchen und anzuzeigen, die eine beliebige URL enthalten, die mit diesem Teil übereinstimmt. Wenn Sie beispielsweise nach E-Mail-Nachrichten suchen möchten, die die URL `https://example.com/path?option 1` enthalten, verwendet Cloud App Security example.com/path als Suchkriterium und zeigt in der Antwort nicht nur die E-Mail-Nachrichten an, die https://example.com/path?option 1 enthalten, sondern auch diejenigen, die https://example.com/path?option 2 enthalten.
`sender`	Absender-E-Mail-Adresse der zu suchenden E-Mail-Nachrichten Geben Sie eine vollständige E-Mail-Adresse ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel: u*ser@example.com
`recipient`	E-Mail-Adresse des Empfängers der zu suchenden E-Mail-Nachrichten Geben Sie eine vollständige E-Mail-Adresse ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel: u*ser@example.com
`message_id`	Internet-Nachrichten-ID der zu suchenden E-Mail-Nachricht Sie kann über die Microsoft Graph-API oder die EWS-API bezogen werden.
`source_ip`	IP-Quelladresse der zu suchenden E-Mail-Nachrichten Eine IP-Adresse mit oder ohne Subnetzmaske wird unterstützt. Beispiel: xx.yy.zz.ww oder xx.yy.zz.ww/16
`source_domain`	Quelldomäne der zu suchenden E-Mail-Nachrichten Geben Sie einen vollständigen Domänennamen ein. Ein Platzhalter ohne Präfix wird unterstützt. Beispiel:ex*ample.com
`limit`	Anzahl der E-Mail-Nachrichten, deren Meta-Informationen gleichzeitig angezeigt werden sollen. Es sind maximal 1.000 E-Mail-Nachrichten zulässig. Falls nicht angegeben, wird der Wert standardmäßig auf 20 festgelegt. Wenn die Anzahl der angeforderten E-Mail-Nachrichten den angegebenen Grenzwert überschreitet, wird im Feld next_link in der Antwort eine URL angegeben. Verwenden Sie diese URL, um eine zweite Anforderung zum Abrufen von Meta-Informationen der verbleibenden E-Mail-Nachrichten für die vorherige Anforderung durchzuführen. Wiederholen Sie diese Schritte, bis alle Informationen für die erste Anforderung abgerufen wurden.

Beispiel anfordern

Beispiel 1: Suchen Sie nach E-Mail-Nachrichten im Postfach user@example.com, die von 2019-02-12 01:51:31.001 bis 2019-03-12 01:51:31.001 (UTC) empfangen wurden

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?mailbox=user1@example1.com&
     start=2019-02-12T01:51:31.001Z&end=2019-03-12T01:51:31.001Z
     Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Beispiel 2: Suchen Sie nach E-Mail-Nachrichten mit dem Betreff, der den Ausdruck wire transfer (Überweisung) enthält und die innerhalb von zwei Tagen ab dem Zeitpunkt eingehen, an dem die Anforderung gesendet wird, wobei die Anzahl der gleichzeitig anzuzeigenden Nachrichten 10 beträgt

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject="wire transfer"&lastndays=2&limit=10
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Wenn die Gesamtzahl der angeforderten E-Mail-Nachrichten 10 überschreitet, verwenden Sie die URL im Feld next_link in der Antwort, um eine zweite Anforderung durchzuführen:

GET https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject="wire transfer"&lastndays=2&limit=10&
     skipToken=<randomly generated value>=
     Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Antwort

Bei Erfolg sendet der Dienst eine HTTP 200-Antwort zurück und gibt einen Antworttext im JSON-Format zurück; andernfalls sendet der Dienst eine Fehlermeldung im JSON-Format mit Fehlerdetails zurück. Weitere Informationen zu Fehlern finden Sie unter API-Antworten.

Antwortbeispiel

HTTP/1.1 200
Content-Type: application/json

{
    "current_Link": "https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject=test&start=2019-02-12T01:51:31.001Z&
     end=2019-12-12T01:51:31.001Z&limit=1",
    "next_Link": "https://api.tmcas.trendmicro.com/v1/sweeping/mails?subject=test&start=2019-02-12T01:51:31.001Z&
     end=2019-12-12T01:51:31.001Z&limit=1&skipToken=<randomly generated value>=",
    "value": [
        {
            "mail_attachments": [
                {
                    "file_sha1": "34924b49e416befd1106cad406d413e6e4a89577",
                    "file_sha256": "0bfc7d5fc0c7da4cd974c24676a97a5c8796689aaf40a978021554177d4ebf8e",
                    "file_name": "test.txt"
                 }
            ],
            "mail_message_subject": "test sample",
            "mail_urls": [
                "http://www.google.com"
                ],
            "mail_message_id": "<BL0PR01MB4178833793C138CE3414D53B777A0@BL0PR01MB4178.prod.example.com>",
            "mail_unique_id": "AAMkAGRhODQyZDAzLWNmNjEtNDY2OS1iOWM3LWVmODUxMDk7ZjE1ZgBGAAAAAAABcyFCsOdnTo
             hKgA0TJdjUBwAYbtU+cD0jRZmfu0kuMtvEAAAAAAEMAAAYbtU+cD0jRZmfu7kuMtvEAAF/JGRaAAA=",
            "mailbox": "user2@example2.com",
            "source_ip": "xx.yy.zz.ww",
            "mail_message_sender": "user3@example3.com",
            "mail_internet_headers": [
                {
                    "Value": "user3@example3.com",
                    "HeaderName": "Return-Path"
                }
            ],
            "mail_message_recipient": [
                "user2@example2.com"
            ],
            "source_domain": "example3.com",
            "mail_message_delivery_time": "2019-02-25T08:42:45.000Z",
            "org_id": "c2859385-35b4-4cc9-a402-b6f0513db0c9",
            "service": "exchange"
        }
    ]
}

Antwortfelder

In der folgenden Tabelle werden die verfügbaren Felder für den Antworttext beschrieben.

Anmerkung:

Alle zeitbezogenen Felder in der Tabelle sind auf Coordinated Universal Time (UTC) eingestellt.

Feld	Datentyp	Beschreibung
`current_link`	Zeichenfolge	URL in der aktuellen Anforderung
`next_link`	Zeichenfolge	URL für die Nachverfolgungsanforderung, wenn die angeforderten E-Mail-Nachrichten die festgelegte Grenze für die gleichzeitige Anzeige überschreiten. Verwenden Sie diese URL, um eine zweite Anforderung zum Abrufen von Meta-Informationen der verbleibenden E-Mail-Nachrichten für die vorherige Anforderung durchzuführen. Wiederholen Sie diese Schritte, bis alle Informationen für die erste Anforderung abgerufen wurden.
`value`	JSON-Array	Details zu jeder gefundenen E-Mail-Nachricht
`mail_attachments`	JSON-Array	Informationen über jeden Dateianhang in der E-Mail-Nachricht
`mail_attachments/file_sha1`	Zeichenfolge	SHA-1-Hash-Wert des Dateianhangs
`mail_attachments/file_sha256`	Zeichenfolge	SHA-256-Hash-Wert des Dateianhangs
`mail_attachments/file_name`	Zeichenfolge	Name des Dateianhangs
`mail_message_subject`	Zeichenfolge	Betreff der E-Mail-Nachricht
`mail_urls`	Zeichenfolge	Im E-Mail-Text oder Anhang enthaltene URL(s)
`mail_message_id`	Zeichenfolge	Internet-Nachrichten-ID der E-Mail-Nachricht
`mail_unique_id`	Zeichenfolge	Eindeutige ID der E-Mail-Nachricht
`mailbox`	Zeichenfolge	Postfach, in dem die E-Mail-Nachricht angezeigt wird
`source_ip`	Zeichenfolge	IP-Quelladresse der E-Mail-Nachricht
`mail_message_sender`	Zeichenfolge	Sender-E-Mail-Adresse der E-Mail-Nachricht
`mail_internet_headers`	JSON-Array	Informationen über den Internet-Header der E-Mail-Nachricht
`mail_internet_headers/Value`	Zeichenfolge	Sender-E-Mail-Adresse der E-Mail-Nachricht
`mail_internet_headers/HeaderName`	Zeichenfolge	Internet-Header-Name der E-Mail-Adresse
`mail_message_recipient`	JSON-Array	Eine Liste der Empfänger-E-Mail-Adressen der E-Mail-Nachricht
`source_domain`	Zeichenfolge	Quelldomäne der E-Mail-Nachricht
`mail_message_delivery_time`	ISO 8601-Zeitstempel	Datum und Uhrzeit der gesendeten E-Mail-Nachricht
`org_id`	Zeichenfolge	ID zur Identifikation der Organisation, in der der Cloud-Anwendungs-Mandant der E-Mail-Nachricht bereitgestellt wird
`service`	Zeichenfolge	Name des geschützten Diensts Der Wert ist exchange oder gmail.