Socradar incident V4
SOCRadar is a threat intelligence platform that helps organizations detect, analyze, and respond to security threats.
SOCRadar is a comprehensive threat intelligence platform that provides real-time insights into security incidents and vulnerabilities. The Socradar Incident V4 Connector allows Swimlane Turbine users to automate the retrieval and management of security incidents and alarm statuses. By integrating with Socradar, users can efficiently fetch incidents with detailed compliance and response actions, and update alarm statuses seamlessly. This integration enhances the capabilities of security teams by streamlining incident management and enabling proactive threat response within the Swimlane Turbine platform.
Limitations
- Company ID must be supplied on each action; it is not configured on the asset.
- Retrieve Incidents returns up to 100 records per page.
- The API returns newest incidents on page 1; use reverse pagination when processing large result sets chronologically.
- Additional incident management endpoints (comments, assignees, tags, severity) are not included in this release.
Supported Versions
- This SOCRadar connector uses the Incident API v4.
Additional Documents
- Documentation SOCRadar Platform
Configuration
Prerequisites
Before you can use the SOCRadar Incident V4 connector for Turbine, you'll need access to the SOCRadar API. This requires the following:
- API key authentication using the following parameters:
- URL: The endpoint URL for accessing the SOCRadar API.
- API Key: A unique key provided by SOCRadar to authenticate API requests.
Authentication Methods
API Key Authentication for SOCRadar using the following parameters:
- URL: The endpoint URL for accessing the SOCRadar API.
- API Key: A token used to authenticate API requests securely via the Api-Key header.
- Verify SSL Certificates: Optional setting to validate the server TLS certificate.
- HTTP(s) Proxy: Optional proxy URL for outbound requests.
Capabilities
This SOCRadar connector provides the following capabilities:
- Retrieve Incidents
- Update Alarm Status
Retrieve Incidents
- Fetch security incidents from SOCRadar Incident API v4 with details, compliance info, and response actions. Supports pagination, date filters, alarm/tag/assignee filters, and optional enrichment flags (GET /company/{company_id}/incidents/v4).
Update Alarm Status
- Update the status of one or more alarms for a company. Required fields include alarm_ids and status. Optional fields include comments, update_related_finding_status, and email (POST /company/{company_id}/alarms/status/change).
Configurations
API Key Authentication
Authenticates using an API Key passed in the Api-Key header
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | SOCRadar API base URL. | string | Required |
api_key | Company API key from SOCRadar (Settings β API & Integrations β API Options). | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Retrieve Incidents
Fetch security incidents from Socradar Incident API v4 with compliance info and response actions. Supports pagination, date filters, alarm/notification/tag filters, and optional enrichment flags. Requires company_id as a path parameter.
Endpoint
- URL: company/{{company_id}}/incidents/v4
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.company_id | string | Required | SOCRadar company identifier (integer). |
parameters.page | integer | Optional | Page number for pagination. |
parameters.limit | integer | Optional | Number of results per page (maximum 100). |
parameters.start_date | string | Optional | Filter incidents on or after this date (epoch seconds or YYYY-MM-DD). |
parameters.end_date | string | Optional | Filter incidents on or before this date (epoch seconds or YYYY-MM-DD). |
parameters.status | array | Optional | Filter by incident status. |
parameters.severities | array | Optional | Filter by severity levels. |
parameters.alarm_main_types | array | Optional | Filter by main alarm types (for example, Brand Protection). |
parameters.alarm_sub_types | array | Optional | Filter by alarm sub types (for example, Impersonating Domain). |
parameters.alarm_type_ids | array | Optional | Include only alarms matching these type IDs. |
parameters.excluded_alarm_type_ids | array | Optional | Exclude alarms matching these type IDs. |
parameters.excluded_alarm_main_types | array | Optional | Exclude alarms matching these main types. |
parameters.excluded_alarm_sub_types | array | Optional | Exclude alarms matching these sub types. |
parameters.tags | array | Optional | Filter by alarm tags. |
parameters.assignees | array | Optional | Filter by assignee email addresses. |
parameters.include_total_records | boolean | Optional | Include total_pages and total_records in the response. |
parameters.include_alarm_details | boolean | Optional | Include alarm type details in each incident. |
parameters.include_ai_decision | boolean | Optional | Include AI decision details in the response when available. |
parameters.include_rule_details | boolean | Optional | Include rule details in the response when available. |
parameters.include_company_id | boolean | Optional | Include company_id in each alarm record. |
Input Example
{"path_parameters":{"company_id":"string"},"parameters":{"page":1,"limit":20,"start_date":"string","end_date":"string","status":["string"],"severities":["string"],"alarm_main_types":["string"],"alarm_sub_types":["string"],"alarm_type_ids":[],"excluded_alarm_type_ids":[],"excluded_alarm_main_types":["string"],"excluded_alarm_sub_types":["string"],"tags":["string"],"assignees":["string"],"include_total_records":true,"include_alarm_details":true,"include_ai_decision":true,"include_rule_details":true,"include_company_id":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | integer | HTTP status code of the response. |
is_success | boolean | Whether the operation was successful |
message | string | Response message |
data | object | Response data |
data.alarms | array | Response data |
data.total_pages | integer | Response data |
data.total_records | integer | Response data |
Output Example
{"is_success":true,"message":"string","data":{"alarms":[],"total_pages":123,"total_records":123}}
Update Alarm Status
Update the status of SOCRadar alarms for a company using v4 codes. Requires company_id, alarm_ids, and status, with optional comments, related-finding updates, and action owner email.
Endpoint
- URL: company/{{company_id}}/alarms/status/change
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.company_id | string | Required | SOCRadar company identifier (integer). |
alarm_ids | array | Optional | Alarm IDs to update. |
status | integer | Optional | New alarm status code. 0=OPEN, 1=INVESTIGATING, 2=RESOLVED, 4=PENDING_INFO, 5=LEGAL_REVIEW, 6=VENDOR_ASSESSMENT, 9=FALSE_POSITIVE, 10=DUPLICATE, 11=PROCESSED_INTERNALLY, 12=MITIGATED, 13=NOT_APPLICABLE. |
comments | string | Optional | Optional comments explaining the status change. |
update_related_finding_status | boolean | Optional | Whether to update the status of related findings. |
string | Optional | Email of the action owner. Required when update_related_finding_status is true. |
Input Example
{"path_parameters":{"company_id":"string"},"alarm_ids":["string"],"status":123,"comments":"string","update_related_finding_status":true,"email":"[email protected]"}
Output
Parameter | Type | Description |
|---|---|---|
status_code | integer | HTTP status code of the response. |
is_success | boolean | Whether the operation was successful |
message | string | Response message |
data | object | Response data |
Output Example
{"is_success":true,"message":"string","data":{}}
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 |