ParseEmailFilesV2
Parse an email from an eml or msg file and populate all relevant context data to investigate the email. Also extracts inner attachments and returns them to the war room. The incident labels themselves are preserved and not modified - only the "Label/x" context items that originated from the labels, and the best practice is to rely on these for the remainder of the playbook. This script is based on the parse-emails XSOAR python package, check the script documentation for more info.
python · Common Scripts
Details
| ID | ParseEmailFilesV2 |
|---|---|
| Language | python |
| From Version | 5.0.0 |
| Docker Image | demisto/parse-emails:0.1.48.10120494 |
| Tags | email phishing enhancement file |
README
Parse an email from an eml or msg file and populate all relevant context data to investigate the email. Also extracts inner attachments and returns them to the war room. The incident labels themselves are preserved and not modified - only the “Label/x” context items that originated from the labels, and the best practice is to rely on these for the remainder of the playbook.
This script is based on the parse-emails XSOAR python package, check the script documentation for more info.
Script Data
| Name | Description |
|---|---|
| Script Type | python3 |
| Tags | email, phishing, enhancement, file |
Inputs
| Argument Name | Description |
|---|---|
| entryid | Entry ID with the Email as a file in msg or eml format |
| parse_only_headers | Will parse only the headers and return headers table |
| max_depth | How many levels deep we should parse the attached emails (e.g. email contains an emails contains an email). Default depth level is 3. Minimum level is 1, if set to 1 the script will parse only the first level email |
| nesting_level_to_return | In case of nested email files (for instance, an EML file inside an EML file), determines which of the email files to return as an output. “All files” - will return all nested email files as output, “Outer file” - will return only the “outer” email file as output, “Inner file” - will return only the most “inner” email file as output. In case “Inner file” was chosen together with the ‘max_depth’ argument, the inner email will be considered as the email in the depth of the max_size argument. |
Outputs
| Path | Description | Type |
|---|---|---|
| Email.To | This shows to whom the message was addressed, but may not contain the recipient’s address. | string |
| Email.CC | Email ‘cc’ addresses | string |
| Email.From | This displays who the message is from, however, this can be easily forged and can be the least reliable. | string |
| Email.Subject | Email subject | string |
| Email.HTML | Email ‘html’ body if exists | string |
| Email.Text | Email ‘text’ body if exists | string |
| Email.Depth | The depth of the email. Depth=0 for the first level email. If email1 contains email2 contains email3. Then email1 depth is 0, email2 depth is 1, email3 depth is 2 | number |
| Email.Headers | Deprecated - use Email.HeadersMap output instead. The full email headers as a single string | string |
| Email.HeadersMap | The full email headers json | Unknown |
| Email.HeadersMap.From | This displays who the message is from, however, this can be easily forged and can be the least reliable. | Unknown |
| Email.HeadersMap.To | This shows to whom the message was addressed, but may not contain the recipient’s address. | Unknown |
| Email.HeadersMap.Subject | Email subject | String |
| Email.HeadersMap.Date | The date and time the email message was composed | Unknown |
| Email.HeadersMap.CC | Email ‘cc’ addresses | Unknown |
| Email.HeadersMap.Reply-To | The email address for return mail | String |
| Email.HeadersMap.Received | List of all the servers/computers through which the message traveled | String |
| Email.HeadersMap.Message-ID | A unique string assigned by the mail system when the message is first created. These can easily be forged. (e.g. 5c530c1b.1c69fb81.bd826.0eff@mx.google.com) | String |
| Email.AttachmentsData.Name | The name of the attachment | String |
| Email.AttachmentsData.Content-ID | The content-id of the attachment | String |
| Email.AttachmentsData.Content-Disposition | The content-disposition of the attachment | String |
| Email.AttachmentsData.FilePath | the location of the attachment, on the XSOAR server | String |
| Email.AttachmentNames | The list of attachment names in the email | string |
| Email.Format | The format of the email if available | string |
Notes
We handle EML and MSG parsing differently when the email contains HTML.
- If it’s an EML and it has the content-type of text/html, the content of the body will be stored in the html field.
- If it’s an MSG, we store the text inside the HTML in the text field and the HTML in the html field.
args: - default: true description: Entry ID with the Email as a file in msg or eml format. name: entryid required: true - auto: PREDEFINED defaultValue: "false" description: Will parse only the headers and return them as a table. Regardless of the `nesting_level_to_return` parameter, only the headers of the outermost email file will be included. name: parse_only_headers predefined: - "true" - "false" - defaultValue: "3" description: How many levels deep we should parse the attached emails (e.g. email contains an emails contains an email). Default depth level is 3. Minimum level is 1, if set to 1 the script will parse only the first level email. name: max_depth - defaultValue: "All files" description: In case of nested email files (for instance, an EML file inside an EML file), determines which of the email files to return as an output. "All files" - will return all nested email files as output, "Outer file" - will return only the "outer" email file as output, "Inner file" - will return only the most "inner" email file as output. In case "Inner file" was chosen together with the 'max_depth' argument, the inner email will be considered as the email in the depth of the `max_size` argument. name: nesting_level_to_return auto: PREDEFINED predefined: - "All files" - "Outer file" - "Inner file" - name: forced_encoding description: Use only the force encoding when parsing the message, e.g 'iso-2022-jp'. Relevant to msg files only. - name: default_encoding description: Use only the default encoding when parsing the message with the detected encoding fails, e.g 'utf-8'. Relevant to msg files only. comment: Parse an email from an eml or msg file and populate all relevant context data to investigate the email. Also extracts inner attachments and returns them to the war room. The incident labels themselves are preserved and not modified - only the "Label/x" context items that originated from the labels, and the best practice is to rely on these for the remainder of the playbook. This script is based on the parse-emails XSOAR python package, check the script documentation for more info. commonfields: id: ParseEmailFilesV2 version: -1 enabled: true name: ParseEmailFilesV2 outputs: - contextPath: Email.To description: This shows to whom the message was addressed, but may not contain the recipient's address. type: string - contextPath: Email.CC description: Email 'cc' addresses. type: string - contextPath: Email.BCC description: Email 'bcc' addresses. type: string - contextPath: Email.From description: This displays who the message is from, however, this can be easily forged and can be the least reliable. type: string - contextPath: Email.Subject description: Email subject. type: string - contextPath: Email.HTML description: Email 'html' body if exists. type: string - contextPath: Email.HTMLUnescape description: The HTML body with all HTML entities decoded (e.g. '&' becomes '&'). Use this field for indicator extraction from HTML emails to ensure URLs and other indicators are correctly formed. type: string - contextPath: Email.Text description: Email 'text' body if exists. type: string - contextPath: Email.Depth description: The depth of the email. Depth=0 for the first level email. If email1 contains email2 contains email3. Then email1 depth is 0, email2 depth is 1, email3 depth is 2. type: number - contextPath: Email.Headers description: Deprecated - use Email.HeadersMap output instead. The full email headers as a single string. type: string - contextPath: Email.HeadersMap description: The full email headers json. type: Unknown - contextPath: Email.HeadersMap.From description: This displays who the message is from, however, this can be easily forged and can be the least reliable. type: Unknown - contextPath: Email.HeadersMap.To description: This shows to whom the message was addressed, but may not contain the recipient's address. type: Unknown - contextPath: Email.HeadersMap.Subject description: Email subject. type: String - contextPath: Email.HeadersMap.Date description: The date and time the email message was composed. type: Unknown - contextPath: Email.HeadersMap.CC description: Email 'cc' addresses. type: Unknown - contextPath: Email.HeadersMap.Reply-To description: The email address for return mail. type: String - contextPath: Email.HeadersMap.Received description: List of all the servers/computers through which the message traveled. type: String - contextPath: Email.HeadersMap.Message-ID description: A unique string assigned by the mail system when the message is first created. These can easily be forged. (e.g. 5c530c1b.1c69fb81.bd826.0eff@mx.google.com). type: String - contextPath: Email.AttachmentsData.Name description: The name of the attachment. type: String - contextPath: Email.AttachmentsData.Content-ID description: The content-id of the attachment. type: String - contextPath: Email.AttachmentsData.Content-Disposition description: The content-disposition of the attachment. type: String - contextPath: Email.AttachmentsData.FilePath description: The location of the attachment, on the XSOAR server. type: String - contextPath: Email.AttachmentNames description: The list of attachment names in the email. type: string - contextPath: Email.Format description: The format of the email if available. type: string runas: DBotWeakRole script: '' scripttarget: 0 subtype: python3 tags: - email - phishing - enhancement - file type: python fromversion: 5.0.0 tests: - ParseEmailFilesV2-test dockerimage: demisto/parse-emails:0.1.48.10120494