Cyberhaven Connector

Cyberhaven provides advanced data tracing and DLP capabilities to monitor, analyze, and protect sensitive information across endpoints and users.

Cyberhaven is a leading data detection and response (DDR) platform that protects sensitive data from insider threats and data loss by monitoring endpoints, user activity, and incidents in real time. This connector enables Swimlane Turbine users to automate the retrieval, management, and enrichment of Cyberhaven DLP incidents, endpoint compliance status, event details, and insider risk scores—without writing code. By integrating Cyberhaven with Turbine, security teams can streamline incident response, accelerate investigations, and maintain continuous compliance across their environment. The connector empowers users to orchestrate complex workflows, reduce manual effort, and respond faster to data risks and policy violations.

Limitations

not_seen_for_days and unassigned_policy_only on List Endpoints are applied to the page the API returns. Increase the page size, or page with page_id, when you need a wider set. The API status inactive selects endpoints that are not reporting, and general_update_required selects outdated agents.

User risk scores are taken from incident fields risk_score and user_risk_groups on the incident page you request.

Supported Versions

Cyberhaven public API v2.

Prerequisites

To use the Cyberhaven connector, ensure you have the following prerequisites:

Token authentication using a long-lived refresh token. The connector exchanges this for a short-lived access token and refreshes it automatically. The refresh token is securely stored in the Swimlane vault.

URL: The base URL for your Cyberhaven API instance.

Refresh Token: A long-lived refresh token used to obtain and renew access tokens for API authentication.

Authentication Methods

The connector posts the refresh token to /public/v2/auth/token/access and sends the returned bearer token on later calls. Access tokens last about 15 minutes. The connector refreshes the token before it expires and again if Cyberhaven returns HTTP 401.

Capabilities

List Endpoints

List Incidents

Get Incident

Update Incident

Get Event Details

Get Event Lineage

Get User Risk Scores

List Endpoints

Retrieves endpoint inventory from POST /public/v2/endpoints/list.

Use case	Inputs
Outlook plugin disabled	statuses: win_outlook_plugin_disabled
Operating system	oses: windows
Endpoint group	groups: Testing
Outdated agent	statuses: general_update_required, or lightbeam_versions
Not seen	statuses: inactive, or not_seen_for_days
No assigned group	unassigned_policy_only: true

List Incidents

Lists incidents from POST /public/v2/incidents/list. Filter with policy_severities (informational, low, medium, high, critical), status, user, assignee, or time range.

Get Incident

Loads one incident by id, including policy, user, risk score, and event details.

Update Incident

Updates an incident with PATCH /public/v2/incidents/{id}. Set status to closed and a close_reason to close it. API close reasons are valid, invalid_data_mislabled, invalid_destination_not_risk, invalid_user_exempt, and invalid_other.

Get Event Details

Loads EventService records from POST /public/v2/event-details.

Get Event Lineage

Loads the lineage chain between two events from POST /public/v2/event-lineage.

Get User Risk Scores

Lists incidents for the users you name and returns each user's highest risk_score, user_risk_groups, and incident count.

Additional Documentation

Cyberhaven API documentation

Configurations

Cyberhaven API Authentication

Token authentication using a long-lived refresh token. The connector exchanges it for a short-lived access token and refreshes that token automatically. The refresh token is stored as a password so Turbine keeps it in the vault.

Configuration Parameters

Parameter	Description	Type	Required
url	Cyberhaven tenant URL, for example https://example.cyberhaven.io.	string	Required
refresh_token	Long-lived refresh token from the Cyberhaven console (Preferences > API token management). Stored in the Turbine vault.	string	Required
verify_ssl	Verify the Cyberhaven server certificate.	boolean	Optional
http_proxy	Proxy to route requests through.	string	Optional

Actions

Get Event Details

Retrieve detailed records for one or more Cyberhaven event IDs by calling the EventService endpoint.

Endpoint

URL: /public/v2/event-details

Method: POST

Input

Argument Name	Type	Required	Description
event_ids	array	Optional	Event UUIDs to retrieve.

Input Example

{"json_body":{"event_ids":["11111111-2222-3333-4444-555555555555"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
resources	array	Output field: resources
resources.id	string	Unique identifier
resources.timestamp	string	Output field: resources.timestamp
resources.user	object	Output field: resources.user
resources.action	object	Output field: resources.action
resources.source	object	Output field: resources.source
resources.destination	object	Output field: resources.destination

Output Example

{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","timestamp":"2024-01-01T00:00:00Z","user":{},"action":{},"source":{},"destination":{}}]}

Get Event Lineage

Retrieve the lineage chain between two Cyberhaven events by specifying start and end event IDs, providing a detailed trace of related activities.

Endpoint

URL: /public/v2/event-lineage

Method: POST

Input

Argument Name	Type	Required	Description
start_event_id	string	Optional	UUID of the first event in the chain.
end_event_id	string	Optional	UUID of the last event in the chain.

Input Example

{"json_body":{"start_event_id":"11111111-2222-3333-4444-555555555555","end_event_id":"66666666-7777-8888-9999-aaaaaaaaaaaa"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
resources	array	Output field: resources

Output Example

{"resources":["string"]}

Get Incident

Fetch a specific Cyberhaven incident by incident ID, including policy, user, risk score, and event details using the POST /public/v2/incidents/list endpoint.

Endpoint

URL: /public/v2/incidents/list

Method: POST

Input

Argument Name	Type	Required	Description
incident_id	string	Optional	Cyberhaven incident id.
include_ai_summaries	boolean	Optional	Include the AI-generated summary. Defaults to true.

Input Example

{"json_body":{"incident_id":"6f1c0a2e-1b2c-4d5e-8f90-1234567890ab","include_ai_summaries":true}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
resources	array	Output field: resources
resources.id	string	Unique identifier
resources.status	string	Status value
resources.blocked	boolean	Output field: resources.blocked
resources.trigger_time	string	Time value
resources.event_time	string	Time value
resources.ai_summary	string	Output field: resources.ai_summary
resources.risk_score	number	Score value
resources.user_risk_groups	array	Output field: resources.user_risk_groups
resources.assigned_to	string	Output field: resources.assigned_to
resources.close_reason	string	Response reason phrase
resources.close_note	string	Output field: resources.close_note
resources.user	object	Output field: resources.user
resources.policy	object	Output field: resources.policy
resources.dataset	object	Response data
resources.event_details	object	Output field: resources.event_details
resources.event_lineage_id	object	Unique identifier
page_response	object	Output field: page_response

Output Example

{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","blocked":true,"trigger_time":"string","event_time":"string","ai_summary":"string","risk_score":123,"user_risk_groups":[],"assigned_to":"string","close_reason":"string","close_note":"string","user":{},"policy":{},"dataset":{},"event_details":{}}],"page_response":{}}

Get User Risk Scores

Retrieve insider-risk scores for users from Cyberhaven incidents, returning each user's highest risk score, associated risk groups, and incident count.

Endpoint

URL: /public/v2/incidents/list

Method: POST

Input

Argument Name	Type	Required	Description
user	string	Optional	Email or alias of one user. Combined with users when both are set.
users	array	Optional	Emails or aliases to include.
policy_severities	array	Optional	Only consider incidents at these severities.
resolution_statuses	array	Optional	Only consider incidents in these statuses.
start_time	string	Optional	Include incidents at or after this UTC time, formatted as yyyy-mm-ddTHH:MM:SSZ.
end_time	string	Optional	Include incidents before this UTC time, formatted as yyyy-mm-ddTHH:MM:SSZ.
page_size	number	Optional	Incidents to read when building scores. The API accepts up to 200.
page_id	string	Optional	page_response.next_id from a previous response.

Input Example

{"json_body":{"user":"[email protected]","policy_severities":["high","critical"],"page_size":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
users	array	One score row per user found in the incident page.
users.id	string	Unique identifier
users.email	string	Output field: users.email
users.local_id	string	Unique identifier
users.risk_score	number	Highest incident risk score seen for this user on the page.
users.user_risk_groups	array	Output field: users.user_risk_groups
users.incident_count	number	Unique identifier
users.highest_policy_severity	string	Output field: users.highest_policy_severity
resources	array	Incidents used to build the scores.
page_response	object	Output field: page_response

Output Example

{"users":[{"id":"12345678-1234-1234-1234-123456789abc","email":"[email protected]","local_id":"string","risk_score":123,"user_risk_groups":[],"incident_count":123,"highest_policy_severity":"string"}],"resources":[],"page_response":{}}

List Endpoints

Retrieve and filter Cyberhaven endpoints based on compliance criteria such as disabled Outlook plugins, operating system, group assignment, agent status, and activity.

Endpoint

URL: /public/v2/endpoints/list

Method: POST

Input

Argument Name	Type	Required	Description
statuses	array	Optional	Endpoint statuses to include. Outlook plugin disabled is win_outlook_plugin_disabled. Outdated agents use general_update_required. Endpoints that are not reporting use inactive.
not_statuses	array	Optional	Endpoint statuses to exclude.
oses	array	Optional	Operating systems to include, for example windows.
os_versions	array	Optional	Operating system versions to include.
groups	array	Optional	Endpoint group names to include, for example Testing.
hostnames	array	Optional	Hostnames to include.
ids	array	Optional	Endpoint record ids to include.
lightbeam_versions	array	Optional	Sensor versions to include. Use this with general_update_required to find outdated agents.
status_groups	array	Optional	Status groups to include.
deleted	boolean	Optional	When true, include deleted endpoints.
not_seen_for_days	number	Optional	Keep endpoints on this page whose last report_time is older than this many days, or that have no report time. Pair with a large page size. The inactive status filter asks the API for endpoints that are not reporting.
unassigned_policy_only	boolean	Optional	Keep endpoints on this page that have no group id and no group name.
page_id	string	Optional	next_page_id from a previous response. Leave empty for the first page.
size	number	Optional	Number of endpoints to request.
sort_by	string	Optional	Column to sort by.
sort_ascending	boolean	Optional	When true, sort ascending.

Input Example

{"json_body":{"statuses":["win_outlook_plugin_disabled"],"oses":["windows"],"groups":["Testing"],"size":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
next_page_id	string	Unique identifier
total_records	number	Output field: total_records
matched_records	number	Count after not_seen_for_days or unassigned_policy_only is applied to this page.
records	array	Output field: records
records.id	string	Unique identifier
records.endpoint_id	string	Unique identifier
records.hostname	string	Name of the resource
records.os	string	Output field: records.os
records.os_version	string	Output field: records.os_version
records.group_id	string	Unique identifier
records.group_name	string	Name of the resource
records.lightbeam_version	string	Output field: records.lightbeam_version
records.report_time	string	Time value
records.deleted	boolean	Output field: records.deleted
records.statuses_and_actions	array	Status value
records.statuses_and_actions.status	string	Status value
records.statuses_and_actions.required_action	string	Status value

Output Example

{"next_page_id":"string","total_records":123,"matched_records":123,"records":[{"id":"12345678-1234-1234-1234-123456789abc","endpoint_id":"string","hostname":"Example Name","os":"string","os_version":"string","group_id":"string","group_name":"Example Name","lightbeam_version":"string","report_time":"string","deleted":true,"statuses_and_actions":[]}]}

List Incidents

Retrieve a list of Cyberhaven DLP incidents with options to filter by policy severity, status, assignee, user, time range, or incident ID.

Endpoint

URL: /public/v2/incidents/list

Method: POST

Input

Argument Name	Type	Required	Description
policy_severities	array	Optional	Policy severities to include.
resolution_statuses	array	Optional	Incident statuses to include.
assignees	array	Optional	Analyst emails assigned to the incident.
users	array	Optional	Emails or aliases of users who triggered the incident.
incident_ids	array	Optional	Incident ids to include.
start_time	string	Optional	Include incidents at or after this UTC time, formatted as yyyy-mm-ddTHH:MM:SSZ.
end_time	string	Optional	Include incidents before this UTC time, formatted as yyyy-mm-ddTHH:MM:SSZ.
include_ai_summaries	boolean	Optional	Include AI-generated incident summaries. Defaults to true.
page_size	number	Optional	Incidents per page. The API defaults to 25 and accepts up to 200.
page_id	string	Optional	page_response.next_id from a previous response. Leave empty for the first page.
sort_by	string	Optional	Field to sort by. Defaults to trigger_time.

Input Example

{"json_body":{"policy_severities":["high","critical"],"resolution_statuses":["open"],"page_size":25,"sort_by":"trigger_time"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
resources	array	Output field: resources
resources.id	string	Unique identifier
resources.status	string	Status value
resources.blocked	boolean	Output field: resources.blocked
resources.trigger_time	string	Time value
resources.event_time	string	Time value
resources.reaction_time	string	Time value
resources.ai_summary	string	Output field: resources.ai_summary
resources.ai_severity	string	Output field: resources.ai_severity
resources.risk_score	number	Score value
resources.user_risk_groups	array	Output field: resources.user_risk_groups
resources.created_by	string	Output field: resources.created_by
resources.assigned_to	string	Output field: resources.assigned_to
resources.close_reason	string	Response reason phrase
resources.close_note	string	Output field: resources.close_note
resources.warning_status	string	Status value
resources.user	object	Output field: resources.user
resources.user.id	string	Unique identifier
resources.user.local_id	string	Unique identifier
resources.user.email	string	Output field: resources.user.email
resources.policy	object	Output field: resources.policy
resources.policy.id	string	Unique identifier
resources.policy.name	string	Name of the resource

Output Example

{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","blocked":true,"trigger_time":"string","event_time":"string","reaction_time":"string","ai_summary":"string","ai_severity":"string","risk_score":123,"user_risk_groups":[],"created_by":"string","assigned_to":"string","close_reason":"string","close_note":"string","warning_status":"active"}],"page_response":{"next_id":"string","total":123}}

Update Incident

Update or close a Cyberhaven incident by setting its status and providing a close reason such as valid, invalid_data_mislabled, invalid_destination_not_risk, invalid_user_exempt, or invalid_other.

Endpoint

URL: /public/v2/incidents/{{incident_id}}

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.incident_id	string	Required	Cyberhaven incident id to update.
status	string	Optional	New incident status.
close_reason	string	Optional	Reason recorded when closing the incident.
close_note	string	Optional	Free-text note stored with the closure.
assigned_to	string	Optional	Email of the analyst to assign.

Input Example

{"json_body":{"status":"closed","close_reason":"valid","close_note":"User confirmed the transfer was approved."},"path_parameters":{"incident_id":"6f1c0a2e-1b2c-4d5e-8f90-1234567890ab"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
resources	array	Output field: resources
resources.id	string	Unique identifier
resources.status	string	Status value
resources.assigned_to	string	Output field: resources.assigned_to
resources.close_reason	string	Response reason phrase
resources.close_note	string	Output field: resources.close_note

Output Example

{"resources":[{"id":"12345678-1234-1234-1234-123456789abc","status":"active","assigned_to":"string","close_reason":"string","close_note":"string"}]}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT