The best way to control Claude Code, Codex and more from any computer or phone

main
ts 289 lines 10.9 KB
Raw
1 import * as securitylake from "@distilled.cloud/aws/securitylake";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Option from "effect/Option";
8 import * as Stream from "effect/Stream";
9 import type { Providers } from "../Providers.ts";
10 import { retryWhileConflict } from "./internal.ts";
11
12 /**
13 * The Glue crawler configuration Security Lake uses to catalog the custom
14 * source's OCSF data.
15 */
16 export interface CustomLogSourceCrawlerConfiguration {
17 /**
18 * ARN of the IAM role the Glue crawler assumes. The role must be assumable
19 * by `glue.amazonaws.com` and grant access to the Security Lake bucket
20 * prefix for this source.
21 */
22 roleArn: string;
23 }
24
25 /**
26 * The AWS identity (principal + external ID) the custom-source provider uses
27 * to write data into the data lake.
28 */
29 export interface CustomLogSourceProviderIdentity {
30 /** The AWS account ID (or principal) of the log provider. */
31 principal: string;
32 /** The external ID the provider must present when assuming the role. */
33 externalId: string;
34 }
35
36 export interface CustomLogSourceProps {
37 /**
38 * Name of the custom log source. Must be unique per account/Region.
39 * If omitted, a unique physical name is generated from the app, stage,
40 * and logical ID. Changing this replaces the source.
41 */
42 sourceName?: string;
43
44 /**
45 * The version of the custom source schema. Changing this replaces the
46 * source.
47 * @default - Security Lake assigns a version
48 */
49 sourceVersion?: string;
50
51 /**
52 * The Open Cybersecurity Schema Framework (OCSF) event classes the source
53 * emits (e.g. `FILE_ACTIVITY`, `DNS_ACTIVITY`). Changing this replaces the
54 * source.
55 */
56 eventClasses?: string[];
57
58 /**
59 * The Glue crawler configuration for cataloging the source's data.
60 * Changing this replaces the source.
61 */
62 crawlerConfiguration: CustomLogSourceCrawlerConfiguration;
63
64 /**
65 * The AWS identity of the provider that writes this source's data.
66 * Changing this replaces the source.
67 */
68 providerIdentity: CustomLogSourceProviderIdentity;
69 }
70
71 /** @resource */
72 export interface CustomLogSource extends Resource<
73 "AWS.SecurityLake.CustomLogSource",
74 CustomLogSourceProps,
75 {
76 /** Name of the custom log source. */
77 sourceName: string;
78 /** The resolved source schema version. */
79 sourceVersion: string | undefined;
80 /** ARN of the Glue crawler created for the source. */
81 crawlerArn: string | undefined;
82 /** ARN of the Glue database created for the source. */
83 databaseArn: string | undefined;
84 /** ARN of the Glue table created for the source. */
85 tableArn: string | undefined;
86 /** ARN of the IAM role the provider assumes to write data. */
87 providerRoleArn: string | undefined;
88 /** S3 location the provider writes OCSF data to. */
89 providerLocation: string | undefined;
90 },
91 never,
92 Providers
93 > {}
94
95 /**
96 * A custom (third-party) log source registered with Amazon Security Lake.
97 * Security Lake provisions a Glue crawler, database, and table for the
98 * source, plus an IAM role the provider assumes to write OCSF-formatted data
99 * into the data lake. Requires `SecurityLake.DataLake` to already be enabled
100 * in the Region.
101 *
102 * Every configuration property is create-only — changing any of them
103 * replaces the source.
104 *
105 * ### Registering a custom source
106 * **Example:** Custom source with a crawler role
107 * ```typescript
108 * const custom = yield* SecurityLake.CustomLogSource("AppLogs", {
109 * sourceName: "my-app-logs",
110 * eventClasses: ["FILE_ACTIVITY"],
111 * crawlerConfiguration: { roleArn: crawlerRole.roleArn },
112 * providerIdentity: {
113 * principal: "123456789012",
114 * externalId: "my-app-external-id",
115 * },
116 * });
117 * ```
118 */
119 const CustomLogSourceResource = Resource<CustomLogSource>("AWS.SecurityLake.CustomLogSource");
120
121 export { CustomLogSourceResource as CustomLogSource };
122
123 const buildAttrs = (source: securitylake.CustomLogSourceResource) => ({
124 sourceName: source.sourceName!,
125 sourceVersion: source.sourceVersion,
126 crawlerArn: source.attributes?.crawlerArn,
127 databaseArn: source.attributes?.databaseArn,
128 tableArn: source.attributes?.tableArn,
129 providerRoleArn: source.provider?.roleArn,
130 providerLocation: source.provider?.location,
131 });
132
133 export const CustomLogSourceProvider = () =>
134 Provider.effect(
135 CustomLogSourceResource,
136 Effect.gen(function* () {
137 const createName = Effect.fn(function* (id: string, props: { sourceName?: string }) {
138 return props.sourceName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
139 });
140
141 // listLogSources reports only the source identity (name + version) for
142 // custom sources — the Glue/provider attributes are only returned by
143 // createCustomLogSource, so `output` is the cache for those.
144 const findByName = (sourceName: string, sourceVersion: string | undefined) =>
145 securitylake.listLogSources.items({}).pipe(
146 Stream.map((entry) => entry.sources ?? []),
147 Stream.flattenIterable,
148 Stream.filter(
149 (source) =>
150 source.customLogSource?.sourceName === sourceName &&
151 (sourceVersion === undefined ||
152 source.customLogSource.sourceVersion === sourceVersion),
153 ),
154 Stream.take(1),
155 Stream.runHead,
156 Effect.map(Option.getOrUndefined),
157 Effect.map((source) => source?.customLogSource),
158 );
159
160 return {
161 read: Effect.fn(function* ({ id, olds, output }) {
162 const sourceName = output?.sourceName ?? (yield* createName(id, olds ?? {}));
163 const sourceVersion = output?.sourceVersion ?? olds?.sourceVersion;
164 // An account that never onboarded Security Lake rejects
165 // listLogSources — that means "no source", not a failure.
166 const observed = yield* findByName(sourceName, sourceVersion).pipe(
167 Effect.catchTag(
168 ["AccessDeniedException", "ResourceNotFoundException", "UnauthorizedException"],
169 () => Effect.undefined,
170 ),
171 );
172 if (observed === undefined) return undefined;
173 // Custom log sources carry no tags, so ownership can't be
174 // distinguished — read reports observed state (merged with cached
175 // create-time attributes).
176 return {
177 sourceName,
178 sourceVersion: observed.sourceVersion ?? sourceVersion,
179 crawlerArn: output?.crawlerArn,
180 databaseArn: output?.databaseArn,
181 tableArn: output?.tableArn,
182 providerRoleArn: output?.providerRoleArn,
183 providerLocation: output?.providerLocation,
184 };
185 }),
186
187 list: () =>
188 securitylake.listLogSources.items({}).pipe(
189 Stream.map((entry) => entry.sources ?? []),
190 Stream.flattenIterable,
191 Stream.runCollect,
192 Effect.map((entries) => {
193 const seen = new Set<string>();
194 const attrs: ReturnType<typeof buildAttrs>[] = [];
195 for (const entry of entries) {
196 const source = entry.customLogSource;
197 if (source?.sourceName === undefined) continue;
198 const key = `${source.sourceName}@${source.sourceVersion ?? ""}`;
199 if (seen.has(key)) continue;
200 seen.add(key);
201 attrs.push(buildAttrs(source));
202 }
203 return attrs;
204 }),
205 // An account that never onboarded Security Lake has no data lake
206 // to list sources for.
207 Effect.catchTag(
208 ["AccessDeniedException", "ResourceNotFoundException", "UnauthorizedException"],
209 () => Effect.succeed([]),
210 ),
211 ),
212
213 // There is no UpdateCustomLogSource — every property is create-only.
214 diff: Effect.fn(function* ({ news, olds }) {
215 if (!isResolved(news)) return undefined;
216 const changed =
217 news.sourceName !== olds.sourceName ||
218 news.sourceVersion !== olds.sourceVersion ||
219 JSON.stringify(news.eventClasses ?? []) !== JSON.stringify(olds.eventClasses ?? []) ||
220 news.crawlerConfiguration.roleArn !== olds.crawlerConfiguration.roleArn ||
221 news.providerIdentity.principal !== olds.providerIdentity.principal ||
222 news.providerIdentity.externalId !== olds.providerIdentity.externalId;
223 if (changed) return { action: "replace" } as const;
224 }),
225
226 reconcile: Effect.fn(function* ({ id, news, output, session }) {
227 const sourceName = yield* createName(id, news);
228
229 // 1. OBSERVE — is the source already registered?
230 const observed = yield* findByName(sourceName, news.sourceVersion);
231
232 // 2. ENSURE — create when missing. A ConflictException means a
233 // concurrent create won the race; fall through to observation.
234 let attrs = output;
235 if (observed === undefined) {
236 const created = yield* securitylake
237 .createCustomLogSource({
238 sourceName,
239 sourceVersion: news.sourceVersion,
240 eventClasses: news.eventClasses,
241 configuration: {
242 crawlerConfiguration: news.crawlerConfiguration,
243 providerIdentity: news.providerIdentity,
244 },
245 })
246 .pipe(
247 Effect.map((response) => response.source),
248 // A concurrent create won the race — keep cached attributes.
249 Effect.catchTag("ConflictException", () => Effect.undefined),
250 );
251 if (created !== undefined) {
252 attrs = buildAttrs(created);
253 }
254 }
255
256 // 3. RETURN — merge observed identity with cached create-time
257 // attributes (Glue ARNs / provider role are only reported by
258 // create).
259 const final = {
260 sourceName,
261 sourceVersion: attrs?.sourceVersion ?? observed?.sourceVersion ?? news.sourceVersion,
262 crawlerArn: attrs?.crawlerArn,
263 databaseArn: attrs?.databaseArn,
264 tableArn: attrs?.tableArn,
265 providerRoleArn: attrs?.providerRoleArn,
266 providerLocation: attrs?.providerLocation,
267 };
268 yield* session.note(sourceName);
269 return final;
270 }),
271
272 delete: Effect.fn(function* ({ output }) {
273 yield* securitylake
274 .deleteCustomLogSource({
275 sourceName: output.sourceName,
276 sourceVersion: output.sourceVersion,
277 })
278 .pipe(
279 retryWhileConflict,
280 // Gone already, or the data lake itself was offboarded first.
281 Effect.catchTag(
282 ["AccessDeniedException", "ResourceNotFoundException", "UnauthorizedException"],
283 () => Effect.void,
284 ),
285 );
286 }),
287 };
288 }),
289 );