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

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

/** Whether the automation rule is applied to new and updated findings. */
export type RuleStatus = "ENABLED" | "DISABLED";

export interface AutomationRuleProps {
  /**
   * Name of the rule. If omitted, a unique name is generated. Updatable in
   * place.
   */
  ruleName?: string;

  /**
   * Description of the rule. Updatable in place.
   */
  description: string;

  /**
   * Order in which rules are applied (1 first; lower wins on conflicts).
   * Updatable in place.
   */
  ruleOrder: number;

  /**
   * Whether the rule is applied to findings: `ENABLED` or `DISABLED`.
   * Updatable in place.
   * @default "ENABLED"
   */
  ruleStatus?: RuleStatus;

  /**
   * Whether matching findings stop evaluating further rules. Updatable in
   * place.
   * @default false
   */
  isTerminal?: boolean;

  /**
   * The criteria findings are matched against, e.g.
   * `{ SeverityLabel: [{ Value: "INFORMATIONAL", Comparison: "EQUALS" }] }`.
   * Updatable in place.
   */
  criteria: securityhub.AutomationRulesFindingFilters;

  /**
   * The updates applied to matching findings, e.g.
   * `[{ Type: "FINDING_FIELDS_UPDATE", FindingFieldsUpdate: { Workflow: { Status: "SUPPRESSED" } } }]`.
   * Updatable in place.
   */
  actions: securityhub.AutomationRulesAction[];

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

/** @resource */
export interface AutomationRule extends Resource<
  "AWS.SecurityHub.AutomationRule",
  AutomationRuleProps,
  {
    /** ARN of the automation rule (its identity). */
    ruleArn: string;
    /** Name of the rule. */
    ruleName: string;
    /** Evaluation order of the rule. */
    ruleOrder: number | undefined;
    /** Whether the rule is applied to findings. */
    ruleStatus: string | undefined;
    /** Whether matching findings stop evaluating further rules. */
    isTerminal: boolean | undefined;
  },
  never,
  Providers
> {}

/**
 * A Security Hub automation rule — automatically updates findings that match
 * its criteria (suppress, change severity, add notes) as they are ingested.
 *
 * ### Automating Finding Triage
 * **Example:** Suppress Informational Findings
 * ```typescript
 * const rule = yield* AWS.SecurityHub.AutomationRule("SuppressInfo", {
 *   description: "Suppress informational findings",
 *   ruleOrder: 1,
 *   criteria: {
 *     SeverityLabel: [{ Value: "INFORMATIONAL", Comparison: "EQUALS" }],
 *   },
 *   actions: [{
 *     Type: "FINDING_FIELDS_UPDATE",
 *     FindingFieldsUpdate: { Workflow: { Status: "SUPPRESSED" } },
 *   }],
 * });
 * ```
 *
 * **Example:** Escalate Production Findings
 * ```typescript
 * const rule = yield* AWS.SecurityHub.AutomationRule("EscalateProd", {
 *   description: "Raise severity of findings on production resources",
 *   ruleOrder: 2,
 *   isTerminal: true,
 *   criteria: {
 *     ResourceTags: [{ Key: "env", Value: "prod", Comparison: "EQUALS" }],
 *   },
 *   actions: [{
 *     Type: "FINDING_FIELDS_UPDATE",
 *     FindingFieldsUpdate: { Severity: { Label: "CRITICAL" } },
 *   }],
 * });
 * ```
 */
const AutomationRuleResource = Resource<AutomationRule>("AWS.SecurityHub.AutomationRule");

export { AutomationRuleResource as AutomationRule };

export const AutomationRuleProvider = () =>
  Provider.effect(
    AutomationRuleResource,
    Effect.gen(function* () {
      const toName = (id: string, props: { ruleName?: string }) =>
        props.ruleName
          ? Effect.succeed(props.ruleName)
          : createPhysicalName({ id, maxLength: 128 });

      const getRule = (arn: string) =>
        securityhub.batchGetAutomationRules({ AutomationRulesArns: [arn] }).pipe(
          Effect.map((r) => r.Rules?.[0]),
          Effect.catchTags({
            ResourceNotFoundException: () => Effect.undefined,
            InvalidAccessException: () => Effect.undefined,
          }),
        );

      // `ListAutomationRules` is not modeled as paginated in the Smithy spec
      // (no `.pages` helper) — page manually, bounded (accounts are limited
      // to 100 rules).
      const listRules = Effect.gen(function* () {
        const out: securityhub.AutomationRulesMetadata[] = [];
        let nextToken: string | undefined;
        for (let i = 0; i < 10; i++) {
          const page = yield* securityhub.listAutomationRules({
            MaxResults: 100,
            NextToken: nextToken,
          });
          out.push(...(page.AutomationRulesMetadata ?? []));
          nextToken = page.NextToken;
          if (!nextToken) break;
        }
        return out;
      }).pipe(
        Effect.catchTag("InvalidAccessException", () =>
          Effect.succeed([] as securityhub.AutomationRulesMetadata[]),
        ),
      );

      const readTags = (arn: string) =>
        securityhub.listTagsForResource({ ResourceArn: arn }).pipe(
          Effect.map((r) => tagRecord(r.Tags)),
          Effect.orElseSucceed(() => ({})),
        );

      const buildAttrs = (r: {
        RuleArn?: string;
        RuleName?: string;
        RuleOrder?: number;
        RuleStatus?: string;
        IsTerminal?: boolean;
      }) => ({
        ruleArn: r.RuleArn!,
        ruleName: r.RuleName ?? "",
        ruleOrder: r.RuleOrder,
        ruleStatus: r.RuleStatus,
        isTerminal: r.IsTerminal,
      });

      return {
        stables: ["ruleArn"],
        read: Effect.fn(function* ({ id, olds, output }) {
          let arn = output?.ruleArn;
          if (!arn) {
            // No prior state — find by (deterministic) name.
            const name = yield* toName(id, olds ?? {});
            const all = yield* listRules;
            arn = all.find((r) => r.RuleName === name)?.RuleArn;
          }
          if (!arn) return undefined;
          const live = yield* getRule(arn);
          if (!live) return undefined;
          const attrs = buildAttrs(live);
          const tags = yield* readTags(arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        list: () =>
          listRules.pipe(
            Effect.map((all) => all.filter((r) => r.RuleArn).map((r) => buildAttrs(r))),
          ),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* toName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — by cached ARN first, then by name.
          let arn = output?.ruleArn;
          let live = arn ? yield* getRule(arn) : undefined;
          if (!live) {
            const all = yield* listRules;
            arn = all.find((r) => r.RuleName === name)?.RuleArn;
            live = arn ? yield* getRule(arn) : undefined;
          }

          if (!live) {
            // 2. ENSURE — create with tags applied inline.
            const { RuleArn } = yield* securityhub.createAutomationRule({
              RuleName: name,
              Description: news.description,
              RuleOrder: news.ruleOrder,
              RuleStatus: news.ruleStatus ?? "ENABLED",
              IsTerminal: news.isTerminal ?? false,
              Criteria: news.criteria,
              Actions: news.actions,
              Tags: desiredTags,
            });
            arn = RuleArn!;
          } else {
            arn = live.RuleArn!;
            // 3. SYNC settings — observed ↔ desired.
            const desiredStatus = news.ruleStatus ?? "ENABLED";
            const desiredTerminal = news.isTerminal ?? false;
            const drift =
              live.RuleName !== name ||
              live.Description !== news.description ||
              live.RuleOrder !== news.ruleOrder ||
              live.RuleStatus !== desiredStatus ||
              (live.IsTerminal ?? false) !== desiredTerminal ||
              JSON.stringify(live.Criteria) !== JSON.stringify(news.criteria) ||
              JSON.stringify(live.Actions) !== JSON.stringify(news.actions);
            if (drift) {
              yield* securityhub.batchUpdateAutomationRules({
                UpdateAutomationRulesRequestItems: [
                  {
                    RuleArn: arn,
                    RuleName: name,
                    Description: news.description,
                    RuleOrder: news.ruleOrder,
                    RuleStatus: desiredStatus,
                    IsTerminal: desiredTerminal,
                    Criteria: news.criteria,
                    Actions: news.actions,
                  },
                ],
              });
            }

            // 3b. SYNC tags — diff against OBSERVED cloud tags.
            const currentTags = yield* readTags(arn);
            const { upsert, removed } = diffTags(currentTags, desiredTags);
            if (upsert.length > 0) {
              yield* securityhub.tagResource({
                ResourceArn: arn,
                Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
              });
            }
            if (removed.length > 0) {
              yield* securityhub.untagResource({
                ResourceArn: arn,
                TagKeys: removed,
              });
            }
          }

          // 4. RETURN fresh attributes.
          const final = yield* getRule(arn);
          yield* session.note(arn);
          return buildAttrs(final ?? { RuleArn: arn, RuleName: name });
        }),
        delete: Effect.fn(function* ({ output }) {
          // Idempotent — an unknown ARN comes back in
          // UnprocessedAutomationRules rather than as an error.
          yield* securityhub
            .batchDeleteAutomationRules({
              AutomationRulesArns: [output.ruleArn],
            })
            .pipe(
              Effect.catchTags({
                ResourceNotFoundException: () => Effect.void,
                InvalidAccessException: () => Effect.void,
              }),
            );
        }),
      };
    }),
  );