sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ GuardDuty/ ThreatIntelSet.ts

import * as guardduty from "@distilled.cloud/aws/guardduty";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/** File format of the hosted threat intelligence list. */
export type ThreatIntelSetFormat =
  | "TXT"
  | "STIX"
  | "OTX_CSV"
  | "ALIEN_VAULT"
  | "PROOF_POINT"
  | "FIRE_EYE";

export interface ThreatIntelSetProps {
  /**
   * ID of the detector the threat intel set belongs to. Changing this
   * replaces the set.
   */
  detectorId: string;

  /**
   * Display name of the threat intel set. If omitted, a unique name is
   * generated. Updatable in place.
   */
  name?: string;

  /**
   * Format of the file hosting the threat list. Changing this replaces the
   * set.
   */
  format: ThreatIntelSetFormat;

  /**
   * S3 URI of the file containing known malicious IP addresses, e.g.
   * `https://s3.amazonaws.com/my-bucket/threats.txt`. Updatable in place.
   */
  location: string;

  /**
   * Whether GuardDuty actively uses the list. Traffic to/from listed IPs
   * generates findings while active. Updatable in place.
   * @default true
   */
  activate?: boolean;

  /**
   * Account ID of the bucket owner hosting the list (guards against bucket
   * squatting).
   */
  expectedBucketOwner?: string;

  /**
   * Tags applied to the threat intel set. Alchemy ownership tags are merged
   * in automatically.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface ThreatIntelSet extends Resource<
  "AWS.GuardDuty.ThreatIntelSet",
  ThreatIntelSetProps,
  {
    /** ID of the detector the set belongs to. */
    detectorId: string;
    /** The auto-generated threat intel set ID. */
    threatIntelSetId: string;
    /** ARN of the threat intel set. */
    threatIntelSetArn: string;
    /** Display name of the set. */
    name: string;
    /** File format of the hosted list. */
    format: string;
    /** S3 URI of the hosted list. */
    location: string;
    /** Current status (`ACTIVE`, `INACTIVE`, `ACTIVATING`, `ERROR`, …). */
    status: string;
  },
  never,
  Providers
> {}

/**
 * A GuardDuty threat intelligence set — an S3-hosted list of known malicious
 * IP addresses that GuardDuty generates findings for. The list file must
 * exist in S3 before activation; name, location, and activation are
 * updatable in place, while format changes replace the set.
 *
 * ### Custom Threat Intelligence
 * **Example:** Feed a custom threat list
 * ```typescript
 * const detector = yield* AWS.GuardDuty.Detector("Detector", {});
 * const threats = yield* AWS.GuardDuty.ThreatIntelSet("BadIPs", {
 *   detectorId: detector.detectorId,
 *   format: "TXT",
 *   location: "https://s3.amazonaws.com/my-security-bucket/threats.txt",
 * });
 * ```
 */
const ThreatIntelSetResource = Resource<ThreatIntelSet>("AWS.GuardDuty.ThreatIntelSet");

export { ThreatIntelSetResource as ThreatIntelSet };

const threatIntelSetArn = (
  region: string,
  accountId: string,
  detectorId: string,
  threatIntelSetId: string,
) =>
  `arn:aws:guardduty:${region}:${accountId}:detector/${detectorId}/threatintelset/${threatIntelSetId}`;

/** Statuses that count as "the set is (becoming) active". */
const ACTIVE_STATUSES = ["ACTIVE", "ACTIVATING"];

export const ThreatIntelSetProvider = () =>
  Provider.effect(
    ThreatIntelSetResource,
    Effect.gen(function* () {
      const toName = (id: string, props: { name?: string }) =>
        props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 64 });

      const getSet = (detectorId: string, threatIntelSetId: string) =>
        guardduty
          .getThreatIntelSet({
            DetectorId: detectorId,
            ThreatIntelSetId: threatIntelSetId,
          })
          .pipe(Effect.catchTag("BadRequestException", () => Effect.undefined));

      // Recover the set id after state loss by matching the deterministic
      // name across the detector's threat intel sets.
      const findByName = Effect.fn(function* (detectorId: string, name: string) {
        const pages = yield* guardduty.listThreatIntelSets
          .pages({ DetectorId: detectorId })
          .pipe(Stream.runCollect);
        for (const threatIntelSetId of Array.from(pages).flatMap(
          (page) => page.ThreatIntelSetIds ?? [],
        )) {
          const s = yield* getSet(detectorId, threatIntelSetId);
          if (s?.Name === name && s.Status !== "DELETE_PENDING") {
            return { threatIntelSetId, set: s };
          }
        }
        return undefined;
      });

      const buildAttrs = Effect.fn(function* (
        detectorId: string,
        threatIntelSetId: string,
        s: guardduty.GetThreatIntelSetResponse,
      ) {
        const { accountId, region } = yield* AWSEnvironment.current;
        return {
          detectorId,
          threatIntelSetId,
          threatIntelSetArn: threatIntelSetArn(region, accountId, detectorId, threatIntelSetId),
          name: s.Name,
          format: s.Format,
          location: s.Location,
          status: s.Status,
        };
      });

      return {
        stables: ["detectorId", "threatIntelSetId", "threatIntelSetArn"],
        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          if (olds.detectorId !== news.detectorId || olds.format !== news.format) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const detectorId = output?.detectorId ?? olds?.detectorId;
          if (!detectorId) return undefined;
          let threatIntelSetId = output?.threatIntelSetId;
          let set = threatIntelSetId ? yield* getSet(detectorId, threatIntelSetId) : undefined;
          if (!set) {
            const found = yield* findByName(detectorId, yield* toName(id, olds ?? {}));
            if (!found) return undefined;
            ({ threatIntelSetId, set } = found);
          }
          const attrs = yield* buildAttrs(detectorId, threatIntelSetId!, set);
          return (yield* hasAlchemyTags(id, set.Tags)) ? attrs : Unowned(attrs);
        }),
        list: () =>
          Effect.gen(function* () {
            const { DetectorIds } = yield* guardduty.listDetectors({});
            const out: ThreatIntelSet["Attributes"][] = [];
            for (const detectorId of DetectorIds ?? []) {
              const pages = yield* guardduty.listThreatIntelSets
                .pages({ DetectorId: detectorId })
                .pipe(Stream.runCollect);
              for (const threatIntelSetId of Array.from(pages).flatMap(
                (page) => page.ThreatIntelSetIds ?? [],
              )) {
                const s = yield* getSet(detectorId, threatIntelSetId);
                if (s) {
                  out.push(yield* buildAttrs(detectorId, threatIntelSetId, s));
                }
              }
            }
            return out;
          }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const detectorId = news.detectorId;
          const name = yield* toName(id, news);
          const desiredActivate = news.activate ?? true;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — output.threatIntelSetId is only a cache; fall back
          // to a name search so a crash-and-retry converges.
          let threatIntelSetId = output?.threatIntelSetId;
          let live = threatIntelSetId ? yield* getSet(detectorId, threatIntelSetId) : undefined;
          if (!live) {
            const found = yield* findByName(detectorId, name);
            if (found) ({ threatIntelSetId, set: live } = found);
          }

          if (!live || !threatIntelSetId) {
            // 2. ENSURE — create with tags applied inline.
            const created = yield* guardduty.createThreatIntelSet({
              DetectorId: detectorId,
              Name: name,
              Format: news.format,
              Location: news.location,
              Activate: desiredActivate,
              ExpectedBucketOwner: news.expectedBucketOwner,
              Tags: desiredTags,
            });
            threatIntelSetId = created.ThreatIntelSetId;
          } else {
            // 3. SYNC settings — observed ↔ desired.
            const observedActive = ACTIVE_STATUSES.includes(live.Status);
            const drift =
              live.Name !== name ||
              live.Location !== news.location ||
              observedActive !== desiredActivate;
            if (drift) {
              yield* guardduty.updateThreatIntelSet({
                DetectorId: detectorId,
                ThreatIntelSetId: threatIntelSetId,
                Name: name,
                Location: news.location,
                Activate: desiredActivate,
                ExpectedBucketOwner: news.expectedBucketOwner,
              });
            }

            // 3b. SYNC tags — diff against OBSERVED cloud tags.
            const { accountId, region } = yield* AWSEnvironment.current;
            const arn = threatIntelSetArn(region, accountId, detectorId, threatIntelSetId);
            const { upsert, removed } = diffTags(tagRecord(live.Tags), desiredTags);
            if (upsert.length > 0) {
              yield* guardduty.tagResource({
                ResourceArn: arn,
                Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
              });
            }
            if (removed.length > 0) {
              yield* guardduty.untagResource({
                ResourceArn: arn,
                TagKeys: removed,
              });
            }
          }

          // 4. RETURN fresh attributes.
          const final = yield* guardduty.getThreatIntelSet({
            DetectorId: detectorId,
            ThreatIntelSetId: threatIntelSetId,
          });
          yield* session.note(`${detectorId}/${threatIntelSetId}`);
          return yield* buildAttrs(detectorId, threatIntelSetId, final);
        }),
        delete: Effect.fn(function* ({ output }) {
          // Idempotent — the set (or its whole detector) may already be
          // gone; both surface as BadRequestException.
          yield* guardduty
            .deleteThreatIntelSet({
              DetectorId: output.detectorId,
              ThreatIntelSetId: output.threatIntelSetId,
            })
            .pipe(Effect.catchTag("BadRequestException", () => Effect.void));
        }),
      };
    }),
  );