feat(recorded-future): Recorded Future + ASI integrations

Recorded Future (enrichment): native ConnectAPI v2 (X-RFToken). ip/domain/url/ file/cve risk reputation, full entity intelligence, and alert ingestion (alerts search) with an OCSF mapper and a 'Recorded Future Alert' default type, plus alert lookup and alert-rule search. Recorded Future ASI (enrichment): Attack Surface Intelligence (SecurityTrails API, APIKEY header, project-scoped). Project issue ingestion (project_issues) with an OCSF mapper and a 'Recorded Future ASI Issue' default type, filtered by a configurable minimum severity, plus recent-issues and recent-issues-by-host queries. The XSOAR-gateway packs (alerts/lists) were re-implemented against Recorded Future's native ConnectAPI rather than the XSOAR-coupled gateway protocol. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-27 15:19:40 +02:00
parent ef215daa88
commit fcf516ca82
20 changed files with 862 additions and 0 deletions
@@ -0,0 +1,3 @@
+name: "Recorded Future ASI Issue"
+color: "#f4a261"
+icon: "alert"
@@ -0,0 +1,84 @@
+id: recorded_future_asi
+name: Recorded Future ASI
+version: 1.0.0
+description: "Recorded Future Attack Surface Intelligence (SecurityTrails) — fetch attack-surface risk issues for a project (ingestion), and query recent added issues globally or grouped by host."
+changelog: "1.0.0 — Initial release: project issue ingestion (project_issues) with an OCSF mapper, plus recent-issues and recent-issues-by-host queries."
+category: enrichment
+
+# Per-instance configuration. The SecurityTrails ASI API is authenticated with an
+# API key sent in the APIKEY header and scoped to a project.
+config_schema:
+  properties:
+    api_key:
+      type: string
+      description: "SecurityTrails / ASI API key"
+      x-soar-sensitive: true
+    project_id:
+      type: string
+      description: "ASI Project ID to fetch issues from"
+    min_severity:
+      type: string
+      description: "Minimum issue severity to fetch: Informational, Moderate or Critical (default Moderate)"
+      default: Moderate
+  required:
+    - api_key
+    - project_id
+
+auth:
+  - id: apikey
+    type: api_key
+    in: header
+    name: APIKEY
+    value_template: "{{secret}}"
+    secret_field: api_key
+
+commands:
+  # ── Ingestion ───────────────────────────────────────────────────────────────
+  - id: project_issues
+    name: asi-project-issues
+    description: "Fetch the current attack-surface risk issues for the project. Used for ingestion: results path = data. Issues below the configured minimum severity are filtered out."
+    risk: read
+    inputs_schema:
+      properties:
+        snapshot: { type: string, description: "Snapshot to read (default 'recent')" }
+      required: []
+    outputs_schema: { properties: {} }
+    ingest:
+      results_path: data
+      dedup_key: name
+
+  - id: recent_issues
+    name: asi-recent-issues
+    description: "List risk issues added to the project since a given time, filtered by the configured minimum severity."
+    risk: read
+    inputs_schema:
+      properties:
+        start: { type: string, description: "Lower bound: a timestamp or snapshot date" }
+      required: []
+    outputs_schema: { properties: {} }
+
+  - id: recent_issues_by_host
+    name: asi-recent-issues-by-host
+    description: "List hosts with risk issues added since a given time, with per-host risk-score changes."
+    risk: read
+    inputs_schema:
+      properties:
+        last_checked: { type: string, description: "Lower bound: a timestamp or snapshot date" }
+        limit: { type: number, description: "Maximum number of hosts to return (default 200)" }
+      required: []
+    outputs_schema: { properties: {} }
+
+  # ── Connectivity test ─────────────────────────────────────────────────────
+  - id: test_connection
+    name: asi-test-connection
+    description: "Verify connectivity, credentials and project access (used by the Test button)."
+    risk: read
+    inputs_schema:
+      properties: {}
+      required: []
+    outputs_schema: { properties: {} }
+
+ingestion:
+  command: project_issues
+  mapper: project_issues
+  default_incident_type: "Recorded Future ASI Issue"
@@ -0,0 +1,18 @@
+name: "Recorded Future ASI Issues → OCSF"
+description: "Maps a Recorded Future ASI risk issue (project issues, results_path = data) to OCSF Detection Finding fields. Each issue is a triggered risk rule with example affected hosts."
+field_mappings:
+  title: "name"
+  description: "description"
+  # _severity is injected by the fetch script (high=5, moderate=3, informational=1).
+  severity: "_severity"
+# results_path = data; source_path is JSONata over ONE issue object.
+ocsf:
+  # ── Finding ───────────────────────────────────────────────────────
+  - { source_path: "name",                          ocsf_field: "finding_info.uid" }
+  - { source_path: "name",                          ocsf_field: "finding_info.title" }
+  - { source_path: "description",                   ocsf_field: "finding_info.desc" }
+  - { source_path: "classification",                ocsf_field: "activity_name" }
+  - { source_path: "rule_metadata.references[0]",   ocsf_field: "finding_info.src_url" }
+  # ── Example affected host ─────────────────────────────────────────
+  - { source_path: "example_entities.domains[0].example", ocsf_field: "src_endpoint.hostname" }
+  - { source_path: "example_entities.ips[0].example",     ocsf_field: "src_endpoint.ip" }
@@ -0,0 +1,51 @@
+import json, os, sys, urllib.request, urllib.parse, urllib.error
+
+MIN_SEVERITY = {"Informational": {"high", "moderate", "informational"}, "Moderate": {"high", "moderate"}, "Critical": {"high"}}
+SEV_NUM = {"high": 5, "moderate": 3, "informational": 1}
+
+
+def _cfg():
+    s = json.loads(os.environ.get("INTEGRATION_SECRETS", "{}"))
+    base = "https://api.securitytrails.com/v1/asi"
+    headers = {"APIKEY": s.get("api_key", ""), "Accept": "application/json"}
+    project = str(s.get("project_id", ""))
+    min_sev = str(s.get("min_severity") or "Moderate")
+    return base, headers, project, min_sev
+
+
+def _inputs():
+    return json.loads(os.environ.get("INTEGRATION_INPUTS", "{}"))
+
+
+def request(path):
+    base, headers, _, _ = _cfg()
+    req = urllib.request.Request(base + "/" + path.lstrip("/"), headers=headers, method="GET")
+    with urllib.request.urlopen(req, timeout=90) as r:
+        raw = r.read()
+        return json.loads(raw) if raw else {}
+
+
+def run():
+    _, _, project, min_sev = _cfg()
+    snapshot = _inputs().get("snapshot") or "recent"
+    out = request("/rules/" + urllib.parse.quote(project, safe="") + "/" + urllib.parse.quote(snapshot, safe="") + "/issues")
+    allowed = MIN_SEVERITY.get(min_sev, MIN_SEVERITY["Moderate"])
+    issues = []
+    for issue in out.get("data", []):
+        cls = str(issue.get("classification", "")).lower()
+        if cls and cls not in allowed:
+            continue
+        # Inject a 1-5 severity so the mapper can map it without string comparisons.
+        issue["_severity"] = SEV_NUM.get(cls, 2)
+        issues.append(issue)
+    print(json.dumps({"data": issues, "meta": out.get("meta", {})}))
+
+
+try:
+    run()
+except urllib.error.HTTPError as e:
+    print(json.dumps({"error": "HTTP " + str(e.code), "detail": e.read().decode("utf-8", "replace")}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
@@ -0,0 +1,47 @@
+import json, os, sys, urllib.request, urllib.parse, urllib.error
+
+MIN_SEVERITY = {"Informational": "high,moderate,informational", "Moderate": "high,moderate", "Critical": "high"}
+
+
+def _cfg():
+    s = json.loads(os.environ.get("INTEGRATION_SECRETS", "{}"))
+    base = "https://api.securitytrails.com/v1/asi"
+    headers = {"APIKEY": s.get("api_key", ""), "Accept": "application/json"}
+    project = str(s.get("project_id", ""))
+    min_sev = str(s.get("min_severity") or "Moderate")
+    return base, headers, project, min_sev
+
+
+def _inputs():
+    return json.loads(os.environ.get("INTEGRATION_INPUTS", "{}"))
+
+
+def request(path, params):
+    base, headers, _, _ = _cfg()
+    clean = {k: v for k, v in params.items() if v not in (None, "")}
+    url = base + "/" + path.lstrip("/") + ("?" + urllib.parse.urlencode(clean, doseq=True) if clean else "")
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    with urllib.request.urlopen(req, timeout=90) as r:
+        raw = r.read()
+        return json.loads(raw) if raw else {}
+
+
+def run():
+    _, _, project, min_sev = _cfg()
+    inp = _inputs()
+    params = {
+        "rule_action": "added",
+        "start": inp.get("start"),
+        "classification": MIN_SEVERITY.get(min_sev, "high,moderate"),
+    }
+    print(json.dumps(request("/rules/history/" + urllib.parse.quote(project, safe="") + "/activity", params)))
+
+
+try:
+    run()
+except urllib.error.HTTPError as e:
+    print(json.dumps({"error": "HTTP " + str(e.code), "detail": e.read().decode("utf-8", "replace")}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
@@ -0,0 +1,48 @@
+import json, os, sys, urllib.request, urllib.parse, urllib.error
+
+MIN_SEVERITY = {"Informational": "high,moderate,informational", "Moderate": "high,moderate", "Critical": "high"}
+
+
+def _cfg():
+    s = json.loads(os.environ.get("INTEGRATION_SECRETS", "{}"))
+    base = "https://api.securitytrails.com/v1/asi"
+    headers = {"APIKEY": s.get("api_key", ""), "Accept": "application/json"}
+    project = str(s.get("project_id", ""))
+    min_sev = str(s.get("min_severity") or "Moderate")
+    return base, headers, project, min_sev
+
+
+def _inputs():
+    return json.loads(os.environ.get("INTEGRATION_INPUTS", "{}"))
+
+
+def request(path, params):
+    base, headers, _, _ = _cfg()
+    clean = {k: v for k, v in params.items() if v not in (None, "")}
+    url = base + "/" + path.lstrip("/") + ("?" + urllib.parse.urlencode(clean, doseq=True) if clean else "")
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    with urllib.request.urlopen(req, timeout=90) as r:
+        raw = r.read()
+        return json.loads(raw) if raw else {}
+
+
+def run():
+    _, _, project, min_sev = _cfg()
+    inp = _inputs()
+    params = {
+        "rule_action": "added",
+        "last_checked": inp.get("last_checked"),
+        "classification": MIN_SEVERITY.get(min_sev, "high,moderate"),
+        "limit": inp.get("limit") or 200,
+    }
+    print(json.dumps(request("/rules/history/" + urllib.parse.quote(project, safe="") + "/activity/by_host/compare", params)))
+
+
+try:
+    run()
+except urllib.error.HTTPError as e:
+    print(json.dumps({"error": "HTTP " + str(e.code), "detail": e.read().decode("utf-8", "replace")}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
@@ -0,0 +1,40 @@
+import json, os, sys, urllib.request, urllib.parse, urllib.error
+
+
+def _cfg():
+    s = json.loads(os.environ.get("INTEGRATION_SECRETS", "{}"))
+    base = "https://api.securitytrails.com/v1/asi"
+    headers = {"APIKEY": s.get("api_key", ""), "Accept": "application/json"}
+    project = str(s.get("project_id", ""))
+    return base, headers, project
+
+
+def request(path):
+    base, headers, _ = _cfg()
+    req = urllib.request.Request(base + "/" + path.lstrip("/"), headers=headers, method="GET")
+    with urllib.request.urlopen(req, timeout=60) as r:
+        raw = r.read()
+        return json.loads(raw) if raw else {}
+
+
+def run():
+    _, _, project = _cfg()
+    request("/rules/" + urllib.parse.quote(project, safe="") + "/recent/issues")
+    print(json.dumps({"ok": True}))
+
+
+try:
+    run()
+except urllib.error.HTTPError as e:
+    detail = e.read().decode("utf-8", "replace")
+    if e.code in (401, 403):
+        msg = "API key is not valid or has no access to this project."
+    elif e.code == 404:
+        msg = "Project not found. Check the Project ID."
+    else:
+        msg = "HTTP " + str(e.code)
+    print(json.dumps({"ok": False, "error": msg, "detail": detail}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"ok": False, "error": str(e)}))
+    sys.exit(1)