f3nris
306450a4b6
Both mappers read that field through a hardcoded list of keys — hostname, process.cmd_line, parent_process.*, user — taken from the one alert this work was built against, a process_start_event detection. Every entry is a JSONata predicate on an exact key, so a rule emitting anything else matches none of them. A real alert from a second tenant showed what that costs. It is a custom ingress_auth rule, and its keys are: account locuz_hma@totogroup.net source_ip 183.82.103.101 geoip_country_code IN result SUCCESS Not one appears in the hardcoded list. The alert was fetched, inlined and mapped, and produced an incident as empty as the ones this integration set out to fix — with the account and the source IP sitting in the payload, unread. Two changes: - The whole list is flattened verbatim into `detection`, and rule_matching_keys into `detection_match`. Keys nobody anticipated now arrive intact, and they reach the AI analysis, which reads the mapped context and never `raw`. - account, source_ip, destination_ip, geoip_country_code and result gain explicit OCSF entries. The explicit mappings are not redundant with the flattening: a value under `detection.` is only ever seen by the IOC regex, so an account there would be indexed as an email, or not at all, rather than as a user. Typing an entity correctly still requires naming its field. evidences[] carries the flattened keys too, so the same holds for the second and third alert of an investigation, not only the first. Verified against both rule shapes end to end. The process rule yields the two hosts it did before; the authentication rule now yields the source IP and the account, where it previously yielded nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
480 lines
33 KiB
YAML
480 lines
33 KiB
YAML
id: rapid7_insightidr
|
|
name: Rapid7 InsightIDR
|
|
version: 1.5.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.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_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 — 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). 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: {} }
|
|
|
|
- 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)" }
|
|
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"
|