feat(rapid7-insightidr): add the Alert Triage API commands (v1.1.0)
An ingested investigation carried almost nothing: title, priority, status,
assignee and timestamps. Not a host, not an account, not a command line — so
no entity was ever indexed, and neither the pivot graph nor the AI analysis
had anything to read. Fetching the investigation's alerts did not help: that
endpoint answers with the rule name (already the investigation's title), the
alert source and an alert RRN, and nothing else.
The detection content lives in a different API. The Alert Triage API is served
under /idr/at — its own base, next to /idr/v1 and /idr/v2 — and it is where
the evidence, the actors, the MITRE T-codes and the process trees actually
are. It was missing from this package entirely.
Six read commands:
search_alerts POST /alerts/ops/search
get_alert GET /alerts/{rrn}
get_alert_evidence GET /alerts/{rrn}/evidences
get_alert_actors GET /alerts/{rrn}/actors
get_alert_process_trees POST /alerts/{rrn}/process_trees/latest
list_alert_fields GET /alerts/2/fields
search_alerts is the one that changes the shape of the feed. It returns full
alert objects — rule with its mitre_tcodes, rule_keys_of_interest, the
AI-suggested disposition, the parent investigation RRN, the status transition
timings and the log entries behind the alert — and its start_time is required
by the API, which makes it a natural incremental watermark. So the alerts can
be read directly, paginated, with no per-investigation fan-out.
Two things worth knowing before using them:
- field_ids is not optional in practice. The API returns no additional
fields when it is empty, and those additional fields are where the
hostnames, accounts and command lines are. Their ids are per-tenant dotted
paths (process.cmd_line, …), which is what list_alert_fields is for.
/alerts/fields is deprecated, hence /alerts/2/fields.
- the whole API is gated on Managed Detection and Response with access to
the Alerts experience. A key that works on every investigation endpoint
can still be refused here, so 401 and 403 are reported with that named
explanation rather than as a bare status code — a licence boundary should
not read as a bug.
Written against the published OpenAPI spec (SIEM Alerts API 39.10.0); not yet
exercised against a live tenant.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
id: rapid7_insightidr
|
||||
name: Rapid7 InsightIDR
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
description: "Rapid7 InsightIDR (REST API) — investigation ingestion and full lifecycle (list/get/search/create/update/assign/set-status/bulk-close), investigation alerts and Rapid7 product alerts, custom threat indicators (add/replace), log management and LEQL log/log-set queries with downloads, and user directory search."
|
||||
changelog: "1.0.0 — Initial release: investigation ingestion (list_investigations) with an exhaustive OCSF mapper, 18 commands across investigations, alerts, custom threats, logs/LEQL search and users. API v1/v2 selectable per instance and per command."
|
||||
changelog: "1.1.0 — Add the Alert Triage API (/idr/at): search alerts, get an alert, its evidence, its actors and its process trees, plus the tenant's alert field catalogue. These carry the detection content the investigation endpoints do not — MITRE T-codes, matched rule keys, assets and accounts, command lines. MDR-gated. | 1.0.0 — Initial release: investigation ingestion (list_investigations) with an exhaustive OCSF mapper, 18 commands across investigations, alerts, custom threats, logs/LEQL search and users. API v1/v2 selectable per instance and per command."
|
||||
category: siem
|
||||
|
||||
# Per-instance configuration. The Insight platform region selects the API host
|
||||
@@ -315,6 +315,104 @@ commands:
|
||||
required: []
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
|
||||
# ── Alert Triage API (/idr/at) ──────────────────────────────────────────────
|
||||
# A separate API from the investigation endpoints, and the only place the
|
||||
# actual detection content lives: an investigation and its /alerts list carry
|
||||
# metadata (title, priority, rule name) and no evidence at all. Access is
|
||||
# restricted to Managed Detection and Response customers with the Alerts
|
||||
# experience — a key that works everywhere else can still be refused here,
|
||||
# which the commands report as a named 401/403 rather than an empty result.
|
||||
- id: search_alerts
|
||||
name: rapid7-insight-idr-search-alerts
|
||||
description: "Search alerts over a time window (Alert Triage API). Returns full alert details — detection rule with its MITRE T-codes, priority, status, disposition, Rapid7's AI-suggested disposition, the parent investigation RRN and the log entries behind it. Results path = alerts; use field_ids to pull the per-tenant fields (hostnames, accounts, command lines) that are otherwise absent."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
start_time: { type: string, description: "ISO-8601 start of the search window (required by the API; defaults to default_days ago). Incremental fetch watermark." }
|
||||
end_time: { type: string, description: "ISO-8601 end of the search window" }
|
||||
default_days: { type: string, description: "Window size in days used when start_time is absent (default 1)" }
|
||||
leql: { type: string, description: "LEQL WHERE clause to match against" }
|
||||
field_ids: { type: string, description: "Comma-separated additional field ids to include on each alert (see rapid7-insight-idr-list-alert-fields). Empty means no additional fields are returned." }
|
||||
search_field: { type: string, description: "Comma-separated field ids for a single search term" }
|
||||
search_values: { type: string, description: "Comma-separated values the search_field must match (OR'ed together)" }
|
||||
search_operator: { type: string, description: "EQUALS, NOT_EQUALS, CONTAINS, GREATER_THAN or LESS_THAN (default EQUALS)" }
|
||||
terms_json: { type: string, description: "Raw JSON array of search terms, for criteria the simple triple cannot express. Takes precedence over search_field/search_values." }
|
||||
sort_field: { type: string, description: "Field id to sort on" }
|
||||
sort_direction: { type: string, description: "ASC or DESC (default ASC)" }
|
||||
rrns_only: { type: string, description: "Return only alert RRNs instead of full details (true/false)" }
|
||||
index: { type: string, description: "0-based page index to start from" }
|
||||
page_size: { type: string, description: "Page size" }
|
||||
limit: { type: number, description: "Maximum number of alerts to retrieve (default 50)" }
|
||||
required: []
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
- id: get_alert
|
||||
name: rapid7-insight-idr-get-alert
|
||||
description: "Retrieve a single alert by its RRN (Alert Triage API), optionally with additional fields."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
alert_rrn: { type: string, description: "Alert RRN (rrn:alerts:<region>:<org>:alert:...)" }
|
||||
field_ids: { type: string, description: "Comma-separated additional field ids to include" }
|
||||
required: [alert_rrn]
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
- id: get_alert_evidence
|
||||
name: rapid7-insight-idr-get-alert-evidence
|
||||
description: "Retrieve the evidence behind a single alert (Alert Triage API): the events that triggered it, the keys and values the rule matched on, and the log entries they came from."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
alert_rrn: { type: string, description: "Alert RRN" }
|
||||
index: { type: string, description: "0-based page index" }
|
||||
page_size: { type: string, description: "Page size" }
|
||||
limit: { type: number, description: "Maximum number of evidence items (default 50)" }
|
||||
required: [alert_rrn]
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
- id: get_alert_actors
|
||||
name: rapid7-insight-idr-get-alert-actors
|
||||
description: "Retrieve an alert's actors (Alert Triage API): the assets, accounts and IP addresses involved, each with its display name. This is where an alert's observables come from — nothing in the investigation endpoints carries them."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
alert_rrn: { type: string, description: "Alert RRN" }
|
||||
index: { type: string, description: "0-based page index" }
|
||||
page_size: { type: string, description: "Page size" }
|
||||
limit: { type: number, description: "Maximum number of actors (default 50)" }
|
||||
required: [alert_rrn]
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
- id: get_alert_process_trees
|
||||
name: rapid7-insight-idr-get-alert-process-trees
|
||||
description: "Retrieve all process trees for an alert (Alert Triage API): process name, PID, command line, executing user and file hashes, with child processes nested."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
alert_rrn: { type: string, description: "Alert RRN" }
|
||||
force_refresh: { type: string, description: "Regenerate the tree instead of returning the cached one (true/false). Documented as expensive and slow — leave off unless the cached tree is stale." }
|
||||
branch: { type: string, description: "Branch number to generate the process tree with" }
|
||||
index: { type: string, description: "0-based page index" }
|
||||
page_size: { type: string, description: "Page size" }
|
||||
limit: { type: number, description: "Maximum number of trees (default 10)" }
|
||||
required: [alert_rrn]
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
- id: list_alert_fields
|
||||
name: rapid7-insight-idr-list-alert-fields
|
||||
description: "List the alert fields supported by the tenant (Alert Triage API v2). Field ids are dotted paths (process.cmd_line, …) and are what search_alerts and get_alert accept in field_ids — run this first to learn which ones this tenant exposes."
|
||||
risk: read
|
||||
inputs_schema:
|
||||
properties:
|
||||
path: { type: string, description: "Limit results to fields at or below this node of the dotted hierarchy" }
|
||||
path_depth: { type: string, description: "Depth to round results to, after path is applied" }
|
||||
index: { type: string, description: "0-based page index" }
|
||||
page_size: { type: string, description: "Page size (default 200)" }
|
||||
limit: { type: number, description: "Maximum number of fields to retrieve" }
|
||||
required: []
|
||||
outputs_schema: { properties: {} }
|
||||
|
||||
# ── Connectivity test ─────────────────────────────────────────────────────
|
||||
- id: test_connection
|
||||
name: rapid7-insight-idr-test-connection
|
||||
|
||||
Reference in New Issue
Block a user