Fortinet black logo

Utilities Connector

Home FortiSOAR Connectors Utilities Connector
3.2.2
3.3.0
3.2.6
3.2.5
3.2.4
3.2.3
3.2.2
3.2.1

Utilities Connector v3.2.2

Overview

FortiSOAR™ provides you with a number of pre-installed connectors or built-ins, such as the Utilities or Database connectors that you can use within FortiSOAR™ playbooks, as a connector step, and perform automated operations. These connectors are bundled and named based on the type of operations the connectors can perform. For example, the Database connector would contain actions that you can perform with respect to the database like querying the database. It is easy to extend and enhance these connectors.

Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as FortiSIEM, Splunk, etc., and Ticketing systems such as Jira. You can see a list of published connectors on the FortiSOAR Connectors Documentation site.

The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the "Connectors Guide", which is part of the FortiSOAR™ documentation or see the Installing a connector and Configuring a connector articles.

FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. Use the Content Hub to upgrade your connectors to the latest version, in case you want to only upgrade the connectors and not FortiSOAR™. For more information on the connector store, see the Introduction to connectors chapter and see the FortiSOAR Built-in connectors article.

Important: Before you upgrade your FortiSOAR™ version, it is highly recommended that you take a backup of your FortiSOAR™ Built-in connector's (SSH, IMAP, Database, Utilities, etc.) configuration since the configuration of your FortiSOAR™ Built-in connectors might be reset if there are changes to the configuration parameters across versions.

FortiSOAR™ in release 6.0.0 has refactored the output of some operations of some built-in connectors such as the "Email: Extracts email's metadata from email file" operation of the Utilities connector. Due to refactoring, there have been some changes to the output of the Utilities connector which are not backward compatible. For more information on these changes and steps to be followed if you want to retain the old output format, see the Utilities Connector v3.2.1 document.

Utilities

Use this connector for performing operations in FortiSOAR™, such as performing a FortiSOAR™ search using the Query API, updating a FortiSOAR™ resource, and creating a FortiSOAR™ resource. This connector also contains other useful utilities such as extracting email metadata such as indicators from an email file, uploading a file to FortiSOAR™ and associating that file with an attachment, i.e., providing the File IRI in the output, converting file formats, such as XML to JSON or CEF to JSON, and zipping and password protecting a file.

NOTE: This connector is ready to use, and you do not need to configure this connector.

Version information

Connector Version: 3.2.2

Authored By: Fortinet.

Certified: Yes

Release Notes for version 3.2.2

Following enhancements have been made to the Utilities connector in version 3.2.2:

  • Fixed the issue of the email metadata not getting extracted correctly while using the "Email: Extract email's metadata from email file" action. The output of this action did not contain metadata details such as 'file name', 'subject', 'to', 'date', etc., and in some cases contained only the 'agent_id'.
  • Added the 'Documentation' link on the Connector configuration popup, which opens the documentation for this version of the connector.

NOTE: For more information on previous releases of the Utilities connector, see the Utilities Connector v3.2.1 document.

Examples of using the Utilities connector

Utils: Convert JSON into an HTML table"

The "Utils: Convert JSON into an HTML table" action generates an HTML-formatted string based on the input JSON. You can also select the layout of the converted HTML table to be either Vertical or Horizontal(default).
The HTML-formatted string will appear as follows:

<table class="cs-data-table">
<tr>
<th>pid</th>
<th>path</th>
<th>username</th>
</tr>
<tr>
<td>4</td>
<td>c:\\windows\\system32\\ntoskrnl.exe</td>
<td>NT AUTHORITY\\SYSTEM</td>
</tr>
<tr>
<td>296</td>
<td>c:\\windows\\system32\\smss.exe</td>
<td>NT AUTHORITY\\SYSTEM</td>
</tr>
</table>

For the given input JSON:

{
"operation": "get_process_list",
"data": [
{
"path": "c:\\windows\\system32\\ntoskrnl.exe",
"create_time": 1529090266,
"command_line": "",
"parent_guid": "00000004-0000-0000-0000-000000000000",
"proc_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
"parent": 0,
"username": "NT AUTHORITY\\SYSTEM",
"pid": 4,
"sid": "s-1-5-18"
},
{
"path": "c:\\windows\\system32\\smss.exe",
"create_time": 1529090266,
"command_line": "\\SystemRoot\\System32\\smss.exe",
"parent_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
"proc_guid": "00000004-0000-0128-01d4-04dd8ae6291c",
"parent": 4,
"username": "NT AUTHORITY\\SYSTEM",
"pid": 296,
"sid": "s-1-5-18"
},
"status": "Success",
"message": ""
}

Utils: Convert Markdown string

The "Utils: Convert Markdown string to HTML" action converts markdown strings to HTML. These HTML strings can then be used in emails etc, with proper formatting such as working hyperlinks.

Email: Extracts email's metadata from email file

The "Email: Extracts email's metadata from email file" action extracts the metadata of the specified eml/msg file that is present in the /tmp directory on your system.

FSR: Create/Update Global Variables

The "FSR: Create/Update Global Variables" action updates the value of an existing global variable or if the global variable does not exist it creates a new global variable.

File: Upload a file in the system and Create an Attachment

The "File: Upload a file in the system and Create an Attachment" action uploads a file that is present in the /tmp directory to your FortiSOAR system and also creates an attachment record, optionally, in your FortiSOAR system.

File: Read PEM Certificate

The "File: Read PEM Certificate" action ingests PEM files and parses their content, i.e., you can specify the file path, file IRI, or attachment IRI of the certificate (.pem) file, whose contents are then read and parsed by this operation.

File: Unzip

The "File: Unzip" action allows you to unzip a file or a password-protected file that is present in your FortiSOAR™ instance, i.e., the file must either be present in the Attachment module in FortiSOAR™ or in the /tmp folder of your FortiSOAR™ instance.

IMPORTANT: For more information on some other utilities, operations, enhancements, bug fixes, etc., done in the various releases of the Utilities connector, see the Utilities Connector v3.2.1 document.

Notes on using actions in the Utilities connector

  • If you use the download file action of the Utilities connector in a playbook, for example, the "File: Download File From URL" step, the "cyops_filepath" key in the response contains the name of the file under /tmp on a FortiSOAR instance. You can use this value as an input to any next step that needs to consume this file. For example, sending the file as an attachment using the corresponding action of the 'Exchange' connector.
  • Any file that is downloaded on the agent using the download file action of the Utilities connector will not be available for any of the next steps in the playbook. For example, if you create a playbook add then add the Utilities connector operation "File: Download File From URL" step for an FSR Agent configuration, add the download URL, and save the step. Next, you add the "File: Create Attachment From File" step that provides the file reference from the "Download" step, and save and run the playbook. The playbook will fail with an error such as "Connector step is failing with error 'Invalid input :: Given filename/filepath /tmp/f68ab00fb7da4dfd9db4bb95abb1471e doesn't exists'". This is expected behavior since when a file download operation is performed on an FSR agent, the operation cleans the file when the response is returned to the base FortiSOAR™ node. Therefore, if any following step expects the downloaded file to be present at the agent will cause that step to fail. For more information on FSR agents, see the Segmented Network Support chapter in the "Administration Guide", which is part of the FortiSOAR™ documentation.
Previous
Next

Overview

FortiSOAR™ provides you with a number of pre-installed connectors or built-ins, such as the Utilities or Database connectors that you can use within FortiSOAR™ playbooks, as a connector step, and perform automated operations. These connectors are bundled and named based on the type of operations the connectors can perform. For example, the Database connector would contain actions that you can perform with respect to the database like querying the database. It is easy to extend and enhance these connectors.

Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as FortiSIEM, Splunk, etc., and Ticketing systems such as Jira. You can see a list of published connectors on the FortiSOAR Connectors Documentation site.

The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the "Connectors Guide", which is part of the FortiSOAR™ documentation or see the Installing a connector and Configuring a connector articles.

FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. Use the Content Hub to upgrade your connectors to the latest version, in case you want to only upgrade the connectors and not FortiSOAR™. For more information on the connector store, see the Introduction to connectors chapter and see the FortiSOAR Built-in connectors article.

Important: Before you upgrade your FortiSOAR™ version, it is highly recommended that you take a backup of your FortiSOAR™ Built-in connector's (SSH, IMAP, Database, Utilities, etc.) configuration since the configuration of your FortiSOAR™ Built-in connectors might be reset if there are changes to the configuration parameters across versions.

FortiSOAR™ in release 6.0.0 has refactored the output of some operations of some built-in connectors such as the "Email: Extracts email's metadata from email file" operation of the Utilities connector. Due to refactoring, there have been some changes to the output of the Utilities connector which are not backward compatible. For more information on these changes and steps to be followed if you want to retain the old output format, see the Utilities Connector v3.2.1 document.

Utilities

Use this connector for performing operations in FortiSOAR™, such as performing a FortiSOAR™ search using the Query API, updating a FortiSOAR™ resource, and creating a FortiSOAR™ resource. This connector also contains other useful utilities such as extracting email metadata such as indicators from an email file, uploading a file to FortiSOAR™ and associating that file with an attachment, i.e., providing the File IRI in the output, converting file formats, such as XML to JSON or CEF to JSON, and zipping and password protecting a file.

NOTE: This connector is ready to use, and you do not need to configure this connector.

Version information

Connector Version: 3.2.2

Authored By: Fortinet.

Certified: Yes

Release Notes for version 3.2.2

Following enhancements have been made to the Utilities connector in version 3.2.2:

NOTE: For more information on previous releases of the Utilities connector, see the Utilities Connector v3.2.1 document.

Examples of using the Utilities connector

Utils: Convert JSON into an HTML table"

The "Utils: Convert JSON into an HTML table" action generates an HTML-formatted string based on the input JSON. You can also select the layout of the converted HTML table to be either Vertical or Horizontal(default).
The HTML-formatted string will appear as follows:

<table class="cs-data-table">
<tr>
<th>pid</th>
<th>path</th>
<th>username</th>
</tr>
<tr>
<td>4</td>
<td>c:\\windows\\system32\\ntoskrnl.exe</td>
<td>NT AUTHORITY\\SYSTEM</td>
</tr>
<tr>
<td>296</td>
<td>c:\\windows\\system32\\smss.exe</td>
<td>NT AUTHORITY\\SYSTEM</td>
</tr>
</table>

For the given input JSON:

{
"operation": "get_process_list",
"data": [
{
"path": "c:\\windows\\system32\\ntoskrnl.exe",
"create_time": 1529090266,
"command_line": "",
"parent_guid": "00000004-0000-0000-0000-000000000000",
"proc_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
"parent": 0,
"username": "NT AUTHORITY\\SYSTEM",
"pid": 4,
"sid": "s-1-5-18"
},
{
"path": "c:\\windows\\system32\\smss.exe",
"create_time": 1529090266,
"command_line": "\\SystemRoot\\System32\\smss.exe",
"parent_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
"proc_guid": "00000004-0000-0128-01d4-04dd8ae6291c",
"parent": 4,
"username": "NT AUTHORITY\\SYSTEM",
"pid": 296,
"sid": "s-1-5-18"
},
"status": "Success",
"message": ""
}

Utils: Convert Markdown string

The "Utils: Convert Markdown string to HTML" action converts markdown strings to HTML. These HTML strings can then be used in emails etc, with proper formatting such as working hyperlinks.

Email: Extracts email's metadata from email file

The "Email: Extracts email's metadata from email file" action extracts the metadata of the specified eml/msg file that is present in the /tmp directory on your system.

FSR: Create/Update Global Variables

The "FSR: Create/Update Global Variables" action updates the value of an existing global variable or if the global variable does not exist it creates a new global variable.

File: Upload a file in the system and Create an Attachment

The "File: Upload a file in the system and Create an Attachment" action uploads a file that is present in the /tmp directory to your FortiSOAR system and also creates an attachment record, optionally, in your FortiSOAR system.

File: Read PEM Certificate

The "File: Read PEM Certificate" action ingests PEM files and parses their content, i.e., you can specify the file path, file IRI, or attachment IRI of the certificate (.pem) file, whose contents are then read and parsed by this operation.

File: Unzip

The "File: Unzip" action allows you to unzip a file or a password-protected file that is present in your FortiSOAR™ instance, i.e., the file must either be present in the Attachment module in FortiSOAR™ or in the /tmp folder of your FortiSOAR™ instance.

IMPORTANT: For more information on some other utilities, operations, enhancements, bug fixes, etc., done in the various releases of the Utilities connector, see the Utilities Connector v3.2.1 document.

Notes on using actions in the Utilities connector

Previous
Next