infraweaver 0.1.0

package/src/mcp/terraform/prowlerOcsf.ts

@@ -0,0 +1,380 @@
+import { type } from "arktype";
+import type { ExternalFinding } from "#app/mcp/terraform/cspm";
+import type { Severity } from "#app/mcp/terraform/types";
+
+/**
+ * Prowler OCSF ingestion (CSPM phase 1).
+ *
+ * Prowler is an Apache-2.0 live-cloud CSPM scanner. Infraweaver CONSUMES its
+ * findings and never runs it: the customer runs Prowler in their own CI with
+ * their own cloud credentials and Infraweaver ingests the resulting JSON. The
+ * zero-credential invariant is unchanged — this module only parses a file.
+ *
+ * Prowler writes OCSF `DetectionFinding` objects (class_uid 2004) as a single
+ * JSON ARRAY, not NDJSON. Field locations follow the OCSF 1.x DetectionFinding
+ * schema; `severity_id` is the OCSF enum (0 Unknown, 1 Informational, 2 Low,
+ * 3 Medium, 4 High, 5 Critical, 6 Fatal), which is deliberately NOT routed
+ * through `normalizeExternalSeverity()` — that function reads bare numbers as
+ * CVSS scores and would silently downgrade a Critical (5) to medium.
+ *
+ * Output is the existing `ExternalFinding` shape, so everything downstream —
+ * correlation, concern building, grouping, the Cloud report — is unchanged.
+ */
+
+/** OCSF `type_uid` for DetectionFinding: Create — what Prowler emits. */
+export const DETECTION_FINDING_CREATE = 200401;
+
+/**
+ * Lenient schema: only what we actually read, everything optional except the
+ * check id. A finding that fails this is routed to unmapped-alerts rather than
+ * failing the run — an external feed must never break a scan.
+ */
+const ProwlerResource = type({
+  "uid?": "string",
+  "name?": "string",
+  "type?": "string",
+  "region?": "string",
+  "labels?": "string[]",
+});
+
+const ProwlerFinding = type({
+  "metadata?": type({
+    "event_code?": "string",
+    "product?": type({ "name?": "string", "version?": "string" }),
+  }),
+  "status_code?": "string",
+  "status?": "string",
+  "status_detail?": "string",
+  "message?": "string",
+  "severity?": "string",
+  "severity_id?": "number",
+  "finding_info?": type({ "title?": "string", "desc?": "string" }),
+  "remediation?": type({ "desc?": "string", "references?": "string[]" }),
+  "resources?": ProwlerResource.array(),
+  "cloud?": type({
+    "provider?": "string",
+    "account?": type({ "uid?": "string" }),
+    "region?": "string",
+  }),
+  "type_uid?": "number",
+  "unmapped?": "object",
+});
+
+export type ProwlerFindingInput = typeof ProwlerFinding.infer;
+
+/**
+ * True for a parsed value that looks like a Prowler OCSF feed: a non-empty array
+ * whose first item is a DetectionFinding or carries Prowler's product name.
+ * Checked BEFORE the native `infraweaver.external-findings/v1` validator, which is
+ * safe because the native feed is an OBJECT and this requires a non-empty ARRAY —
+ * the two shapes cannot collide, so existing feeds keep their exact behaviour.
+ */
+export function isProwlerOcsf(parsed: unknown): boolean {
+  if (!Array.isArray(parsed) || parsed.length === 0) return false;
+  const first = parsed[0] as Record<string, unknown> | undefined;
+  if (!first || typeof first !== "object") return false;
+  if (first.type_uid === DETECTION_FINDING_CREATE) return true;
+  const metadata = first.metadata as
+    | { product?: { name?: unknown } }
+    | undefined;
+  return (
+    typeof metadata?.product?.name === "string" &&
+    /prowler/i.test(metadata.product.name)
+  );
+}
+
+/**
+ * Detect a Prowler output file that was never closed. Prowler streams `[`, then
+ * findings, and only seeks back to write `]` when the scan completes — so a
+ * crashed or still-running scan leaves an unterminated array that `JSON.parse`
+ * rejects with a message no operator can act on.
+ */
+export function isUnterminatedJsonArray(raw: string): boolean {
+  const trimmed = raw.trim();
+  return trimmed.startsWith("[") && !trimmed.endsWith("]");
+}
+
+/** OCSF severity_id → our scale. Explicitly NOT the CVSS band reading. */
+const SEVERITY_BY_ID: Record<number, Severity> = {
+  0: "info", // Unknown — the honest floor, never assumed severe
+  1: "info", // Informational
+  2: "low",
+  3: "medium",
+  4: "high",
+  5: "critical",
+  6: "critical", // Fatal
+};
+
+const SEVERITY_BY_NAME: Record<string, Severity> = {
+  critical: "critical",
+  fatal: "critical",
+  high: "high",
+  medium: "medium",
+  low: "low",
+  informational: "info",
+  info: "info",
+  unknown: "info",
+};
+
+/**
+ * Resolve a finding's severity: the OCSF severity NAME first (what Prowler
+ * writes), then the numeric enum, then `medium` — matching the default the
+ * existing external-findings path uses when a feed says nothing.
+ */
+export function prowlerSeverity(finding: ProwlerFindingInput): Severity {
+  const name = finding.severity?.trim().toLowerCase();
+  if (name && SEVERITY_BY_NAME[name]) return SEVERITY_BY_NAME[name] as Severity;
+  if (typeof finding.severity_id === "number") {
+    const byId = SEVERITY_BY_ID[finding.severity_id];
+    if (byId) return byId;
+  }
+  return "medium";
+}
+
+/**
+ * Framework keys we accept from `unmapped.compliance`. FREE frameworks only —
+ * everything else (CIS, ISO, PCI, SOC2, …) is dropped at parse time and never
+ * reaches storage or the UI. Two independent reasons, both binding:
+ *
+ * 1. LICENCE. CIS/ISO/PCI content is paywalled or no-derivatives; we do not
+ *    redistribute it in any form, not even requirement ids sourced from a
+ *    third-party pack.
+ * 2. NO STANDARDS OVERLOAD. The catalogue is a hard ceiling, not a starting
+ *    point — users see the 12 infra themes first; framework ids appear only on
+ *    control drill-down.
+ *
+ * Matching is prefix-based and case-insensitive because Prowler keys carry a
+ * version suffix (`ENS-RD2022`, `NIST-800-53-REVISION-5`).
+ */
+const FREE_FRAMEWORK_PREFIXES = [
+  "ens",
+  "nis2",
+  "gdpr",
+  "c5",
+  "nist-800-53",
+  "nist_800_53",
+  "nist-csf",
+  "nist_csf",
+] as const;
+
+/** True when a Prowler compliance key names a framework we may lawfully carry. */
+export function isFreeFrameworkKey(key: string): boolean {
+  const k = key.trim().toLowerCase();
+  return FREE_FRAMEWORK_PREFIXES.some((p) => k.startsWith(p));
+}
+
+/**
+ * The free-framework compliance references a finding carries, as
+ * `FRAMEWORK: req-id` strings. Paywalled frameworks are dropped silently and by
+ * design. Returns [] when the finding carries none.
+ */
+export function freeComplianceRefs(finding: ProwlerFindingInput): string[] {
+  const compliance = (finding.unmapped as { compliance?: unknown } | undefined)
+    ?.compliance;
+  if (!compliance || typeof compliance !== "object") return [];
+  const refs: string[] = [];
+  for (const [key, value] of Object.entries(
+    compliance as Record<string, unknown>,
+  )) {
+    if (!isFreeFrameworkKey(key)) continue;
+    if (!Array.isArray(value)) continue;
+    for (const req of value) {
+      if (typeof req === "string" && req.trim())
+        refs.push(`${key}: ${req.trim()}`);
+    }
+  }
+  return refs;
+}
+
+export interface ProwlerParseResult {
+  /** FAIL findings mapped into the shared external-finding shape. */
+  findings: ExternalFinding[];
+  summary: {
+    total: number;
+    /** mapped to concerns (status_code FAIL, not muted). */
+    failed: number;
+    passed: number;
+    manual: number;
+    /** muted by the customer's Prowler mutelist — user intent we honour. */
+    muted: number;
+    /** items that did not match the DetectionFinding shape at all. */
+    malformed: number;
+    /** items whose `status_code` is one we do not model — distinct from malformed,
+     *  so an operator can tell "new Prowler status" from "not a finding". */
+    unknown_status: number;
+    /** `metadata.product.version`, when the feed declared one. */
+    product_version: string | null;
+    /** set when type_uid drifted from the expected DetectionFinding value. */
+    schema_warning: string | null;
+  };
+}
+
+/**
+ * Parse a Prowler OCSF array into external findings + an honest tally.
+ *
+ * Only `status_code === "FAIL"` findings become concerns. PASS/MANUAL and muted
+ * findings are COUNTED but never mapped: a passing check is not a defect, and
+ * Prowler's mutelist is user-authored intent. The counts still matter — phase-2
+ * requirement coverage needs to say "3 checks FAIL, 12 PASS" rather than
+ * treating absence as unknown.
+ *
+ * Pure: no fs, no network.
+ */
+export function parseProwlerOcsf(
+  items: readonly unknown[],
+): ProwlerParseResult {
+  const findings: ExternalFinding[] = [];
+  let failed = 0;
+  let passed = 0;
+  let manual = 0;
+  let muted = 0;
+  let malformed = 0;
+  let unknown_status = 0;
+  let productVersion: string | null = null;
+  let schemaWarning: string | null = null;
+
+  for (const raw of items) {
+    const parsed = ProwlerFinding(raw);
+    if (parsed instanceof type.errors) {
+      malformed++;
+      continue;
+    }
+    const finding = parsed as ProwlerFindingInput;
+    productVersion ??= finding.metadata?.product?.version ?? null;
+    // Version drift is a warning, never a failure — a newer Prowler that still
+    // writes recognisable findings should keep working.
+    if (
+      schemaWarning === null &&
+      typeof finding.type_uid === "number" &&
+      finding.type_uid !== DETECTION_FINDING_CREATE
+    ) {
+      schemaWarning = `unexpected OCSF type_uid ${finding.type_uid} (expected ${DETECTION_FINDING_CREATE}); parsed anyway`;
+    }
+
+    const status = finding.status_code?.trim().toUpperCase();
+    // The schema is deliberately lenient (every field optional), so ANY object
+    // satisfies it — `status_code` is what actually distinguishes a
+    // DetectionFinding from arbitrary JSON. Without it, this is not a finding.
+    if (!status) {
+      malformed++;
+      continue;
+    }
+    // `status: "Suppressed"` marks a muted finding; status_code still carries the
+    // real result, so check muting BEFORE the FAIL branch.
+    // PASS/MANUAL are tallied on their real result first: a muted PASS is still a
+    // PASS, and requirement coverage ("3 FAIL, 12 PASS") is computed off that
+    // tally, so folding it into `muted` would understate what actually ran.
+    if (status === "PASS") {
+      passed++;
+      continue;
+    }
+    if (status === "MANUAL") {
+      manual++;
+      continue;
+    }
+    // `status: "Suppressed"` marks a finding the customer mutelisted; status_code
+    // still carries the real (FAIL) result. Mutelist entries are user-authored
+    // intent we honour, so it is counted and never reported as a defect.
+    if (finding.status?.trim().toLowerCase() === "suppressed") {
+      muted++;
+      continue;
+    }
+    if (status !== "FAIL") {
+      unknown_status++;
+      continue;
+    }
+
+    const checkId = finding.metadata?.event_code?.trim();
+    if (!checkId) {
+      malformed++;
+      continue;
+    }
+    failed++;
+
+    const resource = finding.resources?.[0];
+    const remediationParts = [finding.remediation?.desc?.trim()].filter(
+      Boolean,
+    ) as string[];
+    for (const ref of finding.remediation?.references ?? []) {
+      if (typeof ref === "string" && ref.trim())
+        remediationParts.push(ref.trim());
+    }
+    const compliance = freeComplianceRefs(finding);
+    if (compliance.length > 0)
+      remediationParts.push(`Compliance: ${compliance.join("; ")}`);
+    const hints = tagHints(resource?.labels);
+
+    const message = finding.status_detail?.trim() || finding.message?.trim();
+    const remediation = remediationParts.join(" ");
+    findings.push({
+      rule_id: checkId,
+      provider: finding.cloud?.provider?.trim().toLowerCase() || "prowler",
+      severity: prowlerSeverity(finding),
+      title: finding.finding_info?.title?.trim() || checkId,
+      ...(message ? { message } : {}),
+      ...(remediation ? { remediation } : {}),
+      // NB: OCSF `resources[].type` is a CLOUD type ("AwsS3Bucket"), not a
+      // Terraform type ("aws_s3_bucket"). Passing it through as `resource.type`
+      // would make the correlator's type-narrowed passes silently never match,
+      // so it is deliberately omitted and correlation runs on uid/name instead.
+      resource: {
+        ...(resource?.uid ? { arn: resource.uid } : {}),
+        ...(resource?.name ? { id: resource.name } : {}),
+        ...(hints.length > 0 ? { tags: hints } : {}),
+      },
+    });
+  }
+
+  return {
+    findings,
+    summary: {
+      total: items.length,
+      failed,
+      passed,
+      manual,
+      muted,
+      malformed,
+      unknown_status,
+      product_version: productVersion,
+      schema_warning: schemaWarning,
+    },
+  };
+}
+
+/**
+ * Tag keys whose value NAMES a specific resource. OCSF unrolls cloud tags into
+ * `labels` as `key:value`, but only an identity tag is correlation evidence: an
+ * `env=production` or `owner=platform-team` tag describes a whole fleet, so
+ * matching on it would pin every finding in that fleet to whichever single
+ * Terraform block happened to contain the word.
+ */
+const IDENTITY_TAG_KEYS = new Set(["name", "resourcename", "resource_name"]);
+
+/**
+ * The identity-bearing cloud tags a Prowler finding carries, lower-cased, as
+ * last-resort correlation hints.
+ *
+ * Two filters, both about not mis-mapping: only identity keys (above), and only
+ * values long enough to identify something — a short value like `eu` would match
+ * half the repo. A wrong mapping is worse than an honest unmapped alert, because
+ * it puts a real cloud finding on an unrelated line of someone's code.
+ */
+export function tagHints(labels: readonly string[] | undefined): string[] {
+  const hints = new Set<string>();
+  for (const label of labels ?? []) {
+    if (typeof label !== "string") continue;
+    const idx = label.indexOf(":");
+    // No key at all — not attributable to an identity tag, so not evidence.
+    if (idx < 0) continue;
+    const key = label.slice(0, idx).trim().toLowerCase().replace(/[\s-]/g, "");
+    if (!IDENTITY_TAG_KEYS.has(key)) continue;
+    // Take everything after the FIRST colon: an ARN-valued Name tag keeps its
+    // colons, and the whole ARN is the identity.
+    const value = label
+      .slice(idx + 1)
+      .trim()
+      .toLowerCase();
+    if (value.length >= 4) hints.add(value);
+  }
+  return [...hints];
+}