Files
riposte-marketplace/integrations/rapid7-insightidr/manifest.yaml
T
f3nris b6903d4590 feat(rapid7-insightidr): map alerts to OCSF, with real observables (v1.2.0)
An incident built from a Rapid7 investigation indexed zero entities. Nothing to
pivot on, nothing to correlate, and an AI analysis with nothing to read. The
reason turned out not to be the mapper but the feed: an investigation is an
envelope, and neither it nor its /alerts list carries a host, an account, a
process or a MITRE code.

The Alert Triage API does, in rule_keys_of_interest. On the alert behind the
investigation that started this, that field holds:

  hostname                            NBSGIT01-26
  process.name                        bcdedit.exe
  process.cmd_line                    bcdedit  /set {default} recoveryenabled No
  process.exe_path                    C:\WINDOWS\System32\bcdedit.exe
  parent_process.name                 cmd.exe
  parent_process.cmd_line             "C:\WINDOWS\system32\cmd.exe"
  parent_process.exe_file.hashes.md5  e463e36104d22a2479046a7d4f620816

with rule.mitre_tcodes ["TA0040", "T1490"] — Impact / Inhibit System Recovery,
which is what disabling Windows recovery actually is. None of it was reachable
before.

It is a list of {key, values} pairs rather than an object, so every entry reads
through a JSONata predicate — rule_keys_of_interest[key='hostname'].values[0].
A key a rule does not emit resolves to nothing and is skipped, so one file
covers every detection rule.

Two details worth keeping:

  - mitre_tcodes mixes tactics and techniques in one array ("TA0040" beside
    "T1490"). They are split on the "TA" prefix so a tactic never lands in the
    technique field, where it would name a technique that does not exist.

  - rule.name is documented but absent from live ABA alerts, so the analytic
    name falls back to `type`, which repeats the rule's display name.

Rapid7's own status, disposition and AI-suggested disposition ride as custom
fields. They cannot reach the incident's status and verdict columns — MapFields
accepts only title, severity, source, description and custom:* — but an analyst
can at least see that the source already closed the alert and what it decided.
The AI suggestion is exposed as a fact, never as a verdict.

Validated end to end against a live alert: field mapping, OCSF mapping and
entity extraction, which now yields the host and the parent process hash where
it previously yielded nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-07 23:07:53 +02:00

431 lines
27 KiB
YAML

id: rapid7_insightidr
name: Rapid7 InsightIDR
version: 1.2.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.2.0 — Add the search_alerts OCSF mapper: rule_keys_of_interest carries the host, the process, its command line, its parent and the file hashes, so an alert-based feed indexes entities where the investigation feed indexed none. Validated against a live ABA alert. | 1.1.1 — list_alert_fields: default path_depth to 1 and expose the search filter. The V2 fields endpoint refuses an unbounded walk of the tree (\"root path with path depth greater than 1 is not supported for V2 without a search filter\"), so the bare call returned HTTP 400. | 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
# (https://<region>.api.insight.rapid7.com). Authentication is an Organization
# API key sent in the X-Api-Key header.
config_schema:
properties:
region:
type: string
description: "Insight platform region: us, eu, ca, au or ap"
default: us
api_key:
type: string
description: "InsightIDR Organization API key (Read/Write)"
x-soar-sensitive: true
is_v2:
type: string
description: "Use API v2 by default for investigation commands (true/false). Can be overridden per command with api_version. Defaults to true (v2)."
default: "true"
is_multi_customer:
type: string
description: "Set to true if the API key has multi-customer access (adds the multi-customer query parameter on v2 calls)."
default: "false"
required:
- region
- api_key
auth:
- id: apikey
type: api_key
in: header
name: X-Api-Key
value_template: "{{secret}}"
secret_field: api_key
commands:
# ── Ingestion ───────────────────────────────────────────────────────────────
- id: list_investigations
name: rapid7-insight-idr-list-investigations
description: "List investigations, sorted by created_time descending. Used for ingestion: results path = data. Investigations aggregate the applicable alert data and are tied to alerts and detection rules."
risk: read
inputs_schema:
properties:
api_version: { type: string, description: "API version to use: V1, V2 or Default (uses the instance default)" }
statuses: { type: string, description: "Comma-separated statuses to include (open, investigating, closed)" }
start_time: { type: string, description: "Only investigations created after this ISO-8601 timestamp (e.g. 2018-07-01T00:00:00Z). Incremental fetch watermark; V2 only." }
end_time: { type: string, description: "Only investigations created before this ISO-8601 timestamp. V2 only." }
time_range: { type: string, description: "Relative time range string (e.g. 1 week, 1 day) instead of start_time/end_time" }
sources: { type: string, description: "Comma-separated sources to include (User, Alert). V2 only." }
priorities: { type: string, description: "Comma-separated priorities to include (Unspecified, Low, Medium, High, Critical). V2 only." }
assignee_email: { type: string, description: "Only investigations assigned to this user email" }
tags: { type: string, description: "Comma-separated tags; only investigations having all of them are returned. V2 only." }
sort_field: { type: string, description: "Field to sort by (Created time, Priority, RRN Last Created Alert, Last Detection Alert). V2 only." }
sort_direction: { type: string, description: "Sort direction (ASC, DESC). V2 only." }
index: { type: string, description: "0-based page index" }
page_size: { type: string, description: "Page size (1-1000)" }
limit: { type: number, description: "Maximum number of records to retrieve (default 50)" }
required: []
outputs_schema: { properties: {} }
ingest:
results_path: data
dedup_key: rrn
incremental_field: start_time
- id: get_investigation
name: rapid7-insight-idr-get-investigation
description: "Get a single investigation by ID or Rapid7 Resource Name (RRN). With api_version=V2 the ID must be in RRN format."
risk: read
inputs_schema:
properties:
api_version: { type: string, description: "API version to use: V1, V2 or Default" }
investigation_id: { type: string, description: "Investigation ID or RRN" }
required: [investigation_id]
outputs_schema: { properties: {} }
- id: search_investigation
name: rapid7-insight-idr-search-investigation
description: "Search investigations matching the given search/sort criteria (v2)."
risk: read
inputs_schema:
properties:
start_time: { type: string, description: "ISO-8601 lower bound on created_time (default 28 days ago)" }
end_time: { type: string, description: "ISO-8601 upper bound on created_time (default now)" }
actor_asset_hostname: { type: string, description: "Comma-separated values; CONTAINS match on actor_asset_hostname" }
actor_user_name: { type: string, description: "Comma-separated values; CONTAINS match on actor_user_name" }
alert_mitre_t_codes: { type: string, description: "Comma-separated values; EQUALS match on alert_mitre_t_codes" }
alert_rule_rrn: { type: string, description: "Comma-separated values; EQUALS match on alert_rule_rrn" }
assignee_id: { type: string, description: "Comma-separated values; EQUALS match on assignee_id" }
organization_id: { type: string, description: "Comma-separated values; EQUALS match on organization_id" }
priority: { type: string, description: "Comma-separated values; EQUALS match on priority (UNSPECIFIED, LOW, MEDIUM, HIGH, CRITICAL)" }
rrn: { type: string, description: "Comma-separated values; EQUALS match on rrn" }
source: { type: string, description: "Comma-separated values; EQUALS match on source (USER, ALERT)" }
status: { type: string, description: "Comma-separated values; EQUALS match on status (OPEN, CLOSED, INVESTIGATING, WAITING)" }
title: { type: string, description: "Comma-separated values; CONTAINS match on title" }
sort: { type: string, description: "Comma-separated fields to sort by (Created time, Priority, RRN, Alert created time, Alert detection created time)" }
sort_direction: { type: string, description: "Sort direction (asc, desc)" }
index: { type: string, description: "0-based page index" }
page_size: { type: string, description: "Page size (1-1000)" }
limit: { type: number, description: "Maximum number of records to retrieve (default 50)" }
required: []
outputs_schema: { properties: {} }
- id: create_investigation
name: rapid7-insight-idr-create-investigation
description: "Create a new investigation manually (v2)."
risk: safe_write
inputs_schema:
properties:
title: { type: string, description: "Name of the investigation" }
status: { type: string, description: "Open, Investigating or Closed (default Open)" }
priority: { type: string, description: "Unspecified, Low, Medium, High or Critical (default Unspecified)" }
disposition: { type: string, description: "Undecided, Benign, Malicious or Not Applicable (default Undecided)" }
user_email_address: { type: string, description: "Email of the user to assign the investigation to" }
required: [title]
outputs_schema: { properties: {} }
- id: update_investigation
name: rapid7-insight-idr-update-investigation
description: "Update fields of an investigation by ID or RRN (v2)."
risk: safe_write
inputs_schema:
properties:
investigation_id: { type: string, description: "Investigation ID or RRN to update" }
title: { type: string, description: "Name of the investigation" }
status: { type: string, description: "Open, Investigating or Closed" }
priority: { type: string, description: "Unspecified, Low, Medium, High or Critical" }
disposition: { type: string, description: "Undecided, Benign, Malicious or Not Applicable" }
user_email_address: { type: string, description: "Email of the user to assign the investigation to" }
threat_command_free_text: { type: string, description: "Additional text when closing an associated Threat Command alert (status=Closed)" }
threat_command_close_reason: { type: string, description: "Threat Command close reason (status=Closed)" }
required: [investigation_id]
outputs_schema: { properties: {} }
- id: assign_user
name: rapid7-insight-idr-assign-user
description: "Assign a user (by email) to one or more investigations. With api_version=V2 the IDs must be in RRN format."
risk: safe_write
inputs_schema:
properties:
api_version: { type: string, description: "API version to use: V1, V2 or Default" }
investigation_id: { type: string, description: "Comma-separated investigation IDs or RRNs" }
user_email_address: { type: string, description: "Email of the user to assign" }
required: [investigation_id, user_email_address]
outputs_schema: { properties: {} }
- id: set_status
name: rapid7-insight-idr-set-status
description: "Set the status of one or more investigations. Closing requires a disposition (v2). With api_version=V2 the IDs must be in RRN format."
risk: safe_write
inputs_schema:
properties:
api_version: { type: string, description: "API version to use: V1, V2 or Default" }
investigation_id: { type: string, description: "Comma-separated investigation IDs or RRNs" }
status: { type: string, description: "open, closed, investigating or waiting" }
disposition: { type: string, description: "benign, malicious or not_applicable (status=closed, V2 only)" }
threat_command_close_reason: { type: string, description: "Threat Command close reason (status=closed, V2 only)" }
threat_command_free_text: { type: string, description: "Additional text for a Threat Command alert (status=closed, V2 only)" }
required: [investigation_id, status]
outputs_schema: { properties: {} }
- id: close_investigations
name: rapid7-insight-idr-close-investigations
description: "Bulk-close all investigations matching the request parameters within a time window (v2)."
risk: safe_write
inputs_schema:
properties:
source: { type: string, description: "Investigation source to close: ALERT, MANUAL or HUNT. ALERT requires alert_type or detection_rule_rrn." }
start_time: { type: string, description: "ISO-8601 lower bound on createTime (e.g. 2018-07-01T00:00:00Z)" }
end_time: { type: string, description: "ISO-8601 upper bound on createTime (e.g. 2018-07-28T23:59:00Z)" }
alert_type: { type: string, description: "Alert category to close. Required when source=ALERT." }
disposition: { type: string, description: "Disposition to set: Undecided, Benign, Malicious or Not Applicable (default Not Applicable)" }
detection_rule_rrn: { type: string, description: "Detection rule RRN; only investigations linked to it are closed. Requires alert_type 'Attacker Behavior Detected'." }
max_investigations_to_close: { type: string, description: "Maximum number of investigations to close (no maximum if omitted)" }
required: [source, start_time, end_time]
outputs_schema: { properties: {} }
- id: list_investigation_alerts
name: rapid7-insight-idr-list-investigation-alerts
description: "List all alerts associated with an investigation, sorted by alert created time descending (v2)."
risk: read
inputs_schema:
properties:
investigation_id: { type: string, description: "Investigation ID or RRN (V2 RRN format)" }
all_results: { type: string, description: "Return all results, overriding the limit (true/false, default false)" }
limit: { type: number, description: "Maximum number of records to retrieve (default 50)" }
required: [investigation_id]
outputs_schema: { properties: {} }
- id: list_investigation_product_alerts
name: rapid7-insight-idr-list-investigation-product-alerts
description: "List all Rapid7 product alerts (from other Rapid7 products) associated with an investigation (v2)."
risk: read
inputs_schema:
properties:
investigation_id: { type: string, description: "Investigation ID or RRN (V2 RRN format)" }
all_results: { type: string, description: "Return all results, overriding the limit (true/false, default false)" }
limit: { type: number, description: "Maximum number of records to retrieve (default 50)" }
required: [investigation_id]
outputs_schema: { properties: {} }
- id: add_threat_indicators
name: rapid7-insight-idr-add-threat-indicators
description: "Add indicators (IPs, hashes, domains, URLs) to one or more custom threats by key."
risk: safe_write
inputs_schema:
properties:
key: { type: string, description: "Comma-separated threat keys to add indicators to" }
ip_addresses: { type: string, description: "Comma-separated IP address indicators" }
hashes: { type: string, description: "Comma-separated hash indicators" }
domain_names: { type: string, description: "Comma-separated domain indicators" }
url: { type: string, description: "Comma-separated URL indicators" }
required: [key]
outputs_schema: { properties: {} }
- id: replace_threat_indicators
name: rapid7-insight-idr-replace-threat-indicators
description: "Replace all indicators of one or more custom threats: deletes existing indicators and adds the supplied ones."
risk: safe_write
inputs_schema:
properties:
key: { type: string, description: "Comma-separated threat keys to replace indicators for" }
ip_addresses: { type: string, description: "Comma-separated IP address indicators" }
hashes: { type: string, description: "Comma-separated hash indicators" }
domain_names: { type: string, description: "Comma-separated domain indicators" }
url: { type: string, description: "Comma-separated URL indicators" }
required: [key]
outputs_schema: { properties: {} }
- id: list_logs
name: rapid7-insight-idr-list-logs
description: "List all logs available to the account."
risk: read
inputs_schema:
properties: {}
required: []
outputs_schema: { properties: {} }
- id: list_log_sets
name: rapid7-insight-idr-list-log-sets
description: "List all log sets configured for the InsightIDR instance."
risk: read
inputs_schema:
properties: {}
required: []
outputs_schema: { properties: {} }
- id: query_log
name: rapid7-insight-idr-query-log
description: "Run a LEQL query against a single log, following pagination links to gather all events."
risk: read
inputs_schema:
properties:
log_id: { type: string, description: "Log key to query" }
query: { type: string, description: "Valid LEQL query (no calculations)" }
time_range: { type: string, description: "Relative time range (e.g. 1 week, 1 day). When set, start_time/end_time are not needed." }
start_time: { type: string, description: "Lower bound as a UNIX timestamp in milliseconds" }
end_time: { type: string, description: "Upper bound as a UNIX timestamp in milliseconds" }
logs_per_page: { type: string, description: "Maximum log entries per page (default 50)" }
sequence_number: { type: string, description: "Earliest sequence number of a log entry to start from" }
required: [log_id, query]
outputs_schema: { properties: {} }
- id: query_log_set
name: rapid7-insight-idr-query-log-set
description: "Run a LEQL query against a log set, following pagination links to gather all events."
risk: read
inputs_schema:
properties:
log_set_id: { type: string, description: "Log set ID to query" }
query: { type: string, description: "Valid LEQL query (no calculations)" }
time_range: { type: string, description: "Relative time range (e.g. 1 week, 1 day). When set, start_time/end_time are not needed." }
start_time: { type: string, description: "Lower bound as a UNIX timestamp in milliseconds" }
end_time: { type: string, description: "Upper bound as a UNIX timestamp in milliseconds" }
logs_per_page: { type: string, description: "Maximum log entries per page (default 50)" }
sequence_number: { type: string, description: "Earliest sequence number of a log entry to start from" }
required: [log_set_id, query]
outputs_schema: { properties: {} }
- id: download_logs
name: rapid7-insight-idr-download-logs
description: "Download raw log events for up to 10 logs over a time window, optionally filtered by a LEQL query. Returns the events as text."
risk: read
inputs_schema:
properties:
log_ids: { type: string, description: "Comma-separated log IDs to download (up to 10)" }
time_range: { type: string, description: "Relative time range (e.g. Last 4 Days). Defaults to Last 3 days when no bounds are given." }
start_time: { type: string, description: "Lower bound as a UNIX timestamp in milliseconds" }
end_time: { type: string, description: "Upper bound as a UNIX timestamp in milliseconds" }
query: { type: string, description: "LEQL query to match desired events (no calculations)" }
limit: { type: string, description: "Maximum number of events to download (cannot exceed 20 million)" }
required: [log_ids]
outputs_schema: { properties: {} }
- id: list_users
name: rapid7-insight-idr-list-users
description: "List users matching the search/sort criteria, or retrieve a single user by RRN."
risk: read
inputs_schema:
properties:
rrn: { type: string, description: "RRN of a single user to retrieve. When set, the other filters are ignored." }
first_name: { type: string, description: "Comma-separated values to match on first_name (requires search_operator)" }
last_name: { type: string, description: "Comma-separated values to match on last_name (requires search_operator)" }
name: { type: string, description: "Comma-separated values to match on name (requires search_operator)" }
search_operator: { type: string, description: "Filter operator when first_name/last_name/name are used: contains or equals" }
sort: { type: string, description: "Comma-separated fields to sort by (first_name, last_name, name)" }
sort_direction: { type: string, description: "Sort direction (asc, desc)" }
index: { type: string, description: "0-based page index" }
page_size: { type: string, description: "Page size (1-1000)" }
limit: { type: number, description: "Maximum number of records to retrieve (default 50)" }
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. With no path, search or path_depth the command lists the top-level nodes: the API refuses an unbounded walk of the whole tree."
risk: read
inputs_schema:
properties:
path: { type: string, description: "Limit results to descendants of this node of the dotted hierarchy (e.g. process)" }
path_depth: { type: string, description: "Depth to round results to, after path is applied (e.g. path=process with depth 1 returns process.cmd_line). Defaults to 1 when neither path nor search is given, which the API requires." }
search: { type: string, description: "Case-insensitive substring the field must contain. Also lifts the depth restriction, so it is the way to search the whole tree at once (e.g. hostname)." }
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
description: "Verify connectivity and credentials (used by the Test button)."
risk: read
inputs_schema:
properties: {}
required: []
outputs_schema: { properties: {} }
ingestion:
command: list_investigations
mapper: list_investigations
default_incident_type: "Rapid7 InsightIDR Investigation"