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

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 category of a Macie finding. */
export type FindingCategory = "CLASSIFICATION" | "POLICY";

/** The qualitative severity of a Macie finding. */
export type FindingSeverityDescription = "Low" | "Medium" | "High";

/**
 * The `detail` payload Macie delivers to EventBridge for a finding — the full
 * finding document. Only the commonly-matched fields are typed; the schema
 * grows over time.
 */
export interface FindingEventDetail {
  /** The finding id. */
  id?: string;
  /** The finding type, e.g. `SensitiveData:S3Object/Personal`. */
  type?: string;
  /** Whether the finding is a sensitive-data or policy finding. */
  category?: FindingCategory;
  /** The finding severity (score 1-3 plus a qualitative description). */
  severity?: { score?: number; description?: FindingSeverityDescription };
  /** The account the finding was generated in. */
  accountId?: string;
  /** The region the finding was generated in. */
  region?: string;
  /** The finding title. */
  title?: string;
  /** The finding description. */
  description?: string;
  /** The affected resources document (S3 bucket + object details). */
  resourcesAffected?: Record<string, unknown>;
  /** For classification findings, the sensitive-data detection details. */
  classificationDetails?: Record<string, unknown>;
  /** Additional finding fields (the schema grows over time). */
  [key: string]: unknown;
}

/** A Macie finding EventBridge event delivered to the handler. */
export type FindingEvent = EventRecord<FindingEventDetail>;

export interface FindingEventSourceProps extends EventRouteProps {
  /**
   * Logical id for the backing EventBridge rule.
   * @default "MacieFindings"
   */
  id?: string;
  /**
   * Restrict to specific finding types (matched against `detail.type`),
   * e.g. `["SensitiveData:S3Object/Personal"]`.
   */
  types?: readonly string[];
  /**
   * Restrict to a finding category: `CLASSIFICATION` (sensitive data found in
   * an object) or `POLICY` (a bucket policy/configuration issue).
   */
  categories?: readonly FindingCategory[];
  /**
   * Restrict to qualitative severities (matched against
   * `detail.severity.description`), e.g. `["High"]`.
   */
  severities?: readonly FindingSeverityDescription[];
}

/**
 * Event source connecting Amazon Macie findings to the hosting compute.
 * Macie publishes every new finding (and periodic updates for recurring ones,
 * at the session's `findingPublishingFrequency`) to the account's default
 * EventBridge bus (source `aws.macie`, detail-type `Macie Finding`); this
 * subscribes the host Function to those events so it can triage, notify, or
 * quarantine the affected S3 objects.
 *
 * Macie 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 High-Severity Sensitive Data
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * export default AlertFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     yield* AWS.Macie2.consumeFindings(
 *       { categories: ["CLASSIFICATION"], severities: ["High"] },
 *       (events) =>
 *         Stream.runForEach(events, (event) =>
 *           Effect.logError(
 *             `Macie: ${event.detail.type} in ${event.detail.accountId}`,
 *           ),
 *         ),
 *     );
 *     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 ?? "MacieFindings",
    {
      source: ["aws.macie"],
      "detail-type": ["Macie Finding"],
      ...(props.types !== undefined ||
      props.categories !== undefined ||
      props.severities !== undefined
        ? {
            detail: {
              ...(props.types !== undefined ? { type: [...props.types] } : {}),
              ...(props.categories !== undefined ? { category: [...props.categories] } : {}),
              ...(props.severities !== undefined
                ? { severity: { description: [...props.severities] } }
                : {}),
            },
          }
        : {}),
    },
    { description: props.description, state: props.state },
    process,
  );