Publisher: Splunk Community
Connector Version: 2.0.1
Product Vendor: Cofense
Product Name: Triage
Product Version Supported (regex): ".*"
Minimum Product Version: 4.9.39220
This app supports investigative actions that enable the security teams to analyze and respond to phishing faster
The asset settings page has several ingestions related settings. This app is currently written to support the ingestion of either the Cofense Triage Threat Indicators or the Cofense Triage Reports. This is set by the ingestion_method variable by a pull-down menu. If you wish to ingest both sets of data, it is suggested you set up a second Cofense Triage asset with the same credentials, but with the variable set to the other value.
1. Remaining Settings
Setting | Description | Notes |
---|---|---|
max_results | Maximum number of results retrieved during the ingestion run. | This is adjustable to any number. The practical limit is dictated by the number of API calls that your rate limit allows. Each API call will retrieve the maximum allowed of 50 results. |
start_date | The initial start date and time of the ingestion. The default is six days ago. | This setting is used only if there weren't any prior successful ingestions and were ignored afterward. If left blank, it will default to the product setting of six days ago. If one or more results are successfully ingested, the relevant date of the last ingested result is used to set the start date for the next ingestion run. It is important to set this setting to date within a range that contains data. |
date_sort | Retrieve either the oldest results first or the latest results first. | This setting is used to set which pages of results to retrieve and how they are sorted. This setting makes the observed assumption that the result ID is ordered by ascending date. ie. ID=1 is an older result than ID=2. If this setting is the Oldest first the results are retrieved and sorted with the lowest ID first. If the ingestion run of max_results does not completely exhaust this list of results, it will continue to retrieve the oldest entries until all the results are exhausted. If this setting is the latest first the results are retrieved and sorted with the highest ID first. We will ingest the newest results first and then work our way down to older results until we hit max_results or your rate limit. If older results remaining in the ingestion run, they will be ignored on the next ingestion run. This will always guarantee your latest results are ingested first at the risk of losing older results if it exceeds your max_result or rate limit. |
cef_mapping | JSON dictionary is represented as a serialized JSON string. Only applicable if ingesting new artifacts | This parameter is a JSON dictionary represented as a serialized JSON string, such as the result of json.dumps(). Each key in the dictionary is a potential key name in an artifact that is to be renamed to the value. For example, if the cef_mapping is {"website": "requestURL"} your artifact will have requestURL cef fields in place of website cef fields. |
ingestion_method | Ingestion of either Threat Indicators or Reports | User can select whether to ingest Threat Indicators or Reports |
2. Ingestion Settings for Ingesting Threat Indicators
Setting | Description | Notes |
---|---|---|
threat_type | Filter results by threat indicator type, default retrieve All. Types are; Subject, Sender, Domain, URL, MD5, SHA256. | These are applied as filters in the API call to retrieved results. You may retrieve all results or filter results by a single type. At the moment, if you wish to ingest two types, it is suggested you create a second asset. |
threat_level | Filter results by threat indicator level, default retrieve All. Levels are; Malicious, Suspicious, Benign. | Similar to the threat_type setting, these will allow either all results or filtered to a single level. |
3. Ingestion Settings for Ingesting Reports
Setting | Description | Notes |
---|---|---|
report_type | Type of reports to retrieve, default retrieve All. | Possible values are; All - All reports in Inbox, Recon, and Processed folders; Inbox - Uncategorized reports in the Inbox and Recon folders; Processed - Categorized reports in the Processed folder. Be aware that the reports in the Recon folder are ingested only if the option is All or Inbox but not Processed. Reports from the Inbox folder are unreviewed reports and therefore missing any evaluated information |
report_ingest_subfields | Only applicable if ingesting reports. This option will ingest the dictionary and list fields of the subject as additional artifacts. | If set to true, during ingestion of reports, in addition to the Report Artifact which contains the entire report as an artifact, it will extract various sub-elements and create individual artifacts for the following items; URLs, tags, rules, and attachments. |
report_match_priority | The highest match priority is based on rule hits for the report. | |
report_category_id | Filter by category ID, default retrieve All. | The category ID (1-5) for processed reports. Takes either string or number. Only valid when retrieving "All" or "Processed" reports. Category IDs correspond to category names as follows: 5 (lowest): Phishing Simulation; 1: Non-Malicious; 2: Spam; 3: Crimeware; 4 (highest): Advanced Threats. You may retrieve all results or filter results by a single category. At the moment, if you wish to ingest two categories, it is suggested you create a second asset. |
report_tags | One or more tags of processed reports to filter on. Use commas to separate multiple tags. |
NOTE : The Triage devices fetch data according to their own rules. If you look carefully at the logs or the output of the poll-now, you may see the last result from the previous ingestion, reingested and marked as a duplicate container. This is to guarantee we do not miss any results since the last ingestion.
The below configuration variables are required for this Connector to operate. These variables are specified when configuring a Triage asset in SOAR.
VARIABLE | REQUIRED | TYPE | DESCRIPTION |
---|---|---|---|
base_url | required | string | Base URL of the Triage appliance |
verify_server_cert | optional | boolean | Verify SSL certificate |
api_email | required | string | API email address for authentication |
api_token | required | password | API token for authentication |
ingestion_method | optional | string | You can ingest either Threat Indicators or Reports (More details in Section 1: Remaining Settings of the readme/documentation) |
max_results | optional | numeric | Maximum number of results to ingest into containers |
start_date | optional | string | The initial start date and time of the ingestion. The default is six days ago |
date_sort | optional | string | Retrieve results either the oldest first or the latest first |
cef_mapping | optional | string | JSON dictionary represented as a serialized JSON string (More details in Section 1: Remaining Settings of the readme/documentation) |
threat_type | optional | string | Filter results by threat indicator type, default retrieve All. Types are: Subject, Sender, Domain, URL, MD5, SHA256 |
threat_level | optional | string | Filter results by threat indicator level, default retrieve All. Levels are: Malicious, Suspicious, Benign |
report_ingest_subfields | optional | boolean | Only applicable if ingesting reports. This option will ingest dictionary and list fields of the subject as additional artifacts |
report_type | optional | string | Type of reports to retrieve (More details in Section 3: Ingestion Settings for Ingesting Reports of the readme/documentation) |
report_match_priority | optional | numeric | The highest match priority based on rule hits for the report |
report_category_id | optional | string | Report category ID (Select any value from the value_list) (More details in Section 3: Ingestion Settings for Ingesting Reports of the readme/documentation) |
report_tags | optional | string | One or more tags of processed reports to filter on. Use commas to separate multiple tags |
test connectivity - Validate the asset configuration for connectivity using the supplied configuration
on poll - Callback action for the on_poll ingest functionality
get threat indicators - Retrieve the subjects, senders, domains, URLs, or MD5 or SHA256 hashes that operators identified in Cofense Triage as threat indicators within a specified timeframe
get reports - Retrieve all reports in the Inbox, Recon, and Processed folders that match specified parameters
get report - Retrieve a single report that matches the specified report ID. Optionally ingest to a provided label
get email - Downloads the raw email attachment for the report that matches the specified report ID
get file - Downloads and vault the attachment that matches the specified attachment ID
get reporters - Retrieves information about reporters, such as their email address and credit score, whether they are VIP reporters, how many reports they reported, and the date and time of their last report
get reporter - Retrieve reporter that matches the specified reporter ID
run query - Retrieve integration results based on the specified hash (MD5 or SHA256) or URL. Specify only one parameter (sha256, md5, or URL) with this method
Validate the asset configuration for connectivity using the supplied configuration
Type: test
Read only: True
No parameters are required for this action
No Output
Callback action for the on_poll ingest functionality
Type: ingest
Read only: True
No parameters are required for this action
No Output
Retrieve the subjects, senders, domains, URLs, or MD5 or SHA256 hashes that operators identified in Cofense Triage as threat indicators within a specified timeframe
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
max_results | required | If the number of total results exceeds max_results, return only the first max_results number of items retrieved | numeric | |
date_sort | optional | Retrieve either the oldest results first or the latest results first | string | |
type | optional | Filter results by threat indicator type, default retrieve All. Types are: Subject, Sender, Domain, URL, MD5, SHA256 | string | |
level | optional | Filter results by threat indicator level, default retrieve All. Levels are: Malicious, Suspicious, Benign | string | |
start_date | optional | The start date and time of the query. The default is six days ago | string | cofensetriage date |
end_date | optional | The end date and time of the query. The default is current time | string | cofensetriage date |
all_pages | optional | Retrieve all pages or only a specific page and number of results | boolean | |
page | optional | Ignored if all_pages is set to true. The page number of results to retrieve. The default is zero, which is the same as all pages. The header of the response contains the number of the next page and the total number of results | numeric | |
per_page | optional | Ignored if all_pages is set to true. The number of results rendered per page. The maximum value is 50 results per page | numeric | |
ingest_to_label | optional | If set, ingest report(s) into container(s) with provided label. The label must be valid or action will fail | string | |
tenant | optional | Required if ingest_to_label is set. Must provide a valid tenant name or id or action will fail | string | |
cef_mapping | optional | Only applicable if ingesting new artifacts. This parameter is a JSON dictionary represented as a serialized JSON string, such as the result of json.dumps(). Each key in the dictionary is a potential key name in an artifact that is to be renamed to the value. For example, if the cef_mapping is {"website":"requestURL"} your artifact will have requestURL cef fields in place of website cef fields | string |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.all_pages | boolean | |
action_result.parameter.cef_mapping | string | |
action_result.parameter.date_sort | string | |
action_result.parameter.end_date | string | cofensetriage date |
action_result.parameter.ingest_to_label | string | |
action_result.parameter.level | string | |
action_result.parameter.max_results | numeric | |
action_result.parameter.page | numeric | |
action_result.parameter.per_page | numeric | |
action_result.parameter.start_date | string | cofensetriage date |
action_result.parameter.tenant | string | |
action_result.parameter.type | string | |
action_result.data.*.container_id | string | cofensetriage container id |
action_result.data.*.created_at | string | cofensetriage date |
action_result.data.*.id | string | cofensetriage threat indicator id |
action_result.data.*.operator_id | string | |
action_result.data.*.report_id | string | cofensetriage report id |
action_result.data.*.threat_key | string | |
action_result.data.*.threat_level | string | |
action_result.data.*.threat_value | string | sha256 md5 url hash domain hostname |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Retrieve all reports in the Inbox, Recon, and Processed folders that match specified parameters
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
max_results | required | If the number of total results exceeds max_results, return only the first max_results number of items retrieved | numeric | |
date_sort | optional | Retrieve either the oldest results first or the latest results first | string | |
type | required | Type of reports to retrieve, default All. Possible values are: All - All reports in Inbox, Recon, and Processed folders; Inbox - Uncategorized reports in the Inbox and Recon folders; Processed - Categorized reports in the Processed folder | string | |
match_priority | optional | The highest match priority based on rule hits for the report | numeric | cofensetriage match priority |
category_id | optional | Filter by category ID, default retrieves All. The category ID (1-5) for processed reports. Takes either string or number. Only valid when retrieving "All" or "Processed" reports. Category IDs correspond to category names as follows: 5 (lowest): Phishing Simulation; 1: Non-Malicious; 2: Spam; 3: Crimeware; 4 (highest): Advanced Threats | string | cofensetriage category id |
tags | optional | One or more tags of processed reports to filter on. Use commas to separate multiple tags | string | cofensetriage tags |
start_date | optional | The start date and time of the query. The default is six days ago | string | cofensetriage date |
end_date | optional | The end date and time of the query. The default is current time | string | cofensetriage date |
all_pages | optional | Retrieve all pages or only a specific page and number of results | boolean | |
page | optional | Ignored if all_pages is set to true. The page number of results to retrieve. The default is zero, which is the same as all pages. The header of the response contains the number of the next page and the total number of results | numeric | |
per_page | optional | Ignored if all_pages is set to true. The number of results rendered per page. The maximum value is 50 results per page | numeric | |
ingest_to_label | optional | If set, ingest report(s) into container(s) with provided label. The label must be valid or action will fail | string | |
tenant | optional | Required if ingest_to_label is set. Must provide a valid tenant name or id or action will fail | string | |
ingest_subfields | optional | Only applicable if ingesting new containers/artifacts. This option will ingest dictionary and list fields of the subject as additional artifacts | boolean | |
cef_mapping | optional | Only applicable if ingesting new artifacts. This parameter is a JSON dictionary represented as a serialized JSON string, such as the result of json.dumps(). Each key in the dictionary is a potential key name in an artifact that is to be renamed to the value. For example, if the cef_mapping is {"website":"requestURL"} your artifact will have requestURL cef fields in place of website cef fields | string |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.all_pages | boolean | |
action_result.parameter.category_id | string | cofensetriage category id |
action_result.parameter.cef_mapping | string | |
action_result.parameter.date_sort | string | |
action_result.parameter.end_date | string | cofensetriage date |
action_result.parameter.ingest_subfields | boolean | |
action_result.parameter.ingest_to_label | string | |
action_result.parameter.match_priority | numeric | cofensetriage match priority |
action_result.parameter.max_results | numeric | |
action_result.parameter.page | numeric | |
action_result.parameter.per_page | numeric | |
action_result.parameter.start_date | string | cofensetriage date |
action_result.parameter.tags | string | cofensetriage tags |
action_result.parameter.tenant | string | |
action_result.parameter.type | string | |
action_result.data.*.category_id | string | cofensetriage category id |
action_result.data.*.container_id | string | cofensetriage container id |
action_result.data.*.id | string | cofensetriage report id |
action_result.data.*.location | string | |
action_result.data.*.match_priority | string | cofensetriage match priority |
action_result.data.*.md5 | string | md5 hash |
action_result.data.*.processed_at | string | cofensetriage date |
action_result.data.*.report_subject | string | |
action_result.data.*.reported_at | string | cofensetriage date |
action_result.data.*.reporter_id | string | cofensetriage reporter id |
action_result.data.*.sha256 | string | sha256 hash |
action_result.data.*.tags | string | cofensetriage tags |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Retrieve a single report that matches the specified report ID. Optionally ingest to a provided label
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
report_id | required | The ID of the report to retrieve | numeric | cofensetriage report id |
ingest_to_label | optional | If set, ingest report(s) into container(s) with provided label. The label must be valid or action will fail | string | |
tenant | optional | Required if ingest_to_label is set. Must provide a valid tenant name or id or action will fail | string | |
ingest_subfields | optional | Only applicable if ingesting new containers/artifacts. This option will ingest dictionary and list fields of the subject as additional artifacts | boolean | |
cef_mapping | optional | Only applicable if ingesting new artifacts. This parameter is a JSON dictionary represented as a serialized JSON string, such as the result of json.dumps(). Each key in the dictionary is a potential key name in an artifact that is to be renamed to the value. For example, if the cef_mapping is {"website":"requestURL"} your artifact will have requestURL cef fields in place of website cef fields | string |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.cef_mapping | string | |
action_result.parameter.ingest_subfields | boolean | |
action_result.parameter.ingest_to_label | string | |
action_result.parameter.report_id | numeric | cofensetriage report id |
action_result.parameter.tenant | string | |
action_result.data.*.category_id | string | cofensetriage category id |
action_result.data.*.container_id | string | cofensetriage container id |
action_result.data.*.id | string | cofensetriage report id |
action_result.data.*.location | string | |
action_result.data.*.match_priority | string | cofensetriage match priority |
action_result.data.*.md5 | string | md5 hash |
action_result.data.*.processed_at | string | cofensetriage date |
action_result.data.*.report_subject | string | |
action_result.data.*.reported_at | string | cofensetriage date |
action_result.data.*.reporter_id | string | cofensetriage reporter id |
action_result.data.*.sha256 | string | sha256 hash |
action_result.data.*.tags | string | cofensetriage tags |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Downloads the raw email attachment for the report that matches the specified report ID
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
report_id | required | The ID of the report to retrieve | numeric | cofensetriage report id |
download_method | required | Download as artifact or as vaulted file | string | |
create_vaulted_file_artifact | optional | If downloading vaulted file, create an artifact referencing the file | boolean |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.create_vaulted_file_artifact | boolean | |
action_result.parameter.download_method | string | |
action_result.parameter.report_id | numeric | cofensetriage report id |
action_result.data.*.artifact_id | string | cofensetriage artifact id |
action_result.data.*.filename | string | file name |
action_result.data.*.md5 | string | md5 hash |
action_result.data.*.report_id | string | cofensetriage report id |
action_result.data.*.sha1 | string | sha1 hash |
action_result.data.*.sha256 | string | sha256 hash |
action_result.data.*.size | string | |
action_result.data.*.vault_id | string | vault id |
action_result.data.*.vaulted | string | file path |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Downloads and vault the attachment that matches the specified attachment ID
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
attachment_id | required | The ID of the attachment to retrieve | numeric | cofensetriage attachment id |
create_vaulted_file_artifact | optional | If downloading vaulted file, create an artifact referencing the file | boolean |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.attachment_id | numeric | cofensetriage attachment id |
action_result.parameter.create_vaulted_file_artifact | boolean | |
action_result.data.*.artifact_id | string | cofensetriage artifact id |
action_result.data.*.attachment_id | string | cofensetriage attachment id |
action_result.data.*.filename | string | file name |
action_result.data.*.md5 | string | md5 hash |
action_result.data.*.sha1 | string | sha1 hash |
action_result.data.*.sha256 | string | sha256 hash |
action_result.data.*.size | string | |
action_result.data.*.vault_id | string | vault id |
action_result.data.*.vaulted | string | file path |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Retrieves information about reporters, such as their email address and credit score, whether they are VIP reporters, how many reports they reported, and the date and time of their last report
Type: investigate
Read only: True
If the value of vip field is true, then only vip reporters will be retrieved otherwise, both vip and non-vip reporters will be retrieved.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
max_results | required | If the number of total results exceeds max_results, return only the first max_results number of items retrieved | numeric | |
date_sort | optional | Retrieve either the oldest results first or the latest results first | string | |
vip | optional | Whether to fetch VIP reporters (true) or not (false) | boolean | |
optional | The email address of the reporter to fetch. If you do not pass a value for this parameter, Cofense Triage returns all reporters | string | email |
|
start_date | optional | The start date and time of the query. The default is six days ago | string | cofensetriage date |
end_date | optional | The end date and time of the query. The default is current time | string | cofensetriage date |
all_pages | optional | Retrieve all pages or only a specific page and number of results | boolean | |
page | optional | Ignored if all_pages is set to true. The page number of results to retrieve. The default is zero, which is the same as all pages. The header of the response contains the number of the next page and the total number of results | numeric | |
per_page | optional | Ignored if all_pages is set to true. The number of results rendered per page. The maximum value is 50 results per page | numeric |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.all_pages | boolean | |
action_result.parameter.date_sort | string | |
action_result.parameter.email | string | email |
action_result.parameter.end_date | string | cofensetriage date |
action_result.parameter.max_results | numeric | |
action_result.parameter.page | numeric | |
action_result.parameter.per_page | numeric | |
action_result.parameter.start_date | string | cofensetriage date |
action_result.parameter.vip | boolean | |
action_result.data.*.created_at | string | |
action_result.data.*.credibility_score | string | |
action_result.data.*.email | string | email |
action_result.data.*.id | string | cofensetriage reporter id |
action_result.data.*.last_reported_at | string | |
action_result.data.*.reports_count | string | |
action_result.data.*.updated_at | string | |
action_result.data.*.vip | string | |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Retrieve reporter that matches the specified reporter ID
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
reporter_id | required | Required. The ID of the reporter to retrieve | numeric | cofensetriage reporter id |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.reporter_id | numeric | cofensetriage reporter id |
action_result.data.*.created_at | string | cofensetriage date |
action_result.data.*.credibility_score | string | |
action_result.data.*.email | string | email |
action_result.data.*.id | string | cofensetriage reporter id |
action_result.data.*.last_reported_at | string | cofensetriage date |
action_result.data.*.reports_count | string | |
action_result.data.*.updated_at | string | cofensetriage date |
action_result.data.*.vip | string | |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
action_result.summary.requests_url | string | |
action_result.summary.requests_params | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Retrieve integration results based on the specified hash (MD5 or SHA256) or URL. Specify only one parameter (sha256, md5, or URL) with this method
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
query_type | required | Type of parameter | string | |
search_term | required | Search parameter for query | string | sha256 md5 url hash |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.parameter.query_type | string | |
action_result.parameter.search_term | string | sha256 md5 url hash |
action_result.data | string | |
action_result.status | string | |
action_result.message | string | |
action_result.summary | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |