Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

About the connector

Cyware secures your organizations by creating a robust security perimeter through real-time cybersecurity alerts driven situational awareness and enables participative information and intelligence exchange within and outside your organizations for proactively mitigating cyber risk. The Cyware Situational Awareness Platform (CSAP) enhances your security capabilities through strategic threat intelligence sharing, crisis communication capabilities, and human-to-machine orchestration. 

This document provides information about the Cyware connector, which facilitates automated interactions, with a Cyware server, and specifically CSAP, using FortiSOAR™ playbooks. Add the Cyware connector as a step in FortiSOAR™ playbooks and perform automated operations, such as reporting an incident to CSAP and retrieving incident details and details of active Recipient Groups (RG) in your organization from CSAP.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Cyware Versions: 2.2.1 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL of the Cyware server on which you will perform the automated operations and the Access ID and Secret Key configured for your account to access that server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™ , on the Connectors page, select the Cyware connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL of the Cyware server to which you will connect and perform automated operations.
Access ID Access ID configured for your account to access the Cyware server to which you will connect and perform the automated operations.
Secret Key Secret Key configured for your account to access the Cyware server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Report an Incident Reports an incident to CSAP. create_incident
Investigation
List Reported Incidents Retrieves details for all reported incidents from CSAP, based on the time range that you have specified. get_incidents
Investigation
Get Incident Details Retrieves detailed information for a particular incident from CSAP, based on the incident ID that you have specified. get_incidents
Investigation
List Incident Types Retrieves a list of all the possible values of incident types from CSAP. incident_type
Investigation
List Threat Methods Retrieves a list of all the possible threat methods of incidents from CSAP. incident_threat_method
Investigation
List Severity Retrieves a list of all the possible values of incident severities from CSAP. incident_severity
Investigation
Get Recipient Group Retrieves details of all the active Recipient Groups (RG) in your organization from CSAP. get_groups
Investigation
Get Alert Categories Retrieves details of all the alert categories from CSAP. get_alert_categories
Investigation
Get Info Source Retrieves details on all the available information sources from CSAP. get_info_source
Investigation
List Reported Intel Retrieves details of all intel reported by you or your team from CSAP. list_intel_reported
Investigation
List users Retrieves details for all active users present in the organization from CSAP. get_users
Investigation
Get User by Email Retrieves detailed information for a specific user from CSAP, based on the email address that you have specified. get_user_by_email
Investigation
Get User Personalized Keywords Retrieves the complete list and details of the user-added personalized keywords from CSAP, based on the email address that you have specified. get_user_keywords
Investigation
Get Executive Protection Details Retrieves a list and details about users who are marked with executive protection from CSAP. get_executive_protection
Investigation
Get User Cyware Index Retrieves detailed information on User Cyware Index from CSAP, based on the email address that you have specified. get_user_cyware_index
Investigation

 

operation: Report an Incident

Input parameters

 

Parameter Description
Title Title of the incident that you want to report to CSAP.
Description Description of the incident that you want to report to CSAP.
Attachment Attachment that needs to be uploaded with the incident that you want to report to CSAP.
Enter the attachment details in the format: [{"file": "URL of the file"}]. For example, [{"file": "https://www.worldatlas.com/r/w728-h425-c728x425/upload/b8/98/20/640px-primo-piano-del-monte-bianco-al-lago-di-pietra-rossa.jpg"}] 
Note: If you do not want to upload an attachment with the incident, then enter value = [] in this field.
Incident Types (Optional) List of incident types in which you want to add the incident that you want to report to CSAP.
You can choose more than one option from the following list of options: APT, Asset Defacement, Attempts to Gain Unauthorized Access, Botnet, Brute Force, Compromised User Accounts, Configuration Error, Cross-Site Scripting, Cyber Espionage, Data Breach, Denial of Service, DNS Poisoning, Drive-by Download, Eavesdropping, Email Spoofing, Exploit Kit, Hardware Fault, Hash Collision Attack, IP Spoofing, Keylogger, Malicious Communication, Malspam, Malware, Man-in-the-Middle Attack, Masquerade, Misuse of Data, Misuse of Resources, Other, Phishing, Probe, Product Vulnerability, Rootkit, Scanning, Social Engineering, Spam, Spyware, SQL Injection, Trojan, Virus, Vishing, Web App Attacks, and Worm.
Note: By default this is set to APT.
Threat Methods (Optional) List of threat methods in which you want to add the incident that you want to report to CSAP.
You can choose more than one option from the following list of options: APT, Brute Force, DDoS, Malware, Other, Spearphishing, and Spoofing.
Note: By default this is set to Other.
Severity (Optional) Severity of the incident that you want to report to CSAP.
You can choose from one of the following options: Informational (Normal), Major Business Disruption (Crisis), Minimal Impact (Normal), Moderate Impact (Normal), or Significant Impact (Urgent).
Note: By default this is set to Informational (Normal).

 

Important: If you attach a file to the incident which is in an incompatible file format, it might result in the playbook failing with an error such as ERROR connectors.cyware operations make_rest_call(): Bad/Invalid Request.

Output

The JSON output contains the details of the incident that you have reported to CSAP.

Following image displays a sample output:

 

Sample output of the Report an Incident operation

 

operation: List Reported Incidents

Input parameters

 

Parameter Description
From DateTime from when you want to retrieve reported incidents from CSAP.
To DateTime to when you want to retrieve reported incidents from CSAP.
Pagesize (Optional) Number of incident records to be displayed per page.
By default this is set to 10.

 

Output

The JSON output contains details of all the reported incidents, based on the time range that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Reported Incidents operation

 

operation: Get Incident Details

Input parameters

 

Parameter Description
Incident ID ID of the incident for which you want to retrieve details from CSAP.

 

Output

The JSON output contains detailed information for a particular incident, based on the incident ID that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Incident Details operation

 

operation: List Incident Types

Input parameters

None.

Output

The JSON output contains a list of all the possible values of incident types retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Incident Types operation

 

operation: List Threat Methods

Input parameters

None.

Output

The JSON output contains a list of all the possible threat methods of incidents retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Threat Methods operation

 

operation: List Severity

Input parameters

None.

Output

The JSON output contains a list of all the possible incident severities retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Severity operation

 

operation: Get Recipient Groups

Input parameters

None.

Output

The JSON output contains details of all the active Recipient Groups (RG) in your organization retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Recipient Groups operation

 

operation: Get Alert Categories

Input parameters

None.

Output

The JSON output contains details of all alert categories retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Alert Categories operation

 

operation: Get Info Source

Input parameters

None.

Output

The JSON output contains details on all the available information sources retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Info Source operation

 

operation: List Reported Intel

Input parameters

 

Parameter Description
Pagesize (Optional) Number of records to be displayed per page.
By default, this is set to 10.

 

Output

The JSON output contains detailed information of all intel reported by you or your team retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Reported Intel operation

 

operation: List Users

Input parameters

None.

Output

The JSON output contains details for all active users present in the organization retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Users operation

 

operation: Get User by Email

Input parameters

 

Parameter Description
Email Email address based on which you want to retrieve details for a specific user.

 

Output

The JSON output contains detailed information for a specific user, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User by Email operation

 

operation: Get User Personalized Keywords

Input parameters

 

Parameter Description
Email Email address based on which you want you to retrieve the complete list of user-added personalized keywords.

 

Output

The JSON output contains the complete list and details of the user-added personalized keywords, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User Personalized Keywords operation

 

operation: Get Executive Protection Details

Input parameters

None.

Output

The JSON output contains a list and details about users who are marked with executive protection retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Get Executive Protection Details operation

 

operation: Get User Cyware Index

Input parameters

 

Parameter Description
Email Email address based on which you want to retrieve details of the User Cyware Index.

 

Output

The JSON output contains detailed information on User Cyware Index, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User Cyware Index operation

 

Included playbooks

The Sample - Cyware - 1.0.0 playbook collection comes bundled with the Cyware connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cyware connector.

  • Get Alert Categories
  • Get Executive Protection Details
  • Get Incident Details
  • Get Info Source
  • Get Recipient Groups
  • Get User by Email
  • Get User Cyware Index
  • Get User Personalized Keywords
  • List Incident Types
  • List Reported Incidents
  • List Reported Intel
  • List Severity
  • List Threat Methods
  • List Users
  • Report an Incident

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

 

About the connector

Cyware secures your organizations by creating a robust security perimeter through real-time cybersecurity alerts driven situational awareness and enables participative information and intelligence exchange within and outside your organizations for proactively mitigating cyber risk. The Cyware Situational Awareness Platform (CSAP) enhances your security capabilities through strategic threat intelligence sharing, crisis communication capabilities, and human-to-machine orchestration. 

This document provides information about the Cyware connector, which facilitates automated interactions, with a Cyware server, and specifically CSAP, using FortiSOAR™ playbooks. Add the Cyware connector as a step in FortiSOAR™ playbooks and perform automated operations, such as reporting an incident to CSAP and retrieving incident details and details of active Recipient Groups (RG) in your organization from CSAP.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Cyware Versions: 2.2.1 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™ , on the Connectors page, select the Cyware connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL of the Cyware server to which you will connect and perform automated operations.
Access ID Access ID configured for your account to access the Cyware server to which you will connect and perform the automated operations.
Secret Key Secret Key configured for your account to access the Cyware server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Report an Incident Reports an incident to CSAP. create_incident
Investigation
List Reported Incidents Retrieves details for all reported incidents from CSAP, based on the time range that you have specified. get_incidents
Investigation
Get Incident Details Retrieves detailed information for a particular incident from CSAP, based on the incident ID that you have specified. get_incidents
Investigation
List Incident Types Retrieves a list of all the possible values of incident types from CSAP. incident_type
Investigation
List Threat Methods Retrieves a list of all the possible threat methods of incidents from CSAP. incident_threat_method
Investigation
List Severity Retrieves a list of all the possible values of incident severities from CSAP. incident_severity
Investigation
Get Recipient Group Retrieves details of all the active Recipient Groups (RG) in your organization from CSAP. get_groups
Investigation
Get Alert Categories Retrieves details of all the alert categories from CSAP. get_alert_categories
Investigation
Get Info Source Retrieves details on all the available information sources from CSAP. get_info_source
Investigation
List Reported Intel Retrieves details of all intel reported by you or your team from CSAP. list_intel_reported
Investigation
List users Retrieves details for all active users present in the organization from CSAP. get_users
Investigation
Get User by Email Retrieves detailed information for a specific user from CSAP, based on the email address that you have specified. get_user_by_email
Investigation
Get User Personalized Keywords Retrieves the complete list and details of the user-added personalized keywords from CSAP, based on the email address that you have specified. get_user_keywords
Investigation
Get Executive Protection Details Retrieves a list and details about users who are marked with executive protection from CSAP. get_executive_protection
Investigation
Get User Cyware Index Retrieves detailed information on User Cyware Index from CSAP, based on the email address that you have specified. get_user_cyware_index
Investigation

 

operation: Report an Incident

Input parameters

 

Parameter Description
Title Title of the incident that you want to report to CSAP.
Description Description of the incident that you want to report to CSAP.
Attachment Attachment that needs to be uploaded with the incident that you want to report to CSAP.
Enter the attachment details in the format: [{"file": "URL of the file"}]. For example, [{"file": "https://www.worldatlas.com/r/w728-h425-c728x425/upload/b8/98/20/640px-primo-piano-del-monte-bianco-al-lago-di-pietra-rossa.jpg"}] 
Note: If you do not want to upload an attachment with the incident, then enter value = [] in this field.
Incident Types (Optional) List of incident types in which you want to add the incident that you want to report to CSAP.
You can choose more than one option from the following list of options: APT, Asset Defacement, Attempts to Gain Unauthorized Access, Botnet, Brute Force, Compromised User Accounts, Configuration Error, Cross-Site Scripting, Cyber Espionage, Data Breach, Denial of Service, DNS Poisoning, Drive-by Download, Eavesdropping, Email Spoofing, Exploit Kit, Hardware Fault, Hash Collision Attack, IP Spoofing, Keylogger, Malicious Communication, Malspam, Malware, Man-in-the-Middle Attack, Masquerade, Misuse of Data, Misuse of Resources, Other, Phishing, Probe, Product Vulnerability, Rootkit, Scanning, Social Engineering, Spam, Spyware, SQL Injection, Trojan, Virus, Vishing, Web App Attacks, and Worm.
Note: By default this is set to APT.
Threat Methods (Optional) List of threat methods in which you want to add the incident that you want to report to CSAP.
You can choose more than one option from the following list of options: APT, Brute Force, DDoS, Malware, Other, Spearphishing, and Spoofing.
Note: By default this is set to Other.
Severity (Optional) Severity of the incident that you want to report to CSAP.
You can choose from one of the following options: Informational (Normal), Major Business Disruption (Crisis), Minimal Impact (Normal), Moderate Impact (Normal), or Significant Impact (Urgent).
Note: By default this is set to Informational (Normal).

 

Important: If you attach a file to the incident which is in an incompatible file format, it might result in the playbook failing with an error such as ERROR connectors.cyware operations make_rest_call(): Bad/Invalid Request.

Output

The JSON output contains the details of the incident that you have reported to CSAP.

Following image displays a sample output:

 

Sample output of the Report an Incident operation

 

operation: List Reported Incidents

Input parameters

 

Parameter Description
From DateTime from when you want to retrieve reported incidents from CSAP.
To DateTime to when you want to retrieve reported incidents from CSAP.
Pagesize (Optional) Number of incident records to be displayed per page.
By default this is set to 10.

 

Output

The JSON output contains details of all the reported incidents, based on the time range that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Reported Incidents operation

 

operation: Get Incident Details

Input parameters

 

Parameter Description
Incident ID ID of the incident for which you want to retrieve details from CSAP.

 

Output

The JSON output contains detailed information for a particular incident, based on the incident ID that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Incident Details operation

 

operation: List Incident Types

Input parameters

None.

Output

The JSON output contains a list of all the possible values of incident types retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Incident Types operation

 

operation: List Threat Methods

Input parameters

None.

Output

The JSON output contains a list of all the possible threat methods of incidents retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Threat Methods operation

 

operation: List Severity

Input parameters

None.

Output

The JSON output contains a list of all the possible incident severities retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Severity operation

 

operation: Get Recipient Groups

Input parameters

None.

Output

The JSON output contains details of all the active Recipient Groups (RG) in your organization retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Recipient Groups operation

 

operation: Get Alert Categories

Input parameters

None.

Output

The JSON output contains details of all alert categories retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Alert Categories operation

 

operation: Get Info Source

Input parameters

None.

Output

The JSON output contains details on all the available information sources retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Info Source operation

 

operation: List Reported Intel

Input parameters

 

Parameter Description
Pagesize (Optional) Number of records to be displayed per page.
By default, this is set to 10.

 

Output

The JSON output contains detailed information of all intel reported by you or your team retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Reported Intel operation

 

operation: List Users

Input parameters

None.

Output

The JSON output contains details for all active users present in the organization retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the List Users operation

 

operation: Get User by Email

Input parameters

 

Parameter Description
Email Email address based on which you want to retrieve details for a specific user.

 

Output

The JSON output contains detailed information for a specific user, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User by Email operation

 

operation: Get User Personalized Keywords

Input parameters

 

Parameter Description
Email Email address based on which you want you to retrieve the complete list of user-added personalized keywords.

 

Output

The JSON output contains the complete list and details of the user-added personalized keywords, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User Personalized Keywords operation

 

operation: Get Executive Protection Details

Input parameters

None.

Output

The JSON output contains a list and details about users who are marked with executive protection retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get Get Executive Protection Details operation

 

operation: Get User Cyware Index

Input parameters

 

Parameter Description
Email Email address based on which you want to retrieve details of the User Cyware Index.

 

Output

The JSON output contains detailed information on User Cyware Index, based on the email address that you have specified, retrieved from CSAP.

Following image displays a sample output:

 

Sample output of the Get User Cyware Index operation

 

Included playbooks

The Sample - Cyware - 1.0.0 playbook collection comes bundled with the Cyware connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cyware connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.