diff --git a/Packs/EWS/Classifiers/classifier-mapper-incoming-EWS_v2.json b/Packs/EWS/Classifiers/classifier-mapper-incoming-EWS_v2.json index 2941dec19a84..a0b6689c4787 100644 --- a/Packs/EWS/Classifiers/classifier-mapper-incoming-EWS_v2.json +++ b/Packs/EWS/Classifiers/classifier-mapper-incoming-EWS_v2.json @@ -181,8 +181,13 @@ "simple": "body" }, "Email Headers": { - "complex": null, - "simple": "headers" + "complex": { + "accessor": "", + "filters": [], + "root": " ", + "transformers": [] + }, + "simple": null }, "Email Message ID": { "complex": null, @@ -351,6 +356,10 @@ ] }, "simple": "" + }, + "Phishing Reporter Email Headers": { + "complex": null, + "simple": "headers" } } } diff --git a/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2.yml b/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2.yml new file mode 100644 index 000000000000..21ca066198fb --- /dev/null +++ b/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2.yml @@ -0,0 +1,307 @@ +id: Get Original Email - EWS v2 +version: -1 +contentitemexportablefields: + contentitemfields: {} +name: Get Original Email - EWS v2 +description: |- + This v2 playbook retrieves the original email in the thread as an eml file by using the EWS v2 integration. + This playbook will retrieve the email as an eml and not as an Email object (like the previous version). It also reduces the amount of tasks needed to perform the fetch action. + You must have the necessary permissions in the EWS integration to execute global search: eDiscovery. +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 5607d1c6-85b0-4181-8b10-bb3a5b113c6f + type: start + task: + id: 5607d1c6-85b0-4181-8b10-bb3a5b113c6f + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "1" + separatecontext: false + view: |- + { + "position": { + "x": 122.5, + "y": 280 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "1": + id: "1" + taskid: 43203523-8fe7-4403-8c1b-ba175d568d59 + type: condition + task: + id: 43203523-8fe7-4403-8c1b-ba175d568d59 + version: -1 + name: Is EWS v2 enabled? + description: Returns 'yes' if an integration brand is available. Otherwise returns + 'no'. + scriptName: IsIntegrationAvailable + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + "yes": + - "3" + scriptarguments: + brandname: + simple: EWS v2 + results: + - brandInstances + separatecontext: false + view: |- + { + "position": { + "x": 122.5, + "y": 430 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: d2eca123-db35-4b27-88d8-a8b77ffd6784 + type: title + task: + id: d2eca123-db35-4b27-88d8-a8b77ffd6784 + version: -1 + name: Done + type: title + iscommand: false + brand: "" + description: '' + separatecontext: false + view: |- + { + "position": { + "x": 122.5, + "y": 1570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 15ad973f-06c8-417d-8f63-9fcb9dfc7bef + type: condition + task: + id: 15ad973f-06c8-417d-8f63-9fcb9dfc7bef + version: -1 + name: Verify required inputs + description: Verifies that the required input values exist for retrieving the original + email. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + Inputs-Exist: + - "4" + separatecontext: false + conditions: + - label: Inputs-Exist + condition: + - - operator: isExists + left: + value: + complex: + root: inputs.TargetMailbox + iscontext: true + - - operator: isExists + left: + value: + complex: + root: inputs.MessageID + iscontext: true + view: |- + { + "position": { + "x": 122.5, + "y": 640 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: f5a63cbd-d9d6-49ca-8812-88c74426bb82 + type: regular + task: + id: f5a63cbd-d9d6-49ca-8812-88c74426bb82 + version: -1 + name: Search for messages by MessageID + description: Retrieves all messages found in the thread of the forwarded email. + script: EWS v2|||ews-search-mailbox + type: regular + iscommand: true + brand: EWS v2 + nexttasks: + '#none#': + - "5" + scriptarguments: + message-id: + complex: + root: inputs.MessageID + selected-fields: + simple: item_id + target-mailbox: + complex: + root: inputs.TargetMailbox + separatecontext: false + view: |- + { + "position": { + "x": 122.5, + "y": 885 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "5": + id: "5" + taskid: 2c433705-840b-4ad0-8214-ed8db8588d35 + type: condition + task: + id: 2c433705-840b-4ad0-8214-ed8db8588d35 + version: -1 + name: Was a matching email found? + description: Verifies that an email object with a Message-Id that matches the + InReplayTo ID of the forwarded email was found. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + "yes": + - "7" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: EWS.Items + accessor: itemId + iscontext: true + view: |- + { + "position": { + "x": 122.5, + "y": 1090 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "7": + id: "7" + taskid: 095d6baa-7a84-4f34-87d1-5b2d5a4287f2 + type: regular + task: + id: 095d6baa-7a84-4f34-87d1-5b2d5a4287f2 + version: -1 + name: Get original email as eml + description: Retrieves items by item ID and uploads the content as an eml file. + script: EWS v2|||ews-get-items-as-eml + type: regular + iscommand: true + brand: EWS v2 + nexttasks: + '#none#': + - "2" + scriptarguments: + item-id: + complex: + root: EWS.Items + accessor: itemId + target-mailbox: + complex: + root: inputs.TargetMailbox + separatecontext: false + view: |- + { + "position": { + "x": 122.5, + "y": 1360 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +system: true +view: |- + { + "linkLabelsPosition": {}, + "paper": { + "dimensions": { + "height": 1355, + "width": 380, + "x": 122.5, + "y": 280 + } + } + } +inputs: +- key: TargetMailbox + value: {} + required: false + description: The target mailbox for which to retrieve the eml file. + playbookInputQuery: +- key: MessageID + value: {} + required: false + description: The InReplyTo header in the forwarded email. + playbookInputQuery: +outputs: +- contextPath: File + description: The original email as an eml file. + type: string +tests: +- Get Original Email - EWS v2 - test +fromversion: 6.1.0 diff --git a/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2_README.md b/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2_README.md new file mode 100644 index 000000000000..43caf50917f2 --- /dev/null +++ b/Packs/EWS/Playbooks/playbook-Get_Original_Email_-_EWS_v2_README.md @@ -0,0 +1,38 @@ +This v2 playbook retrieves the original email in the thread as an eml file by using the EWS v2 integration. +This playbook will retrieve the email as an eml and not as an Email object (like the previous version). It also reduces the amount of tasks needed to perform the fetch action. +You must have the necessary permissions in the EWS integration to execute global search: eDiscovery. + +## Dependencies +This playbook uses the following sub-playbooks, integrations, and scripts. + +### Sub-playbooks +This playbook does not use any sub-playbooks. + +### Integrations +* EWS v2 + +### Scripts +* IsIntegrationAvailable + +### Commands +* ews-search-mailbox +* ews-get-items-as-eml + +## Playbook Inputs +--- + +| **Name** | **Description** | **Default Value** | **Required** | +| --- | --- | --- | --- | +| TargetMailbox | The target mailbox for which retrieve the eml file. | | Optional | +| MessageID | The InReplyTo header in the forwarded email. | | Optional | + +## Playbook Outputs +--- + +| **Path** | **Description** | **Type** | +| --- | --- | --- | +| File | The original email as an eml file. | string | + +## Playbook Image +--- +![Get Original Email - EWS v2](../doc_imgs/Get_Original_Email_-_EWS_v2.png) diff --git a/Packs/EWS/ReleaseNotes/1_10_0.md b/Packs/EWS/ReleaseNotes/1_10_0.md new file mode 100644 index 000000000000..071cf560af76 --- /dev/null +++ b/Packs/EWS/ReleaseNotes/1_10_0.md @@ -0,0 +1,13 @@ + +#### Mappers +##### EWS - Incoming Mapper +- Adding the "Phishing Reporter Email Headers" field. +- **BREAKING FIX**: Disassociate "Email Headers" field since it represents the original email headers and not the reporter headers. + +#### Playbooks +##### New: Get Original Email - EWS v2 +This v2 playbook retrieves the original email in the thread as an eml file, by using the EWS v2 integration. + +This playbook will retrieve the email as eml and not as an Email object (like the previous version). This version also reduces the amount of tasks needed to perform the fetch action. + +You must have the necessary permissions in the EWS integration to execute global search: eDiscovery. diff --git a/Packs/EWS/TestPlaybooks/playbook-Get_Original_Email_-_EWS_v2_-_test.yml b/Packs/EWS/TestPlaybooks/playbook-Get_Original_Email_-_EWS_v2_-_test.yml new file mode 100644 index 000000000000..917b19714df6 --- /dev/null +++ b/Packs/EWS/TestPlaybooks/playbook-Get_Original_Email_-_EWS_v2_-_test.yml @@ -0,0 +1,215 @@ +id: Get Original Email - EWS v2 - test +version: -1 +name: Get Original Email - EWS v2 - test +description: '"Get Original Email - EWS v2" test playbook.' +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 15d27661-5221-4106-81cb-1beb7ce1e7fd + type: start + task: + id: 15d27661-5221-4106-81cb-1beb7ce1e7fd + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "5" + separatecontext: false + view: |- + { + "position": { + "x": 450, + "y": 50 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: f00380e0-6efc-4c9c-87ff-279b353d80a9 + type: condition + task: + id: f00380e0-6efc-4c9c-87ff-279b353d80a9 + version: -1 + name: Check output + description: Check the playbook outputs. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "4" + "yes": + - "3" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isEqualString + left: + value: + complex: + root: File + accessor: SHA256 + iscontext: true + right: + value: + simple: b566b3812fcfaeb3474f9b43dc891a51e9a378d00d57d4e3048017715ef18fe1 + view: |- + { + "position": { + "x": 450, + "y": 400 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + type: regular + task: + id: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + version: -1 + name: Print success + description: Prints text to war room (Markdown supported) + scriptName: Print + type: regular + iscommand: false + brand: "" + scriptarguments: + value: + simple: SUCCESS + separatecontext: false + view: |- + { + "position": { + "x": 680, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: acf8565e-b649-41af-8631-75ddd75af037 + type: regular + task: + id: acf8565e-b649-41af-8631-75ddd75af037 + version: -1 + name: Print Error + description: Prints an error entry with a given message + scriptName: PrintErrorEntry + type: regular + iscommand: false + brand: "" + scriptarguments: + message: + simple: ERROR + separatecontext: false + view: |- + { + "position": { + "x": 220, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "5": + id: "5" + taskid: eee8500a-b9c6-4e6e-8565-6b15a55d1ef2 + type: playbook + task: + id: eee8500a-b9c6-4e6e-8565-6b15a55d1ef2 + version: -1 + name: Get Original Email - EWS v2 + description: |- + This v2 playbook retrieves the original email in the thread (as eml file) by using the EWS v2 integration. + The main difference between this playbook and its previous version is that this playbook will retrieve the email as eml and not as an Email object. This version also reduces the amount of tasks needed to perform the fetch action. + You must have the necessary permissions in the EWS integration to execute global search: eDiscovery + playbookName: Get Original Email - EWS v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "2" + scriptarguments: + MessageID: + simple: ${inputs.MessageID} + TargetMailbox: + simple: ${inputs.UserID} + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": 450, + "y": 220 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +view: |- + { + "linkLabelsPosition": {}, + "paper": { + "dimensions": { + "height": 615, + "width": 840, + "x": 220, + "y": 50 + } + } + } +inputs: +- key: UserID + value: + simple: demistoadmin@demisto.int + required: false + description: "" + playbookInputQuery: +- key: MessageID + value: + simple: <1635327546298.23756@demisto.int> + required: false + description: "" + playbookInputQuery: +outputs: [] +tests: +- No tests (auto formatted) +fromversion: 6.1.0 diff --git a/Packs/EWS/doc_imgs/Get_Original_Email_-_EWS_v2.png b/Packs/EWS/doc_imgs/Get_Original_Email_-_EWS_v2.png new file mode 100644 index 000000000000..127c14fc847f Binary files /dev/null and b/Packs/EWS/doc_imgs/Get_Original_Email_-_EWS_v2.png differ diff --git a/Packs/EWS/pack_metadata.json b/Packs/EWS/pack_metadata.json index b231e8c0da96..9bbda3974e36 100644 --- a/Packs/EWS/pack_metadata.json +++ b/Packs/EWS/pack_metadata.json @@ -2,7 +2,7 @@ "name": "EWS", "description": "Exchange Web Services and Office 365 (mail)", "support": "xsoar", - "currentVersion": "1.9.6", + "currentVersion": "1.10.0", "author": "Cortex XSOAR", "url": "https://www.paloaltonetworks.com/cortex", "email": "", diff --git a/Packs/Gmail/.pack-ignore b/Packs/Gmail/.pack-ignore index f47d2d12a344..0e53390812f7 100644 --- a/Packs/Gmail/.pack-ignore +++ b/Packs/Gmail/.pack-ignore @@ -2,7 +2,7 @@ ignore=IN126 [file:README.md] -ignore=RM106 +ignore=RM106,RM104 [file:classifier-mapper-incoming-Gsuite-gmail.json] ignore=BA101 \ No newline at end of file diff --git a/Packs/Gmail/.secrets-ignore b/Packs/Gmail/.secrets-ignore index 5dda0a7fdadf..b4f4c68a0136 100644 --- a/Packs/Gmail/.secrets-ignore +++ b/Packs/Gmail/.secrets-ignore @@ -26,3 +26,4 @@ send.grammarly.com 203.88.139.34 172.17.0.2 user1@nimbledata.io +Sm8c-3vbdUa_mgnnjCA_6cpuBm_Av+Q@mail.gmail.com \ No newline at end of file diff --git a/Packs/Gmail/Classifiers/classifier-mapper-incoming-Gsuite-gmail.json b/Packs/Gmail/Classifiers/classifier-mapper-incoming-Gsuite-gmail.json index de7155e32c86..fe86236211b8 100644 --- a/Packs/Gmail/Classifiers/classifier-mapper-incoming-Gsuite-gmail.json +++ b/Packs/Gmail/Classifiers/classifier-mapper-incoming-Gsuite-gmail.json @@ -124,8 +124,13 @@ "simple": "Html" }, "Email Headers": { - "complex": null, - "simple": "Headers" + "complex": { + "accessor": "", + "filters": [], + "root": " ", + "transformers": [] + }, + "simple": null }, "Email Message ID": { "complex": { @@ -153,6 +158,10 @@ "transformers": [] }, "simple": "" + }, + "Phishing Reporter Email Headers": { + "complex": null, + "simple": "Headers" } } } diff --git a/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2.yml b/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2.yml new file mode 100644 index 000000000000..342645c1f018 --- /dev/null +++ b/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2.yml @@ -0,0 +1,380 @@ +id: Get Original Email - Gmail v2 +version: -1 +contentitemexportablefields: + contentitemfields: {} +name: Get Original Email - Gmail v2 +description: | + This v2 playbook uses the reporter email headers to retrieve the original email. This decreases the amount of the tasks needed to retrieve the original email. + + Use this playbook to retrieve the original email using Gmail integration, including headers and attachments. + + You must have the necessary permissions in your Gmail service to execute global search: Google Apps Domain-Wide Delegation of Authority. +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: d8403573-b211-4d44-885c-a365045c61a2 + type: start + task: + id: d8403573-b211-4d44-885c-a365045c61a2 + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "2" + separatecontext: false + view: |- + { + "position": { + "x": 280, + "y": 1540 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: 77fd3720-3d21-4ffb-8f78-e6b62e5a5eb6 + type: condition + task: + id: 77fd3720-3d21-4ffb-8f78-e6b62e5a5eb6 + version: -1 + name: Is Gmail enabled? + description: Returns 'yes' if an integration brand is available. Otherwise returns + 'no'. + scriptName: IsIntegrationAvailable + type: condition + iscommand: false + brand: "" + nexttasks: + "no": + - "3" + "yes": + - "17" + scriptarguments: + brandname: + simple: Gmail + results: + - brandInstances + separatecontext: false + view: |- + { + "position": { + "x": 280, + "y": 1690 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 185c00fb-4375-4607-8b99-7538c88315bc + type: title + task: + id: 185c00fb-4375-4607-8b99-7538c88315bc + version: -1 + name: Done + type: title + iscommand: false + brand: "" + description: '' + separatecontext: false + view: |- + { + "position": { + "x": 280, + "y": 2720 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: 8e8c940f-71fd-456e-8f11-fd6a450616c9 + type: regular + task: + id: 8e8c940f-71fd-456e-8f11-fd6a450616c9 + version: -1 + name: Retrieve the Original email from Gmail + description: Searches for Gmail records of a specified Google user. + script: Gmail|||gmail-search + type: regular + iscommand: true + brand: Gmail + nexttasks: + '#none#': + - "5" + scriptarguments: + query: + simple: Rfc822msgid:${inputs.MessageID} + user-id: + complex: + root: inputs.UserID + reputationcalc: 2 + separatecontext: false + view: |- + { + "position": { + "x": 280, + "y": 2100 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "5": + id: "5" + taskid: ea7b5d02-8ad9-435f-849b-d8aa29f18cdc + type: condition + task: + id: ea7b5d02-8ad9-435f-849b-d8aa29f18cdc + version: -1 + name: Was the original email retrieved? + description: Verifies that there is a Gmail email object in the context. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "3" + "yes": + - "15" + - "13" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isExists + left: + value: + complex: + root: Gmail + accessor: ID + iscontext: true + view: |- + { + "position": { + "x": 510, + "y": 2280 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "13": + id: "13" + taskid: 9384d956-2f69-4882-852d-6c86a0060ee3 + type: regular + task: + id: 9384d956-2f69-4882-852d-6c86a0060ee3 + version: -1 + name: Get attachments of the original email + description: Retrieves the attachments of the original email from Gmail. + script: Gmail|||gmail-get-attachments + type: regular + iscommand: true + brand: Gmail + nexttasks: + '#none#': + - "3" + scriptarguments: + message-id: + complex: + root: Gmail + accessor: ID + user-id: + complex: + root: Gmail + accessor: Mailbox + user-key: + complex: + root: OriginalEmail + accessor: Mailbox + reputationcalc: 2 + separatecontext: false + view: |- + { + "position": { + "x": 280, + "y": 2450 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "15": + id: "15" + taskid: 7d541973-de31-41bd-89ae-70c3869b01de + type: regular + task: + id: 7d541973-de31-41bd-89ae-70c3869b01de + version: -1 + name: Set output + description: Sets the playbook outputs to context. + scriptName: Set + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "3" + scriptarguments: + key: + simple: Email + value: + simple: '${Gmail={Subject: val[''Subject''], To: val[''To''], From: val[''From''], + Text: val[''Body''], HTML: val[''Html''], Headers: val[''Headers''], CC: + val[''CC''], BCC: val[''BCC'']}}' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 737.5, + "y": 2450 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "17": + id: "17" + taskid: 67c1298f-d944-4a7f-83db-45f260e9977d + type: condition + task: + id: 67c1298f-d944-4a7f-83db-45f260e9977d + version: -1 + name: Verify Playbook Inputs + description: Verifies the playbook inputs. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "3" + Inputs-Exist: + - "4" + separatecontext: false + conditions: + - label: Inputs-Exist + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: inputs.MessageID + iscontext: true + - - operator: isNotEmpty + left: + value: + complex: + root: inputs.UserID + iscontext: true + view: |- + { + "position": { + "x": 280, + "y": 1890 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +view: |- + { + "linkLabelsPosition": {}, + "paper": { + "dimensions": { + "height": 1245, + "width": 837.5, + "x": 280, + "y": 1540 + } + } + } +inputs: +- key: MessageID + value: {} + required: false + description: The original email message id to retrieve. Holds the value + of the "Message-ID" header of the original email and not Gmail's internal ID of + the message. + playbookInputQuery: +- key: UserID + value: {} + required: false + description: The email address of the user for which to fetch the original email. + the authenticated user. + playbookInputQuery: +outputs: +- contextPath: Email + description: The email object + type: string +- contextPath: Email.To + description: The recipient of the email. + type: string +- contextPath: Email.From + description: The sender of the email. + type: string +- contextPath: Email.CC + description: The CC address of the email. + type: string +- contextPath: Email.BCC + description: The BCC address of the email. + type: string +- contextPath: Email.HTML + description: The HTML of the email. + type: string +- contextPath: Email.Body + description: The text body of the email. + type: string +- contextPath: Email.Headers + description: The headers of the email. + type: string +- contextPath: Email.Subject + description: The subject of the email. + type: string +- contextPath: File + description: The original attachments. + type: string +tests: +- Get Original Email - Gmail v2 - test +fromversion: 6.1.0 diff --git a/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2_README.md b/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2_README.md new file mode 100644 index 000000000000..05f3f71ed874 --- /dev/null +++ b/Packs/Gmail/Playbooks/playbook-Get_Original_Email_-_Gmail_v2_README.md @@ -0,0 +1,51 @@ +This v2 playbook uses the reporter email headers to retrieve the original email. This decreases the amount of the tasks needed to retrieve the original email. + +Use this playbook to retrieve the original email using Gmail integration, including headers and attachments. + +You must have the necessary permissions in your Gmail service to execute global search: Google Apps Domain-Wide Delegation of Authority. + + +## Dependencies +This playbook uses the following sub-playbooks, integrations, and scripts. + +### Sub-playbooks +This playbook does not use any sub-playbooks. + +### Integrations +* Gmail + +### Scripts +* Set +* IsIntegrationAvailable + +### Commands +* gmail-search +* gmail-get-attachments + +## Playbook Inputs +--- + +| **Name** | **Description** | **Default Value** | **Required** | +| --- | --- | --- | --- | +| MessageID | The original email message id to retrieve. Holds the value of the "Message-ID" header of the original email and not Gmail's internal ID of the message. | | Optional | +| UserID | The email address of the user for which to fetch the original email. | | Optional | + +## Playbook Outputs +--- + +| **Path** | **Description** | **Type** | +| --- | --- | --- | +| Email | The email object. | string | +| Email.To | The recipient of the email. | string | +| Email.From | The sender of the email. | string | +| Email.CC | The CC address of the email. | string | +| Email.BCC | The BCC address of the email. | string | +| Email.HTML | The HTML of the email. | string | +| Email.Body | The text body of the email. | string | +| Email.Headers | The headers of the email. | string | +| Email.Subject | The subject of the email. | string | +| File | The original attachments. | string | + +## Playbook Image +--- +![Get Original Email - Gmail v2](../doc_files/Get_Original_Email_-_Gmail_v2.png) diff --git a/Packs/Gmail/ReleaseNotes/1_1_10.md b/Packs/Gmail/ReleaseNotes/1_1_10.md new file mode 100644 index 000000000000..1a22c7e3ddb5 --- /dev/null +++ b/Packs/Gmail/ReleaseNotes/1_1_10.md @@ -0,0 +1,14 @@ + +#### Mappers +##### Gmail - Incoming Mapper +- Adding the "Phishing Reporter Email Headers" field. +- **BREAKING FIX** Disassociate the "Email Headers" field as it represents the original email headers and not the reporter headers. + +#### Playbooks +##### New: Get Original Email - Gmail v2 +- This v2 playbook uses the reporter email headers to retrieve the original email. This decreases the amount of the tasks needed to retrieve the original email. + +Use this playbook to retrieve the original email using Gmail integration, including headers and attachments. + +You must have the necessary permissions in your Gmail service to execute global search: Google Apps Domain-Wide Delegation of Authority. + diff --git a/Packs/Gmail/TestPlaybooks/playbook-Get_Original_Email_-_Gmail_v2_-_test.yml b/Packs/Gmail/TestPlaybooks/playbook-Get_Original_Email_-_Gmail_v2_-_test.yml new file mode 100644 index 000000000000..a28b4094ed8f --- /dev/null +++ b/Packs/Gmail/TestPlaybooks/playbook-Get_Original_Email_-_Gmail_v2_-_test.yml @@ -0,0 +1,236 @@ +id: Get Original Email - Gmail v2 - test +version: -1 +name: Get Original Email - Gmail v2 - test +description: '"Get Original Email - Gmail v2" test playbook.' +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 15d27661-5221-4106-81cb-1beb7ce1e7fd + type: start + task: + id: 15d27661-5221-4106-81cb-1beb7ce1e7fd + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "1" + separatecontext: false + view: |- + { + "position": { + "x": 450, + "y": 50 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "1": + id: "1" + taskid: b763db56-b600-46a0-8959-0e369221283d + type: playbook + task: + id: b763db56-b600-46a0-8959-0e369221283d + version: -1 + name: Get Original Email - Gmail v2 + description: | + This v2 playbook, will use the reporter email headers in order to retrieve the original email. This will assist with decreasing the amount of the tasks needed in order to do that. + + Use this playbook to retrieve the original email using Gmail integration, including headers and attachments. + + You must have the necessary permissions in your Gmail service to execute global search: Google Apps Domain-Wide Delegation of Authority + playbookName: Get Original Email - Gmail v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "2" + scriptarguments: + MessageID: + simple: ${inputs.MessageID} + UserID: + simple: ${inputs.UserID} + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": 450, + "y": 230 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: c71f5978-238a-4ec7-8d75-b9d28c0a0086 + type: condition + task: + id: c71f5978-238a-4ec7-8d75-b9d28c0a0086 + version: -1 + name: Check output + description: Check the playbook outputs. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "4" + "yes": + - "3" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isEqualString + left: + value: + complex: + root: Email.Headers + filters: + - - operator: isEqualString + left: + value: + simple: Email.Headers.Name + iscontext: true + right: + value: + simple: Message-ID + accessor: Value + iscontext: true + right: + value: + simple: + - - operator: isEqualString + left: + value: + complex: + root: File + accessor: SHA256 + iscontext: true + right: + value: + simple: c46104a05abce619a3447ecdb194919099eafa3d4080222ed1c7797655eddc22 + view: |- + { + "position": { + "x": 450, + "y": 400 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + type: regular + task: + id: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + version: -1 + name: Print success + description: Prints text to war room (Markdown supported) + scriptName: Print + type: regular + iscommand: false + brand: "" + scriptarguments: + value: + simple: SUCCESS + separatecontext: false + view: |- + { + "position": { + "x": 680, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: acf8565e-b649-41af-8631-75ddd75af037 + type: regular + task: + id: acf8565e-b649-41af-8631-75ddd75af037 + version: -1 + name: Print Error + description: Prints an error entry with a given message + scriptName: PrintErrorEntry + type: regular + iscommand: false + brand: "" + scriptarguments: + message: + simple: ERROR + separatecontext: false + view: |- + { + "position": { + "x": 220, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +view: |- + { + "linkLabelsPosition": {}, + "paper": { + "dimensions": { + "height": 615, + "width": 840, + "x": 220, + "y": 50 + } + } + } +inputs: +- key: UserID + value: + simple: admin@demistodev.com + required: false + description: "" + playbookInputQuery: +- key: MessageID + value: + simple: + required: false + description: "" + playbookInputQuery: +outputs: [] +tests: +- No tests (auto formatted) +fromversion: 6.1.0 diff --git a/Packs/Gmail/doc_files/Get_Original_Email_-_Gmail_v2.png b/Packs/Gmail/doc_files/Get_Original_Email_-_Gmail_v2.png new file mode 100644 index 000000000000..425a76c4eaf0 Binary files /dev/null and b/Packs/Gmail/doc_files/Get_Original_Email_-_Gmail_v2.png differ diff --git a/Packs/Gmail/pack_metadata.json b/Packs/Gmail/pack_metadata.json index bf63a0c16dd6..22dee7b33488 100644 --- a/Packs/Gmail/pack_metadata.json +++ b/Packs/Gmail/pack_metadata.json @@ -2,7 +2,7 @@ "name": "Gmail", "description": "Gmail API and user management (This integration replaces the Gmail functionality in the GoogleApps API and G Suite integration).", "support": "xsoar", - "currentVersion": "1.1.9", + "currentVersion": "1.1.10", "author": "Cortex XSOAR", "url": "https://www.paloaltonetworks.com/cortex", "email": "", diff --git a/Packs/MicrosoftGraphMail/.secrets-ignore b/Packs/MicrosoftGraphMail/.secrets-ignore index ebcefd6cead2..a2b1fe130ca3 100644 --- a/Packs/MicrosoftGraphMail/.secrets-ignore +++ b/Packs/MicrosoftGraphMail/.secrets-ignore @@ -1,2 +1,3 @@ AM6PR07MB44530DA96C2DF255705F30FD83CA0@AM6PR07MB4453.eurprd07.prod.outlook.com -AM6PR07MB44530DA96C2DF255705F30FD83CA0@AM6PR07MB4453.eurprd07.prod.outlook. \ No newline at end of file +AM6PR07MB44530DA96C2DF255705F30FD83CA0@AM6PR07MB4453.eurprd07.prod.outlook. +VI1PR07MB4751252DDE7DD134E41EB032E2859@VI1PR07MB4751.eurprd07.prod.outlook.com \ No newline at end of file diff --git a/Packs/MicrosoftGraphMail/Classifiers/classifier-Microsoft_Graph_Mail_Mapper.json b/Packs/MicrosoftGraphMail/Classifiers/classifier-Microsoft_Graph_Mail_Mapper.json index 7b22dfcc95d6..e5f40979fddd 100644 --- a/Packs/MicrosoftGraphMail/Classifiers/classifier-Microsoft_Graph_Mail_Mapper.json +++ b/Packs/MicrosoftGraphMail/Classifiers/classifier-Microsoft_Graph_Mail_Mapper.json @@ -111,8 +111,13 @@ "simple": "Body" }, "Email Headers": { - "complex": null, - "simple": "Headers" + "complex": { + "accessor": "", + "filters": [], + "root": " ", + "transformers": [] + }, + "simple": null }, "Email Message ID": { "complex": { @@ -294,6 +299,10 @@ ] }, "simple": "" + }, + "Phishing Reporter Email Headers": { + "complex": null, + "simple": "Headers" } } }, diff --git a/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail.yml b/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail.yml new file mode 100644 index 000000000000..0bd80bbf0be8 --- /dev/null +++ b/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail.yml @@ -0,0 +1,354 @@ +id: Get Original Email - Microsoft Graph Mail +version: -1 +contentitemexportablefields: + contentitemfields: {} +name: Get Original Email - Microsoft Graph Mail +description: |- + Use this playbook to retrieve the original email using Microsoft Graph Mail integration. + + You must have the necessary permissions in the Microsoft Graph Mail integration as described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 5607d1c6-85b0-4181-8b10-bb3a5b113c6f + type: start + task: + id: 5607d1c6-85b0-4181-8b10-bb3a5b113c6f + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "10" + separatecontext: false + view: |- + { + "position": { + "x": -20, + "y": 160 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: d2eca123-db35-4b27-88d8-a8b77ffd6784 + type: title + task: + id: d2eca123-db35-4b27-88d8-a8b77ffd6784 + version: -1 + name: Done + type: title + iscommand: false + brand: "" + description: '' + separatecontext: false + view: |- + { + "position": { + "x": -20, + "y": 1590 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "10": + id: "10" + taskid: 0db04b60-0358-4214-851a-42598fa48cd3 + type: condition + task: + id: 0db04b60-0358-4214-851a-42598fa48cd3 + version: -1 + name: Is Microsoft Graph Mail enabled? + description: Returns 'yes' if an integration brand is available. Otherwise returns + 'no'. + scriptName: IsIntegrationAvailable + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + "yes": + - "14" + scriptarguments: + brandname: + simple: MicrosoftGraphMail + results: + - brandInstances + separatecontext: false + view: |- + { + "position": { + "x": -20, + "y": 340 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "11": + id: "11" + taskid: 4e24bc0c-facd-4823-8f1e-67e4458fd4b5 + type: regular + task: + id: 4e24bc0c-facd-4823-8f1e-67e4458fd4b5 + version: -1 + name: Search for messages by MessageID + description: Gets the properties of returned emails. Typically shows partial + results. Use the "page_size" and "pages_to_pull" arguments to get all results. + script: MicrosoftGraphMail|||msgraph-mail-list-emails + type: regular + iscommand: true + brand: MicrosoftGraphMail + nexttasks: + '#none#': + - "12" + scriptarguments: + search: + simple: subject:${inputs.ThreadTopic} + user_id: + complex: + root: inputs.UserID + reputationcalc: 2 + separatecontext: false + view: |- + { + "position": { + "x": -20, + "y": 805 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "12": + id: "12" + taskid: b22d3fc0-5801-4c61-8b57-87dfc491682e + type: condition + task: + id: b22d3fc0-5801-4c61-8b57-87dfc491682e + version: -1 + name: Was a matching email found? + description: Verifies that an email object with a Message-Id that matches the + InReplyTo ID of the forwarded email was found. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + "Yes": + - "13" + separatecontext: false + conditions: + - label: "Yes" + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: MSGraphMail.InternetMessageID + filters: + - - operator: isEqualString + left: + value: + simple: MSGraphMail.InternetMessageID + iscontext: true + right: + value: + simple: inputs.MessageID + iscontext: true + iscontext: true + view: |- + { + "position": { + "x": -20, + "y": 1010 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "13": + id: "13" + taskid: ca359a26-a418-44a6-86f9-4b9cee53dfaa + type: regular + task: + id: ca359a26-a418-44a6-86f9-4b9cee53dfaa + version: -1 + name: Get original email + description: Retrieves an email message by message ID and uploads the content + as an EML file. + script: MicrosoftGraphMail|||msgraph-mail-get-email-as-eml + type: regular + iscommand: true + brand: MicrosoftGraphMail + nexttasks: + '#none#': + - "2" + scriptarguments: + message_id: + complex: + root: MSGraphMail + filters: + - - operator: isEqualString + left: + value: + simple: MSGraphMail.InternetMessageID + iscontext: true + right: + value: + simple: inputs.MessageID + iscontext: true + accessor: ID + transformers: + - operator: StripChars + args: + chars: + value: + simple: <> + - operator: uniq + user_id: + complex: + root: inputs.UserID + reputationcalc: 2 + separatecontext: false + view: |- + { + "position": { + "x": -20, + "y": 1280 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "14": + id: "14" + taskid: 015f4932-563b-458f-8009-e7daafc60547 + type: condition + task: + id: 015f4932-563b-458f-8009-e7daafc60547 + version: -1 + name: Verify required inputs + description: Verifies that the required input values exist for retrieving the original + email. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + "yes": + - "11" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isExists + left: + value: + complex: + root: inputs.UserID + iscontext: true + - operator: isExists + left: + value: + complex: + root: inputs.MessageID + iscontext: true + - operator: isExists + left: + value: + complex: + root: inputs.ThreadTopic + iscontext: true + view: |- + { + "position": { + "x": -20, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +system: true +view: |- + { + "linkLabelsPosition": { + "10_14_yes": 0.57, + "10_2_#default#": 0.31, + "12_13_Yes": 0.58, + "12_2_#default#": 0.78, + "14_11_yes": 0.59, + "14_2_#default#": 0.37 + }, + "paper": { + "dimensions": { + "height": 1495, + "width": 380, + "x": -20, + "y": 160 + } + } + } +inputs: +- key: UserID + value: {} + required: false + description: The email address of the reporting user. + playbookInputQuery: +- key: MessageID + value: {} + required: false + description: The InReplyTo header in the forwarded email. + playbookInputQuery: +- key: ThreadTopic + value: {} + required: false + description: The ThreadTopic header in the forwarded email. + playbookInputQuery: +outputs: +- contextPath: File + description: The original email as an eml file. + type: string +tests: +- Get Original Email - Microsoft Graph Mail - test +fromversion: 6.1.0 diff --git a/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_README.md b/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_README.md new file mode 100644 index 000000000000..81eecc8202a5 --- /dev/null +++ b/Packs/MicrosoftGraphMail/Playbooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_README.md @@ -0,0 +1,41 @@ +Use this playbook to retrieve the original email using Microsoft Graph Mail integration. + +You must have the necessary permissions in the Microsoft Graph Mail integration as described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + +## Dependencies +This playbook uses the following sub-playbooks, integrations, and scripts. + +### Sub-playbooks +This playbook does not use any sub-playbooks. + +### Integrations +* MicrosoftGraphMail + +### Scripts +* IsIntegrationAvailable + +### Commands +* msgraph-mail-list-emails +* msgraph-mail-get-email-as-eml + +## Playbook Inputs +--- + +| **Name** | **Description** | **Default Value** | **Required** | +| --- | --- | --- | --- | +| UserID | The email address of the reporting user. | | Optional | +| MessageID | The InReplyTo header in the forwarded email. | | Optional | +| ThreadTopic | The ThreadTopic header in the forwarded email. | | Optional | + +## Playbook Outputs +--- + +| **Path** | **Description** | **Type** | +| --- | --- | --- | +| File | The original email as an eml file. | string | + +## Playbook Image +--- +![Get Original Email - Microsoft Graph Mail](../doc_files/Get_Original_Email_-_Microsoft_Graph_Mail.png) diff --git a/Packs/MicrosoftGraphMail/ReleaseNotes/1_1_0.md b/Packs/MicrosoftGraphMail/ReleaseNotes/1_1_0.md new file mode 100644 index 000000000000..ec5f3f119a5c --- /dev/null +++ b/Packs/MicrosoftGraphMail/ReleaseNotes/1_1_0.md @@ -0,0 +1,12 @@ + +#### Mappers +##### Microsoft Graph Mail Mapper +- Adding the "Phishing Reporter Email Headers" field. +- **BREAKING FIX** Disassociate the "Email Headers" field, as it represents the original email headers and not the reporter headers. + +#### Playbooks +##### New: Get Original Email - Microsoft Graph Mail +Use this playbook to retrieve the original email in the thread as an eml file when the reporting user forwarded the original email not as an attachment. +You must have the necessary permissions in the Microsoft Graph Mail integration as described here: + - https://docs.microsoft.com/en-us/graph/api/message-get + - https://docs.microsoft.com/en-us/graph/api/user-list-messages diff --git a/Packs/MicrosoftGraphMail/TestPlaybooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_-_test.yml b/Packs/MicrosoftGraphMail/TestPlaybooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_-_test.yml new file mode 100644 index 000000000000..618d7a53cbf9 --- /dev/null +++ b/Packs/MicrosoftGraphMail/TestPlaybooks/playbook-Get_Original_Email_-_Microsoft_Graph_Mail_-_test.yml @@ -0,0 +1,228 @@ +id: Get Original Email - Microsoft Graph Mail - test +version: -1 +name: Get Original Email - Microsoft Graph Mail - test +description: '"Get Original Email - Microsoft Graph Mail" test playbook.' +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 15d27661-5221-4106-81cb-1beb7ce1e7fd + type: start + task: + id: 15d27661-5221-4106-81cb-1beb7ce1e7fd + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "5" + separatecontext: false + view: |- + { + "position": { + "x": 450, + "y": 50 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: 22c123c2-df9c-4ae6-8632-45b3e1c1393e + type: condition + task: + id: 22c123c2-df9c-4ae6-8632-45b3e1c1393e + version: -1 + name: Check output + description: Check the playbook outputs. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "4" + "yes": + - "3" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isEqualString + left: + value: + complex: + root: File + accessor: SHA256 + iscontext: true + right: + value: + simple: 5284e46729c4f554172494938be7482627cbfb3d91b83f83b7a5c70cf647ae94 + view: |- + { + "position": { + "x": 450, + "y": 400 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + type: regular + task: + id: 23abaa87-7be6-4efa-84c3-d7e0689f3d27 + version: -1 + name: Print success + description: Prints text to war room (Markdown supported) + scriptName: Print + type: regular + iscommand: false + brand: "" + scriptarguments: + value: + simple: SUCCESS + separatecontext: false + view: |- + { + "position": { + "x": 680, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: 4d7dc1e1-b5ca-48bc-824f-41bad4755526 + type: regular + task: + id: 4d7dc1e1-b5ca-48bc-824f-41bad4755526 + version: -1 + name: Print Error + description: Prints an error entry with a given message + scriptName: PrintErrorEntry + type: regular + iscommand: false + brand: "" + scriptarguments: + message: + simple: ERROR + separatecontext: false + view: |- + { + "position": { + "x": 220, + "y": 570 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "5": + id: "5" + taskid: 6d2d3cde-0030-464a-8bda-a99ab24a9fa1 + type: playbook + task: + id: 6d2d3cde-0030-464a-8bda-a99ab24a9fa1 + version: -1 + name: Get Original Email - Microsoft Graph Mail + description: |- + Use this playbook to retrieve the original email using Microsoft Graph Mail integration. + + You must have the necessary permissions in the Microsoft Graph Mail integration as described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + playbookName: Get Original Email - Microsoft Graph Mail + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "2" + scriptarguments: + MessageID: + complex: + root: inputs.MessageID + ThreadTopic: + complex: + root: inputs.EmailSubject + UserID: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": 450, + "y": 200 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +view: |- + { + "linkLabelsPosition": {}, + "paper": { + "dimensions": { + "height": 615, + "width": 840, + "x": 220, + "y": 50 + } + } + } +inputs: +- key: UserID + value: + simple: avishai@demistodev.onmicrosoft.com + required: false + description: "" + playbookInputQuery: +- key: MessageID + value: + simple: + required: false + description: "" + playbookInputQuery: +- key: EmailSubject + value: + simple: TEST_EMAIL_DO_NOT_DELETE + required: false + description: "" + playbookInputQuery: +outputs: [] +tests: +- No tests (auto formatted) +fromversion: 6.1.0 diff --git a/Packs/MicrosoftGraphMail/doc_files/Get_Original_Email_-_Microsoft_Graph_Mail.png b/Packs/MicrosoftGraphMail/doc_files/Get_Original_Email_-_Microsoft_Graph_Mail.png new file mode 100644 index 000000000000..a044e3af703f Binary files /dev/null and b/Packs/MicrosoftGraphMail/doc_files/Get_Original_Email_-_Microsoft_Graph_Mail.png differ diff --git a/Packs/MicrosoftGraphMail/pack_metadata.json b/Packs/MicrosoftGraphMail/pack_metadata.json index 813bb9de9bec..31604ba140aa 100644 --- a/Packs/MicrosoftGraphMail/pack_metadata.json +++ b/Packs/MicrosoftGraphMail/pack_metadata.json @@ -2,7 +2,7 @@ "name": "Microsoft Graph Mail", "description": "Microsoft Graph lets your app get authorized access to a user's Outlook mail data in a personal or organization account.", "support": "xsoar", - "currentVersion": "1.0.27", + "currentVersion": "1.1.0", "author": "Cortex XSOAR", "url": "https://www.paloaltonetworks.com/cortex", "email": "", diff --git a/Packs/Phishing/IncidentFields/incidentfield-Phishing_Reporter_Email_Headers.json b/Packs/Phishing/IncidentFields/incidentfield-Phishing_Reporter_Email_Headers.json new file mode 100644 index 000000000000..1a77fedb4b5c --- /dev/null +++ b/Packs/Phishing/IncidentFields/incidentfield-Phishing_Reporter_Email_Headers.json @@ -0,0 +1,45 @@ +{ + "id": "incident_phishingreporteremailheaders", + "version": -1, + "modified": "2021-09-22T22:00:56.93721224Z", + "name": "Phishing Reporter Email Headers", + "ownerOnly": false, + "cliName": "phishingreporteremailheaders", + "type": "grid", + "closeForm": false, + "editForm": true, + "required": false, + "neverSetAsRequired": false, + "isReadOnly": false, + "useAsKpi": false, + "locked": false, + "system": false, + "content": true, + "group": 0, + "hidden": false, + "openEnded": false, + "associatedTypes": [ + "Phishing" + ], + "associatedToAll": false, + "unmapped": false, + "unsearchable": false, + "caseInsensitive": true, + "columns": [ + { + "key": "headername", + "displayName": "headername", + "type": "shortText", + "required": false, + "script": "", + "width": 150, + "isDefault": true, + "fieldCalcScript": "", + "isReadOnly": false, + "selectValues": null + } + ], + "sla": 0, + "threshold": 72, + "fromVersion": "6.0.0" +} \ No newline at end of file diff --git a/Packs/Phishing/IncidentTypes/New_6_1/incidenttype-Phishing_6.1.json b/Packs/Phishing/IncidentTypes/New_6_1/incidenttype-Phishing_6.1.json index fa67db80745a..bedea283e9fc 100644 --- a/Packs/Phishing/IncidentTypes/New_6_1/incidenttype-Phishing_6.1.json +++ b/Packs/Phishing/IncidentTypes/New_6_1/incidenttype-Phishing_6.1.json @@ -18,7 +18,7 @@ "default": false, "autorun": false, "disabled": false, - "reputationCalc": 1, + "reputationCalc": 2, "onChangeRepAlg": 2, "fromVersion": "6.1.0", "layout": "Phishing", diff --git a/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_-_6_0.yml b/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_-_6_0.yml index 23df5c7cf8dc..24ddfae51066 100644 --- a/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_-_6_0.yml +++ b/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_-_6_0.yml @@ -163,10 +163,10 @@ tasks: quietmode: 0 "12": id: "12" - taskid: dc2824f3-564e-4270-893b-80318ac5c5f6 + taskid: eda53266-2df9-40a6-8f16-bc4bf3bb8e76 type: regular task: - id: dc2824f3-564e-4270-893b-80318ac5c5f6 + id: eda53266-2df9-40a6-8f16-bc4bf3bb8e76 version: -1 name: Store the email address of the reporting user description: Store the email address of the user that reported the incident. @@ -179,19 +179,21 @@ tasks: - "53" - "85" scriptarguments: + append: {} key: simple: ReporterAddress + stringify: {} value: complex: - root: incident - accessor: labels.Email/from + root: ExtractedIndicators.Email + accessor: '[0]' reputationcalc: 1 separatecontext: false view: |- { "position": { "x": 1182.5, - "y": 350 + "y": 515 } } note: false @@ -237,7 +239,7 @@ tasks: { "position": { "x": 1182.5, - "y": 710 + "y": 880 } } note: false @@ -390,7 +392,7 @@ tasks: description: '' nexttasks: '#none#': - - "12" + - "134" separatecontext: false view: |- { @@ -907,10 +909,7 @@ tasks: - "13" scriptarguments: Domain: - complex: - root: Domain - transformers: - - operator: uniq + simple: ' ' Email: complex: root: ReporterAddress @@ -926,7 +925,7 @@ tasks: { "position": { "x": 1182.5, - "y": 530 + "y": 700 } } note: false @@ -1239,7 +1238,7 @@ tasks: { "position": { "x": 1650, - "y": 530 + "y": 700 } } note: false @@ -1691,6 +1690,7 @@ tasks: iscontext: true transformers: - operator: uniq + separatecontext: false view: |- { "position": { @@ -1980,7 +1980,7 @@ tasks: type: condition iscommand: false brand: "" - description: '' + description: "" nexttasks: '#default#': - "84" @@ -2054,6 +2054,43 @@ tasks: ignoreworker: false skipunavailable: false quietmode: 0 + "134": + id: "134" + taskid: bfac256a-f19f-45b2-8982-9e36d827438d + type: regular + task: + id: bfac256a-f19f-45b2-8982-9e36d827438d + version: -1 + name: Extract the email address of the reporting user + description: commands.local.cmd.extract.indicators + script: Builtin|||extractIndicators + type: regular + iscommand: true + brand: Builtin + nexttasks: + '#none#': + - "12" + scriptarguments: + entryID: {} + filePath: {} + investigationID: {} + text: + complex: + root: incident.labels + accessor: Email/from + separatecontext: false + view: |- + { + "position": { + "x": 1182.5, + "y": 350 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 system: true view: |- { diff --git a/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_README.md b/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_README.md index 9ff0b269a3c6..0ff0ecc443b3 100644 --- a/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_README.md +++ b/Packs/Phishing/Playbooks/Phishing_Investigation_-_Generic_v2_README.md @@ -65,6 +65,7 @@ This playbook does not use any integrations. * setIncident * closeInvestigation * send-mail +* extractIndicators ## Playbook Inputs --- diff --git a/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2.yml b/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2.yml new file mode 100644 index 000000000000..0092440d6704 --- /dev/null +++ b/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2.yml @@ -0,0 +1,1772 @@ +id: Process Email - Generic v2 +version: -1 +contentitemexportablefields: + contentitemfields: {} +name: Process Email - Generic v2 +description: | + Add email details to the relevant context entities and handle the case where original emails are attached. + + Added on this v2 playbook: + - Uses incident fields and not incident labels. + - Provides separate paths to "Phishing Alerts". + - Uses the new "Get Original Email - Generic v2" playbook to retrieve original emails as eml files for both EWS v2 and Microsoft Graph Mail integration. This will assist with parsing the email artifacts in a more efficient way. +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 028c057d-2a33-4b5e-8501-ad0166f55e06 + type: start + task: + id: 028c057d-2a33-4b5e-8501-ad0166f55e06 + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "23" + separatecontext: false + view: |- + { + "position": { + "x": 367.5, + "y": -510 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "1": + id: "1" + taskid: 161bad06-c10f-4c3b-8599-1743e279f703 + type: condition + task: + id: 161bad06-c10f-4c3b-8599-1743e279f703 + version: -1 + name: Do we have original emails attached? + description: Identify whether the incident includes an email message attached + as an eml or msg file and return the answer to playbook. Also saves the identified + entry ID to context for use for later. Commonly used in automated playbooks + that handle phishing reports sent to a special phishing mailbox set up by + the security team. + scriptName: IdentifyAttachedEmail + type: condition + iscommand: false + brand: "" + nexttasks: + "no": + - "16" + "yes": + - "3" + scriptarguments: + entryid: + simple: ${inputs.File.EntryID} + reputationcalc: 1 + results: + - reportedemailentryid + separatecontext: false + view: |- + { + "position": { + "x": 367.5, + "y": 15 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "2": + id: "2" + taskid: e5d2019a-9e65-4698-8e1f-1c9ae1dcda0f + type: regular + task: + id: e5d2019a-9e65-4698-8e1f-1c9ae1dcda0f + version: -1 + name: Add original email details to context + description: Sets the details of the email that was forwarded under the Email + context key. + scriptName: Set + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "11" + scriptarguments: + key: + simple: Email + value: + simple: '${inputs={To: val[''Email''], CC: val[''EmailCC''], From: val[''EmailFrom''], + Subject: val[''EmailSubject''], Text: val[''EmailText''], HTML: val[''EmailHtml''], + Headers: val[''EmailHeaders''], Format: val[''EmailFormat'']}}' + separatecontext: false + view: |- + { + "position": { + "x": -110, + "y": 2020 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: 869479fe-4f37-4211-8d7f-333e7931bc80 + type: regular + task: + id: 869479fe-4f37-4211-8d7f-333e7931bc80 + version: -1 + name: Extract email artifacts and attachments + description: Parses an email from an EML or MSG file and populates all relevant + context data to investigate the email. Also extracts indicators from the email + messages. + scriptName: ParseEmailFiles + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "39" + scriptarguments: + entryid: + simple: ${reportedemailentryid} + reputationcalc: 2 + results: + - AttachmentName + separatecontext: false + view: |- + { + "position": { + "x": 660, + "y": 1075 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "4": + id: "4" + taskid: e3b5e51d-c643-400d-84fd-fd54ad6b5014 + type: condition + task: + id: e3b5e51d-c643-400d-84fd-fd54ad6b5014 + version: -1 + name: Can an image of the email be rendered? + description: Checks whether the email is HTML-formatted, and whether the Rasterize + integration is enabled. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "6" + "yes": + - "5" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isExists + left: + value: + complex: + root: Email + accessor: HTML + iscontext: true + - - operator: isNotEmpty + left: + value: + simple: Email.HTML + iscontext: true + - - operator: isExists + left: + value: + complex: + root: modules + filters: + - - operator: isEqualString + left: + value: + simple: brand + iscontext: true + right: + value: + simple: Rasterize + - - operator: isEqualString + left: + value: + simple: state + iscontext: true + right: + value: + simple: active + iscontext: true + view: |- + { + "position": { + "x": 340, + "y": 2390 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "5": + id: "5" + taskid: c41951dc-221e-41e2-8c39-87bb5e20b74c + type: regular + task: + id: c41951dc-221e-41e2-8c39-87bb5e20b74c + version: -1 + name: Render HTML to an image + description: Rasterize an email body into an image + tags: + - email_html_image + script: '|||rasterize-email' + type: regular + iscommand: true + brand: "" + nexttasks: + '#none#': + - "6" + scriptarguments: + htmlBody: + complex: + root: Email + accessor: HTML + offline: + simple: "true" + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 100, + "y": 2610 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "6": + id: "6" + taskid: b2be48ca-b624-4cd5-87d1-0124aa3e741d + type: title + task: + id: b2be48ca-b624-4cd5-87d1-0124aa3e741d + version: -1 + name: Done + type: title + iscommand: false + brand: "" + description: '' + separatecontext: false + view: |- + { + "position": { + "x": 340, + "y": 2840 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "11": + id: "11" + taskid: 9fe923a7-22d9-49ee-81e1-9e2c4fb762f7 + type: title + task: + id: 9fe923a7-22d9-49ee-81e1-9e2c4fb762f7 + version: -1 + name: Email Screenshot + type: title + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "4" + separatecontext: false + view: |- + { + "position": { + "x": 340, + "y": 2260 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "16": + id: "16" + taskid: 6d65c30c-731e-4eeb-84d3-fcf30b3cd04c + type: condition + task: + id: 6d65c30c-731e-4eeb-84d3-fcf30b3cd04c + version: -1 + name: Should the original email be retrieved? + description: If True, retrieve the original email in the thread + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + Yes-Alerts: + - "34" + Yes-Forwarded: + - "33" + separatecontext: false + conditions: + - label: Yes-Forwarded + condition: + - - operator: isEqualString + left: + value: + complex: + root: inputs.GetOriginalEmail + iscontext: true + right: + value: + simple: "True" + ignorecase: true + - - operator: isNotEmpty + left: + value: + complex: + root: incident + accessor: phishingreporteremailheaders + iscontext: true + - label: Yes-Alerts + condition: + - - operator: isEqualString + left: + value: + complex: + root: inputs.GetOriginalEmail + iscontext: true + right: + value: + simple: "True" + view: |- + { + "position": { + "x": -260, + "y": 200 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "18": + id: "18" + taskid: eefa9fe2-e6a7-4031-893a-2765e539d1c4 + type: condition + task: + id: eefa9fe2-e6a7-4031-893a-2765e539d1c4 + version: -1 + name: Was the original email retrieved? + description: Is there an "Email" object in the context? + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + Email Exist: + - "22" + separatecontext: false + conditions: + - label: Email Exist + condition: + - - operator: isExists + left: + value: + complex: + root: Email + iscontext: true + view: |- + { + "position": { + "x": 180, + "y": 1240 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "19": + id: "19" + taskid: fa0cb93f-20d4-4972-8e3b-b2784250864d + type: regular + task: + id: fa0cb93f-20d4-4972-8e3b-b2784250864d + version: -1 + name: Display email information in layout + description: Updates Cortex XSOAR incident fields using data from the email + object. + script: Builtin|||setIncident + type: regular + iscommand: true + brand: Builtin + nexttasks: + '#none#': + - "11" + scriptarguments: + attachmentcount: + complex: + root: Email + accessor: | + Attachment.Count + attachmentextension: + complex: + root: Email + accessor: Attachment.Extension + attachmenthash: + complex: + root: Email + accessor: Attachment.Hash + attachmentid: + complex: + root: Email + accessor: Attachment.ID + attachmentitem: + complex: + root: Email + accessor: Attachment.Item + attachmentname: + complex: + root: Email + accessor: Attachment.Name + attachmentsize: + complex: + root: Email + accessor: Attachment.Size + attachmenttype: + complex: + root: Email + accessor: Attachment.Type + deleteEmptyField: + simple: "True" + emailbcc: + complex: + root: Email + accessor: HeadersMap.BCC + transformers: + - operator: uniq + - operator: Stringify + emailbody: + complex: + root: Email + accessor: Text + transformers: + - operator: Stringify + emailbodyformat: + complex: + root: Email + accessor: BodyFormat + emailbodyhtml: + complex: + root: Email + accessor: HTML + transformers: + - operator: Stringify + emailcc: + complex: + root: Email + accessor: CC + transformers: + - operator: uniq + - operator: Stringify + emailclientname: + complex: + root: Email + accessor: ClientName + emailfrom: + complex: + root: Email + accessor: From + transformers: + - operator: uniq + - operator: Stringify + emailhtml: + complex: + root: Email + accessor: HTML + transformers: + - operator: uniq + emailimage: + complex: + root: Email + accessor: Image + emailinreplyto: + complex: + root: Email + accessor: InReplyTo + emailkeywords: + complex: + root: Email + accessor: Keywords + emailmessageid: + complex: + root: Email + accessor: HeadersMap.Message-ID + transformers: + - operator: uniq + emailreplyto: + complex: + root: Email + accessor: HeadersMap.Reply-To + transformers: + - operator: uniq + emailreturnpath: + complex: + root: Email + accessor: HeadersMap.Return-Path + transformers: + - operator: uniq + emailsenderip: + complex: + root: Email + accessor: SenderIP + transformers: + - operator: uniq + emailsize: + complex: + root: Email + accessor: Size + transformers: + - operator: uniq + emailsource: + complex: + root: Email + accessor: Source + transformers: + - operator: uniq + emailsubject: + complex: + root: Email + accessor: Subject + transformers: + - operator: uniq + - operator: Stringify + emailto: + complex: + root: Email + accessor: To + transformers: + - operator: uniq + - operator: join + args: + separator: + value: + simple: ',' + emailtocount: + complex: + root: Email + accessor: To + transformers: + - operator: uniq + - operator: count + emailurlclicked: + complex: + root: EmailUrlClicked + separatecontext: false + view: |- + { + "position": { + "x": 1280, + "y": 2090 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "20": + id: "20" + taskid: 5a305f89-a43d-403d-8105-3c6da2421f45 + type: regular + task: + id: 5a305f89-a43d-403d-8105-3c6da2421f45 + version: -1 + name: Display email headers in layout - Email.Headers + description: Fills the "Email Headers" grid field in the incident layout with + the retrieved email headers. + scriptName: SetGridField + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "11" + scriptarguments: + columns: + simple: headername,headervalue + context_path: + simple: Email.Headers + grid_id: + simple: emailheaders + overwrite: + simple: "true" + sort_by: + simple: headername + unpack_nested_elements: + simple: "false" + continueonerror: true + separatecontext: false + view: |- + { + "position": { + "x": 340, + "y": 2020 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "21": + id: "21" + taskid: 02773e7a-623b-491d-8667-76e99063765c + type: condition + task: + id: 02773e7a-623b-491d-8667-76e99063765c + version: -1 + name: Were email headers extracted successfully? + description: Checks whether the email headers were extracted from the original + email that was either attached or retrieved using available email integrations. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "2" + Headers: + - "20" + HeadersMap: + - "40" + separatecontext: false + conditions: + - label: HeadersMap + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: Email + accessor: HeadersMap + iscontext: true + - label: Headers + condition: + - - operator: isNotEmpty + left: + value: + simple: Email.Headers + iscontext: true + view: |- + { + "position": { + "x": 660, + "y": 1660 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "22": + id: "22" + taskid: c6b99de4-efa1-4a02-88fb-b39e7a0804cc + type: title + task: + id: c6b99de4-efa1-4a02-88fb-b39e7a0804cc + version: -1 + name: Incident Layout Display + type: title + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "21" + - "25" + separatecontext: false + view: |- + { + "position": { + "x": 1060, + "y": 1490 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "23": + id: "23" + taskid: b6224cc9-ed84-4bed-8fcb-d077722b4f14 + type: condition + task: + id: b6224cc9-ed84-4bed-8fcb-d077722b4f14 + version: -1 + name: Are there any files in the incident? + description: Checks whether the incident contains any kind of file. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "16" + "yes": + - "24" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: inputs.File + accessor: EntryID + iscontext: true + view: |- + { + "position": { + "x": 367.5, + "y": -360 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "24": + id: "24" + taskid: 9c9c52d2-81ed-4dc4-820b-0be7f403ecc4 + type: regular + task: + id: 9c9c52d2-81ed-4dc4-820b-0be7f403ecc4 + version: -1 + name: Save incident files separately from email attachments + description: Saves the files that were initially involved with the incident + in a separate context key so that they are available separate from email attachment + files. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "1" + scriptarguments: + key: + simple: IncidentFiles + value: + complex: + root: inputs.File + separatecontext: false + view: |- + { + "position": { + "x": 367.5, + "y": -170 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "25": + id: "25" + taskid: 4b384f12-dc73-45ae-8990-d193d01095c0 + type: title + task: + id: 4b384f12-dc73-45ae-8990-d193d01095c0 + version: -1 + name: Attachment Information + description: Set multiple keys/values to the context. + type: title + iscommand: false + brand: "" + nexttasks: + '#none#': + - "26" + - "27" + - "28" + - "29" + - "30" + - "31" + separatecontext: false + view: |- + { + "position": { + "x": 2370, + "y": 1660 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "26": + id: "26" + taskid: 67edc7b4-d501-4e1c-81f6-81ad153677cb + type: regular + task: + id: 67edc7b4-d501-4e1c-81f6-81ad153677cb + version: -1 + name: Save number of attachments + description: Saves the number of attachments in the email. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Count + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + transformers: + - operator: count + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 1760, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "27": + id: "27" + taskid: d105cce8-ab7c-4719-8962-c91351b8f245 + type: regular + task: + id: d105cce8-ab7c-4719-8962-c91351b8f245 + version: -1 + name: Save attachment extensions + description: Saves the email attachment extensions. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Extension + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + accessor: Extension + transformers: + - operator: join + args: + separator: + value: + simple: ', ' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 1360, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "28": + id: "28" + taskid: 8c120a38-8df9-4f1f-872b-53bd062b968c + type: regular + task: + id: 8c120a38-8df9-4f1f-872b-53bd062b968c + version: -1 + name: Save attachment MD5 hashes + description: Saves the email attachment MD5 hashes. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Hash + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + accessor: MD5 + transformers: + - operator: join + args: + separator: + value: + simple: ', ' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 2167.5, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "29": + id: "29" + taskid: a1330e9f-c433-42f9-8593-ca456d69dab6 + type: regular + task: + id: a1330e9f-c433-42f9-8593-ca456d69dab6 + version: -1 + name: Save attachment names + description: Saves the email attachment names. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Name + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + accessor: Name + transformers: + - operator: join + args: + separator: + value: + simple: ', ' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 2980, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "30": + id: "30" + taskid: 0bac780b-129b-4b4b-84df-6325cabc8431 + type: regular + task: + id: 0bac780b-129b-4b4b-84df-6325cabc8431 + version: -1 + name: Save attachment sizes + description: Saves the email attachment sizes. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Size + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + accessor: Size + transformers: + - operator: join + args: + separator: + value: + simple: ', ' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 2580, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "31": + id: "31" + taskid: 56901aa0-20e7-44b1-8ea4-a54c6ddf9185 + type: regular + task: + id: 56901aa0-20e7-44b1-8ea4-a54c6ddf9185 + version: -1 + name: Save attachment types + description: Saves the email attachment types. + scriptName: SetAndHandleEmpty + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "19" + scriptarguments: + key: + simple: Email.Attachment.Type + value: + complex: + root: File + filters: + - - operator: notIn + left: + value: + simple: File.EntryID + iscontext: true + right: + value: + simple: IncidentFiles.EntryID + iscontext: true + accessor: Type + transformers: + - operator: join + args: + separator: + value: + simple: ', ' + reputationcalc: 1 + separatecontext: false + view: |- + { + "position": { + "x": 3390, + "y": 1860 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "32": + id: "32" + taskid: d04d1f99-cc47-41a7-8b3f-2dc99f51677f + type: regular + task: + id: d04d1f99-cc47-41a7-8b3f-2dc99f51677f + version: -1 + name: Normalize Reporter Email Headers + description: This task normalizes the keys names of the headers which are different + with each client. It will assist with extracting the relevant values for the + next tasks. + scriptName: SetGridField + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "38" + scriptarguments: + columns: + simple: headername,headervalue + context_path: + simple: headers + grid_id: + simple: phishingreporteremailheaders + overwrite: + simple: "true" + sort_by: + simple: headername + unpack_nested_elements: + simple: "false" + continueonerror: true + separatecontext: false + view: |- + { + "position": { + "x": 380, + "y": 530 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "33": + id: "33" + taskid: a353acb2-9257-4df4-8af5-63f652d7a3ed + type: regular + task: + id: a353acb2-9257-4df4-8af5-63f652d7a3ed + version: -1 + name: Extract Reporter Email Headers + description: Preserves the original state of reporter's headers, which are stored + in the context. + scriptName: Set + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "32" + scriptarguments: + key: + simple: headers + value: + complex: + root: incident + accessor: phishingreporteremailheaders + separatecontext: false + view: |- + { + "position": { + "x": 380, + "y": 365 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "34": + id: "34" + taskid: d9b2f7bd-fa99-4fea-8655-8e859fa2cd0a + type: playbook + task: + id: d9b2f7bd-fa99-4fea-8655-8e859fa2cd0a + version: -1 + name: Get Original Email - Generic v2 + description: |- + Use this playbook to retrieve the original email in the thread, including headers and attahcments, when the reporting user forwarded the original email not as an attachment. + + You must have the necessary permissions in your email service to execute global search. + + - EWS: eDiscovery + - Gmail: Google Apps Domain-Wide Delegation of Authority + - MSGraph: As described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + playbookName: Get Original Email - Generic v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "36" + scriptarguments: + EmailSubject: + complex: + root: inputs.Thread-Topic + MessgaeID: + complex: + root: inputs.MessageID + UserID: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": -30, + "y": 690 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "36": + id: "36" + taskid: 838269c2-4da2-4b5b-8734-7f1d86422cfe + type: condition + task: + id: 838269c2-4da2-4b5b-8734-7f1d86422cfe + version: -1 + name: Do we have original emails attached? + description: Identifies whether the incident includes an email message attached + as an eml or msg file and returns the answer to a playbook. Also saves the + identified entry ID to context for later use. Commonly used in automated playbooks + that handle phishing reports sent to a special phishing mailbox set up by + the security team. + scriptName: IdentifyAttachedEmail + type: condition + iscommand: false + brand: "" + nexttasks: + "no": + - "18" + "yes": + - "3" + scriptarguments: + entryid: + simple: ${File.EntryID} + reputationcalc: 1 + results: + - reportedemailentryid + separatecontext: false + view: |- + { + "position": { + "x": 180, + "y": 885 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "37": + id: "37" + taskid: 25a645a6-540d-447d-8de9-fc3ae16bc466 + type: regular + task: + id: 25a645a6-540d-447d-8de9-fc3ae16bc466 + version: -1 + name: Display email headers in layout - Email.HeadersMap + description: Fills the "Email Headers" grid field in the incident layout with + the retrieved email headers. + scriptName: SetGridField + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "11" + scriptarguments: + columns: + simple: headername,headervalue + context_path: + simple: ExtractedHeadersMap + grid_id: + simple: emailheaders + overwrite: + simple: "true" + sort_by: + simple: headername + unpack_nested_elements: + simple: "true" + continueonerror: true + separatecontext: false + view: |- + { + "position": { + "x": 790, + "y": 2020 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "38": + id: "38" + taskid: 60428e3a-d35f-4be9-852e-1834a3055810 + type: playbook + task: + id: 60428e3a-d35f-4be9-852e-1834a3055810 + version: -1 + name: Get Original Email - Generic v2 + description: |- + Use this playbook to retrieve the original email in the thread, including headers and attahcments, when the reporting user forwarded the original email not as an attachment. + + You must have the necessary permissions in your email service to execute global search. + + - EWS: eDiscovery + - Gmail: Google Apps Domain-Wide Delegation of Authority + - MSGraph: As described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + playbookName: Get Original Email - Generic v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "36" + scriptarguments: + EmailBrand: + complex: + root: incident + accessor: sourceBrand + EmailSubject: + complex: + root: incident.phishingreporteremailheaders + filters: + - - operator: isEqualString + left: + value: + simple: incident.phishingreporteremailheaders.headername + iscontext: true + right: + value: + simple: Thread-Topic + accessor: headervalue + MessgaeID: + complex: + root: incident.phishingreporteremailheaders + filters: + - - operator: isEqualString + left: + value: + simple: incident.phishingreporteremailheaders.headername + iscontext: true + right: + value: + simple: In-Reply-To + accessor: headervalue + UserID: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": 380, + "y": 695 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "39": + id: "39" + taskid: 2113716f-6e64-4016-8a79-99704e0f558a + type: condition + task: + id: 2113716f-6e64-4016-8a79-99704e0f558a + version: -1 + name: Check if attachments were found in eml file + description: Checks if attachments were found in an eml file to display their + details in the layout. + type: condition + iscommand: false + brand: "" + nexttasks: + '#default#': + - "21" + "yes": + - "22" + separatecontext: false + conditions: + - label: "yes" + condition: + - - operator: isNotEmpty + left: + value: + complex: + root: Email + accessor: AttachmentNames + iscontext: true + view: |- + { + "position": { + "x": 660, + "y": 1240 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "40": + id: "40" + taskid: 49bc5e00-458f-4a76-8b78-7a6722b1a655 + type: regular + task: + id: 49bc5e00-458f-4a76-8b78-7a6722b1a655 + version: -1 + name: Set ExtractedHeadersMap + description: Set a value in context under the key you entered. + scriptName: Set + type: regular + iscommand: false + brand: "" + nexttasks: + '#none#': + - "37" + scriptarguments: + key: + simple: ExtractedHeadersMap + value: + complex: + root: Email.HeadersMap + filters: + - - operator: isNotEmpty + left: + value: + simple: Email.HeadersMap + iscontext: true + separatecontext: false + view: |- + { + "position": { + "x": 790, + "y": 1850 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +system: true +view: |- + { + "linkLabelsPosition": { + "16_2_#default#": 0.28, + "16_34_Yes-Alerts": 0.45, + "18_22_Email Exist": 0.38, + "23_24_yes": 0.49, + "4_5_yes": 0.57 + }, + "paper": { + "dimensions": { + "height": 3415, + "width": 4030, + "x": -260, + "y": -510 + } + } + } +inputs: +- key: File + value: + complex: + root: File + required: false + description: An EML or MSG file with + playbookInputQuery: +- key: Email + value: + complex: + root: incident + accessor: emailto + required: false + description: The receiving email address. + playbookInputQuery: +- key: EmailCC + value: + complex: + root: incident + accessor: emailcc + required: false + description: CC addresses. + playbookInputQuery: +- key: EmailFrom + value: + complex: + root: incident + accessor: emailfrom + required: false + description: The originator of the email. + playbookInputQuery: +- key: EmailSubject + value: + complex: + root: incident + accessor: emailsubject + required: false + description: The email’s subject. + playbookInputQuery: +- key: EmailText + value: + complex: + root: incident + accessor: emailbody + required: false + description: The email’s text. + playbookInputQuery: +- key: EmailHtml + value: + complex: + root: incident + accessor: emailhtml + required: false + description: The email’s html. + playbookInputQuery: +- key: EmailHeaders + value: + complex: + root: incident + accessor: phishingreporteremailheaders + required: false + description: The email’s headers. + playbookInputQuery: +- key: EmailFormat + value: + complex: + root: incident + accessor: emailformat + required: false + description: The email’s format. + playbookInputQuery: +- key: GetOriginalEmail + value: + simple: "False" + required: false + description: |- + Retrieves the original email in the thread. Default is "False". + + You must have the necessary permissions in your email service to execute global search. + + - EWS: eDiscovery + - Gmail: Google Apps Domain-Wide Delegation of Authority + - MSGraph: As described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + playbookInputQuery: +- key: MessageID + value: {} + required: false + description: The original email message id to retrieve. Holds the value of the "Message-ID" + header of the original email. This value will be passed as an input to the playbook + "Get Original Email - Generic v2" + playbookInputQuery: +- key: UserID + value: + complex: + root: incident + accessor: emailfrom + transformers: + - operator: replaceMatch + args: + regex: + value: + simple: (?i).*<([A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,})> + replaceWith: + value: + simple: $1 + required: false + description: The user's email address for which to retrieve the original email. + This value will be passed as an input to the playbook "Get Original Email - Generic + v2". + playbookInputQuery: +- key: Thread-Topic + value: {} + required: false + description: The value of the "Thread-Topic" header which holds the original email + subject. This is necessary for forwarded emails scenarios. It will be passed as + an input to the "Get Original Email - Generic v2" playbook to be used in the relevant + sub-playbooks. + playbookInputQuery: +outputs: +- contextPath: Email.HTML + description: Email 'html' body if exists. + type: string +- contextPath: Email + description: Email object. + type: string +- contextPath: Email.CC + description: Email 'cc' addresses. + type: string +- contextPath: Email.From + description: Email 'from' sender. + type: string +- contextPath: Email.Subject + description: Email subject. + type: string +- contextPath: Email.To + description: Email 'to' addresses. + type: string +- contextPath: Email.Text + description: Email 'text' body if exists. + type: string +- contextPath: Email.Headers + description: The full email headers as a single string. + type: string +- contextPath: Email.Attachments + description: The list of attachment names in the email. + type: string +- contextPath: Email.Format + description: The format of the email if available. + type: string +- contextPath: File + description: The File object. + type: string +tests: +- Process Email - Generic - Test - Incident Starter +fromversion: 6.1.0 diff --git a/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2_README.md b/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2_README.md new file mode 100644 index 000000000000..fff1c03121f1 --- /dev/null +++ b/Packs/Phishing/Playbooks/Process_Email_-_Generic_v2_README.md @@ -0,0 +1,67 @@ +Add email details to the relevant context entities and handle the case where original emails are attached. + +Added on this v2 playbook: +- Uses incident fields and not incident labels. +- Provides separate paths to "Phishing Alerts". +- Uses the new "Get Original Email - Generic v2" playbook to retrieve original emails as eml files for both EWS v2 and Microsoft Graph Mail integration. This will assist with parsing the email artifacts in a more efficient way. + + +## Dependencies +This playbook uses the following sub-playbooks, integrations, and scripts. + +### Sub-playbooks +* Get Original Email - Generic v2 + +### Integrations +This playbook does not use any integrations. + +### Scripts +* SetGridField +* Set +* SetAndHandleEmpty +* ParseEmailFiles +* IdentifyAttachedEmail + +### Commands +* rasterize-email +* setIncident + +## Playbook Inputs +--- + +| **Name** | **Description** | **Default Value** | **Required** | +| --- | --- | --- | --- | +| File | An EML or MSG file. | File.None | Optional | +| Email | The receiving email address. | incident.emailto | Optional | +| EmailCC | CC addresses. | incident.emailcc | Optional | +| EmailFrom | The originator of the email. | incident.emailfrom | Optional | +| EmailSubject | The email’s subject. | incident.emailsubject | Optional | +| EmailText | The email’s text. | incident.emailbody | Optional | +| EmailHtml | The email’s html. | incident.emailhtml | Optional | +| EmailHeaders | The email’s headers. | incident.phishingreporteremailheaders | Optional | +| EmailFormat | The email’s format. | incident.emailformat | Optional | +| GetOriginalEmail | Retrieve the original email in the thread. Default is "False".

You must have the necessary permissions in your email service to execute global search.

- EWS: eDiscovery
- Gmail: Google Apps Domain-Wide Delegation of Authority
- MSGraph: As described here:
\* https://docs.microsoft.com/en-us/graph/api/message-get
\* https://docs.microsoft.com/en-us/graph/api/user-list-messages | False | Optional | +| MessageID | The original email message id to retrieve. This should hold the value of the "Message-ID" header of the original email. This value will be passed as an input to the playbook "Get Original Email - Generic v2" | | Optional | +| UserID | The user's email address for which to retrieve the original email. This value will be passed as an input to the playbook "Get Original Email - Generic v2". | incident.emailfrom | Optional | +| Thread-Topic | The value of the "Thread-Topic" header which holds the original email subject. This is necessary for forwarded emails scenarios. It will be passed as an input to the "Get Original Email - Generic v2" playbook to be used in the relevant sub-playbooks. | | Optional | + +## Playbook Outputs +--- + +| **Path** | **Description** | **Type** | +| --- | --- | --- | +| Email.HTML | Email 'html' body if exists. | string | +| Email | Email object. | string | +| Email.CC | Email 'cc' addresses. | string | +| Email.From | Email 'from' sender. | string | +| Email.Subject | Email subject. | string | +| Email.To | Email 'to' addresses. | string | +| Email.Text | Email 'text' body if exists. | string | +| Email.Headers | The full email headers as a single string. | string | +| Email.Attachments | The list of attachment names in the email. | string | +| Email.Format | The format of the email if available. | string | +| File | The File object. | string | + +## Playbook Image +--- +![Process Email - Generic v2](../doc_files/Process_Email_-_Generic_v2.png) diff --git a/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2.yml b/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2.yml new file mode 100644 index 000000000000..c8b824364bd4 --- /dev/null +++ b/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2.yml @@ -0,0 +1,408 @@ +id: Get Original Email - Generic v2 +version: -1 +contentitemexportablefields: + contentitemfields: {} +name: Get Original Email - Generic v2 +description: |- + This v2 playbook is being used inside the "Phishing" flow. It will retrieve an original mail based on the inputs. + + The inputs in this version are not using any labels and also allow the user to supply an email brand. + + You must have the necessary permissions in your email service to execute global search. + + - EWS: eDiscovery + - Gmail: Google Apps Domain-Wide Delegation of Authority + - MSGraph: As described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages +starttaskid: "0" +tasks: + "0": + id: "0" + taskid: 6baf77d7-3f70-422a-83ce-93358e3cd5de + type: start + task: + id: 6baf77d7-3f70-422a-83ce-93358e3cd5de + version: -1 + name: "" + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "13" + separatecontext: false + view: |- + { + "position": { + "x": -130, + "y": -270 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "3": + id: "3" + taskid: ecc651e4-02b6-4a33-83d6-e2cab8198ece + type: title + task: + id: ecc651e4-02b6-4a33-83d6-e2cab8198ece + version: -1 + name: Done + type: title + iscommand: false + brand: "" + description: '' + separatecontext: false + view: |- + { + "position": { + "x": -130, + "y": 390 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "10": + id: "10" + taskid: 748c9413-daec-465d-8062-b7bae35a5edd + type: playbook + task: + id: 748c9413-daec-465d-8062-b7bae35a5edd + version: -1 + name: Get Original Email - Microsoft Graph Mail + description: |- + Use this playbook to retrieve the original email in the thread as eml file when the reporting user forwarded the original email not as an attachment. + + You must have the necessary permissions in the Microsoft Graph Mail integration as described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + playbookName: Get Original Email - Microsoft Graph Mail + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "3" + scriptarguments: + MessageID: + complex: + root: inputs.MessgaeID + ThreadTopic: + complex: + root: inputs.EmailSubject + UserID: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": -1300, + "y": 220 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "11": + id: "11" + taskid: a6705ddd-01c1-45ea-8766-d463c27664a4 + type: playbook + task: + id: a6705ddd-01c1-45ea-8766-d463c27664a4 + version: -1 + name: Get Original Email - EWS v2 + description: |- + Use this playbook to retrieve the original email in the thread (as eml file), when the reporting user forwarded the original email not as an attachment. + + You must have the necessary permissions in the EWS integration to execute global search: eDiscovery + playbookName: Get Original Email - EWS v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "3" + scriptarguments: + MessageID: + complex: + root: inputs.MessgaeID + TargetMailbox: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": -820, + "y": 220 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "12": + id: "12" + taskid: 5401737b-c8e8-4394-8518-2957e73d8260 + type: playbook + task: + id: 5401737b-c8e8-4394-8518-2957e73d8260 + version: -1 + name: Get Original Email - Gmail v2 + description: | + Unlike the previous version of this playbook, this will use the reporter email headers in order to retrieve the original email. This will assist with decreasing the amount of the tasks needed in order to do that. + Use this playbook to retrieve the original email in the thread, including headers and attachments, when the reporting user forwarded the original email not as an attachment. + + You must have the necessary permissions in your Gmail service to execute global search: Google Apps Domain-Wide Delegation of Authority + playbookName: Get Original Email - Gmail v2 + type: playbook + iscommand: false + brand: "" + nexttasks: + '#none#': + - "3" + scriptarguments: + MessageID: + complex: + root: inputs.MessgaeID + UserID: + complex: + root: inputs.UserID + separatecontext: true + loop: + iscommand: false + exitCondition: "" + wait: 1 + max: 100 + view: |- + { + "position": { + "x": -340, + "y": 220 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "13": + id: "13" + taskid: 1f43899f-c0b2-4543-8466-27514587c289 + type: condition + task: + id: 1f43899f-c0b2-4543-8466-27514587c289 + version: -1 + name: Check EmailBrand + type: condition + iscommand: false + brand: "" + description: Check if "EmailBrand" has a valid value. + nexttasks: + '#default#': + - "14" + EWS v2: + - "11" + Gmail: + - "12" + MSGraph: + - "10" + separatecontext: false + conditions: + - label: Gmail + condition: + - - operator: isEqualString + left: + value: + complex: + root: inputs.EmailBrand + iscontext: true + right: + value: + simple: Gmail + - label: EWS v2 + condition: + - - operator: isEqualString + left: + value: + complex: + root: inputs.EmailBrand + iscontext: true + right: + value: + simple: EWS v2 + - label: MSGraph + condition: + - - operator: isEqualString + left: + value: + complex: + root: inputs.EmailBrand + iscontext: true + right: + value: + simple: MicrosoftGraphMail + view: |- + { + "position": { + "x": -130, + "y": -120 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false + "14": + id: "14" + taskid: bf9f5223-a55a-4906-8512-7cca469cbe66 + type: title + task: + id: bf9f5223-a55a-4906-8512-7cca469cbe66 + version: -1 + name: No brand - run all + type: title + iscommand: false + brand: "" + description: '' + nexttasks: + '#none#': + - "10" + - "11" + - "12" + separatecontext: false + view: |- + { + "position": { + "x": -130, + "y": 70 + } + } + note: false + timertriggers: [] + ignoreworker: false + skipunavailable: false + quietmode: 0 + isoversize: false + isautoswitchedtoquietmode: false +system: true +view: |- + { + "linkLabelsPosition": { + "13_10_MSGraph": 0.9, + "13_11_EWS v2": 0.9, + "13_12_Gmail": 0.85 + }, + "paper": { + "dimensions": { + "height": 725, + "width": 1550, + "x": -1300, + "y": -270 + } + } + } +inputs: +- key: MessgaeID + value: {} + required: false + description: The original email message id to retrieve. This should hold the value + of the "Message-ID" header of the original email. + playbookInputQuery: +- key: UserID + value: {} + required: false + description: The email address of the user for which to fetch the original email. + the authenticated user (gmail). + playbookInputQuery: +- key: EmailSubject + value: {} + required: false + description: The original email subject. + playbookInputQuery: +- key: EmailBrand + value: {} + required: false + description: |- + When this value supplied, only the relevant playbook will run. + Possible values: + - Gmail + - EWS v2 + - MicrosoftGraphMail + + If none of the above values is supplied, all of the playbooks will run. + playbookInputQuery: +outputs: +- contextPath: Email + description: The email object + type: string +- contextPath: File + description: Original attachments + type: string +- contextPath: Email.To + description: The recipient of the email + type: string +- contextPath: Email.From + description: The sender of the email + type: string +- contextPath: Email.CC + description: The CC address of the email + type: string +- contextPath: Email.BCC + description: The BCC address of the email + type: string +- contextPath: Email.HTML + description: The email HTML + type: string +- contextPath: Email.Body + description: The email text body + type: string +- contextPath: Email.Headers + description: The email headers + type: string +- contextPath: Email.Subject + description: The email subject + type: string +- contextPath: Email.HeadersMap + description: The headers of the email. +- contextPath: reportedemailentryid + description: In case the original eml was retrieved, this field will hold the File's + Entry ID. + type: string +tests: +- No tests (auto formatted) +fromversion: 6.1.0 diff --git a/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2_README.md b/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2_README.md new file mode 100644 index 000000000000..312c3e86b5a0 --- /dev/null +++ b/Packs/Phishing/Playbooks/playbook-Get_Original_Email_-_Generic_v2_README.md @@ -0,0 +1,60 @@ +This v2 playbook is being used inside the "Phishing" flow. It will retrieve an original mail based on the inputs. + +The inputs in this version are not using any labels and also allow the user to supply an email brand. + +You must have the necessary permissions in your email service to execute global search. + +- EWS: eDiscovery +- Gmail: Google Apps Domain-Wide Delegation of Authority +- MSGraph: As described here: + * https://docs.microsoft.com/en-us/graph/api/message-get + * https://docs.microsoft.com/en-us/graph/api/user-list-messages + +## Dependencies +This playbook uses the following sub-playbooks, integrations, and scripts. + +### Sub-playbooks +* Get Original Email - Microsoft Graph Mail +* Get Original Email - Gmail v2 +* Get Original Email - EWS v2 + +### Integrations +This playbook does not use any integrations. + +### Scripts +This playbook does not use any scripts. + +### Commands +This playbook does not use any commands. + +## Playbook Inputs +--- + +| **Name** | **Description** | **Default Value** | **Required** | +| --- | --- | --- | --- | +| MessgaeID | The original email message id to retrieve. This should hold the value of the "Message-ID" header of the original email. | | Optional | +| UserID | The email address of the user for which to fetch the original email. | | Optional | +| EmailSubject | The original email subject. | | Optional | +| EmailBrand | When this value is supplied only the relevant playbook will run.
Possible values:
- Gmail
- EWS v2
- MicrosoftGraphMail

If none of the above values is supplied, all of the playbooks will run. | | Optional | + +## Playbook Outputs +--- + +| **Path** | **Description** | **Type** | +| --- | --- | --- | +| Email | The email object | string | +| File | Original attachments | string | +| Email.To | The recipient of the email | string | +| Email.From | The sender of the email | string | +| Email.CC | The CC address of the email | string | +| Email.BCC | The BCC address of the email | string | +| Email.HTML | The email HTML | string | +| Email.Body | The email text body | string | +| Email.Headers | The email headers | string | +| Email.Subject | The email subject | string | +| Email.HeadersMap | The headers of the email. | string | +| reportedemailentryid | In case the original eml was retrieved, this field will hold the File's Entry ID. | unknown | + +## Playbook Image +--- +![Get Original Email - Generic v2](../doc_files/Get_Original_Email_-_Generic_v2.png) diff --git a/Packs/Phishing/ReleaseNotes/2_5_0.md b/Packs/Phishing/ReleaseNotes/2_5_0.md new file mode 100644 index 000000000000..3529cd55983f --- /dev/null +++ b/Packs/Phishing/ReleaseNotes/2_5_0.md @@ -0,0 +1,30 @@ + +#### Incident Fields +- Added the **Phishing Reporter Email Headers** field, which represents the headers of the reporter's email. + +#### Playbooks +##### Phishing Investigation - Generic v2 +- Removing "Domain" input from task 53 since it is not needed and may cause a failure of the workflow due to late field extraction. +- Adding a task to extract the "ReporterAddress" field correctly before storing it in the context. + +##### New: Process Email - Generic v2 +This is a new version of the playbook (Available from Cortex XSOAR 6.1.0). Its functionality is the same as the previous version with these changes: +- Changing incident labels to incident fields. +- A new task was added to extract email artifacts when retrieving the original eml file. +- Removing indicators extraction inside tasks where unnecessary. +- Use the "Get Original Email - Generic v2" playbook. +- Adding 3 playbook inputs that will be passed to the new "Get Original Email - Generic v2" playbook: MessageID, UserID, ThreadTopic. + These inputs will assist with generalizing the playbook in order to support other phishing scenarios as well. + +##### New: Get Original Email - Generic v2 +This is a new version of the playbook. Its functionality is the same as the previous version with these changes: + +- Removing existing playbook inputs and adding 4 new ones: MessageID, UserID, ThreadTopic, EmailBrand. + These inputs assist with generalizing the playbook to support other phishing scenarios as well and also to allow the user to choose a specific email brand. +- Adding the new playbook "Get Original Email - Microsoft Graph Mail" to the flow. +- Using the new EWS playbook "Get Original Email - EWS v2" instead of the previous one. +- Using the new Gmail playbook "Get Original Email - Gmail v2" instead of the previous one. + +#### Incident Types +##### Phishing +- Changing the "On incident creation" under the "Indicators Extraction Rules" to "Inline". This will extract indicators when the incident is created. diff --git a/Packs/Phishing/doc_files/Get_Original_Email_-_Generic_v2.png b/Packs/Phishing/doc_files/Get_Original_Email_-_Generic_v2.png new file mode 100644 index 000000000000..2ada702d3173 Binary files /dev/null and b/Packs/Phishing/doc_files/Get_Original_Email_-_Generic_v2.png differ diff --git a/Packs/Phishing/doc_files/Get_Original_Email_Gmail.png b/Packs/Phishing/doc_files/Get_Original_Email_Gmail.png deleted file mode 100644 index cee13a1eedd4..000000000000 Binary files a/Packs/Phishing/doc_files/Get_Original_Email_Gmail.png and /dev/null differ diff --git a/Packs/Phishing/doc_files/Phishing_Investigation_-_Generic_v2_-_6_0.png b/Packs/Phishing/doc_files/Phishing_Investigation_-_Generic_v2_-_6_0.png index 745454a479e2..2a29b823ce89 100644 Binary files a/Packs/Phishing/doc_files/Phishing_Investigation_-_Generic_v2_-_6_0.png and b/Packs/Phishing/doc_files/Phishing_Investigation_-_Generic_v2_-_6_0.png differ diff --git a/Packs/Phishing/doc_files/Process_Email_-_Generic_v2.png b/Packs/Phishing/doc_files/Process_Email_-_Generic_v2.png new file mode 100644 index 000000000000..fe70b6493a18 Binary files /dev/null and b/Packs/Phishing/doc_files/Process_Email_-_Generic_v2.png differ diff --git a/Packs/Phishing/pack_metadata.json b/Packs/Phishing/pack_metadata.json index e6dadb726ace..dc6e3068ad42 100644 --- a/Packs/Phishing/pack_metadata.json +++ b/Packs/Phishing/pack_metadata.json @@ -2,7 +2,7 @@ "name": "Phishing", "description": "Phishing emails still hooking your end users? This Content Pack can drastically reduce the time your security team spends on phishing alerts.", "support": "xsoar", - "currentVersion": "2.4.4", + "currentVersion": "2.5.0", "serverMinVersion": "6.0.0", "author": "Cortex XSOAR", "url": "https://www.paloaltonetworks.com/cortex", diff --git a/Tests/conf.json b/Tests/conf.json index 1dd891564111..a75d45ab1cb6 100644 --- a/Tests/conf.json +++ b/Tests/conf.json @@ -4624,6 +4624,29 @@ "timeout": 2400 }, { + "playbookID": "Get Original Email - Microsoft Graph Mail - test", + "fromversion": "6.1.0", + "integrations": [ + "MicrosoftGraphMail" + ], + "instance_names": "ms_graph_mail_dev_no_oproxy" + }, + { + "playbookID": "Get Original Email - Gmail v2 - test", + "fromversion": "6.1.0", + "integrations": [ + "Gmail" + ] + }, + { + "playbookID": "Get Original Email - EWS v2 - test", + "fromversion": "6.1.0", + "integrations": [ + "EWS v2" + ], + "instance_names": "ewv2_regular" + }, + { "integrations": [ "Demisto REST API" ],