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

import * as guardduty from "@distilled.cloud/aws/guardduty";
import { Unowned } from "alchemy/AdoptPolicy";
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 { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/**
 * How frequently GuardDuty exports updated findings.
 */
export type FindingPublishingFrequency = "FIFTEEN_MINUTES" | "ONE_HOUR" | "SIX_HOURS";

export interface DetectorProps {
  /**
   * Whether the detector is enabled. A disabled detector stops analyzing data
   * sources but is not deleted.
   * @default true
   */
  enable?: boolean;

  /**
   * How frequently GuardDuty publishes updated findings to CloudWatch Events.
   * @default "SIX_HOURS"
   */
  findingPublishingFrequency?: FindingPublishingFrequency;

  /**
   * Tags applied to the detector. Alchemy ownership tags are merged in
   * automatically so the detector can be recognized on subsequent runs.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface Detector extends Resource<
  "AWS.GuardDuty.Detector",
  DetectorProps,
  {
    /** The auto-generated detector ID (unique per account/region). */
    detectorId: string;
    /** ARN of the detector — the IAM resource for detector-scoped actions. */
    detectorArn: string;
    /** Current status of the detector (`ENABLED` / `DISABLED`). */
    status: string | undefined;
    /** The effective finding-publishing frequency. */
    findingPublishingFrequency: string | undefined;
  },
  never,
  Providers
> {}

/**
 * A GuardDuty detector — the account/region singleton that enables Amazon
 * GuardDuty threat detection. Only one detector can exist per region, so this
 * resource is a capture-and-restore singleton: adopting a pre-existing detector
 * that Alchemy did not create requires `--adopt`.
 *
 * ### Enabling GuardDuty
 * **Example:** Enable with default settings
 * ```typescript
 * const detector = yield* GuardDuty.Detector("Detector", {});
 * ```
 *
 * **Example:** Frequent finding publishing
 * ```typescript
 * const detector = yield* GuardDuty.Detector("Detector", {
 *   enable: true,
 *   findingPublishingFrequency: "FIFTEEN_MINUTES",
 *   tags: { team: "security" },
 * });
 * ```
 */
const DetectorResource = Resource<Detector>("AWS.GuardDuty.Detector");

export { DetectorResource as Detector };

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

const buildAttrs = Effect.fn(function* (detectorId: string, d: guardduty.GetDetectorResponse) {
  const { accountId, region } = yield* AWSEnvironment.current;
  return {
    detectorId,
    detectorArn: detectorArn(region, accountId, detectorId),
    status: d.Status,
    findingPublishingFrequency: d.FindingPublishingFrequency,
  };
});

export const DetectorProvider = () =>
  Provider.effect(
    DetectorResource,
    Effect.gen(function* () {
      // Resolve the first (only) detector in the current region, if any.
      const firstDetectorId = guardduty
        .listDetectors({})
        .pipe(Effect.map((r) => r.DetectorIds?.[0]));

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

      return {
        read: Effect.fn(function* ({ id, output }) {
          const detectorId = output?.detectorId ?? (yield* firstDetectorId);
          if (!detectorId) return undefined;
          const d = yield* getDetector(detectorId);
          if (!d) return undefined;
          const attrs = yield* buildAttrs(detectorId, d);
          return (yield* hasAlchemyTags(id, d.Tags)) ? attrs : Unowned(attrs);
        }),

        // GuardDuty allows at most one detector per account/region. Enumerate
        // every detector and hydrate its full attributes.
        list: () =>
          Effect.gen(function* () {
            const { DetectorIds } = yield* guardduty.listDetectors({});
            const out: {
              detectorId: string;
              detectorArn: string;
              status: string | undefined;
              findingPublishingFrequency: string | undefined;
            }[] = [];
            for (const detectorId of DetectorIds ?? []) {
              const d = yield* getDetector(detectorId);
              if (d) out.push(yield* buildAttrs(detectorId, d));
            }
            return out;
          }),

        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredEnable = news.enable ?? true;

          // 1. OBSERVE — cloud state is authoritative; output is only an id cache.
          let detectorId = output?.detectorId ?? (yield* firstDetectorId);
          let live = detectorId ? yield* getDetector(detectorId) : undefined;

          if (!detectorId || !live) {
            // 2. ENSURE — create the detector with tags applied inline.
            const created = yield* guardduty.createDetector({
              Enable: desiredEnable,
              FindingPublishingFrequency: news.findingPublishingFrequency,
              Tags: desiredTags,
            });
            detectorId = created.DetectorId!;
          } else {
            // 3. SYNC settings — observed ↔ desired.
            const observedEnabled = live.Status === "ENABLED";
            const settingsChanged =
              observedEnabled !== desiredEnable ||
              (news.findingPublishingFrequency !== undefined &&
                news.findingPublishingFrequency !== live.FindingPublishingFrequency);
            if (settingsChanged) {
              yield* guardduty.updateDetector({
                DetectorId: detectorId,
                Enable: desiredEnable,
                FindingPublishingFrequency: news.findingPublishingFrequency,
              });
            }

            // 3b. SYNC tags — diff against OBSERVED cloud tags.
            const { upsert, removed } = diffTags(tagRecord(live.Tags), desiredTags);
            const arn = detectorArn(region, accountId, detectorId);
            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.getDetector({
            DetectorId: detectorId,
          });
          yield* session.note(detectorId);
          return yield* buildAttrs(detectorId, final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* guardduty
            .deleteDetector({ DetectorId: output.detectorId })
            .pipe(Effect.catchTag("BadRequestException", () => Effect.void));
        }),
      };
    }),
  );