/v2/hunt-pivots returns ranked investigative actions for threat-hunting agents. Use it when an agent needs to decide what to investigate next, why it matters, and what telemetry fields to collect.
Use /v2/relationships instead when you only need related actors, campaigns, malware, sectors, indicators, or techniques for a resolved subject.
Response Envelope
/v2/hunt-pivots returns:
| Field | Meaning |
|---|---|
mode | Request mode: subject_led or observation_led. |
resolution_status | Whether Kyberis resolved the subject or proceeded from an unresolved observation. |
subject | Resolved or submitted subject context when available. |
likely_attack_chains | ATT&CK-aligned hypotheses that may explain the subject or observation. |
recommended_pivots | Ranked hunt actions for the customer agent to execute. |
next_decision | Recommendation for whether to continue, collect more context, escalate, suppress, or stop. |
caveats | Top-level limitations and assumptions for the response. |
metadata | Request and generation metadata, including degradation or implementation details. |
Modes
| Mode | Use when |
|---|---|
subject_led | You have a resolved Kyberis subject such as an actor, CVE, malware family, campaign, technique, or IOC. |
observation_led | You have weak telemetry, unresolved observables, or an anomaly that does not resolve to a canonical Kyberis subject. |
Recommended Pivots
Each item inrecommended_pivots is an action for the customer agent to execute against local SIEM, EDR, cloud, identity, or asset telemetry.
| Field | Meaning |
|---|---|
pivot_type | Hunt category such as network_pivot, process_pivot, technique_hunt, ioc_expansion, or asset_exposure_check. |
priority | Relative urgency for this pivot. |
question | Investigation question the pivot should answer. |
query_intent | Vendor-neutral search intent for the customer telemetry system. |
why | Rationale for the pivot. |
confidence | Confidence in the pivot recommendation, not proof of compromise. |
required_fields | Telemetry fields the customer agent should collect. |
related_entities | Optional Kyberis relationship context used to support the recommendation. |
evidence_refs | Optional evidence references that support the recommendation. |
caveats | Limits or assumptions for the specific pivot. |
Attack Chains
likely_attack_chains contains ATT&CK-aligned hypotheses. Treat these as hypotheses until customer-local telemetry confirms them.
Next Decision
next_decision summarizes whether the agent should continue hunting, collect more context, escalate, or suppress. Preserve the recommendation and reason in agent output so analysts can see why the workflow continued.