Cyware Documentation

Orchestrate enables security analysts to gather threat data from multiple sources and automate responses to threats and vulnerabilities through advanced workflows. This leads to faster detection, improved analysis, and efficient management of the security operations lifecycle. For more information, see Orchestrate Product Documentation.

The Orchestrate open API allows for programmatic interaction with Orchestrate services, enabling automation and integration with other systems in your environment.

Supported Orchestrate Version: 3.5.5.0 and later versions.

The API reference includes public Orchestrate API endpoints for the following modules:

Integrations

Integrate security tools seamlessly with Orchestrate's App Store.

Playbooks

Automate and orchestrate security operations with playbooks.

Authenticate

Custom Templates

Code Snippets

Persistent List

Analytics

Events

Generate Open API Credentials

You can generate open API credentials in the Orchestrate application to access the open API endpoints. For more information on how to generate Open API credentials in Orchestrate, see Configure Open API.

Mandatory Query Parameters for Requests

After you have generated open API credentials, use them to authenticate your API requests. Ensure the following parameters are included in the query of each request:

Access ID: Indicates the access ID linked to your Orchestrate Open API. For example, 57d008xx-7xxx-xx-b27a-1feb943d0xxx.
Expires: Indicates the validity of the signature parameter. The signature becomes invalid if not used within the specified expiry duration. You can use expires = current time + 30 seconds for authentication. You can specify a margin of 10 to 30 seconds for expiration.
Signature: Signature is a combination of the access ID, secret key, and expiration parameters to authenticate API requests. The signature is hashed using the HMAC-SHA1 algorithm and then encoded using the Base64 scheme.
- Create a StringToSign value using the StringToSign = access_id + \n + expires formula.
- Create a Signature value using the Signature = Base64(HMAC-SHA1UTF-8-Encoding-Of(secret_key), UTF-8-Encoding-Of(StringToSign)) formula.

The following Python code is a sample to generate a signature for endpoint authentication:

Python

 def generate_signature(access_id, secret_key):
    expires = int(time.time() + 30) # expires in 30 seconds
    to_sign = '{}\n{}'.format(access_id, expires)
    signature = base64.b64encode(
       hmac.new(
           secret_key.encode('utf-8'),
           to_sign.encode('utf-8'),
           hashlib.sha1
       ).digest()).decode()
    return expires, signature
#Example:
#access_id = "7e4e6a9c-11ca-40f4-95af-edae017358d0"
#secret_key = "e61e92fb-bfd9-4cef-9b21-6f1e8211b77b"
#Generate signature:
#expires, signature = generate_signature(access_id, secret_key)

Cyware Orchestrate offers a robust App Store with a comprehensive library of apps required to integrate, orchestrate, and respond using various security tools within your organization. These integrations support tasks like threat data collection, prioritization, and other analytics, enabling a holistic approach to orchestration from a unified platform. For more information, see Integrations.

You can perform the following actions in this module:

Retrieve App and Instance Details: Fetch details of available apps and instances, including details of a specific app and instance.
Test Instance Connectivity: Verify the connectivity of a specific app instance to ensure successful integration.
Retrieve App Actions and Details: Fetch a list of actions associated with an app and detailed information about each action.
Execute App Actions: Run specific actions of an app.
Download App Package: Download the ZIP file for a specific app to enable offline access.
Install Custom Apps: Add new custom applications by uploading and installing app packages.

Endpoints

GET

POST

GET

POST

GET

POST

Playbooks are a structured sequence of actions organized into workflows to automate and orchestrate security responses, standardizing processes for effective incident and threat management. Orchestrate offers manual and automated playbooks to meet your organization's specific needs.

Playbooks can be scheduled based on application input sources or automatically triggered by specific events. Additionally, playbooks facilitate seamless integration between different security tools, creating a more connected and efficient security environment. For more information, see Playbooks.

You can perform the following actions in this module:

Export Playbook: Export playbook details for backup or external use.
Retrieve Playbooks and Details: Fetch the list of playbooks and specific playbook details.
Retrieve Playbook Run Logs and Run Details: Fetch the list of playbook results, run logs, and specific run log details.
Execute and Manage Playbooks: Run or terminate specific playbooks.
Download Playbook and Node Results: Fetch and download results of a specific playbook or a specific node output for analysis.

Endpoints

GET

POST

GET

POST

Email templates are predefined email layouts with a header and body in rich text format. Analysts can reuse and customize these templates, reducing the effort required to compose emails from scratch.

These templates can be used in playbooks to automate email notifications. They are compatible with applications that support Rich Text Format fields, such as the Cyware Email Service - Send Email in Rich Text Format action and more. For more information, see Email Templates.

You can perform the following actions in this module:

Get Custom Email Template List: Retrieve a list of available email templates.
Get Custom Email Template Details: Retrieve detailed information about a specific email template.

Endpoints

GET

Code snippets are reusable blocks of code, such as functions, loops, and conditional statements. They support the creation of custom nodes, including custom actions and conditions, within playbooks.

Analysts can leverage a centralized library of reusable code to streamline workflows and reduce effort. This allows them to customize code pieces that are used in multiple playbook workflows from one location. For more information, see Code Snippets.

You can perform the following actions in this module:

Retrieve Code Snippets: Retrieve a list of available code snippets.
Retrieve Code Snippet Details: Fetch detailed information about a specific code snippet.

Endpoints

GET

Persistent List is a collection of key-value pairs that analysts can use to store data and then look up from this data to use in a playbook or playbook node. Data stored in a persistent list can survive system reboots, system crashes, and more. Analysts can then retrieve the data defined in a persistent list using any playbook node. For more information, see Persistent List.

You can perform the following actions in this module:

Retrieve Persistent Lists and Details: Fetch a list of all persistent storage objects and fetch detailed information about a specific object using its unique identifier.
Create and Update Persistent Lists: Create new persistent storage objects or modify existing ones to update their details.
Delete Persistent Storage Objects: Remove a specific persistent storage object from Orchestrate.
Retrieve Persistent List Slugs: Get a list of unique resource identifiers for all persistent lists.
Retrieve Playbooks Associated with a Persistent List: Get details and count of playbooks associated with a specific persistent storage object.

Endpoints

GET

POST

PUT

GET

The Analytics Dashboard in Orchestrate provides an overview of activities across modules. Upon signing in, users can view dashboards that offer insights into playbook workflows, app performance, instance usage, and action execution. By analyzing key metrics such as frequently used playbooks and actions, analysts can optimize workflows and enhance automation. Dashboards also help identify underutilized events, diagnose execution errors, and refine automated responses, reducing manual intervention. For more information, see Analytics Dashboard.

You can perform the following actions in this module:

Retrieve Playbook Execution Metrics: Get insights on playbook run count, most active playbooks, and average playbook execution time.
Retrieve App and Instance Usage Metrics: Get insights into the most used and most active apps, instances, and actions.
Retrieve Event Processing Metrics: Get insights on event count, unprocessed events, events with errors, and incoming source events.

Endpoints

GET

Returns the number of times playbooks were executed for the non-purged data within the specified date range.

Query Parameters

categorize_bystring Required

Passcategorize_by=playbook_run_count to retrieve playbook run count.

created__gtestring

Pass the start time in the Unix time format to retrieve the playbook run count for a specified duration.

created__ltestring

Pass the end time in Unix time format to retrieve the playbook run count for a specified duration.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the number of times playbooks were executed in the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=playbook_run_count&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Dec 22, 2021",
      "value": 77
    }
  ]
}

Returns playbooks with the highest number of executions for the non-purged data.

Query Parameters

categorize_bystring Required

Passcategorize_by=most_active_playbooks to retrieve the most active playbooks.

created__gtestring

Pass the start time in the Unix time format to retrieve the most active playbooks for a specified duration.

created__ltestring

Pass the end time in the Unix time format to retrieve the most active playbooks count for a specified duration.

Response

200

Object

Response Attributes

dataarray

Returns analytics data on the most active playbooks.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_active_playbooks&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "John Doe's Playbook - December 22 2021,",
      "value": 22
    }
  ]
}

Returns the average execution time of playbooks for the non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=playbook_avg_execution_time to retrieve the average playbook execution time.

created__gtestring

Pass the start time in Unix time format to retrieve the average execution time of a playbook run.

created__ltestring

Pass the end time in Unix time format to retrieve the average execution time of a playbook run.

Response

200

Object

Response Attributes

dataarray

Retrieves analytics data on the average playbook execution time for the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=playbook_avg_execution_time&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Enrich Indicator",
      "value": 116.68
    }
  ]
}

Returns the most used instances in playbooks for the non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=most_used_instances to get the most used instances.

created__gtestring

Pass the start time in Unix time format to retrieve the most used instances.

created__ltestring

Pass the end time in Unix time format to retrieve the most used instances.

Response

200

Object

Response Attributes

dataarray

Returns analytics data on the most frequently used instances within the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_used_instances&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Default Instance",
      "value": 6
    }
  ]
}

Returns the most used apps in playbooks for the non-purged data.

Query Parameters

categorize_bystring Required

Passcategorize_by=most_used_apps to retrieve most used apps.

created__gtestring

Pass the start time in Unix time format to retrieve the most used apps.

created__ltestring

Pass the end time in Unix time format to retrieve the most used apps.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the most used apps within the specified date range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_used_apps&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Tanium 1.7.3",
      "value": 7
    }
  ]
}

Returns the most used actions in playbooks for the non-purged data.

Query Parameters

categorize_bystring Required

Passcategorize_by=most_used_actions to get the most used actions.

created__gtestring

Pass the start time in Unix time format to retrieve the most used actions in playbooks.

created__ltestring

Pass the end time in Unix time format to retrieve the most used actions in playbooks.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the most used actions in playbooks.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_used_actions&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Get question result by ID tanium_1_7_3",
      "value": 4
    }
  ]
}

Retrieves the most executed actions in playbooks for the non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=most_active_actions to get the most active action.

created__gtestring

Pass the start time in Unix time format to retrieve the most active actions count.

created__ltestring

Pass the end time in Unix time format to retrieve the most active actions count.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the most executed actions in playbooks

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_active_actions&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Get URL details virus_total_3_0_4",
      "value": 7
    }
  ]
}

Returns the most utilized apps in playbooks for the non-purged data.

Query Parameters

categorize_bystring

Set categorize_by=most_active_apps to retrieve most active apps.

created__gtestring

Pass the start time in Unix time format to retrieve most executed apps in playbooks.

created__ltestring

Pass the end time in Unix time format to retrieve most executed apps in playbooks.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the most utilized apps in playbooks.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=most_active_apps&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Virus Total 3.0.4",
      "value": 8
    }
  ]
}

Returns the most frequently used instances in playbook executions for the non-purged data.

Query Parameters

AccessIDstring

The Access ID is used to authenticate the Cyware Orchestrate API endpoint.

Signaturestring

The Signature is used to authenticate the Cyware Orchestrate API endpoint.

Expiresstring

This parameter is used to define an expiry time for the API call.

categorize_bystring Required

Passcategorize_by=most_active_instances to retrieve the most active instances.

created__gtestring

Pass the start time in unix time format to retrieve the most active instances.

created__ltestring

Pass the end time in unix time format to retrieve the most active instances.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the most active instance for the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?AccessID=57d008c4-xxxx-4880-xxxx-1feb943d06ac%2C&Signature=ohaUEcyA8hH3WPUo7Y%2FQOf%2BzWY0%3D&Expires=72a48f16-xxxx-4023-xxxx-40f8e58d1f41&categorize_by=most_active_instances&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Test Instance",
      "value": 8
    }
  ]
}

Returns the count of automatic and manual events created in Cyware Orchestrate for the non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=event_count to retrieve event count.

created__gtestring

Pass the start time in Unix time format to retrieve event count.

created__ltestring

Pass the end time in Unix time format to retrieve event count.

Response

200

Object

Response Attributes

dataarray

Returns analytics data on the number of events created within the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=event_count&created__gte=1640131200&created__lte=1640723199' \

{
  "data": [
    {
      "label": "Dec 22, 2021",
      "value": 20
    }
  ]
}

Returns the count of incoming source events from the configured event source app for non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=incoming_source_of_events to retrieve incoming source event values.

created__gtestring

Pass the start time in Unix time format to retrieve incoming source events.

created__ltestring

Pass the end time in Unix time format to retrieve incoming source events.

Response

200

Object

Response Attributes

dataarray

Returns the analytics data on the incoming source events within the specified date range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=incoming_source_of_events&created__gte=1630131200&created__lte=1643723199' \

{
  "data": [
    {
      "label": "ctix",
      "value": 4570
    }
  ]
}

Returns the number of unprocessed events for the non-purged data.

Query Parameters

categorize_bystring Required

Pass categorize_by=unprocessed_events to retrieve unprocessed events.

created__gtestring

Pass the start time in Unix time format to retrieve the unprocessed events for a specified duration.

created__ltestring

Pass the end time in Unix time format to retrieve the unprocessed events for a specified duration.

Response

200

Object

Response Attributes

dataobject

Returns analytics data on the unprocessed events within the specified time range.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=unprocessed_events&created__gte=1630131200&created__lte=1643723199' \

{
  "data": {
    "label": "Percentage of Unprocessed Events",
    "total_value": 4744,
    "value": 415
  }
}

Returns the number of events that failed due to errors or system issues during playbook execution.

Query Parameters

categorize_bystring Required

Pass categorize_by=event_count to get events with error value.

created__gtestring

Pass the start time in Unix time format to retrieve the number of events with errors.

created__ltestring

Pass the end time in Unix time format to retrieve the number of events with errors.

Response

200

Object

Response Attributes

dataobject

Returns analytics data on the number of events that encountered errors during playbook execution.

Show child attributes

curl --location 'https://tenantname.cyware.com/soarapi/openapi/v1/analytics/data-source/?categorize_by=events_with_error&created__gte=1630131200&created__lte=1643723199' \

{
  "data": {
    "label": "Events Giving Error",
    "total_value": 4329,
    "value": 4277
  }
}

A Source Event acts as a trigger for a playbook to execute. You can configure triggers to automatically trigger the execution of a playbook based on the occurrence of an event. These events can occur in Orchestrate or on external platforms such as Respond, Intel Exchange, Splunk, and more. You can configure the source event app and source event type to execute pre-configured playbook workflows. For more information, see Events.

When a Source Event is triggered in Cyware Orchestrate, it carries the Source Event Data from integrated tools like Splunk, Respond, and other apps. This data is transmitted in JSON format via the Cyware Orchestrate REST API.

Authorization

These APIs require an OpenAPI access ID and a generated secret key for authentication.

You can perform the following actions in this module:

Create Events: Create new events with either detailed or concise response data.
Retrieve Source Events and Details: Fetch a list of all source events and retrieve the details of a specific event.
Configure and Manage Events: Configure events by passing the app identifier, action identifier, and labels through the payload.
Download Event Data: Export event data for further analysis.

Endpoints

POST

GET

POST

GET

A playbook tag can be used to define role-based access control (RBAC) for playbooks. To configure RBAC, analysts must create playbook tags and associate them with both playbooks and user groups in Respond. Members of a Respond user group can execute playbooks only if the assigned tags match those of the user group. For more information, see Create Playbook Tags.

You can perform the following actions in this module:

Retrieve Tags: Fetch the list of tags.
Retrieve Tag Details: Fetch the details of a specific tag.

Endpoints

GET

Webhooks are serialized messages/information sent from one application to another's unique URL over the web. Webhooks enable analysts to bypass data exchange complications by generating token-based URLs and authenticating endpoints whenever events (GET and POST requests) are triggered in the Orchestrate application.

Webhooks module allows users to create and manage webhook configurations and tokens. Users will be able to access features based on the permissions assigned to the user in the Orchestrate application. For more information, see Configure Webhooks.

Authentication

These APIs require a webhook token as a mandatory parameter.

Generate Webhook Credentials

Navigate to the Admin Panel and select Webhooks.
Click Add Webhook and enter the webhook details.
After entering the details, click Generate Webhook URL.
After the webhook URL is generated, copy the token and the Base URL displayed to you, and then configure the keys in the required application.

You can perform the following actions in this module:

Test Connectivity: Verify the webhook connection to ensure a successful event creation.
Create Events: Create new events with either detailed or concise response data.
Create Events through Payload: Create new events by passing the app identifier, action identifier, and data through the payload.

Sections

Orchestrate API Reference

Integrations

Playbooks

What made this section unhelpful for you?

What made this section unhelpful for you?

Authentication

Generate Open API Credentials

Mandatory Query Parameters for Requests

Integrations

Endpoints

GET

GET

GET

POST

GET

GET

GET

GET

POST

GET

POST

Playbooks

Endpoints

GET

GET

GET

GET

GET

GET

POST

GET

GET

GET

POST

Custom Email Templates

Endpoints

GET

GET

Code Snippets

Endpoints

GET

GET

Persistent List

Endpoints

GET

GET

POST

PUT

PUT

GET

GET

Analytics

What made this section unhelpful for you?

Endpoints

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

What made this section unhelpful for you?

Get Playbook Run Count

Query Parameters

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Get Most Active Playbooks

Query Parameters

ResponseExpand all

Response Attributes

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response

Response