×
Built-In: Email Nodes
Nevelex Labs Logo

Overview

The Email nodes provide the ability to convert EML (RFC 822) attachments into email messages for processing within a flow, associate email attachments to incidents, and add email attachments to the message for sending.

Functionality

The Email nodes expose the following functionality:

  • Associate attachments to an Incident’s message, remove the attachments from the incoming email message, and collect attachment meta data via the NL-Email-Attachments-Processor node.
  • Convert EML attachment files into email messages for passing through the flows via the NL-Parse-EML node.
  • Add email attachments to the message via the NL-Add-Email-Attachments node.

Flow Nodes

Utility node to remove email attachments out of an incoming email, associate the attachments with the Incident, and save the attachments within the Security Flow stack. This node should take a message from the email input node or the NL Parse EML node for processing. Other than the email input nodes, this should be the first NL node in a flow to prevent attachments from being added to a messages during creation of an Incident. Incoming emails typically contain raw text in msg.payload which is moved to msg.payload.message by this node. msg.html is the HTML content of the message. The contents of msg.payload.message and msg.html are packaged together and should be passed on to the NL-Find-IoCs node to find IoC artifacts within the message. The raw email message may contain information in msg.payload or msg.html or both.
Property
Description

Name

The display name of the node within the flows.


Excluded Attachment

If Excluded Attachment(s) is defined, any file attachment name matching the glob pattern, e.g. *.foo, will not be processed. Excluded Attachment(s), if supplied, is a glob or extended glob pattern. Any file attachment name matching the glob pattern is skipped from processing. For example, *.foo will exclude any attachment with an extension of foo. *.+(jpg|gif|png) will exclude the three supplied file extensions of jpg, gif, and png. Globbing is configured to be case insensitive.


Aggregation

This node supports five modes for aggregating incidents. With all of the aggregation modes (except None), one can provide a number of occurrences after which a closed incident will be re-opened. For example, if this value is 10 and the incident is closed, after ten more messages match the incident, the incident will be re-opened.

If aggregation is configured to Check Only, by checking Keep Incidents Separate, then aggregation checks are still performed, but the actual process of aggregating the message into a single incident does not happen. The performed flag in the aggregation section of the message is set to false.

  • None: Never aggregate any incidents (default).
  • Field Match: For a given source field of a message (or jsonata query of the message), aggregate together all messages whose field value exactly matches a previously checked message.
  • Exact Match: For a given source field of the message (or jsonata query of the message), aggregate together all messages whose field exactly matches a given value. One can specify multiple values. Each value specifies a separate grouping of incidents. Useful to aggregate messages with known content.
  • Keyword Match: For a given source field of the message (or jsonata query of the message), aggregate together all messages with a given keyword appearing as a word within the field. One can specify multiple keywords. Each keyword specifies a separate grouping of incidents. An incident is grouped with the first keyword it matches. Useful to aggregate messages with somewhat known content.
  • Fuzzy Match: For a given source field of the message (or jsonata query of the message), aggregate together all messages for which this field is sufficiently similar to the message which started the incident. With this method, one can specify a similarity threshold. Messages matched with the fuzzy matcher get a similarity attribute added to the message which can be inspected to assist when establishing a threshold.
Utility node to look for EML attachments, *.eml, in the incoming email, per RFC 822, and parse it into a format compatible with the standard email input node. Unlike most other NL-* nodes, this node does not audit its behavior. This is intentional to prevent writing large attachments into the create message audit entry of an Incident. This node must be used directly after an email input node, such as the email input node or the NL-Outlook-Email-In node. The attachments are scanned for any EML attachment. For each EML attachment, an individual email message is output on the Parsed EML output. If no EML attachments are found, the original input message is sent out the Original Email (no EML attachments) output. The output from this node should be sent to the NL-Email-Attachments-Processor node.
Property
Description

Name

The display name of the node within the flows.


Attach EML

If Attach EML evaluates to a JavaScript truthy value, an EML file is included as an attachment on the outputs of this node if the incoming message contains an EML attachment or the incoming email node, such as NL-Outlook-Email-In, was configured to retrieve the message in RFC 822 format. In the latter case, an EML file with a file name of GeneratedEml.eml is included in the attachments list. The NL-Email-Attachments-Processor, the next node in the flow, automatically associates the EML file to the message as one of the attachments. Attach EML is useful to report the message to an external service, such as Microsoft’s message analysis service.

Utility node to add files associated with the current message into the message traversing the flow, so the files can be sent via email. If there were no attachments saved via the NL Email Attachments Processor node and no other files were created and associated with this message, nothing is done by this node. The Included Attachment(s) setting takes precedence over the Excluded Attachment(s) setting. We recommend defining only one setting, but not both. If Included Attachment(s) is defined, only file names matching the glob pattern, e.g. *.foo, are added as attachments. If Exclude Attachment(s) is defined, only file names not matching the glob pattern, e.g. *.foo, are added as attachments.
Property
Description

Name

The display name of the node within the flows.


Included Attachments

Included Attachment(s), if supplied, is a glob or extended glob pattern. Only file names matching the glob pattern are included as an attachment. For example, *.foo will include only those attachments with an extension of foo. *.+(jpg|gif|png) will include the three supplied file extensions of jpg, gif, and png. Globbing is configured to be case insensitive.


Excluded Attachments

Excluded Attachment(s), if supplied, is a glob or extended glob pattern. Any file attachment name matching the glob pattern is skipped from processing. For example, *.foo will exclude any attachment with an extension of foo. *.+(jpg|gif|png) will exclude the three supplied file extensions of jpg, gif, and png. Globbing is configured to be case insensitive.

Learn More

JSON Message Format

Success

The italicized, green text is retrieved by the NL Email Attachments Processor node after passing through the NL Parse EML node. In the following example, an email with file.txt and file.eml attachments is routed out the Attachment File Hashes output.

{
  "date": "2020-07-15T19:47:10.000Z",
  "from": "###########",
  "html": "###########",
  "topic": "###########",
  "_msgid": "79d04ffe.be17d",
  "header": {
    "to": "###########",
    "date": "Wed, 15 Jul 2020 14:47:10 -0500",
    "from": "###########",
    "subject": "###########",
    "message-id": "",
    "content-type": "multipart/mixed; boundary=\"0000000000008fa7d605aa803038\"",
    "mime-version": "1.0"
  },
  "payload": {
    "attachment": {
      "md5": "790d9f299b8efc4787488511aa427b64",
      "sha1": "f0cd00bd84b5eae571c49c7d2c825194aa120b4a",
      "length": 8326,
      "sha256": "7e15ce77878f772defdd84020d9e5aaf4a71672c56cd971339bc7afac36a80ef",
      "checksum": "790d9f299b8efc4787488511aa427b64",
      "fileName": "file.txt",
      "contentType": "text/plain"
    }
  }
}
{
  "date": "2020-07-15T19:47:10.000Z",
  "from": "###########",
  "html": "###########",
  "topic": "###########",
  "_msgid": "79d04ffe.be17d",
  "header": {
    "to": "###########",
    "date": "Wed, 15 Jul 2020 14:47:10 -0500",
    "from": "###########",
    "subject": "###########",
    "message-id": "",
    "content-type": "multipart/mixed; boundary=\"0000000000008fa7d605aa803038\"",
    "mime-version": "1.0"
  },
  "payload": {
    "attachment": {
      "md5": "165e802327790ba2dde31c2e6e67c8b0",
      "sha1": "898098d0cd4e66953a3418214fa839b57030958f",
      "length": 302,
      "sha256": "6c92e3deb07af1b6d119a3bd3a225c796b03a86f484ed7ef7020bc3f8bb7568d",
      "checksum": "165e802327790ba2dde31c2e6e67c8b0",
      "fileName": "file.eml",
      "contentType": "message/rfc822"
    }
  }
}

In the following example, an email with no attachments is routed out the Email Message Without Attachments output.

{
  "date": "2020-07-16T16:56:54.000Z",
  "from": "###########",
  "html": "###########",
  "topic": "###########",
  "_msgid": "b8c34e9b.847e4",
  "header": {
    "to": "###########",
    "date": "Thu, 16 Jul 2020 11:56:54 -0500",
    "from": "###########",
    "subject": "###########",
    "message-id": "",
    "references": "",
    "in-reply-to": "",
    "content-type": "multipart/alternative; boundary=\"0000000000008508ff05aa91edc1\"",
    "mime-version": "1.0"
  },
  "payload": {
    "buffer": "www.hulu.com\n\nOn Thu, Jul 16, 2020 at 11:51 AM ##### ####### <###########> wrote:\n\n> Email nodes test.\n>\n> --\n> ##### #######\n>\n>\n>\n>\n\n-- \n##### #######\n ltr http://www.hulu.com www.hulu.com gmail_quote ltr gmail_attr On Thu, Jul 16, 2020 at 11:51 AM ##### #######  < mailto:########### ########### >  wrote: gmail_quote margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex ltr Email nodes test. all --  ltr ltr ltr ltr ltr ltr ##### ####### ltr \n all --  ltr gmail_signature ltr ltr ltr ltr ltr ##### ####### ltr \n"
  }
}
Nevelex Labs, Main Office

Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921

©Nevelex Labs, LLC. 2018-2021, All Rights Reserved.

EULA