SOCRadar Integration Guide

Overview

The SOCRadar integration connects NINA workflows to SOCRadar's Extended Threat Intelligence (XTI) platform across 8 resources and 35 operations:

Digital Risk Protection:

Incident — List, retrieve, change the status of, comment on, and tag SOCRadar incidents/alarms
Takedown — Request domain, social media, and source code takedowns and track their progress
Brand Protection — Impersonating accounts/domains, rogue mobile apps, bad reputation, and social media findings
Dark Web — Botnet data, black market, suspicious content, PII exposure, and IM content monitoring
Fraud Protection — Phishing, scam, and payment fraud findings

Attack Surface & Audit:

Digital Footprint (ASM) — Discover assets, add new assets, mark false positives, and toggle monitoring
Audit Log — Retrieve user activity / audit log entries

Threat Intelligence:

Threat Intelligence — Score IPs/domains/hashes, enrich indicators, rapid reputation lookups, and threat feed collections

Authentication uses a single company API key plus a company ID. All resources share the same credential.

Rate limits: SOCRadar enforces a strict budget of 6 requests/minute and 1,500 requests/month per API key. Design workflows to be conservative — avoid tight polling loops and cache results where possible.

Credential Configuration

Authentication

Field	Description	Default
API Key	Your SOCRadar company API key	—
Company ID	Your SOCRadar company ID	—
Base URL	API endpoint	`https://platform.socradar.com/api`

The API key is sent as the Api-Key header for most endpoints, and as the key query parameter for the threat analysis endpoints. The integration handles this automatically — you only supply the key once.

How to Get Your SOCRadar API Key

Log in to the SOCRadar Platform
Navigate to Settings → Integration Page → API Reference tab
Copy your API Key and Company ID
Confirm your subscription tier includes the modules your workflows require (Dark Web, ASM, Threat Intelligence, etc.)

Subscription notes:

Available endpoints depend on your SOCRadar subscription and enabled modules
Each company has a unique API key; the company ID scopes all platform/CTI requests to your tenant

Creating a Credential in NINA

Navigate to Credentials → Add New Credential
Select integration service: SOCRadar
Auth type: API Key
Fill in your API Key and Company ID, and optionally override the Base URL
Click Test Connection then Save

The connection test calls SOCRadar's lightweight /threat/analysis/check/auth endpoint to verify the key without consuming meaningful quota.

Supported Resources and Operations

Incident

SOCRadar incidents/alarms: list, retrieve, change status, comment, and tag.

Operation	Name	HTTP	Description
`list`	List Incidents	`GET /company/{companyId}/incidents/v4`	List incidents/alarms for the company
`get`	Get Incident	`GET /company/{companyId}/incidents/v4`	Retrieve a single incident, filtered by `id`
`changeStatus`	Change Status	`POST /company/{companyId}/alarms/status/change`	Change the status of one or more incidents/alarms
`addComment`	Add Comment	`POST /company/{companyId}/alarm/add/comment/v2`	Add a comment to an incident/alarm
`addTag`	Add Tag	`POST /company/{companyId}/alarm/tag`	Add a tag to an incident/alarm
`removeTag`	Remove Tag	`DELETE /company/{companyId}/alarm/tag`	Remove a tag from an incident/alarm

Key parameters:

id — incident/alarm ID (required for get)
alarm_id — incident/alarm ID (required for addComment, addTag, removeTag)
comment — comment text (addComment)
tag — tag value (addTag, removeTag)
page / limit / start_date / end_date — optional filters for list

Changing incident status:

changeStatus is how you mark an incident as a false positive, resolve it, or move it through triage.

Parameter	Required	Description
`alarm_ids`	Yes	One or more incident/alarm IDs. A single `alarm_id` is also accepted
`status`	Yes	The new status (see values below)
`comments`	No	Note explaining the status change
`update_related_finding_status`	No	Also apply the status to the findings behind the alarm
`email`	Conditional	Email of the user making the change — required when `update_related_finding_status` is `true`

Available status values:

Status	Meaning	Status	Meaning
`OPEN`	Untriaged	`FALSE_POSITIVE`	Not a genuine finding
`INVESTIGATING`	Under active triage	`DUPLICATE`	Already tracked elsewhere
`RESOLVED`	Closed as handled	`PROCESSED_INTERNALLY`	Handled outside the platform
`PENDING_INFO`	Awaiting more detail	`MITIGATED`	Risk reduced but not closed
`LEGAL_REVIEW`	With legal	`NOT_APPLICABLE`	Out of scope
`VENDOR_ASSESSMENT`	With a third party

The values are also accepted in the spelling the SOCRadar UI shows — "False Positive" works as well as "FALSE_POSITIVE".

Takedown

Create and track takedown requests.

Operation	Name	HTTP	Description
`createDomain`	Create Domain Takedown	`POST /add/company/{companyId}/takedown/request`	Request a takedown for a malicious/phishing domain
`createSocialMedia`	Create Social Media Takedown	`POST /add/company/{companyId}/takedown/request/social_media_risks`	Request a takedown for a social media impersonation/risk
`createSourceCode`	Create Source Code Takedown	`POST /add/company/{companyId}/takedown/request/source_code_leaks`	Request a takedown for leaked source code
`getProgress`	Get Takedown Progress	`GET /get/company/{companyId}/takedown/progress`	Retrieve the status/progress of takedown requests

Key parameters:

domain — target domain (createDomain)
url — offending URL (createSocialMedia, createSourceCode)
note — optional context for the request

Brand Protection

Impersonation, rogue apps, bad reputation, and social media findings.

Operation	Name	HTTP	Description
`list`	List Brand Protection Findings	`GET /company/{companyId}/brand-protection`	List all brand protection findings
`getDetails`	Get Brand Protection Details	`GET /company/{companyId}/brand-protection/{recordId}`	Retrieve details for a specific record
`impersonatingAccounts`	Impersonating Accounts	`GET /company/{companyId}/brand-protection/impersonating-accounts/v2`	List impersonating account findings
`impersonatingDomains`	Impersonating Domains	`GET /company/{companyId}/brand-protection/impersonating-domains/v2`	List impersonating/look-alike domain findings
`rogueMobileApplications`	Rogue Mobile Applications	`GET /company/{companyId}/brand-protection/rogue-mobile-applications/v2`	List rogue mobile application findings
`badReputation`	Bad Reputation	`GET /company/{companyId}/brand-protection/bad-reputation/v2`	List bad reputation findings
`socialMediaFindings`	Social Media Findings	`GET /company/{companyId}/brand-protection/social-media-findings/v2`	List social media findings

Key parameters:

recordId — record ID (required for getDetails, path parameter)
page / limit / start_date / end_date — optional filters

Dark Web

Dark web monitoring: botnet data, black market, suspicious content, PII exposure, and IM content.

Operation	Name	HTTP	Description
`botnetData`	Botnet Data	`GET /company/{companyId}/dark-web-monitoring/botnet-data/v2`	List botnet data findings
`blackmarket`	Black Market	`GET /company/{companyId}/dark-web-monitoring/blackmarket/v2`	List black market findings
`suspiciousContent`	Suspicious Content	`GET /company/{companyId}/dark-web-monitoring/suspicious-content/v2`	List suspicious content findings
`piiExposure`	PII Exposure	`GET /company/{companyId}/dark-web-monitoring/pii-exposure/v2`	List PII exposure / account leak findings
`imContent`	IM Content	`GET /company/{companyId}/dark-web-monitoring/im-content/v2`	List instant-messaging (IM) content findings

Key parameters:

page / limit / start_date / end_date — optional filters (filter by leak date range where supported)

Digital Footprint (ASM)

Attack surface management: assets, false-positive marking, and monitoring.

Operation	Name	HTTP	Description
`getAssets`	Get Digital Assets	`GET /company/{companyId}/asm`	List discovered digital assets
`addAsset`	Add Asset	`POST /company/{companyId}/asm/add/{asset_type}`	Add a new asset of the given type to the inventory
`markFalsePositive`	Mark False Positive	`POST /company/{companyId}/asm/fp`	Mark an asset as a false positive
`toggleMonitoring`	Toggle Monitoring	`POST /company/{companyId}/asm/monitor`	Enable or disable monitoring for an asset

Key parameters:

asset_type — asset type (required for addAsset, path parameter); enum: domain, ipAddress, website, cloudBuckets
value — the asset value (addAsset)
asset_id — target asset ID (markFalsePositive, toggleMonitoring)
monitor — boolean; whether to enable monitoring (toggleMonitoring)

Fraud Protection

Phishing, scams, and payment fraud findings.

Operation	Name	HTTP	Description
`list`	List Fraud Protection Findings	`GET /company/{companyId}/fraud-protection/v2`	List fraud protection findings

Key parameters:

page / limit / start_date / end_date — optional filters

Audit Log

User activity / audit logs.

Operation	Name	HTTP	Description
`list`	List Audit Logs	`GET /company/{companyId}/auditlogs`	List user audit log entries

Key parameters:

page / limit / start_date / end_date — optional filters

Threat Intelligence

IP/domain/hash scoring, IoC enrichment, rapid reputation, and threat feeds. These endpoints sit outside the company tenant path; the integration handles their distinct authentication automatically.

Operation	Name	HTTP	Description
`scoreIp`	Score IP	`GET /threat/analysis`	Threat score and analysis for an IP address
`scoreDomain`	Score Domain	`GET /threat/analysis`	Threat score and analysis for a domain
`scoreHash`	Score Hash	`GET /threat/analysis`	Threat score and analysis for a file hash (MD5/SHA-1/SHA-256)
`checkAuth`	Check Auth	`GET /threat/analysis/check/auth`	Verify the API key against the threat analysis endpoint
`enrichIndicator`	Enrich Indicator	`POST /ioc_enrichment/get/indicator_details`	Enrich an indicator with details, history, and relations
`rapidReputation`	Rapid Reputation	`GET /threatfeed/rapid/reputation`	Rapid reputation verdict for an entity
`getFeedList`	Get Threat Feed	`GET /threat/intelligence/feed_list/{collection_uuid}.{format}`	Fetch indicators from a threat intelligence feed collection

Key parameters:

entity — the value to analyze (required for scoreIp, scoreDomain, scoreHash)
indicator — the indicator value to enrich (enrichIndicator); type is auto-detected (IP, domain, URL, or hash)
fields — enrichment fields array (enrichIndicator); enum: indicator_details, indicator_history, indicator_relations, indicator_ai_insight
includeAiInsights — boolean; adds AI-generated insights to enrichment (enrichIndicator)
entity_value + entity_type — both required for rapidReputation; entity_type enum: ip, hostname, url, hash
collection_uuid — feed collection UUID (required for getFeedList, path parameter); format enum: json (default), csv, stix

Examples

Score an IP Address

{
  "integration_service": "socradar",
  "resource": "threatIntelligence",
  "operation": "scoreIp",
  "parameters": {
    "entity": "8.8.8.8"
  }
}

Enrich an Indicator with AI Insights

{
  "integration_service": "socradar",
  "resource": "threatIntelligence",
  "operation": "enrichIndicator",
  "parameters": {
    "indicator": "malicious-domain.com",
    "includeAiInsights": true
  }
}

Rapid Reputation Lookup

{
  "integration_service": "socradar",
  "resource": "threatIntelligence",
  "operation": "rapidReputation",
  "parameters": {
    "entity_value": "1.2.3.4",
    "entity_type": "ip"
  }
}

List Recent Incidents

{
  "integration_service": "socradar",
  "resource": "incident",
  "operation": "list",
  "parameters": {
    "start_date": "2026-05-01",
    "end_date": "2026-06-01",
    "limit": 50
  }
}

Comment on an Incident

{
  "integration_service": "socradar",
  "resource": "incident",
  "operation": "addComment",
  "parameters": {
    "alarm_id": "123456",
    "comment": "Triaged — confirmed phishing domain. Initiating takedown."
  }
}

Mark an Incident as a False Positive

{
  "integration_service": "socradar",
  "resource": "incident",
  "operation": "changeStatus",
  "parameters": {
    "alarm_ids": ["123456"],
    "status": "FALSE_POSITIVE",
    "comments": "Asset is not ours — belongs to a different tenant."
  }
}

Resolve Several Incidents at Once

{
  "integration_service": "socradar",
  "resource": "incident",
  "operation": "changeStatus",
  "parameters": {
    "alarm_ids": ["123456", "123457", "123458"],
    "status": "RESOLVED",
    "comments": "Credentials rotated and access revoked."
  }
}

{
  "integration_service": "socradar",
  "resource": "incident",
  "operation": "changeStatus",
  "parameters": {
    "alarm_ids": ["123456"],
    "status": "RESOLVED",
    "comments": "Takedown confirmed complete.",
    "update_related_finding_status": true,
    "email": "[email protected]"
  }
}

Request a Domain Takedown

{
  "integration_service": "socradar",
  "resource": "takedown",
  "operation": "createDomain",
  "parameters": {
    "domain": "phishing-example.com",
    "note": "Impersonating our brand login page"
  }
}

List PII Exposure Findings

{
  "integration_service": "socradar",
  "resource": "darkWeb",
  "operation": "piiExposure",
  "parameters": {
    "start_date": "2026-05-01",
    "end_date": "2026-06-01"
  }
}

Add an Asset to the Attack Surface

{
  "integration_service": "socradar",
  "resource": "digitalFootprint",
  "operation": "addAsset",
  "parameters": {
    "asset_type": "domain",
    "value": "new-subsidiary.com"
  }
}

Fetch a Threat Feed Collection

{
  "integration_service": "socradar",
  "resource": "threatIntelligence",
  "operation": "getFeedList",
  "parameters": {
    "collection_uuid": "00000000-0000-0000-0000-000000000000",
    "format": "json"
  }
}

Common Workflow Patterns

Indicator Enrichment Pipeline

Extract an observable (IP/domain/hash) from an upstream node
scoreIp / scoreDomain / scoreHash (threatIntelligence) — get a fast threat score
enrichIndicator — pull detailed context, history, and relations for high-scoring indicators
Branch the workflow on the verdict (alert, block, or ignore)

Incident Triage Workflow

list (incident) — fetch recent incidents/alarms (scope with start_date / end_date)
changeStatus → INVESTIGATING — claim the alarm as it enters triage
addComment — record triage notes on the alarm
addTag — tag the alarm for routing/reporting
createDomain (takedown) — initiate a takedown when the alarm is a confirmed phishing domain
changeStatus → RESOLVED or FALSE_POSITIVE — close the alarm out with a comments note explaining the verdict

Automated False-Positive Suppression

list (incident) — pull new alarms
Match them against your allowlist (known assets, sanctioned tooling, test infrastructure) in an upstream node
changeStatus → FALSE_POSITIVE — batch the matches into a single call via alarm_ids, with comments recording the suppression rule that fired
Route only the unmatched alarms onward to an analyst or ticketing node

Brand & Dark Web Monitoring

impersonatingDomains / impersonatingAccounts (brandProtection) — pull look-alike findings
piiExposure / blackmarket (darkWeb) — check for leaked credentials and data
Forward findings to a ticketing or SIEM integration node
getProgress (takedown) — track open takedown requests to closure

Attack Surface Management

getAssets (digitalFootprint) — list discovered assets
markFalsePositive — clean up incorrectly attributed assets
addAsset — register newly acquired domains/IPs
toggleMonitoring — enable monitoring on critical assets

Troubleshooting

Issue	Resolution
401 / 403 Unauthorized	API key invalid, or the module is not included in your subscription — verify the key and Company ID in Platform Settings
429 Too Many Requests	Rate limit hit (6/min, 1,500/month) — add delays, reduce polling, and cache results
Empty results	No findings for the requested range; widen `start_date` / `end_date` or confirm the module is enabled
`companyId is required`	Company ID missing from the credential — add it under the credential configuration
Missing path parameter error	Ensure `recordId` (brand protection), `asset_type` (ASM add), or `collection_uuid` (threat feed) is supplied
`entity is required` on a score operation	Provide the `entity` parameter (the IP, domain, or hash to analyze)
`entity_type` rejected on rapid reputation	Use exact enum values: `ip`, `hostname`, `url`, `hash`
Threat feed returns unexpected format	Set `format` to `json` for structured output; `csv`/`stix` return raw payloads wrapped under `data`
`unsupported alarm status` on `changeStatus`	Use one of the listed status values (e.g. `FALSE_POSITIVE`, `RESOLVED`) — the error message lists them all
`alarm_ids is required` on `changeStatus`	Supply `alarm_ids` (or a single `alarm_id`); an empty list from an upstream node triggers this too
`email is required when update_related_finding_status is true`	SOCRadar attributes finding-level changes to a user — add the `email` parameter or drop `update_related_finding_status`
`SOCRadar rejected the status change`	The API accepted the request but declined the transition — usually an unknown alarm ID or an API key without write permission on that module
Status change appears to succeed but nothing changes in the UI	Confirm you are targeting the right tenant: `alarm_ids` are scoped to the Company ID on the credential

Security Considerations

Protect API Keys: Store the API key and Company ID exclusively through NINA credential management — never in workflow parameters or logs
Sensitive Data: Dark web, PII exposure, and credential findings are highly sensitive — restrict workflow access accordingly
Respect the Request Budget: The 1,500/month limit is shared across all workflows using the key — monitor usage to avoid exhausting it during incidents
Credential Rotation: Rotate the API key periodically; revoke immediately if compromised
Least Privilege: Scope workflows to the modules they actually need, in line with your SOCRadar subscription

Additional Resources

Updated: 2026-07-27

Overview​

Credential Configuration​

Authentication​

How to Get Your SOCRadar API Key​

Creating a Credential in NINA​

Supported Resources and Operations​

Incident​

Takedown​

Brand Protection​

Dark Web​

Digital Footprint (ASM)​

Fraud Protection​

Audit Log​

Threat Intelligence​

Examples​

Score an IP Address​

Enrich an Indicator with AI Insights​

Rapid Reputation Lookup​

List Recent Incidents​

Comment on an Incident​

Mark an Incident as a False Positive​

Resolve Several Incidents at Once​

Resolve an Incident and Its Related Findings​

Request a Domain Takedown​

List PII Exposure Findings​

Add an Asset to the Attack Surface​

Fetch a Threat Feed Collection​

Common Workflow Patterns​

Indicator Enrichment Pipeline​

Incident Triage Workflow​

Automated False-Positive Suppression​

Brand & Dark Web Monitoring​

Attack Surface Management​

Troubleshooting​

Security Considerations​

Additional Resources​

Overview

Credential Configuration

Authentication

How to Get Your SOCRadar API Key

Creating a Credential in NINA

Supported Resources and Operations

Incident

Takedown

Brand Protection

Dark Web

Digital Footprint (ASM)

Fraud Protection

Audit Log

Threat Intelligence

Examples

Score an IP Address

Enrich an Indicator with AI Insights

Rapid Reputation Lookup

List Recent Incidents

Comment on an Incident

Mark an Incident as a False Positive

Resolve Several Incidents at Once

Resolve an Incident and Its Related Findings

Request a Domain Takedown

List PII Exposure Findings

Add an Asset to the Attack Surface

Fetch a Threat Feed Collection

Common Workflow Patterns

Indicator Enrichment Pipeline

Incident Triage Workflow

Automated False-Positive Suppression

Brand & Dark Web Monitoring

Attack Surface Management

Troubleshooting

Security Considerations

Additional Resources