Hudson Rock Integration Guide

Overview

The Hudson Rock integration lets your NINA workflows query Hudson Rock's Cavalier Infostealers API v3 — a threat-intelligence dataset built from millions of machines compromised by info-stealer malware. Use it to detect and investigate credential exposure: search by domain, employee/user login, IP, stealer, or machine; pull infostealer threat feeds (C2, ClickFix, PhaaS); run investigations (by file, term, keyword, password); and manage monitored companies.

The API is organized into nine resources (mirroring the API's own tags): Domain Intelligence, End User Protection, Investigations, Advanced Search, Keyword Search, Password Search, Threat Feeds, Company Management and Account Management — 32 operations in total.

Status

The integration is spec-driven and comprehensive: it exposes every operation the Cavalier API v3 defines (32 operations across 9 resources), generated directly from the API's OpenAPI specification. Nothing is synthesized — an operation appears only if the API documents it. The single deliberate addition is a client-side mask_passwords toggle (see below).

Supported resources: domain-intelligence, end-user-protection, investigations, advanced-search, keyword-search, password-search, threat-feeds, company-management, account-management.

Out of scope (for now):

OAuth flows — authentication is by API key only.

Credential Configuration

Before using the integration you must configure a credential.

Authentication Method

The Hudson Rock integration uses API Key authentication. The key is sent on every request as the api-key header. The base URL is fixed (https://api.hudsonrock.com/json/v3) and built into the integration, so the credential only needs the key itself.

Field	Description	Example
API Key	Your Hudson Rock Cavalier API key	`1a2b…`

How to get your API Key:

Request a free key at hudsonrock.com/free-api-key, or use the key provided with your commercial Hudson Rock subscription.
Endpoint access is governed by permission scopes on your key. A newly issued key typically has a limited set of scopes enabled; additional scopes (e.g. threat feeds, FortiBleed) are enabled by Hudson Rock via [email protected].

⚠️ Permissions and domain whitelist (most common causes of failures). Two independent access controls apply, and both surface as HTTP 403:

Scope not enabled → 403 "Insufficient permissions". The key is valid but lacks the permission scope for that endpoint. Contact [email protected] to enable it.

Domain not in your whitelist → 403 "…domains are not in your whitelist". The domain-list searches (searchByDomain, getDomainOverview, discovery) only accept domains on your account's whitelist; contact support to add more.

A correct key will still return 403 in either case — this is expected, not a credential error.

Creating a Hudson Rock Credential

Navigate to the Credentials section in NINA.
Click Add New Credential.
Fill in the credential details:
- Name: A descriptive name (e.g., "Hudson Rock Production").
- Integration Service: Select "Hudson Rock".
- Auth Type: "API Key" (selected automatically).
- API Key: Your Cavalier API key.
Click Test Connection to verify the credential (this calls GET /my-account).
Click Save.

Supported Resources and Operations

This is a representative summary; the full operation list is always available in the node's Operation dropdown. The Scope column names the permission required on your key.

Domain Intelligence

Domain-wide compromise intelligence and monitoring. The domain-list searches (searchByDomain, getDomainOverview, discovery) are whitelist-gated — they only accept domains on your account's whitelist (others return 403). assessment, searchByCompany, supplyChainRisks and getFortinetFeed are not domain-whitelist-restricted.

Operation	Description	Scope
`searchByDomain`	Compromised credentials for one or more domains (or `external_domains`)	`search-by-domain`
`getDomainOverview`	Aggregate compromise counts per domain	`search-by-domain`
`discovery`	Compromised URLs discovered for the domains	`search-by-domain`
`assessment`	Exposure assessment for a single domain	`search-by-domain`
`supplyChainRisks`	Inbound supply-chain (partner) risks	`search-by-domain` + `supply_chain_monitoring`
`searchByCompany`	Search by a Hudson Rock company id	`search-by-company`
`getFortinetFeed`	FortiBleed feed — uncensored credentials	`fortibleed`

End User Protection

Search and monitor end-user compromises.

Operation	Description	Scope
`searchByLoginEmails` / `searchByLoginUsernames`	By email / username logins	`search-by-login`
`searchByIp`	By IP address(es) or a CIDR range (mutually exclusive)	`search-by-ip`
`searchByStealer`	By stealer id(s)	`search-by-stealer`
`searchByPc`	By computer name(s)	`search-by-pc`

Investigations

Investigate compromised machines.

Operation	Description	Scope
`searchByFile`	By file name	`search-by-file`
`searchByTerm`	By search term(s)	`search-by-term`
`getInfectionAnalysis`	AI infection analysis for a stealer (5 req/10 s, browsing-history stealers)	`infection-analysis`
`categorizeStealerDomains`	Categorize a stealer's domains	`categorize-domains`

Advanced Search / Keyword Search / Password Search

Operation	Description	Scope
`advancedSearch`	Multi-domain search with company-size / industry / country / USA-region filters	`advanced-search`
`searchByKeyword`	Domains compromised for keyword(s)	`search-by-keyword`
`searchByKeywordUrls`	Compromised URLs for a keyword	`search-by-keyword`
`searchByPassword`	Records containing given password(s)	`search-by-password`

Threat Feeds

Infostealer C2, PhaaS and ClickFix feeds.

Operation	Description	Scope
`getC2Feed` / `getC2HostNetwork`	C2 feed / per-host network detail	`c2_threat_feed`
`getClickfixFeed` / `getClickfixDomain`	ClickFix feed / per-domain lookup	`clickfix_threat_feed`
`getPhaasFeed` / `getPhaasHostNetwork`	PhaaS feed / per-host network detail	`phaas_threat_feed`

Company Management (write operations)

Manage the companies and assets monitored under your account.

Operation	Description
`addCompany` / `removeCompany`	Create / delete a monitored company
`addCompanyAssets` / `removeCompanyAssets`	Add / remove domains, APKs, external domains
`setCompanyWebhook`	Configure the company's result webhook

When your organization has synced_data: true, company mutations require the owner role; other roles receive 403.

Account Management

Operation	Description
`getMyAccount`	Your account details, monitored domains, and whitelist (used by Test Connection)

Key Concepts

mask_passwords (client-side). Credential-returning operations expose a mask_passwords toggle. When enabled, the node redacts password and employee_session_cookies values in the response before writing output (a partial reveal, e.g. ab****). It is a client-side control — it is never sent to the API and does not change what Hudson Rock returns. Default: off. Turn it on for reporting or when the raw secret is not needed.
Rate limits. 50 requests / 10 s in general; 5 requests / 10 s for getInfectionAnalysis. Exceeding them returns 429. The server-side timeout is 90 s (408).
Pagination (cursor-based). Pass cursor and read the next nextCursor from the response (threat feeds use pageInfo.nextCursor; getFortinetFeed uses page/limit). Loop until the cursor is null.
additional_fields. An array of optional data blocks to include: search_data, installed_software, employee_session_cookies, password_strength, sensitive_applications, dir_tree. They increase response size and latency — request only what you consume.

Parameter Merging

The Hudson Rock integration uses NINA's standard parameter merging.

Parameter Sources (in order of precedence)

Node Parameters — values set directly on the integration node.
Extracted Parameters — values automatically pulled from the input data.
Input Data — the merged output of upstream nodes.

Path vs. body vs. query

Most operations are POST; their parameters form the JSON request body (domains, logins, ips, sort_by, cursor, additional_fields, …).
Path parameters are substituted into the URL: getC2HostNetwork/getPhaasHostNetwork take host; getClickfixDomain takes domain; the company-management operations take companyId.
getFortinetFeed is the only operation that uses query parameters (page, limit).

Examples

Search by domain

{
  "resource": "domain-intelligence",
  "operation": "searchByDomain",
  "parameters": {}
}

with input:

{ "domains": ["acme.com"], "types": ["employees"], "sort_by": "date_compromised", "sort_direction": "desc" }

(acme.com is a placeholder — use a domain on your account's whitelist. Enable mask_passwords on the node to redact credentials in the output.)

Search by IP or CIDR

{ "resource": "end-user-protection", "operation": "searchByIp", "parameters": {} }

with input { "ips": ["203.0.113.10"] } or { "cidr": "203.0.113.0/24" } (the two are mutually exclusive).

Read a threat feed with pagination

{ "resource": "threat-feeds", "operation": "getC2Feed", "parameters": {} }

with input { "limit": 50, "dateFrom": "2026-07-01T00:00:00Z" }; feed limit/page are body filters (not query params). Follow nextCursor to page.

Integration in Workflow Context

Common Workflow Patterns

Infostealer exposure monitoring — Schedule → searchByDomain (your whitelisted domain) → prep node (shape findings, keep mask_passwords on) → alert/report Output.
EASM-driven enrichment — EASM assets → foreach loop → searchByIp / searchByDomain per host → aggregate → Output.
Investigation drill-down — searchByDomain → extract a stealer id → getInfectionAnalysis + categorizeStealerDomains (respect the 5 req/10 s limit).
Threat-feed ingestion — Schedule → getC2Feed / getPhaasFeed / getClickfixFeed with cursor loop → store/correlate.

Response Structure

Credential searches return a SearchResponse:

{
  "data": [
    {
      "stealer": "…", "stealer_family": "…", "ip": "…", "operating_system": "…",
      "date_compromised": "…", "date_uploaded": "…", "malware_path": "…",
      "employeeAt": ["…"], "clientAt": [],
      "credentials": [
        { "url": "https://…", "domain": "…", "username": "…", "password": "ab****", "type": "employee" }
      ]
    }
  ],
  "nextCursor": "…"
}

password (and employee_session_cookies, when requested via additional_fields) are redacted when mask_passwords is enabled. Overview, discovery, assessment, keyword and feed operations return their own shapes; consult the operation description in the node for details.

Troubleshooting

Issue	Resolution
HTTP 401 (invalid key)	The API key is wrong or expired. Re-check the credential.
HTTP 403 "Insufficient permissions"	The key lacks the permission scope for that endpoint. Contact `[email protected]` to enable it.
HTTP 403 "…not in your whitelist"	You queried a domain your account doesn't own. Query a whitelisted domain, or ask support to add it.
HTTP 404	Resource not found — e.g. an unknown `stealer` id (`getInfectionAnalysis`) or a domain with no ClickFix record (`getClickfixDomain`).
HTTP 408 (timeout)	The query exceeded the 90 s server limit. Narrow it (fewer domains, tighter date range, fewer `additional_fields`).
HTTP 429 (rate limited)	Slow down: 50 req/10 s general, 5 req/10 s for `getInfectionAnalysis`. Add delays in loops.
HTTP 400 (validation error)	A required field is missing or a value is invalid — e.g. providing both `ips` and `cidr`, or `subdomains` together with `keywords` (mutually exclusive).
Very large responses	`filter_credentials: false` and extra `additional_fields` inflate payloads. Keep filtering on and request only the fields you need.

Best Practices

Query only whitelisted domains. Domain-intelligence searches are scoped to the domains your account owns; confirm your whitelist with getMyAccount.
Enable the scopes you need. Endpoint access is per-scope; request the scopes for the operations you plan to use from Hudson Rock support.
Mask by default when reporting. Turn on mask_passwords when the raw secret isn't needed, and treat all outputs as sensitive PII (compromised credentials).
Respect the rate limits. Especially the 5 req/10 s cap on getInfectionAnalysis; space out loop iterations.
Page with the cursor. Follow nextCursor (or pageInfo.nextCursor for feeds, page/limit for FortiBleed) until exhausted; don't assume one page is complete.
Request additional_fields sparingly. Each block adds size and latency — include only what a downstream node consumes.
Treat company-management as owner-only. When synced_data is on, writes require the owner role.

Updated: 2026-07-28

Overview​

Status​

Credential Configuration​

Authentication Method​

Creating a Hudson Rock Credential​

Supported Resources and Operations​

Domain Intelligence​

End User Protection​

Investigations​

Advanced Search / Keyword Search / Password Search​

Threat Feeds​

Company Management (write operations)​

Account Management​

Key Concepts​

Parameter Merging​

Parameter Sources (in order of precedence)​

Path vs. body vs. query​

Examples​

Search by domain​

Search by IP or CIDR​

Read a threat feed with pagination​

Integration in Workflow Context​

Common Workflow Patterns​

Response Structure​

Troubleshooting​

Best Practices​