feat(rapid7-insightidr): add the Alert Triage API commands (v1.1.0)

An ingested investigation carried almost nothing: title, priority, status, assignee and timestamps. Not a host, not an account, not a command line — so no entity was ever indexed, and neither the pivot graph nor the AI analysis had anything to read. Fetching the investigation's alerts did not help: that endpoint answers with the rule name (already the investigation's title), the alert source and an alert RRN, and nothing else. The detection content lives in a different API. The Alert Triage API is served under /idr/at — its own base, next to /idr/v1 and /idr/v2 — and it is where the evidence, the actors, the MITRE T-codes and the process trees actually are. It was missing from this package entirely. Six read commands: search_alerts POST /alerts/ops/search get_alert GET /alerts/{rrn} get_alert_evidence GET /alerts/{rrn}/evidences get_alert_actors GET /alerts/{rrn}/actors get_alert_process_trees POST /alerts/{rrn}/process_trees/latest list_alert_fields GET /alerts/2/fields search_alerts is the one that changes the shape of the feed. It returns full alert objects — rule with its mitre_tcodes, rule_keys_of_interest, the AI-suggested disposition, the parent investigation RRN, the status transition timings and the log entries behind the alert — and its start_time is required by the API, which makes it a natural incremental watermark. So the alerts can be read directly, paginated, with no per-investigation fan-out. Two things worth knowing before using them: - field_ids is not optional in practice. The API returns no additional fields when it is empty, and those additional fields are where the hostnames, accounts and command lines are. Their ids are per-tenant dotted paths (process.cmd_line, …), which is what list_alert_fields is for. /alerts/fields is deprecated, hence /alerts/2/fields. - the whole API is gated on Managed Detection and Response with access to the Alerts experience. A key that works on every investigation endpoint can still be refused here, so 401 and 403 are reported with that named explanation rather than as a bare status code — a licence boundary should not read as a bug. Written against the published OpenAPI spec (SIEM Alerts API 39.10.0); not yet exercised against a live tenant. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-07 22:31:12 +02:00
parent df27876a8f
commit da44d41555
7 changed files with 572 additions and 2 deletions
@@ -0,0 +1,65 @@
+import json, os, sys, urllib.request, urllib.parse, urllib.error
+
+# The Alert Triage API lives under /idr/at, a base of its own — not /idr/v1 or
+# /idr/v2 like the investigation endpoints. Same host, same API key.
+AT = "idr/at/"
+
+
+def _cfg():
+    s = json.loads(os.environ.get("INTEGRATION_SECRETS", "{}"))
+    region = str(s.get("region") or "us").strip().lower()
+    base = "https://" + region + ".api.insight.rapid7.com/"
+    headers = {"X-Api-Key": s.get("api_key", ""), "Content-Type": "application/json", "Accept": "application/json"}
+    multi = str(s.get("is_multi_customer") or "").strip().lower() in ("1", "true", "yes")
+    return base, headers, multi
+
+
+def _inputs():
+    return json.loads(os.environ.get("INTEGRATION_INPUTS", "{}"))
+
+
+def _list(v):
+    if v in (None, ""):
+        return []
+    if isinstance(v, list):
+        return [str(x).strip() for x in v if str(x).strip()]
+    return [p.strip() for p in str(v).split(",") if p.strip()]
+
+
+def request(method, path, params=None, body=None):
+    base, headers, _ = _cfg()
+    url = base + path.lstrip("/")
+    if params:
+        clean = {k: v for k, v in params.items() if v not in (None, "")}
+        if clean:
+            url += ("&" if "?" in url else "?") + urllib.parse.urlencode(clean, doseq=True)
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    with urllib.request.urlopen(req, timeout=90) as r:
+        raw = r.read()
+        return json.loads(raw) if raw else {}
+
+
+def run():
+    inp = _inputs()
+    rrn = inp.get("alert_rrn", "")
+    params = {}
+    ids = _list(inp.get("field_ids"))
+    if ids:
+        params["field_ids"] = ids
+    print(json.dumps(request("GET", AT + "alerts/" + urllib.parse.quote(rrn, safe=""), params=params)))
+
+
+try:
+    run()
+except urllib.error.HTTPError as e:
+    detail = e.read().decode("utf-8", "replace")
+    if e.code in (401, 403):
+        detail += (" — the Alert Triage API (/idr/at) is only available to Managed Detection and"
+                   " Response customers with access to the Alerts experience; a key that works on"
+                   " the investigation endpoints can still be refused here")
+    print(json.dumps({"error": "HTTP " + str(e.code), "detail": detail}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)