Orchestrate API Reference
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:
What made this section unhelpful for you?
Base URL
Sample:
https://tenantname.cyware.com/soarapi/openapi/
What made this section unhelpful for you?
Authentication
Users with access to Cyware Orchestrate's Open APIs module can generate the credentials for API authentication.
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 credentials. 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 + 20 secondsfor authentication. You can specify a margin of 10 to 15 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 + expiresformula. - Create a Signature value using the
Signature = Base64(HMAC-SHA1(secret_key, UTF-8-Encoding-Of(StringToSign)))formula.
The following Python code is a sample to generate a signature for endpoint authentication:
import base64
import hashlib
import hmac
import time
expires = int(time.time() + 20) # expires in 20 sec
def generate_signature(access_id, secret_key, expires):
to_sign = '{}\n{}'.format(access_id, expires)
return base64.b64encode(
hmac.new(
secret_key.encode('utf-8'),
to_sign.encode('utf-8'),
hashlib.sha1
).digest())#Example:
#access_id = "7e4e6a9c-11ca-40f4-95af-edae017358d0"
#secret_key = "e61e92fb-bfd9-4cef-9b21-6f1e8211b77b"#signature = generate_signature(access_id, secret_key, expires)
#signature = generate_signature(access_id, secret_key, expires)Integrations
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
GET
GET
POST
GET
GET
GET
GET
POST
GET
POST
Playbooks
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
GET
GET
GET
GET
GET
POST
GET
GET
GET
POST
Custom Email Templates
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
GET
Code Snippets
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
GET
Persistent List
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
GET
POST
PUT
PUT
GET
GET
GET
Analytics
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
GET
GET
GET
GET
GET
GET
GET
GET
GET
GET
GET
GET
Events
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
POST
GET
GET
POST
GET
Tags
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
GET
Webhooks
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.