521 lines
40 KiB
YAML
521 lines
40 KiB
YAML
id: rapid7_insightidr
|
||
name: Rapid7 InsightIDR
|
||
version: 1.13.1
|
||
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, investigation comments (add/list), custom threat indicators (add/replace), log management and LEQL log/log-set queries with downloads, and user directory search."
|
||
changelog: "1.13.1 — test_connection: accept an InsightIDR Essential key. Essential answers the Investigations API with a 403 that names the package, so a valid key failed its test; the test now falls back to Log Search and says which commands that package leaves out — the LEQL feeds (query_log, query_log_set) are its way to ingest detections. | 1.13.0 — Add add_comment and list_comments: the investigation comment thread is where an analyst’s reasoning lives, and a playbook had no way to write into it or read it back. The Comments API is v1-only and addresses its target by RRN — the short investigation ID the other v1 endpoints accept is rejected with a 400 that names nothing, so both commands refuse it up front. | 1.12.0 — Make the LEQL queries ingestible: query_log and query_log_set gain an ingest block, a stable event_id for dedup, a bounded page walk and a detection_name stamp, and they now read start_time as ISO-8601, UNIX seconds or milliseconds alike. A tenant whose basic detection rules only notify (email, Slack) creates no investigation and no alert an API can read, so replaying the rule's own query on a schedule is the only way its detections reach a SOAR. | 1.11.1 — Strip the whitespace out of the comma-separated filter params (statuses, priorities, sources, tags) before the URL. \"HIGH, CRITICAL\" as typed sent \" CRITICAL\" to the API, which rejects the whole call — so a priority filter written naturally fetched nothing. | 1.11.0 —Build one evidence row per alert evidence into custom:rapid7_evidence, for the table field: sortable and filterable where the Markdown summary only reads. | 1.10.0 — Render every detection key as Markdown into custom:rapid7_summary, so a layout can show what the OCSF catalogue has no field for. Map both ends of an account action, read source_json top-level scalars, drop placeholder values, and force evidences to stay an array. | 1.9.2 — Read the evidence data in both of its shapes. A parsed source states its event flat, with no source_data/custom_data wrapper, and the parser returned {} for all of them. | 1.9.1 — get_alert_process_trees: explain the 404, which the API returns with an empty body for three different situations. | 1.9.0 — Fetch each alert process tree and flatten it into ctx.process_tree, the shape the layout Process Tree block reads. Gated on the event type by default, since an authentication alert never has one. | 1.8.0 — Fetch each alert evidence at ingestion and parse it: the log line behind the alert lives in a JSON-encoded string no mapper can reach, and it is where the source and destination addresses, the account and the device actually are. | 1.7.0 — Map source/destination assets and accounts to src_endpoint, dst_endpoint, actor.user and user. A connection rule names both ends and neither is \"the host\", so an RDP-to-DC alert produced no entity at all and nothing a layout could show. | 1.6.0 — Surface region_failures: the Alert Triage API answers HTTP 200 with a partial result when it cannot reach a region, and that list was being dropped. Also report the regions seen in the RRNs against the configured one. | 1.5.0 — Flatten the whole of rule_keys_of_interest into the context. It is an open vocabulary — a process rule and an authentication rule share no keys — so the hardcoded list only covered rules already seen and left every other alert empty. | 1.4.1 — Read the alert RRN from `rrn` before `id` and drop anything not RRN-shaped: the investigation alert list also returns bare UUIDs, and one of those rejects the entire /alerts/ops/rrns batch (HTTP 400), losing every alert in the run. | 1.4.0 — Add get_investigations_full: the investigation with its alerts inlined, so it stays the unit that becomes an incident. Drop-in for list_investigations (results_path data, dedup rrn). | 1.3.0 — Add search_investigation_alerts: ingest only the alerts that belong to an investigation, with their full detection content, in 1+N+1 calls. Filtering search_alerts on investigation_rrn does not work — the term is accepted and silently matches nothing. | 1.2.1 — search_alerts: report a malformed terms_json with the input named and echoed, instead of json's bare \"Expecting value: line 1 column 1\". | 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_comment
|
||
name: rapid7-insight-idr-add-comment
|
||
description: "Post a comment on an investigation (v1). The target is addressed by RRN only — the short investigation ID is rejected."
|
||
risk: safe_write
|
||
inputs_schema:
|
||
properties:
|
||
investigation_id: { type: string, description: "Investigation RRN to comment on (rrn:investigation:<region>:<org>:investigation:<id>)" }
|
||
comment: { type: string, description: "Body of the comment" }
|
||
attachments: { type: string, description: "Comma-separated attachment RRNs to associate with the comment" }
|
||
required: [investigation_id, comment]
|
||
outputs_schema: { properties: {} }
|
||
|
||
- id: list_comments
|
||
name: rapid7-insight-idr-list-comments
|
||
description: "List the comments on an investigation, newest first by default (v1). The target is addressed by RRN only."
|
||
risk: read
|
||
inputs_schema:
|
||
properties:
|
||
investigation_id: { type: string, description: "Investigation RRN to read comments from (rrn:investigation:<region>:<org>:investigation:<id>)" }
|
||
sort_direction: { type: string, description: "Sort by creation time: ASC or DESC (default DESC)" }
|
||
index: { type: string, description: "0-based page index to start from" }
|
||
page_size: { type: string, description: "Page size (1-100, default 100)" }
|
||
all_results: { type: string, description: "Walk every page, overriding the limit (true/false, default false)" }
|
||
limit: { type: number, description: "Maximum number of comments 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. Usable as an ingestion feed: point it at the LEQL of a basic detection rule and every matching line becomes an alert (results path = events, one incident per log entry)."
|
||
risk: read
|
||
inputs_schema:
|
||
properties:
|
||
log_id: { type: string, description: "Log key to query" }
|
||
query: { type: string, description: "Valid LEQL query (no calculations: groupby/calculate are rejected by this endpoint)" }
|
||
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: UNIX milliseconds, UNIX seconds or ISO-8601 — all three are accepted. Incremental fetch watermark." }
|
||
end_time: { type: string, description: "Upper bound: UNIX milliseconds, UNIX seconds or ISO-8601" }
|
||
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" }
|
||
limit: { type: number, description: "Maximum events to gather across pages (default 1000). Bounds an unattended run against a query that matches more than it was meant to." }
|
||
detection_name: { type: string, description: "Name of the detection rule this query stands for. Stamped on every event and used as the incident title — a log line does not know which rule it was replayed for." }
|
||
required: [log_id, query]
|
||
outputs_schema: { properties: {} }
|
||
ingest:
|
||
results_path: events
|
||
dedup_key: event_id
|
||
incremental_field: start_time
|
||
|
||
- 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. Usable as an ingestion feed: point it at the LEQL of a basic detection rule and every matching line becomes an alert (results path = events, one incident per log entry)."
|
||
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: groupby/calculate are rejected by this endpoint)" }
|
||
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: UNIX milliseconds, UNIX seconds or ISO-8601 — all three are accepted. Incremental fetch watermark." }
|
||
end_time: { type: string, description: "Upper bound: UNIX milliseconds, UNIX seconds or ISO-8601" }
|
||
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" }
|
||
limit: { type: number, description: "Maximum events to gather across pages (default 1000). Bounds an unattended run against a query that matches more than it was meant to." }
|
||
detection_name: { type: string, description: "Name of the detection rule this query stands for. Stamped on every event and used as the incident title — a log line does not know which rule it was replayed for." }
|
||
required: [log_set_id, query]
|
||
outputs_schema: { properties: {} }
|
||
ingest:
|
||
results_path: events
|
||
dedup_key: event_id
|
||
incremental_field: start_time
|
||
|
||
- 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 — e.g. [{\"field_ids\":[\"investigation_rrn\"],\"operator\":\"CONTAINS\",\"terms\":[\"rrn:investigation\"]}] to keep only alerts attached to an investigation. Paste the array alone, without the field name. 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). Without it the endpoint returns only a CACHED tree, so an alert whose tree was never generated answers 404 even though the data exists — this is the first thing to try on a 404 for an endpoint detection. Documented as expensive and slow." }
|
||
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: {} }
|
||
|
||
- id: search_investigation_alerts
|
||
name: rapid7-insight-idr-search-investigation-alerts
|
||
description: "Ingestion: the alerts that belong to an investigation, with their full detection content. Walks the investigations in a time window, collects their alert RRNs and retrieves the alerts in batches from the Alert Triage API — so an alert Rapid7 never folded into an investigation is never returned. Results path = alerts, dedup on rrn, incremental on start_time (the investigation's creation time). Use the search_alerts mapper: the alert objects are identical, with the parent investigation carried alongside under `investigation`."
|
||
risk: read
|
||
inputs_schema:
|
||
properties:
|
||
start_time: { type: string, description: "ISO-8601 lower bound on investigation created_time. Incremental fetch watermark." }
|
||
end_time: { type: string, description: "ISO-8601 upper bound on investigation created_time" }
|
||
default_days: { type: string, description: "Window size in days used when start_time is absent (default 1)" }
|
||
statuses: { type: string, description: "Comma-separated investigation statuses to include (open, investigating, closed). Leaving out closed skips what the source has already triaged." }
|
||
priorities: { type: string, description: "Comma-separated investigation priorities to include (Unspecified, Low, Medium, High, Critical)" }
|
||
field_ids: { type: string, description: "Comma-separated additional alert field ids to include (see rapid7-insight-idr-list-alert-fields)" }
|
||
include_investigation: { type: string, description: "Carry the parent investigation on each alert under `investigation` (true/false, default true)" }
|
||
max_alerts: { type: string, description: "Ceiling on alert RRNs collected in one run (default 500)" }
|
||
time_budget_seconds: { type: string, description: "Stop walking investigations after this many seconds and report truncated=true, rather than exceed the server's 90-second command budget and lose the whole run (default 60)" }
|
||
index: { type: string, description: "0-based page index of investigations" }
|
||
page_size: { type: string, description: "Investigation page size" }
|
||
limit: { type: number, description: "Maximum number of investigations to walk (default 50)" }
|
||
required: []
|
||
outputs_schema: { properties: {} }
|
||
ingest:
|
||
results_path: alerts
|
||
dedup_key: rrn
|
||
incremental_field: start_time
|
||
|
||
- id: get_investigations_full
|
||
name: rapid7-insight-idr-get-investigations-full
|
||
description: "Ingestion: investigations with their alerts inlined, so the INVESTIGATION stays the unit that becomes an incident. Walks the investigations in a time window, collects their alert RRNs and retrieves the alerts in batches from the Alert Triage API, then nests them under `alerts` with a few first-alert values lifted to the top level. Results path = data, dedup on rrn, incremental on start_time — a drop-in replacement for list_investigations, which carries no host, process or MITRE code. Use the get_investigations_full mapper."
|
||
risk: read
|
||
inputs_schema:
|
||
properties:
|
||
start_time: { type: string, description: "ISO-8601 lower bound on investigation created_time. Incremental fetch watermark." }
|
||
end_time: { type: string, description: "ISO-8601 upper bound on investigation created_time" }
|
||
default_days: { type: string, description: "Window size in days used when start_time is absent (default 1)" }
|
||
statuses: { type: string, description: "Comma-separated investigation statuses to include (open, investigating, closed). Leaving out closed skips what the source has already triaged." }
|
||
priorities: { type: string, description: "Comma-separated investigation priorities to include (Unspecified, Low, Medium, High, Critical)" }
|
||
field_ids: { type: string, description: "Comma-separated additional alert field ids to include (see rapid7-insight-idr-list-alert-fields)" }
|
||
include_evidence: { type: string, description: "Also fetch each alert's evidence — the log line the alert was raised on, parsed and normalised into evidence_fields (true/false, default true). One extra call per alert." }
|
||
max_evidence_per_alert: { type: string, description: "Maximum evidence items per alert (default 5)" }
|
||
include_process_tree: { type: string, description: "Fetch each alert process tree: auto (default, only endpoint event types that produce one), true (every alert), false (never). One extra call per alert asked. Chains are flattened root-first into ctx.process_tree, which the layout Process Tree block reads." }
|
||
max_alerts: { type: string, description: "Ceiling on alert RRNs collected in one run (default 500)" }
|
||
time_budget_seconds: { type: string, description: "Stop walking investigations after this many seconds and report truncated=true, rather than exceed the server's 90-second command budget and lose the whole run (default 60)" }
|
||
index: { type: string, description: "0-based page index" }
|
||
page_size: { type: string, description: "Investigation page size" }
|
||
limit: { type: number, description: "Maximum number of investigations to return (default 50)" }
|
||
required: []
|
||
outputs_schema: { properties: {} }
|
||
ingest:
|
||
results_path: data
|
||
dedup_key: rrn
|
||
incremental_field: start_time
|
||
|
||
# ── 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"
|