sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ SecurityCenter/ SecurityHealthAnalyticsSettingsCustomModule.ts

import * as scc from "@distilled.cloud/gcp/securitycenter_v1";
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 * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { GcpEnvironment } from "../Environment.ts";
import { createInternalLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  collectPages,
  encodeOwnership,
  findOwned,
  hasOwnershipMarker,
  jsonEqual,
  lastSegment,
  ownedByAlchemy,
  parseOwnership,
  projectOf,
  replaceOn,
  sameText,
  shaDisplayNameOf,
  shaSettingsParent,
  updateMaskOf,
} from "./internal.ts";

export type SecurityHealthAnalyticsEnablementState =
  | "ENABLEMENT_STATE_UNSPECIFIED"
  | "ENABLED"
  | "DISABLED"
  | "INHERITED";

export type SecurityHealthAnalyticsCloudProvider =
  | "CLOUD_PROVIDER_UNSPECIFIED"
  | "GOOGLE_CLOUD_PLATFORM"
  | "AMAZON_WEB_SERVICES"
  | "MICROSOFT_AZURE";

export type SecurityHealthAnalyticsSeverity =
  | "SEVERITY_UNSPECIFIED"
  | "CRITICAL"
  | "HIGH"
  | "MEDIUM"
  | "LOW";

export type Expr = {
  /** CEL expression. */
  expression?: string;
  /** Short title. */
  title?: string;
  /** Human-readable description. */
  description?: string;
  /** Source location of the expression. */
  location?: string;
};

export type CustomOutputProperty = {
  /** Property name. */
  name?: string;
  /** CEL expression that produces the property value. */
  valueExpression?: Expr;
};

export type CustomConfig = {
  /** CEL predicate that selects resources. */
  predicate?: Expr;
  /** Resource types this module inspects. */
  resourceSelector?: {
    /** Fully-qualified resource type names. */
    resourceTypes?: string[];
  };
  /** Finding severity. */
  severity?: SecurityHealthAnalyticsSeverity;
  /**
   * Finding description. Alchemy ownership is stored in a `[alchemy …]`
   * prefix here (custom modules have no labels) and stripped from
   * attributes.
   */
  description?: string;
  /** Recommended next steps. */
  recommendation?: string;
  /** Extra properties written onto findings. */
  customOutput?: {
    properties?: CustomOutputProperty[];
  };
};

export type SecurityHealthAnalyticsSettingsCustomModuleProps = {
  /**
   * Module id (the `{customModule}` segment of
   * `projects/{project}/securityHealthAnalyticsSettings/customModules/{customModule}`).
   * Server-assigned on create. Supply it to target an existing module.
   * Immutable — changing it replaces the module.
   */
  moduleId?: string;
  /**
   * Display name. Becomes the finding category. Must start with an
   * uppercase letter, contain only letters, digits, or underscores, and
   * be at most 128 characters. Immutable — changing it replaces the
   * module.
   */
  displayName?: string;
  /**
   * Enablement state at this parent.
   * @default "ENABLED"
   */
  enablementState?: SecurityHealthAnalyticsEnablementState;
  /**
   * Detection configuration. Required on create.
   */
  customConfig: CustomConfig;
  /**
   * Cloud provider this module applies to.
   */
  cloudProvider?: SecurityHealthAnalyticsCloudProvider;
};

export type SecurityHealthAnalyticsSettingsCustomModule = Resource<
  "GCP.SecurityCenter.SecurityHealthAnalyticsSettingsCustomModule",
  SecurityHealthAnalyticsSettingsCustomModuleProps,
  {
    /** Full resource name `projects/{project}/securityHealthAnalyticsSettings/customModules/{customModule}`. */
    name: string;
    /** Module id (last path segment). */
    moduleId: string;
    /** Project id. */
    project: string;
    /** Display name. */
    displayName: string | undefined;
    /** Enablement state. */
    enablementState: string | undefined;
    /** Detection configuration with the Alchemy ownership prefix stripped. */
    customConfig: CustomConfig | undefined;
    /** Cloud provider. */
    cloudProvider: string | undefined;
    /** Ancestor module this one inherits from, if any. */
    ancestorModule: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
    /** Last editor email. */
    lastEditor: string | undefined;
  },
  never,
  Providers
>;

/**
 * A project-scoped Security Health Analytics custom module.
 *
 * Custom modules have no labels field — Alchemy stamps ownership into
 * `customConfig.description` so `list` / nuke can find them. Module id
 * and display name are identity (the id is server-assigned). Enablement
 * and custom config update in place.
 *
 * ### Creating a Custom Module
 * **Example:** Always-true compute instance check
 * ```typescript
 * const module = yield* GCP.SecurityCenter.SecurityHealthAnalyticsSettingsCustomModule(
 *   "AlwaysTrue",
 *   {
 *     displayName: "AlchemyAlwaysTrue",
 *     customConfig: {
 *       predicate: { expression: 'resource.name == "alchemy-nonexistent"' },
 *       resourceSelector: {
 *         resourceTypes: ["compute.googleapis.com/Instance"],
 *       },
 *       severity: "LOW",
 *       description: "always true",
 *       recommendation: "n/a",
 *     },
 *   },
 * );
 * ```
 *
 * ### Updating a Custom Module
 * **Example:** Disable the module
 * ```typescript
 * const module = yield* GCP.SecurityCenter.SecurityHealthAnalyticsSettingsCustomModule(
 *   "AlwaysTrue",
 *   {
 *     enablementState: "DISABLED",
 *     displayName: "AlchemyAlwaysTrue",
 *     customConfig: {
 *       predicate: { expression: 'resource.name == "alchemy-nonexistent"' },
 *       resourceSelector: {
 *         resourceTypes: ["compute.googleapis.com/Instance"],
 *       },
 *       severity: "LOW",
 *     },
 *   },
 * );
 * ```
 *
 * @resource
 * @category SecurityCenter
 */
export const SecurityHealthAnalyticsSettingsCustomModule =
  Resource<SecurityHealthAnalyticsSettingsCustomModule>(
    "GCP.SecurityCenter.SecurityHealthAnalyticsSettingsCustomModule",
  );

export class SecurityHealthAnalyticsSettingsCustomModuleNotResolved extends Data.TaggedError(
  "GCP.SecurityCenter.SecurityHealthAnalyticsSettingsCustomModuleNotResolved",
)<{
  resourceName: string;
}> {}

const resourceName = (project: string, moduleId: string) =>
  `projects/${project}/securityHealthAnalyticsSettings/customModules/${moduleId}`;

const customConfigOf = (
  config: scc.GoogleCloudSecuritycenterV1CustomConfig | undefined,
  stripOwnership: boolean,
): CustomConfig | undefined => {
  if (config === undefined) return undefined;
  const description = stripOwnership ? parseOwnership(config.description).text : config.description;
  return {
    predicate: config.predicate,
    resourceSelector: config.resourceSelector,
    severity: config.severity as SecurityHealthAnalyticsSeverity | undefined,
    description,
    recommendation: config.recommendation,
    customOutput: config.customOutput,
  };
};

const desiredCustomConfig = (
  config: CustomConfig,
  ownership: Record<string, string>,
): scc.GoogleCloudSecuritycenterV1CustomConfig => ({
  ...config,
  description: encodeOwnership(ownership, config.description),
});

const toAttrs = (
  module: scc.GoogleCloudSecuritycenterV1SecurityHealthAnalyticsCustomModule,
  project: string,
) => {
  const name = module.name ?? "";
  return {
    name,
    moduleId: lastSegment(name),
    project: projectOf(name) || project,
    displayName: module.displayName,
    enablementState: module.enablementState,
    customConfig: customConfigOf(module.customConfig, true),
    cloudProvider: module.cloudProvider,
    ancestorModule: module.ancestorModule,
    updateTime: module.updateTime,
    lastEditor: module.lastEditor,
  };
};

const getByName = (name: string) =>
  name.length === 0
    ? Effect.undefined
    : scc
        .getProjectsSecurityHealthAnalyticsSettingsCustomModules({ name })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listModules = (project: string) =>
  collectPages(
    scc.listProjectsSecurityHealthAnalyticsSettingsCustomModules.pages({
      parent: shaSettingsParent(`projects/${project}`),
      pageSize: 100,
    }),
    (page) => page.securityHealthAnalyticsCustomModules,
  ).pipe(
    Effect.catchTag("NotFound", () =>
      Effect.succeed([] as scc.GoogleCloudSecuritycenterV1SecurityHealthAnalyticsCustomModule[]),
    ),
  );

const observe = (project: string, id: string, name: string) =>
  Effect.gen(function* () {
    const existing = yield* getByName(name);
    if (existing !== undefined) return existing;
    const items = yield* listModules(project);
    return yield* findOwned(items, (item) => item.customConfig?.description, id);
  });

export const SecurityHealthAnalyticsSettingsCustomModuleProvider = () =>
  Provider.succeed(SecurityHealthAnalyticsSettingsCustomModule, {
    stables: ["name", "moduleId", "project", "displayName", "ancestorModule"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      return (
        replaceOn(olds?.moduleId ?? output?.moduleId, news.moduleId) ??
        replaceOn(olds?.displayName ?? output?.displayName, news.displayName)
      );
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const moduleId = olds?.moduleId ?? output?.moduleId;
      const name = output?.name ?? (moduleId ? resourceName(env.project, moduleId) : "");
      const existing = yield* observe(env.project, id, name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* ownedByAlchemy(id, existing.customConfig?.description))
        ? attrs
        : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const items = yield* listModules(env.project);
        return items
          .filter((module) => hasOwnershipMarker(module.customConfig?.description))
          .map((module) => toAttrs(module, env.project));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const parent = shaSettingsParent(`projects/${env.project}`);
      const moduleId = news.moduleId ?? output?.moduleId;
      const name = output?.name ?? (moduleId ? resourceName(env.project, moduleId) : "");
      const ownership = yield* createInternalLabels(id);
      const customConfig = desiredCustomConfig(news.customConfig, ownership);
      const enablementState = news.enablementState ?? "ENABLED";
      const displayName =
        news.displayName ??
        shaDisplayNameOf(
          yield* createPhysicalName({
            id,
            maxLength: 63,
            lowercase: true,
          }),
        );
      const body: scc.GoogleCloudSecuritycenterV1SecurityHealthAnalyticsCustomModule = {
        displayName,
        enablementState,
        customConfig,
        cloudProvider: news.cloudProvider,
      };

      let current = yield* observe(env.project, id, name);

      if (current === undefined) {
        current = yield* scc.createProjectsSecurityHealthAnalyticsSettingsCustomModules({
          parent,
          body,
        });
      }

      if (current === undefined) {
        return yield* new SecurityHealthAnalyticsSettingsCustomModuleNotResolved({
          resourceName: name || parent,
        });
      }

      const currentName = current.name ?? name;
      const enablementChanged = !sameText(current.enablementState, enablementState);
      const configChanged = !jsonEqual(
        {
          ...current.customConfig,
          description: current.customConfig?.description,
        },
        customConfig,
      );
      const updateMask = updateMaskOf(
        enablementChanged ? "enablement_state" : undefined,
        configChanged ? "custom_config" : undefined,
      );

      if (updateMask.length > 0) {
        current = yield* scc.patchProjectsSecurityHealthAnalyticsSettingsCustomModules({
          name: currentName,
          updateMask,
          body: {
            enablementState,
            customConfig,
          },
        });
      }

      return toAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* scc
        .deleteProjectsSecurityHealthAnalyticsSettingsCustomModules({
          name: output.name,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });