FindEmailCampaign
Find a campaign of emails based on their textual similarity.
python · Phishing Campaign
Details
| ID | FindEmailCampaign |
|---|---|
| Language | python |
| From Version | 5.0.0 |
| Docker Image | demisto/sklearn:1.0.0.12545527 |
| Tags | ml phishing |
README
Find a campaign of emails based on their textual similarity.
This script can be executed upon each new incoming Phishing incident.
The script would search among past incidents whether past incidents with high text similarity to the current one exist. The script uses NLP techniques for calculating text similarity. The text similarity is calculated based on the email body and email subject fields of the phishing incident.
If such incidents were found, the script would aggregate details regarding them, such as their senders, recipients, dates, mutual indicators, snippets from the email, etc.
This script’s purpose is to provide you an immediate background for phishing incidents when similar incidents exist, and furthermore, help you to detect phishing campaigns more easily.
Script Data
| Name | Description |
|---|---|
| Script Type | python3 |
| Tags | ml, phishing |
| Cortex XSOAR Version | 5.0.0 |
Used In
This script is used in the following playbooks and scripts.
- Detect & Manage Phishing Campaigns
Inputs
| Argument Name | Description |
|---|---|
| incidentTypeFieldName | The name of the incident field in which the incident type is stored. Default is “type”. Change this argument only if you are using a custom field for specifying the incident type. |
| incidentTypes | A comma-separated list of incident types by which to filter. Specify “None” to search through all incident types. |
| existingIncidentsLookback | The date from which to search for similar incidents. Date format is the same as in the incidents query page. For example: “3 days ago”, “2019-01-01T00:00:00 +0200”. |
| query | Additional text by which to query incidents. |
| limit | The maximum number of incidents to fetch. |
| emailSubject | The name of the field that contains the email subject. |
| emailBody | The name of the field that contains the email body. |
| emailBodyHTML | The name of the field that contains the HTML version of the email body. |
| emailFrom | The name of the field that contains the email sender. |
| statusScope | Whether to compare the new incident to closed incidents, unclosed incidents, or all incidents. |
| threshold | Threshold by which to consider incidents as similar. The range of values is 0-1. |
| maxIncidentsToReturn | The maximum number of incidents to display as part of a campaign. If a campaign includes a higher number of incidents, the results will contain only this amount of incidents. |
| minIncidentsForCampaign | Minimum number of incidents to consider as a campaign. |
| minUniqueRecipients | Minimum number of unique recipients of similar email incidents to consider as a campaign. |
| fieldsToDisplay | A comma-seperated list of fields to display. An example is “emailclassification,closereason”. If a list of fields is provided, and a campaign is detected, these incidents fields will be displayed. |
| includeSelf | Include the current incident in EmailCampaign path in context. |
Outputs
| Path | Description | Type |
|---|---|---|
| EmailCampaign.isCampaignFound | Whether a campaign was found. | Boolean |
| EmailCampaign.involvedIncidentsCount | The number of incidents involved in the campaign. | Number |
| EmailCampaign.incidents.id | The IDs of the incidents involved in the campaign. | Unknown |
| EmailCampaign.incidents.similarity | The textual similarity of the related emails to the current incident. | Unknown |
| EmailCampaign.incidents.emailfrom | The senders of the emails involved in the campaign. | Unknown |
| EmailCampaign.incidents.emailfromdomain | The domains of the email senders involved in the campaign. | Unknown |
| EmailCampaign.incidents.recipients | A list of email addresses of recipients involved in the campaign. The list is comprised of the following fields, “Email To”, “Email CC”, “Email BCC”. | Unknown |
| EmailCampaign.incidents.recipientsdomain | A list of the domains of the email addresses of recipients involved in the campaign. The list is comprised of the following fields, “Email To”, “Email CC”, “Email BCC”. | Unknown |
| EmailCampaign.indicators.id | The IDs of the mututal indicators of the incidents involved in the campaign. | Unknown |
| EmailCampaign.indicators.value | The values of the mututal indicators of the incidents involved in the campaign. | Unknown |
| EmailCampaign.fieldsToDisplay | List of fields to display in the linked list table. | Unknown |
| EmailCampaign.firstIncidentDate | The occurrence date of the oldest incident in the campaign. | unknown |
| incident.emailcampaignsummary | Markdown table with email campaign summary. | string |
| incident.emailcampaignsnippets | Markdown table with email content summary. | string |
| incident.emailcampaignmutualindicators | Markdown table with relevant indicators. | string |
| incident.emailcampaigncanvas | Link to the campaign canvas. | string |
args: - defaultValue: type description: The name of the incident field in which the incident type is stored. Default is "type". Change this argument only if you are using a custom field for specifying the incident type. name: incidentTypeFieldName - defaultValue: Phishing description: A comma-separated list of incident types by which to filter. Specify "None" to search through all incident types. name: incidentTypes - defaultValue: 14 days ago description: 'The date from which to search for similar incidents. Date format is the same as in the incidents query page. For example: "3 days ago", "2019-01-01T00:00:00 +0200".' name: existingIncidentsLookback - description: Additional text by which to query incidents. name: query - defaultValue: '1000' description: The maximum number of incidents to fetch. name: limit - auto: PREDEFINED defaultValue: emailsubject description: The name of the field that contains the email subject. name: emailSubject predefined: - Subject of the email. - defaultValue: emailbody description: The name of the field that contains the email body. name: emailBody - defaultValue: emailbodyhtml description: The name of the field that contains the HTML version of the email body. name: emailBodyHTML - defaultValue: emailfrom description: The name of the field that contains the email sender. name: emailFrom - auto: PREDEFINED defaultValue: All description: Whether to compare the new incident to closed incidents, unclosed incidents, or all incidents. name: statusScope predefined: - All - ClosedOnly - NonClosedOnly - defaultValue: '0.8' description: Threshold by which to consider incidents as similar. The range of values is 0-1. name: threshold - defaultValue: '30' description: The maximum number of incidents to display as part of a campaign. If a campaign includes a higher number of incidents, the results will contain only this amount of incidents. name: maxIncidentsToReturn - defaultValue: '3' description: Minimum number of incidents to consider as a campaign. name: minIncidentsForCampaign - defaultValue: '2' description: Minimum number of unique recipients of similar email incidents to consider as a campaign. name: minUniqueRecipients - description: A comma-seperated list of fields to display. An example is "emailclassification,closereason". If a list of fields is provided, and a campaign is detected, these incidents fields will be displayed. name: fieldsToDisplay predefined: - '' - defaultValue: 'false' description: Include the current incident in EmailCampaign path in context. name: includeSelf predefined: - 'true' - 'false' - auto: PREDEFINED defaultValue: 'false' description: 'Whether to plot incidents-indicators relations to canvas. Default is "false". Skipping the canvas plotting stage would improve runtime. Note that canvas plotting would be skipped anyway if the number of incidents exceeds a certain threshold in order to avoid performance issues.' name: plotCanvas predefined: - 'true' - 'false' comment: Find a campaign of emails based on their textual similarity. commonfields: id: FindEmailCampaign version: -1 name: FindEmailCampaign outputs: - contextPath: EmailCampaign.isCampaignFound description: Whether a campaign was found. type: Boolean - contextPath: EmailCampaign.involvedIncidentsCount description: The number of incidents involved in the campaign. type: Number - contextPath: EmailCampaign.incidents.id description: The IDs of the incidents involved in the campaign. type: Unknown - contextPath: EmailCampaign.incidents.similarity description: The textual similarity of the related emails to the current incident. type: Unknown - contextPath: EmailCampaign.incidents.emailfrom description: The senders of the emails involved in the campaign. type: Unknown - contextPath: EmailCampaign.incidents.emailfromdomain description: The domains of the email senders involved in the campaign. type: Unknown - contextPath: EmailCampaign.incidents.recipients description: A list of email addresses of recipients involved in the campaign. The list is comprised of the following fields, "Email To", "Email CC", "Email BCC". type: Unknown - contextPath: EmailCampaign.incidents.recipientsdomain description: A list of the domains of the email addresses of recipients involved in the campaign. The list is comprised of the following fields, "Email To", "Email CC", "Email BCC". type: Unknown - contextPath: EmailCampaign.indicators.id description: The IDs of the mututal indicators of the incidents involved in the campaign. type: Unknown - contextPath: EmailCampaign.indicators.value description: The values of the mututal indicators of the incidents involved in the campaign. type: Unknown - contextPath: EmailCampaign.fieldsToDisplay description: List of fields to display in the linked list table. type: Unknown - contextPath: EmailCampaign.firstIncidentDate description: The occurrence date of the oldest incident in the campaign. type: unknown - contextPath: incident.emailcampaignsummary description: Markdown table with email campaign summary. type: string - contextPath: incident.emailcampaignsnippets description: Markdown table with email content summary. type: string - contextPath: incident.emailcampaignmutualindicators description: Markdown table with relevant indicators. type: string - contextPath: incident.emailcampaigncanvas description: Link to the campaign canvas. type: string script: '-' subtype: python3 tags: - ml - phishing timeout: '0' type: python dockerimage: demisto/sklearn:1.0.0.12545527 tests: - Detect & Manage Phishing Campaigns - Test fromversion: 5.0.0