sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SecurityHub/ FindingEventSource.ts

import type * as securityhub from "@distilled.cloud/aws/securityhub";
import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import {
  consumeBusEvents,
  type EventRecord,
  type EventRouteProps,
} from "../EventBridge/EventSource.ts";

/**
 * The `detail` payload Security Hub delivers to EventBridge — a batch of
 * findings in AWS Security Finding Format (ASFF).
 */
export interface FindingEventDetail {
  /** The findings the event carries (ASFF documents, up to 25 per event). */
  findings?: securityhub.AwsSecurityFinding[];
  /** Additional detail fields (the schema grows over time). */
  [key: string]: unknown;
}

/** A Security Hub findings EventBridge event delivered to the handler. */
export type FindingEvent = EventRecord<FindingEventDetail>;

/**
 * The `detail` payload of a `Security Hub Findings - Custom Action` event —
 * the action that was invoked plus the findings it was invoked on.
 */
export interface CustomActionEventDetail extends FindingEventDetail {
  /** Name of the custom action that was invoked. */
  actionName?: string;
  /** Description of the custom action that was invoked. */
  actionDescription?: string;
}

/** A Security Hub custom-action EventBridge event delivered to the handler. */
export type CustomActionEvent = EventRecord<CustomActionEventDetail>;

export interface FindingEventSourceProps extends EventRouteProps {
  /**
   * Logical id for the backing EventBridge rule.
   * @default "SecurityHubFindings"
   */
  id?: string;
  /**
   * Restrict to findings with specific severity labels (matched against
   * `detail.findings.Severity.Label`), e.g. `["HIGH", "CRITICAL"]`.
   */
  severityLabels?: readonly string[];
  /**
   * Restrict to findings with specific workflow statuses (matched against
   * `detail.findings.Workflow.Status`), e.g. `["NEW"]`.
   */
  workflowStatuses?: readonly string[];
}

/**
 * Event source connecting Security Hub findings to the hosting compute.
 * Security Hub publishes every new finding and finding update to the
 * account's default EventBridge bus (source `aws.securityhub`, detail-type
 * `Security Hub Findings - Imported`); this subscribes the host Function to
 * those events so it can triage, notify, or auto-remediate.
 *
 * Security Hub publishes to EventBridge automatically — no additional
 * resource is created besides the EventBridge rule targeting the host.
 * Provide the host-specific implementation layer (e.g.
 * `AWS.Lambda.EventSource`) on the Function effect.
 *
 * ### Consuming Findings
 * **Example:** Alert on Critical Findings
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * export default AlertFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     yield* AWS.SecurityHub.consumeFindings(
 *       { severityLabels: ["CRITICAL"] },
 *       (events) =>
 *         Stream.runForEach(events, (event) =>
 *           Effect.forEach(event.detail.findings ?? [], (finding) =>
 *             Effect.logError(`Security Hub: ${finding.Title}`),
 *           ),
 *         ),
 *     );
 *     return {};
 *   }).pipe(Effect.provide(AWS.Lambda.EventSource)),
 * );
 * ```
 */
export const consumeFindings = <StreamReq = never, Req = never>(
  props: FindingEventSourceProps,
  process: (
    events: Stream.Stream<FindingEvent, never, StreamReq>,
  ) => Effect.Effect<void, never, Req>,
) =>
  consumeBusEvents(
    props.id ?? "SecurityHubFindings",
    {
      source: ["aws.securityhub"],
      "detail-type": ["Security Hub Findings - Imported"],
      ...(props.severityLabels !== undefined || props.workflowStatuses !== undefined
        ? {
            detail: {
              findings: {
                ...(props.severityLabels !== undefined
                  ? { Severity: { Label: [...props.severityLabels] } }
                  : {}),
                ...(props.workflowStatuses !== undefined
                  ? { Workflow: { Status: [...props.workflowStatuses] } }
                  : {}),
              },
            },
          }
        : {}),
    },
    { description: props.description, state: props.state },
    process,
  );

export interface CustomActionEventSourceProps extends EventRouteProps {
  /**
   * Logical id for the backing EventBridge rule.
   * @default "SecurityHubCustomActions"
   */
  id?: string;
  /**
   * Restrict to specific custom actions (matched against the event's
   * `resources`, which carry the action target ARN), e.g.
   * `[actionTarget.actionTargetArn]`.
   */
  actionArns?: readonly string[];
}

/**
 * Event source connecting Security Hub custom actions to the hosting
 * compute. Selecting a custom action on findings or insights in the console
 * publishes a `Security Hub Findings - Custom Action` event carrying the
 * selected findings; this subscribes the host Function to those events.
 * Define the action with {@link ActionTarget}.
 *
 * ### Consuming Custom Actions
 * **Example:** Handle an Escalation Action
 * ```typescript
 * yield* AWS.SecurityHub.consumeCustomActions(
 *   { actionArns: [escalate.actionTargetArn] },
 *   (events) =>
 *     Stream.runForEach(events, (event) =>
 *       Effect.log(`${event.detail.actionName}:`, event.detail.findings),
 *     ),
 * );
 * ```
 */
export const consumeCustomActions = <StreamReq = never, Req = never>(
  props: CustomActionEventSourceProps,
  process: (
    events: Stream.Stream<CustomActionEvent, never, StreamReq>,
  ) => Effect.Effect<void, never, Req>,
) =>
  consumeBusEvents(
    props.id ?? "SecurityHubCustomActions",
    {
      source: ["aws.securityhub"],
      "detail-type": ["Security Hub Findings - Custom Action"],
      ...(props.actionArns !== undefined ? { resources: [...props.actionArns] } : {}),
    },
    { description: props.description, state: props.state },
    process,
  );