@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 574 lines 19 KB
Raw
1 import * as websecurityscanner from "@distilled.cloud/gcp/websecurityscanner_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import { GcpEnvironment } from "../Environment.ts";
10 import type { Providers } from "../Providers.ts";
11 import {
12 getScanConfig,
13 jsonEqual,
14 lastSegment,
15 sameText,
16 scanConfigNameOf,
17 sortedStrings,
18 stringList,
19 toUserDisplayName,
20 unspecified,
21 updateMaskOf,
22 } from "./internal.ts";
23
24 export type ScanConfigSchedule = {
25 /**
26 * RFC3339 time of the next run. The server refreshes this after each
27 * run. Omit to start the first run immediately when a schedule is set.
28 */
29 scheduleTime?: string;
30 /**
31 * Days between scheduled executions. Required when `schedule` is set.
32 */
33 intervalDurationDays: number;
34 };
35
36 export type ScanConfigGoogleAccount = {
37 /**
38 * Google account username used during the scan.
39 */
40 username: string;
41 /**
42 * Input-only Google account password. Stored encrypted by GCP and
43 * never returned.
44 */
45 password?: string;
46 };
47
48 export type ScanConfigCustomAccount = {
49 /**
50 * Custom account username.
51 */
52 username: string;
53 /**
54 * Input-only custom account password. Stored encrypted by GCP and
55 * never returned.
56 */
57 password?: string;
58 /**
59 * Login form URL of the target site.
60 */
61 loginUrl: string;
62 };
63
64 export type ScanConfigIapCredential = {
65 /**
66 * OAuth2 client id of the IAP-protected resource.
67 */
68 targetAudienceClientId: string;
69 };
70
71 export type ScanConfigAuthentication = {
72 /**
73 * Authenticate with a Google account.
74 */
75 googleAccount?: ScanConfigGoogleAccount;
76 /**
77 * Authenticate with a custom account.
78 */
79 customAccount?: ScanConfigCustomAccount;
80 /**
81 * Authenticate with Identity-Aware Proxy.
82 */
83 iapCredential?: ScanConfigIapCredential;
84 };
85
86 export type ScanConfigLatestRun = {
87 /** Scan run resource name. */
88 name?: string;
89 /** Execution state (`QUEUED`, `SCANNING`, `FINISHED`). */
90 executionState?: string;
91 /** Result state after finish (`SUCCESS`, `ERROR`, `KILLED`). */
92 resultState?: string;
93 /** RFC3339 start time. */
94 startTime?: string;
95 /** RFC3339 end time. */
96 endTime?: string;
97 /** Completion percent 0–100. */
98 progressPercent?: number;
99 /** URLs crawled so far. */
100 urlsCrawledCount?: string;
101 /** URLs tested so far. */
102 urlsTestedCount?: string;
103 /** Whether any vulnerabilities were found. */
104 hasVulnerabilities?: boolean;
105 };
106
107 export type ScanConfigProps = {
108 /**
109 * Server-assigned scan config id (the `{scanConfigId}` segment of
110 * `projects/{project}/scanConfigs/{scanConfigId}`). Immutable —
111 * changing it replaces the config.
112 */
113 scanConfigId?: string;
114 /**
115 * Human-readable display name. If omitted, a unique name is generated
116 * from the stack, stage, and logical id.
117 */
118 displayName?: string;
119 /**
120 * Starting URLs the scanner crawls from. Each URL must belong to this
121 * project (App Engine, a reserved Compute IP, Cloud Run, or Cloud
122 * Functions).
123 */
124 startingUrls: string[];
125 /**
126 * Maximum QPS while scanning. Valid range is 5–20. Unspecified or 0
127 * uses the API default of 15.
128 */
129 maxQps?: number;
130 /**
131 * User agent used while scanning (`CHROME_LINUX`, `CHROME_ANDROID`,
132 * `SAFARI_IPHONE`).
133 */
134 userAgent?: string;
135 /**
136 * URL patterns excluded from the crawl.
137 */
138 blacklistPatterns?: string[];
139 /**
140 * Recurring scan schedule. Omit to keep the config idle until a scan
141 * is started explicitly.
142 */
143 schedule?: ScanConfigSchedule;
144 /**
145 * Credentials used while scanning. Passwords are input-only.
146 */
147 authentication?: ScanConfigAuthentication;
148 /**
149 * Platforms to scan (`APP_ENGINE`, `COMPUTE`, `CLOUD_RUN`,
150 * `CLOUD_FUNCTIONS`). Empty uses `APP_ENGINE`.
151 */
152 targetPlatforms?: string[];
153 /**
154 * Export scan results to Security Command Center (`ENABLED` or
155 * `DISABLED`). Default `ENABLED`.
156 */
157 exportToSecurityCommandCenter?: string;
158 /**
159 * Scan risk level (`NORMAL` or `LOW`). Default `NORMAL`.
160 */
161 riskLevel?: string;
162 /**
163 * When true, the scanner uses static IP addresses.
164 */
165 staticIpScan?: boolean;
166 /**
167 * When true, keep scanning even if most responses are HTTP errors.
168 */
169 ignoreHttpStatusErrors?: boolean;
170 };
171
172 export type ScanConfig = Resource<
173 "GCP.WebSecurityScanner.ScanConfig",
174 ScanConfigProps,
175 {
176 /** Full resource name `projects/{project}/scanConfigs/{scanConfigId}`. */
177 name: string;
178 /** Server-assigned scan config id. */
179 scanConfigId: string;
180 /** Project id used when the config was reconciled. */
181 project: string;
182 /** Human-readable display name. */
183 displayName: string | undefined;
184 /** Starting URLs. */
185 startingUrls: string[];
186 /** Maximum QPS. */
187 maxQps: number | undefined;
188 /** User agent. */
189 userAgent: string | undefined;
190 /** Excluded URL patterns. */
191 blacklistPatterns: string[];
192 /** Recurring schedule, if set. */
193 schedule: ScanConfigSchedule | undefined;
194 /** Authentication with passwords omitted. */
195 authentication: ScanConfigAuthentication | undefined;
196 /** Target platforms. */
197 targetPlatforms: string[];
198 /** Security Command Center export setting. */
199 exportToSecurityCommandCenter: string | undefined;
200 /** Risk level. */
201 riskLevel: string | undefined;
202 /** Whether static IP scanning is enabled. */
203 staticIpScan: boolean | undefined;
204 /** Whether HTTP error codes are ignored. */
205 ignoreHttpStatusErrors: boolean | undefined;
206 /** Whether Web Security Scanner manages this config. */
207 managedScan: boolean | undefined;
208 /** Most recent scan run, if any. */
209 latestRun: ScanConfigLatestRun | undefined;
210 },
211 never,
212 Providers
213 >;
214
215 /**
216 * A Web Security Scanner scan configuration.
217 *
218 * Scan config ids are assigned by Google and scan configs have no labels
219 * field, so Alchemy tracks a config only through the name recorded in
220 * state; a config read without prior state is reported as unowned. Display
221 * name, starting
222 * URLs, QPS, user agent, blacklist, schedule, authentication, platforms,
223 * export, risk, and scan flags update in place. Changing `scanConfigId`
224 * replaces the config.
225 *
226 * Starting URLs must belong to the project — a reserved Compute IP,
227 * App Engine (`https://PROJECT.appspot.com`), Cloud Run, or Cloud
228 * Functions.
229 *
230 * ### Creating a ScanConfig
231 * **Example:** Scan a reserved Compute IP
232 * ```typescript
233 * const ip = yield* GCP.Compute.Address("Target", {
234 * region: "us-central1",
235 * });
236 * const scan = yield* GCP.WebSecurityScanner.ScanConfig("Site", {
237 * displayName: "public site",
238 * startingUrls: [Output.interpolate`http://${ip.address}`],
239 * targetPlatforms: ["COMPUTE"],
240 * exportToSecurityCommandCenter: "DISABLED",
241 * });
242 * ```
243 *
244 * **Example:** Low-risk scan with excluded paths
245 * ```typescript
246 * const scan = yield* GCP.WebSecurityScanner.ScanConfig("Site", {
247 * displayName: "public site",
248 * startingUrls: ["https://my-app-uc.a.run.app/"],
249 * targetPlatforms: ["CLOUD_RUN"],
250 * maxQps: 5,
251 * riskLevel: "LOW",
252 * userAgent: "CHROME_LINUX",
253 * blacklistPatterns: ["https://my-app-uc.a.run.app/logout"],
254 * ignoreHttpStatusErrors: true,
255 * exportToSecurityCommandCenter: "DISABLED",
256 * });
257 * ```
258 *
259 * ### Updating a ScanConfig
260 * **Example:** Raise QPS and change the display name
261 * ```typescript
262 * // Same logical id as before; only the changed props differ.
263 * const scan = yield* GCP.WebSecurityScanner.ScanConfig("Site", {
264 * displayName: "public site v2",
265 * startingUrls: [Output.interpolate`http://${ip.address}`],
266 * targetPlatforms: ["COMPUTE"],
267 * maxQps: 10,
268 * exportToSecurityCommandCenter: "DISABLED",
269 * });
270 * ```
271 *
272 * @resource
273 * @category WebSecurityScanner
274 */
275 export const ScanConfig = Resource<ScanConfig>("GCP.WebSecurityScanner.ScanConfig");
276
277 export class ScanConfigNotResolved extends Data.TaggedError(
278 "GCP.WebSecurityScanner.ScanConfigNotResolved",
279 )<{
280 resourceName: string;
281 }> {}
282
283 const toSchedule = (
284 schedule: websecurityscanner.Schedule | ScanConfigSchedule | undefined,
285 ): ScanConfigSchedule | undefined => {
286 if (schedule === undefined) return undefined;
287 if (schedule.intervalDurationDays === undefined) return undefined;
288 return {
289 intervalDurationDays: schedule.intervalDurationDays,
290 scheduleTime: schedule.scheduleTime,
291 };
292 };
293
294 const toAuthentication = (
295 authentication: websecurityscanner.Authentication | undefined,
296 ): ScanConfigAuthentication | undefined => {
297 if (authentication === undefined) return undefined;
298 const google = authentication.googleAccount;
299 const custom = authentication.customAccount;
300 const iapClientId =
301 authentication.iapCredential?.iapTestServiceAccountInfo?.targetAudienceClientId;
302 const next: ScanConfigAuthentication = {};
303 if (google?.username !== undefined) {
304 next.googleAccount = { username: google.username };
305 }
306 if (custom?.username !== undefined || custom?.loginUrl !== undefined) {
307 next.customAccount = {
308 username: custom?.username ?? "",
309 loginUrl: custom?.loginUrl ?? "",
310 };
311 }
312 if (iapClientId !== undefined) {
313 next.iapCredential = { targetAudienceClientId: iapClientId };
314 }
315 return Object.keys(next).length > 0 ? next : undefined;
316 };
317
318 const authenticationFingerprint = (authentication: ScanConfigAuthentication | undefined) =>
319 JSON.stringify({
320 googleUsername: authentication?.googleAccount?.username ?? "",
321 customUsername: authentication?.customAccount?.username ?? "",
322 customLoginUrl: authentication?.customAccount?.loginUrl ?? "",
323 iapClientId: authentication?.iapCredential?.targetAudienceClientId ?? "",
324 });
325
326 const toLatestRun = (
327 run: websecurityscanner.ScanRun | undefined,
328 ): ScanConfigLatestRun | undefined => {
329 if (run === undefined) return undefined;
330 return {
331 name: run.name,
332 executionState: run.executionState,
333 resultState: run.resultState,
334 startTime: run.startTime,
335 endTime: run.endTime,
336 progressPercent: run.progressPercent,
337 urlsCrawledCount: run.urlsCrawledCount,
338 urlsTestedCount: run.urlsTestedCount,
339 hasVulnerabilities: run.hasVulnerabilities,
340 };
341 };
342
343 const toAttrs = (config: websecurityscanner.ScanConfig, project: string) => {
344 const name = config.name ?? "";
345 return {
346 name,
347 scanConfigId: lastSegment(name),
348 project,
349 displayName: config.displayName,
350 startingUrls: stringList(config.startingUrls),
351 maxQps: config.maxQps,
352 userAgent: unspecified(config.userAgent) || undefined,
353 blacklistPatterns: stringList(config.blacklistPatterns),
354 schedule: toSchedule(config.schedule),
355 authentication: toAuthentication(config.authentication),
356 targetPlatforms: stringList(config.targetPlatforms).filter(
357 (platform) => unspecified(platform).length > 0,
358 ),
359 exportToSecurityCommandCenter: unspecified(config.exportToSecurityCommandCenter) || undefined,
360 riskLevel: unspecified(config.riskLevel) || undefined,
361 staticIpScan: config.staticIpScan,
362 ignoreHttpStatusErrors: config.ignoreHttpStatusErrors,
363 managedScan: config.managedScan,
364 latestRun: toLatestRun(config.latestRun),
365 };
366 };
367
368 const toAuthBody = (
369 authentication: ScanConfigAuthentication | undefined,
370 ): websecurityscanner.Authentication | undefined => {
371 if (authentication === undefined) return undefined;
372 const body: websecurityscanner.Authentication = {};
373 if (authentication.googleAccount !== undefined) {
374 body.googleAccount = {
375 username: authentication.googleAccount.username,
376 password: authentication.googleAccount.password,
377 };
378 }
379 if (authentication.customAccount !== undefined) {
380 body.customAccount = {
381 username: authentication.customAccount.username,
382 password: authentication.customAccount.password,
383 loginUrl: authentication.customAccount.loginUrl,
384 };
385 }
386 if (authentication.iapCredential !== undefined) {
387 body.iapCredential = {
388 iapTestServiceAccountInfo: {
389 targetAudienceClientId: authentication.iapCredential.targetAudienceClientId,
390 },
391 };
392 }
393 return Object.keys(body).length > 0 ? body : undefined;
394 };
395
396 const toBody = (news: ScanConfigProps, displayName: string): websecurityscanner.ScanConfig => {
397 const body: websecurityscanner.ScanConfig = {
398 displayName,
399 startingUrls: news.startingUrls,
400 };
401 if (news.maxQps !== undefined) body.maxQps = news.maxQps;
402 if (news.userAgent !== undefined) body.userAgent = news.userAgent;
403 if (news.blacklistPatterns !== undefined) {
404 body.blacklistPatterns = news.blacklistPatterns;
405 }
406 if (news.schedule !== undefined) {
407 body.schedule = {
408 intervalDurationDays: news.schedule.intervalDurationDays,
409 scheduleTime: news.schedule.scheduleTime,
410 };
411 }
412 const authentication = toAuthBody(news.authentication);
413 if (authentication !== undefined) body.authentication = authentication;
414 if (news.targetPlatforms !== undefined) {
415 body.targetPlatforms = news.targetPlatforms;
416 }
417 if (news.exportToSecurityCommandCenter !== undefined) {
418 body.exportToSecurityCommandCenter = news.exportToSecurityCommandCenter;
419 }
420 if (news.riskLevel !== undefined) body.riskLevel = news.riskLevel;
421 if (news.staticIpScan !== undefined) body.staticIpScan = news.staticIpScan;
422 if (news.ignoreHttpStatusErrors !== undefined) {
423 body.ignoreHttpStatusErrors = news.ignoreHttpStatusErrors;
424 }
425 return body;
426 };
427
428 const lookupNameOf = (
429 project: string,
430 news: { scanConfigId?: string },
431 output: { name?: string; scanConfigId?: string } | undefined,
432 ) =>
433 output?.name ??
434 (news.scanConfigId !== undefined
435 ? scanConfigNameOf(project, news.scanConfigId)
436 : output?.scanConfigId !== undefined
437 ? scanConfigNameOf(project, output.scanConfigId)
438 : "");
439
440 export const ScanConfigProvider = () =>
441 Provider.succeed(ScanConfig, {
442 stables: ["name", "scanConfigId", "project"],
443
444 diff: Effect.fn(function* ({ news, olds, output }) {
445 if (!isResolved(news)) return undefined;
446 const previousId = olds?.scanConfigId ?? output?.scanConfigId;
447 if (
448 news.scanConfigId !== undefined &&
449 previousId !== undefined &&
450 news.scanConfigId !== previousId
451 ) {
452 return { action: "replace" as const, deleteFirst: false };
453 }
454 return undefined;
455 }),
456
457 read: Effect.fn(function* ({ olds, output }) {
458 const env = yield* GcpEnvironment.current;
459 const existing = yield* getScanConfig(lookupNameOf(env.project, olds ?? {}, output));
460 if (existing === undefined) return undefined;
461 const attrs = toAttrs(existing, env.project);
462 // No labels field: without prior state it may not be ours.
463 return output !== undefined ? attrs : Unowned(attrs);
464 }),
465
466 reconcile: Effect.fn(function* ({ id, news, output }) {
467 const env = yield* GcpEnvironment.current;
468 const lookupName = lookupNameOf(env.project, news, output);
469
470 let current = yield* getScanConfig(lookupName);
471 const displayName = yield* toUserDisplayName(
472 id,
473 news.displayName,
474 current?.displayName ?? output?.displayName,
475 );
476 const desired = toBody(news, displayName);
477
478 if (current === undefined) {
479 const created = yield* websecurityscanner
480 .createProjectsScanConfigs({
481 parent: `projects/${env.project}`,
482 body: desired,
483 })
484 .pipe(
485 Effect.catchTag("Conflict", () => getScanConfig(lookupName)),
486 // A just-reserved static IP can take up to a minute to be visible.
487 Effect.retry({
488 while: (e) => e._tag === "StartingUrlIpNotReserved",
489 schedule: Schedule.spaced("3 seconds"),
490 times: 20,
491 }),
492 );
493 current = created ?? undefined;
494 }
495
496 if (current === undefined) {
497 return yield* new ScanConfigNotResolved({
498 resourceName: lookupName.length > 0 ? lookupName : displayName,
499 });
500 }
501
502 const name = current.name ?? lookupName;
503 const displayChanged = !sameText(current.displayName, displayName);
504 const startingChanged = !jsonEqual(stringList(current.startingUrls), news.startingUrls);
505 const maxQpsChanged = news.maxQps !== undefined && (current.maxQps ?? 15) !== news.maxQps;
506 const userAgentChanged =
507 news.userAgent !== undefined &&
508 unspecified(current.userAgent) !== unspecified(news.userAgent);
509 const blacklistChanged =
510 news.blacklistPatterns !== undefined &&
511 !jsonEqual(stringList(current.blacklistPatterns), news.blacklistPatterns);
512 const scheduleChanged =
513 news.schedule !== undefined &&
514 (current.schedule?.intervalDurationDays ?? 0) !== news.schedule.intervalDurationDays;
515 const authenticationChanged =
516 news.authentication !== undefined &&
517 authenticationFingerprint(toAuthentication(current.authentication)) !==
518 authenticationFingerprint(news.authentication);
519 const platformsChanged =
520 news.targetPlatforms !== undefined &&
521 !jsonEqual(
522 sortedStrings(
523 stringList(current.targetPlatforms).filter(
524 (platform) => unspecified(platform).length > 0,
525 ),
526 ),
527 sortedStrings(news.targetPlatforms),
528 );
529 const exportChanged =
530 news.exportToSecurityCommandCenter !== undefined &&
531 unspecified(current.exportToSecurityCommandCenter) !==
532 unspecified(news.exportToSecurityCommandCenter);
533 const riskChanged =
534 news.riskLevel !== undefined &&
535 unspecified(current.riskLevel) !== unspecified(news.riskLevel);
536 const staticIpChanged =
537 news.staticIpScan !== undefined && (current.staticIpScan === true) !== news.staticIpScan;
538 const ignoreHttpChanged =
539 news.ignoreHttpStatusErrors !== undefined &&
540 (current.ignoreHttpStatusErrors === true) !== news.ignoreHttpStatusErrors;
541
542 const updateMask = updateMaskOf(
543 displayChanged ? "displayName" : undefined,
544 startingChanged ? "startingUrls" : undefined,
545 maxQpsChanged ? "maxQps" : undefined,
546 userAgentChanged ? "userAgent" : undefined,
547 blacklistChanged ? "blacklistPatterns" : undefined,
548 scheduleChanged ? "schedule" : undefined,
549 authenticationChanged ? "authentication" : undefined,
550 platformsChanged ? "targetPlatforms" : undefined,
551 exportChanged ? "exportToSecurityCommandCenter" : undefined,
552 riskChanged ? "riskLevel" : undefined,
553 staticIpChanged ? "staticIpScan" : undefined,
554 ignoreHttpChanged ? "ignoreHttpStatusErrors" : undefined,
555 );
556
557 if (updateMask.length > 0) {
558 current = yield* websecurityscanner.patchProjectsScanConfigs({
559 name,
560 updateMask,
561 body: { ...desired, name },
562 });
563 }
564
565 return toAttrs(current, env.project);
566 }),
567
568 delete: Effect.fn(function* ({ output }) {
569 if (output.name.length === 0) return;
570 yield* websecurityscanner
571 .deleteProjectsScanConfigs({ name: output.name })
572 .pipe(Effect.catchTag("NotFound", () => Effect.void));
573 }),
574 });