# PTaaS Integrations The Integrations page shows the integrations you've selected on the Your Integration tab, and all those you have not yet selected, but are available, on the All Integrations tab. Integrations are the connection between all of your NetSPI Platform data and the tools you use daily that need access to that data. ![Integrations page](/static/integrations_page.png) ## Jira integration NetSPI has partnered with Atlassian Marketplace to provide a Jira integration for the NetSPI Platform. The Jira integration allows you to sync all of your NetSPI findings (from the PTaaS and EASM modules) to your own Jira projects to automate ticket creation for remediation. Use the steps below to configure your Jira integration. 1. Navigate to the [NetSPI Integration for Jira](https://marketplace.atlassian.com/apps/1235686/netspi-integration-for-jira?tab=overview&hosting=cloud) on the Atlassian Marketplace and review the Overview. ![Jira integration](/static/jira_integration.png "Jira integration") 2. Select the [Installation](https://marketplace.atlassian.com/apps/1235686/netspi-integration-for-jira?tab=installation&hosting=cloud) tab and follow the instructions to install the integration. !!! Note that you must have the Client Admin role in the NetSPI Platform and also have Admin privileges for your Jira instance in order to set up this integration. !!! ## Workato-based integrations NetSPI has partnered with Workato to provide an easy path to secure and custom integrations between the NetSPI Platform and your apps. The sections below will walk you through the process of setting up and customizing third-party integrations with the NetSPI Platform. At a high level, the process to setup and customize integrations is as follows: 1. Select your integration on the Integrations page. 2. Agree to Workato agreement. 3. Copy a default recipe. 4. Create a NetSPI support ticket to complete the NetSPI necessary configuration adjustments. 5. Configure company-specific integration (third-party app) items in the recipe, like Jira Project name, etc. 6. Support notifies you when the NetSPI config is done and then you can test your third-party integration. !!! EASM integrations are handled within the EASM module. See the [EASM Integrations](/legacy/easm/integrations/) section for details. !!! ## Specific integration requirements Requirements for specific third-party integrations are detailed below. ### ServiceNow specific configurations You must use a ServiceNow account that has access to create, read, and update issues in the ServiceNow entity that will be configured. More information about the ServiceNow Workato connector can be found here: [https://docs.workato.com/connectors/servicenow.html#api-version](https://docs.workato.com/connectors/servicenow.html#api-version) ## Create an integration Use the following steps to create an integration. 1. Select the Settings icon ![Settings icon](/static/settings_icon.png) to display the Settings page. ![Settings page](/static/settings-page.png) 2. Select the Integrations card to display the Integrations page. ![Integrations landing page](/static/integrations-landing-page.png) 3. Select the All Integrations tab to display integrations available to you. ![Add integration](/static/add_integration.png) Note: Select **More Info** to view details about the integration and all the options available with it. 4. Select the **Add** button for any integration to display the integration manager Workato Agreement form for the integration. ![Workato agreement](/static/workato-agreement.png) 5. Read through the terms and select **Accept** in order to use the integration. After selecting **Accept**, the button toggles and displays as **View Integration** and a new browser tab opens displaying the NetSPI/Workato connection center created for your organization. ![Workato connect](/static/workato-connect.png) 6. Select **Let's start!** to display the Workato recipe page for the integration you selected. A Workato recipe is a customizable workflow used to integrate data and processes between NetSPI and your applications. ![Use recipe](/static/use-recipe.png) The Workato recipe will have some configuration steps for you do to do and some for NetSPI support staff to do, and will be called out below. 7. Select **Use this recipe** to display the copy recipe dialog box. This copies the template recipe into your Workato work environment. ![Copy recipe](/static/copy-recipe.png) 8. Select New project from the first drop-down list. 9. Enter "NetSPI Platform Integration" in the Project name field. Note: You can reuse the Project name for other integrations you set up in the NetSPI Platform. 10. Select **Copy and save** to display the recipe customization dialog box. ![Customize recipe](/static/customize-recipe.png) 11. Select Customize recipe to display the Default recipe page. This is where you will customize the template recipe to be specific for your application environment. ![Jira recipe with errors](/static/jira-recipe-with-errors.png) Note that there will likely be some errors displayed above the recipe, indicating customizations are needed (to correctly sync/map the NetSPI Platform to your application). This is expected. The first error list are items that NetSPI support will need to configure. Contact [NetSPI support](https://help.portal.netspi.com/servicedesk/customer/portal/3/group/-1) and let them know you set up an integration with one of the supported applications and would like support to resolve the errors in that first list. The second list of items are integration details that you will need to configure as they are specific to your third-party application. The steps below will walk you through an example of configuring this information. 12. Select **Save**. 13. Follow the instructions below to correct your NetSPI Platform -> third-party application integration configuration. ### Configure your new integration configuration connections 1. Select the Connections tab to display the connections that need configuration. ![Edit recipe](/static/edit-recipe.png) Each item that needs configuration displays in the left navigation. 2. Select each of the configuration items, one at a time to correct configuration. Be sure to configure the My application connection setting first. Examples: * Configuration Item: My application connector * Correction to make: This is the NetSPI Platform connector that connects your third-party application to the NetSPI Platform. ![Platform connector](/static/platform-connector.png) 3. Enter your NetSPI Platform API key in the API key field. The key must be in the following format, and it is case sensitive: "Token api-key-value". 4. Select **Connect**. A "Connection established" message should display beneath the button, letting you know the connection was successful. * Configuration Item: My JIRA connection * Correction to make: 1. Enter a name of your choice for the JIRA connection in the Connection name field. 2. Select the authorization type from the Auth type drop-down list. Options include: Basic (user name and password; Jira may no longer support this), API token (your JIRA API token created in your JIRA instance), OAuth 2.0 (safest), and personal access token. ![Jira connection](/static/jira-connection2.png) Note: You will be prompted to provide further information/credentials depending on your selection in this step, such as JIRA host name, your email, and/or JIRA API token. 3. Enter the host name in the blank field. 4. Select **Connect**. A "Connection established" message should display beneath the button, letting you know the connection was successful. * Configuration Item: My Rest connection * Correction to make: This is a generic REST connection used for making requests to AWS S3 buckets and pulls down a presigned URL the NetSPI Platform uses as a time-limited permission for object download. ![REST connection](/static/my-rest-connection.png) You only need to select **Connect**. 5. Select the Recipe tab and scroll down in the left navigation to view the default recipe for the third-party application for which you entered configuration information in the section above. ![Return to recipe](/static/return-to-recipe.png) 6. Select **Edit recipe** to transition to edit mode. Use the detailed configuration sections below to edit the recipe's Jira connections. (This process should be similar for other application integrations. Jira is used here as an example.) #### Working with Workato tips Note that Workato provides left and right navigation workspaces. * Select your integration recipe (integration action) in the left navigation. * The recipe for the selected integration action displays in the right navigation. * Select any right-navigation input field to display the Recipe data dialog box. This is where all your NetSPI Platform data options appear and you can drag and drop them to the right navigation recipe to add data to your integration. ![Data Workato](/static/data-workato.png) ### Update integration configuration This section walks you through configuring how Jira is updated with its integration with the NetSPI Platform. 1. In edit mode, scroll down in the left navigation and select the Update integration item to display further configuration steps for mapping information between the NetSPI Platform and your third-party application.\ ![Return to recipe](/static/return-to-recipe.png) 2. In the right navigation, connect the NetSPI Platform to the Jira project of your choice by selecting it from the Sample project issue type drop-down list along with the option type (type, epic, task, sub task, etc.)\ ![Project task type](/static/project-task-type.png) 3. Scroll further down and provide mapping values between the NetSPI Platform and the third-party application. In this Jira example, the image below shows mapping a Jira Severity ID to a specific finding severity level in the NetSPI Platform.\ ![Update issue mapping](/static/update-issue-mapping.png) 4. Select Show optional fields to provide further configuration tailored to your environment (metadata) that is based on your project selection in Step 2 above.\ ![Optional fields](/static/optional-fields.png) 5. Select **Apply changes** when done. ### Create integration configuration This section outlines how to configure the create JIRA functionality between your Jira instance and the NetSPI Platform. 1. In edit mode, scroll down in the left navigation and select the Update integration item to display further configuration steps for mapping information between the NetSPI Platform and your third-party application.\ ![Create config](/static/create-config.png) 2. In the right navigation, select your Jira project from the Project issue type drop-down list along with the task type (Jira task in this example). 3. Repeat the same process as above for the Sample project issue type drop-down list.\ ![Platform task](/static/platform-task.png) 4. The Reporter account ID and Description fields are optional and my contain values of your choice. 5. Configure the Priority name as you did in the previous section, step 2.\ ![Priority and label](/static/priority-and-label.png) 6. Configure the Jira label to be applied when a Platform task is created in your Jira instance by mapping it to ID (a Finding ID from the NetSPI Platform). ### Search integration configuration This section walks you through the steps to configure how searches occur between your NetSPI Platform and Jira integration. 1. In edit mode, scroll down in the left navigation and select the Search integration item to display further configuration steps.\ ![Search config](/static/search-config.png) 2. In the right navigation, update the query (JQL query string for Jira integration) and update the query string so it can locate your Jira project and status change event. This allows the NetSPI Platform/Jira integration to search for findings that your organization has remediated so the corresponding finding's status in the NetSPI Platform can be updated to match. This example above shows that all Jira issues with a status change to done in the designated project ("platform testing") are pulled out of this project, validated to confirm each is a NetSPI Platform finding in Jira (based on the key). Once confirmed, the corresponding finding's status in the NetSPI Platform finding is updated to a remediated status. There is additional information built into the configuration to determine if it is remediated or not. ### Post integration configuration This section walks you through the steps to configure how searches occur between your NetSPI Platform and Jira integration. The Post action allows you to configure which columns/table data are shared between your third-party application and the NetSPI Platform. 1. In edit mode, scroll down in the left navigation and select the Post integration item to display further configuration steps.\ ![Post config](/static/post-config.png) 2. In the right navigation, view the default data being queried and pulled from the finding model in the NetSPI Platform to Jira. The default filter is set for specific projects, as identified in the values field in the example below. ![Post filter integrations](/static/post-filter-integrations_latest.png) 3. To change those default values and/or add additional columns, edit the values field or drag and drop data from the Recipe data dialog box into the right navigation. You can also delete data columns by selecting the garbage icon in the top right corner of each item in the right navigation. You can also review the [NetSPI Platform API documentation](https://platform.netspi.ai/apidocs) to see available values. ## Remove or configure an integration Use the steps below to remove or configure an integration. 1. Select the Setting icon ![Settings icon](/static/settings_icon.png) to display the Settings page. 2. Then select the Integrations card to display the Integrations page. 3. Ensure the Your Integrations tab is selected (it should be, by default) and select **View Integration** for any of your integrations to display the active/inactive, delete, and configuration icons. ![Edit integrations](/static/edit_integrations.png) 4. Select one of the following: * The Active/Inactive slider button to change the integration from an active to an inactive state. Your integration will discontinue immediately when you select Inactive. * The delete (garbage) icon to delete the integration. Your integration will discontinue immediately once selected. * The configure (gear) icon, to display the Edit Integration Account dialog box, where you can edit the integration name, account ID, Cross Account Role ARN, and/or External ID. * **Add Account** to display a blank Add Integration Account dialog box where you can enter configuration values for an additional account within that integration. 5. Select **Save** when done to save your integration changes.