Integration Node Guide

Overview

Integration Nodes allow you to connect your NINA workflows with external systems and services. These nodes provide seamless interaction with platforms like Slack, Jira, OpenCTI, and more, enabling you to both retrieve data from and send data to these services.

Use Cases

• Sending notifications to Slack channels
• Creating Jira tickets based on security findings
• Retrieving threat intelligence from OpenCTI
• Accessing email information via Outlook
• Sending reports to security platforms like CrowdStrike
• Retrieving credentials from Zynap's credential management systems
• Performing malware analysis using Zynap's internal integration
• Performing detailed CVE lookup using Zynap's integration
• Posting results to custom APIs or services

Creating an Integration Node

Basic Setup

1. Drag an Integration Node from the node palette onto your workflow canvas
2. Connect it to an input source (typically containing data for the integration)
3. Select the integration service (e.g., Slack, Jira, etc.)
4. Choose the resource type and operation
5. Select a saved credential for authentication
6. Configure operation-specific parameters

Integration Selection

1. In the node configuration panel, select an integration service such as Jira
2. Select a saved credential to use for authentication
3. Choose the resource type you want to interact with (e.g., "channel" for Slack, "issue" for Jira)
4. Select the operation to perform (e.g., "post_message" for Slack, "create_issue" for Jira)

Credential Configuration

Before using an Integration Node, you need to set up credentials for the service you want to integrate with.

Creating and Managing Credentials

1. Drag and drop an integration node (Slack, Jira, etc.)
2. Within the credentials section, click "Add New Credential"
3. Fill in the credential details:
   • Name: A descriptive name for the credential
   • Description: Optional details about the credential's purpose
   • Auth Type: The authentication method (API Key, Basic, OAuth2, etc.)
   • Domain: The domain or instance URL for the service (e.g., acme.atlassian.net for Jira)
   • Service-specific fields: Depending on the chosen integration service fill out the appropriate fields

Credential Properties

Property	Description
Name	A descriptive name for the credential
Description	Optional details about the credential's purpose
Integration Service	The service of integration this credential is for
Auth Type	The authentication method used
Domain	The domain or instance URL for this credential
Service-specific fields	Fields vary based on the integration service and auth type

Credential Security

All sensitive credential data is:

• Encrypted before storage
• Never exposed in API responses
• Automatically refreshed when using OAuth2 tokens

Configuration Options

Node Properties

Property	Description
Name	A descriptive name for the node
Integration Service	The service to connect with (Slack, Jira, etc.)
Resource	The resource type within the service
Operation	The action to perform on the resource
Credential	The saved credential to use for authentication
Parameters	Service-specific configuration parameters

Parameter Merging

A powerful feature of Integration Nodes is their ability to merge parameters from multiple sources:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

How Parameter Merging Works

When an Integration Node executes:

1. It first reads the input data from upstream nodes (requires JSON format)
2. The integration service extracts relevant parameters from the input data based on the selected resource and operation
3. These extracted parameters are merged with the node's configured parameters
4. The node parameters take precedence over extracted parameters for any overlapping keys
5. Any remaining input data fields are also included in the final parameter set
6. The combined parameters are then used when executing the integration operation

Example of Parameter Merging

Let's say you have:

Input Data from Previous Node:

{
  "findings": [
    {"severity": "high", "description": "SQL Injection found"},
    {"severity": "medium", "description": "XSS vulnerability"}
  ],
  "host": "example.com",
  "scan_date": "2024-04-24"
}

Node Parameters (configured in the Integration Node):

{
  "channel": "#security-alerts",
  "title": "Security Scan Results for {{host}}",
  "color": "#FF0000"
}

Final Merged Parameters (used in the operation):

{
  "channel": "#security-alerts",
  "title": "Security Scan Results for example.com",
  "color": "#FF0000",
  "findings": [
    {"severity": "high", "description": "SQL Injection found"},
    {"severity": "medium", "description": "XSS vulnerability"}
  ],
  "host": "example.com",
  "scan_date": "2024-04-24"
}

Special Handling for Arrays

When merging parameters that contain arrays with the same key:

• The arrays are combined without duplicates
• This is useful for merging lists of items from different sources

How Integration Nodes Work

When a workflow is executed:

1. The Integration Node receives input data from upstream nodes
2. It retrieves the specified credential for the integration service
3. If using OAuth2, the system automatically refreshes tokens if needed
4. Parameters are merged from all sources (node parameters, extracted parameters, and input data)
5. The node authenticates with the target service using the credential data
6. The node executes the operation on the target service with the merged parameters
7. The response from the service is formatted and made available to downstream nodes

OAuth2 Authentication Flow

For integration services using OAuth2:

1. Create a credential with OAuth2 auth type
2. Complete the OAuth2 authorization flow through the user interface
3. The system securely stores the access token and refresh token
4. When the Integration Node runs, it automatically:
   • Checks if the access token is valid
   • If expired, uses the refresh token to obtain a new access token
   • Handles the authentication without manual intervention

Example Configurations

Example 1: Creating a Jira Ticket with Merged Parameters

Node Parameters:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "create_issue",
  "parameters": {
    "project_key": "SEC",
    "issue_type": "Task",
    "labels": ["security", "automated"]
  }
}

Input Data from Previous Node:

{
  "summary": "Critical vulnerability found in web application",
  "description": "SQL Injection vulnerability detected in login form",
}

Final Merged Parameters:

{
  "project_key": "SEC",
  "issue_type": "Task",
  "labels": ["security", "automated"],
  "summary": "Critical vulnerability found in web application",
  "description": "SQL Injection vulnerability detected in login form",
}

Best Practices

• Use Descriptive Names: Give your Integration Node and credentials clear names
• Secure Credentials: Keep OAuth client secrets and API keys secure
• Layer Parameters: Use the parameter merging feature to establish defaults in the node configuration while allowing overrides from input data
• Data Transformation: Consider using a Script Node before the Integration Node to format data correctly
• Test Credentials: Verify credential connectivity

Troubleshooting

Issue	Resolution
Authentication failures	Verify credential configuration and ensure tokens are valid
Missing parameters	Check the required parameters for the specific operation
Parameter merging issues	Verify input data structure and parameter naming
OAuth token expiration	Check if the refresh token is still valid; re-authenticate if needed

Next Steps

After configuring your Integration Node, you might want to:

• Add Script Nodes to transform data into the format expected by the service
• Add conditional branches based on service responses
• Chain multiple integrations together for complex workflows