import * as securityhub from "@distilled.cloud/aws/securityhub";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export interface InsightProps {
/**
* Name of the insight. If omitted, a unique name is generated. Updatable
* in place.
*/
name?: string;
/**
* The finding filters the insight aggregates over, e.g.
* `{ SeverityLabel: [{ Value: "CRITICAL", Comparison: "EQUALS" }] }`.
* Updatable in place.
*/
filters: securityhub.AwsSecurityFindingFilters;
/**
* The finding attribute results are grouped by, e.g. `ResourceId`,
* `SeverityLabel`, `AwsAccountId`. Updatable in place.
*/
groupByAttribute: string;
}
/** @resource */
export interface Insight extends Resource<
"AWS.SecurityHub.Insight",
InsightProps,
{
/** ARN of the insight (its identity). */
insightArn: string;
/** Name of the insight. */
name: string;
/** The attribute results are grouped by. */
groupByAttribute: string;
},
never,
Providers
> {}
/**
* A Security Hub custom insight — a saved finding query grouped by an
* attribute. Read its aggregated results at runtime with the
* {@link GetInsightResults} binding.
*
* ### Creating an Insight
* **Example:** Critical Findings by Resource
* ```typescript
* const insight = yield* AWS.SecurityHub.Insight("CriticalByResource", {
* filters: {
* SeverityLabel: [{ Value: "CRITICAL", Comparison: "EQUALS" }],
* RecordState: [{ Value: "ACTIVE", Comparison: "EQUALS" }],
* },
* groupByAttribute: "ResourceId",
* });
* ```
*
* **Example:** Read Insight Results at Runtime
* ```typescript
* const getInsightResults = yield* AWS.SecurityHub.GetInsightResults();
* const { InsightResults } = yield* getInsightResults({
* InsightArn: insight.insightArn,
* });
* ```
*/
const InsightResource = Resource<Insight>("AWS.SecurityHub.Insight");
export { InsightResource as Insight };
export const InsightProvider = () =>
Provider.effect(
InsightResource,
Effect.gen(function* () {
const toName = (id: string, props: { name?: string }) =>
props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 128 });
const getInsight = (arn: string) =>
securityhub.getInsights({ InsightArns: [arn] }).pipe(
Effect.map((r) => r.Insights?.[0]),
Effect.catchTags({
ResourceNotFoundException: () => Effect.undefined,
// The whole hub may be disabled — the insight is gone too.
InvalidAccessException: () => Effect.undefined,
// Security Hub reports an unknown insight ARN as invalid input.
InvalidInputException: () => Effect.undefined,
}),
);
const listInsights = securityhub.getInsights.pages({}).pipe(
Stream.runCollect,
Effect.map((pages) => Array.from(pages).flatMap((page) => page.Insights ?? [])),
Effect.catchTag("InvalidAccessException", () =>
Effect.succeed([] as securityhub.Insight[]),
),
);
const buildAttrs = (i: securityhub.Insight) => ({
insightArn: i.InsightArn!,
name: i.Name ?? "",
groupByAttribute: i.GroupByAttribute ?? "",
});
return {
stables: ["insightArn"],
read: Effect.fn(function* ({ id, olds, output }) {
if (output?.insightArn) {
const live = yield* getInsight(output.insightArn);
return live ? buildAttrs(live) : undefined;
}
// No prior state — find by (deterministic) name. Insights cannot be
// tagged; the generated name embeds the app/stage physical-name
// hash, so a match is ours.
const name = yield* toName(id, olds ?? {});
const all = yield* listInsights;
const match = all.find((i) => i.Name === name);
return match ? buildAttrs(match) : undefined;
}),
list: () => listInsights.pipe(Effect.map((all) => all.map(buildAttrs))),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = yield* toName(id, news);
// 1. OBSERVE — by cached ARN first, then by name.
let live: securityhub.Insight | undefined = output?.insightArn
? yield* getInsight(output.insightArn)
: undefined;
if (!live) {
const all = yield* listInsights;
live = all.find((i) => i.Name === name);
}
let final: securityhub.Insight;
if (!live) {
// 2. ENSURE.
const { InsightArn } = yield* securityhub.createInsight({
Name: name,
Filters: news.filters,
GroupByAttribute: news.groupByAttribute,
});
// The read-after-create may lag — fall back to the desired state.
final = (yield* getInsight(InsightArn)) ?? {
InsightArn,
Name: name,
Filters: news.filters,
GroupByAttribute: news.groupByAttribute,
};
} else if (
live.Name !== name ||
live.GroupByAttribute !== news.groupByAttribute ||
JSON.stringify(live.Filters) !== JSON.stringify(news.filters)
) {
// 3. SYNC — observed ↔ desired.
const arn = live.InsightArn!;
yield* securityhub.updateInsight({
InsightArn: arn,
Name: name,
Filters: news.filters,
GroupByAttribute: news.groupByAttribute,
});
final = (yield* getInsight(arn)) ?? {
InsightArn: arn,
Name: name,
Filters: news.filters,
GroupByAttribute: news.groupByAttribute,
};
} else {
final = live;
}
// 4. RETURN fresh attributes.
yield* session.note(final.InsightArn!);
return buildAttrs(final);
}),
delete: Effect.fn(function* ({ output }) {
// Idempotent — the insight (or the whole hub) may already be gone.
yield* securityhub.deleteInsight({ InsightArn: output.insightArn }).pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.void,
InvalidAccessException: () => Effect.void,
InvalidInputException: () => Effect.void,
}),
);
}),
};
}),
);