import * as cloudtrail from "@distilled.cloud/aws/cloudtrail";
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 { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";
/**
* A data-event resource selection inside a basic event selector. Mirrors the
* CloudTrail `DataResource` wire shape.
*/
export interface TrailDataResource {
/** The resource type, e.g. `AWS::S3::Object` or `AWS::Lambda::Function`. */
type: string;
/** ARNs (or ARN prefixes) of the resources to log data events for. */
values?: string[];
}
/**
* A basic event selector controlling which management/data events the trail
* logs. Mirrors the CloudTrail `EventSelector` wire shape.
*/
export interface TrailEventSelector {
/**
* Whether to log read-only events, write-only events, or all.
* @default "All"
*/
readWriteType?: "ReadOnly" | "WriteOnly" | "All";
/**
* Whether the selector includes management events.
* @default true
*/
includeManagementEvents?: boolean;
/** Data-event resources to log (S3 objects, Lambda functions, …). */
dataResources?: TrailDataResource[];
/**
* Management event sources to exclude (`kms.amazonaws.com`,
* `rdsdata.amazonaws.com`).
*/
excludeManagementEventSources?: string[];
}
/**
* A field selector inside an advanced event selector. Mirrors the CloudTrail
* `AdvancedFieldSelector` wire shape.
*/
export interface TrailFieldSelector {
/**
* The event record field to select on (e.g. `eventCategory`,
* `resources.type`).
*/
field: string;
/** Exact-match values. */
equals?: string[];
/** Prefix-match values. */
startsWith?: string[];
/** Suffix-match values. */
endsWith?: string[];
/** Exact-mismatch values. */
notEquals?: string[];
/** Prefix-mismatch values. */
notStartsWith?: string[];
/** Suffix-mismatch values. */
notEndsWith?: string[];
}
/**
* An advanced event selector controlling which events the trail logs.
* Advanced and basic event selectors are mutually exclusive.
*/
export interface TrailAdvancedEventSelector {
/** Descriptive name for the selector. */
name?: string;
/** Field selectors that events must match to be logged. */
fieldSelectors: TrailFieldSelector[];
}
/**
* An Insights selector enabling anomaly detection on the trail's events.
*/
export interface TrailInsightSelector {
/** The type of Insights to enable. */
insightType: "ApiCallRateInsight" | "ApiErrorRateInsight";
}
export interface TrailProps {
/**
* Name of the trail. Must be 3-128 characters, contain only letters,
* numbers, periods, underscores, and dashes, and start and end with a
* letter or number.
* @default ${app}-${stage}-${id}
*/
trailName?: string;
/**
* Name of the Amazon S3 bucket designated for publishing log files.
* The bucket policy must grant `cloudtrail.amazonaws.com` the
* `s3:GetBucketAcl` and `s3:PutObject` permissions, scoped with an
* `aws:SourceArn` condition on the trail's ARN.
*/
s3BucketName: string;
/**
* Amazon S3 key prefix that follows the name of the bucket designated
* for log file delivery.
*/
s3KeyPrefix?: string;
/**
* Whether the trail publishes events from global services such as IAM
* to the log files.
* @default true
*/
includeGlobalServiceEvents?: boolean;
/**
* Whether the trail applies to all Regions or only the Region in which
* it was created.
* @default false
*/
isMultiRegionTrail?: boolean;
/**
* Whether log file validation (SHA-256 digest files) is enabled.
* @default false
*/
enableLogFileValidation?: boolean;
/**
* ARN of the CloudWatch Logs log group to which CloudTrail delivers
* events. Requires `cloudWatchLogsRoleArn`.
*/
cloudWatchLogsLogGroupArn?: string;
/**
* Role ARN that CloudTrail assumes to write to the CloudWatch Logs
* log group. Requires `cloudWatchLogsLogGroupArn`.
*/
cloudWatchLogsRoleArn?: string;
/**
* KMS key ID (ID, alias, or ARN) used to encrypt the log files
* delivered by CloudTrail. Compared verbatim against the observed
* trail's key, so prefer the full key ARN to avoid a perpetual diff.
*/
kmsKeyId?: string;
/**
* Name of the Amazon SNS topic notified of new log file delivery.
*/
snsTopicName?: string;
/**
* Whether the trail is created for all accounts in an organization,
* or only for the current account.
* @default false
*/
isOrganizationTrail?: boolean;
/**
* Whether the trail is actively logging. Synced via `StartLogging` /
* `StopLogging`.
* @default true
*/
isLogging?: boolean;
/**
* Basic event selectors, synced via `PutEventSelectors`. Mutually
* exclusive with `advancedEventSelectors`. When omitted, the trail's
* selectors are left untouched; pass `[]`-free defaults explicitly to
* converge them.
*/
eventSelectors?: TrailEventSelector[];
/**
* Advanced event selectors, synced via `PutEventSelectors`. Mutually
* exclusive with `eventSelectors`. When omitted, the trail's selectors
* are left untouched.
*/
advancedEventSelectors?: TrailAdvancedEventSelector[];
/**
* Insights selectors, synced via `PutInsightSelectors`. Pass `[]` to
* disable Insights; when omitted, the trail's Insights configuration is
* left untouched.
*/
insightSelectors?: TrailInsightSelector[];
/**
* Tags to apply to the trail. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Trail extends Resource<
"AWS.CloudTrail.Trail",
TrailProps,
{
/** Physical name of the trail. */
trailName: string;
/** ARN of the trail. */
trailArn: string;
/** The region in which the trail was created. */
homeRegion: string;
/** S3 bucket the trail delivers log files to. */
s3BucketName: string;
/** Whether the trail is currently logging. */
isLogging: boolean;
},
never,
Providers
> {}
/**
* An AWS CloudTrail trail that records AWS API activity and delivers log
* files to an S3 bucket.
*
* The destination bucket must carry a bucket policy that allows the
* `cloudtrail.amazonaws.com` service principal to call `s3:GetBucketAcl`
* on the bucket and `s3:PutObject` under `AWSLogs/{accountId}/*`, both
* scoped with an `aws:SourceArn` condition on the trail's ARN.
* ### Creating Trails
* **Example:** Basic Trail
* ```typescript
* import * as AWS from "@alchemy.run/aws";
*
* const bucket = yield* AWS.S3.Bucket("TrailLogs", {
* bucketName: `audit-logs-${accountId}`,
* forceDestroy: true,
* policy: [
* {
* Effect: "Allow",
* Principal: { Service: "cloudtrail.amazonaws.com" },
* Action: ["s3:GetBucketAcl"],
* Resource: `arn:aws:s3:::audit-logs-${accountId}`,
* Condition: { StringEquals: { "aws:SourceArn": trailArn } },
* },
* {
* Effect: "Allow",
* Principal: { Service: "cloudtrail.amazonaws.com" },
* Action: ["s3:PutObject"],
* Resource: `arn:aws:s3:::audit-logs-${accountId}/AWSLogs/${accountId}/*`,
* Condition: {
* StringEquals: {
* "s3:x-amz-acl": "bucket-owner-full-control",
* "aws:SourceArn": trailArn,
* },
* },
* },
* ],
* });
*
* const trail = yield* AWS.CloudTrail.Trail("Audit", {
* trailName: "audit-trail",
* s3BucketName: bucket.bucketName,
* });
* ```
*
* **Example:** Multi-Region Trail with Log File Validation
* ```typescript
* const trail = yield* AWS.CloudTrail.Trail("Audit", {
* trailName: "org-audit-trail",
* s3BucketName: bucket.bucketName,
* isMultiRegionTrail: true,
* enableLogFileValidation: true,
* });
* ```
*
* ### Controlling Logging
* **Example:** Pause logging without deleting the trail
* ```typescript
* const trail = yield* AWS.CloudTrail.Trail("Audit", {
* trailName: "audit-trail",
* s3BucketName: bucket.bucketName,
* isLogging: false,
* });
* ```
*
* ### Selecting Events
* **Example:** Advanced Event Selectors and Insights
* ```typescript
* const trail = yield* AWS.CloudTrail.Trail("Audit", {
* trailName: "audit-trail",
* s3BucketName: bucket.bucketName,
* advancedEventSelectors: [
* {
* name: "Management events only",
* fieldSelectors: [
* { field: "eventCategory", equals: ["Management"] },
* ],
* },
* ],
* insightSelectors: [{ insightType: "ApiCallRateInsight" }],
* });
* ```
*
* @resource
*/
export const Trail = Resource<Trail>("AWS.CloudTrail.Trail");
/**
* S3 bucket-policy propagation is eventually consistent: `CreateTrail` /
* `UpdateTrail` can transiently reject a bucket whose policy was written
* moments earlier with `InsufficientS3BucketPolicyException` (or
* `S3BucketDoesNotExistException` right after bucket creation).
*
* Expressed as an explicitly-typed helper: inlining `Effect.retry` here
* leaves `Retry.Return`'s conditional type unresolved in the provider's
* inferred layer type, which TypeScript's declaration emit widens to an
* `unknown` R — poisoning the whole `AWS.providers()` union for every
* downstream consumer.
*/
const retryThroughBucketPropagation = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) =>
e._tag === "InsufficientS3BucketPolicyException" ||
e._tag === "S3BucketDoesNotExistException" ||
e._tag === "ConflictException",
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
});
/**
* Trail deletion right after a Start/StopLogging call (or another
* concurrent mutation) can raise a transient `ConflictException`.
*/
const retryWhileConflict = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "ConflictException",
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
});
const toWireEventSelectors = (selectors: TrailEventSelector[]): cloudtrail.EventSelector[] =>
selectors.map((s) => ({
ReadWriteType: s.readWriteType,
IncludeManagementEvents: s.includeManagementEvents,
DataResources: s.dataResources?.map((r) => ({
Type: r.type,
Values: r.values,
})),
ExcludeManagementEventSources: s.excludeManagementEventSources,
}));
const toWireAdvancedSelectors = (
selectors: TrailAdvancedEventSelector[],
): cloudtrail.AdvancedEventSelector[] =>
selectors.map((s) => ({
Name: s.name,
FieldSelectors: s.fieldSelectors.map((f) => ({
Field: f.field,
Equals: f.equals,
StartsWith: f.startsWith,
EndsWith: f.endsWith,
NotEquals: f.notEquals,
NotStartsWith: f.notStartsWith,
NotEndsWith: f.notEndsWith,
})),
}));
export const TrailProvider = () =>
Provider.effect(
Trail,
Effect.gen(function* () {
const createTrailName = Effect.fn(function* (
id: string,
props: { trailName?: string | undefined },
) {
if (props.trailName) {
return props.trailName;
}
return yield* createPhysicalName({ id, maxLength: 128 });
});
const fetchObservedTags = (trailArn: string) =>
cloudtrail.listTags({ ResourceIdList: [trailArn] }).pipe(
Effect.map((r) => {
const tags: Record<string, string> = {};
for (const t of r.ResourceTagList?.[0]?.TagsList ?? []) {
tags[t.Key] = t.Value ?? "";
}
return tags;
}),
Effect.orElseSucceed(() => ({}) as Record<string, string>),
);
const readTrail = (name: string) =>
cloudtrail.getTrail({ Name: name }).pipe(
Effect.map((r) => r.Trail),
Effect.catchTag("TrailNotFoundException", () => Effect.undefined),
);
const toAttributes = Effect.fn(function* (trail: cloudtrail.Trail) {
const name = trail.Name!;
const isLogging = yield* cloudtrail.getTrailStatus({ Name: trail.TrailARN ?? name }).pipe(
Effect.map((s) => s.IsLogging ?? false),
Effect.catchTag("TrailNotFoundException", () => Effect.succeed(false)),
);
return {
trailName: name,
trailArn: trail.TrailARN!,
homeRegion: trail.HomeRegion!,
s3BucketName: trail.S3BucketName!,
isLogging,
};
});
return Trail.Provider.of({
stables: ["trailName", "trailArn", "homeRegion"],
list: () =>
Effect.gen(function* () {
const trails = yield* cloudtrail
.describeTrails({ includeShadowTrails: false })
.pipe(Effect.map((r) => r.trailList ?? []));
return yield* Effect.forEach(
trails.filter((t) => t.Name !== undefined && t.TrailARN !== undefined),
(t) => toAttributes(t),
{ concurrency: 5 },
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.trailName ?? (yield* createTrailName(id, olds ?? {}));
const trail = yield* readTrail(name);
if (trail === undefined) return undefined;
const attrs = yield* toAttributes(trail);
const tags = yield* fetchObservedTags(attrs.trailArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createTrailName(id, olds ?? {});
const newName = yield* createTrailName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
// Everything else is mutable via UpdateTrail / Start/StopLogging.
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = output?.trailName ?? (yield* createTrailName(id, news));
const internalTags = yield* createInternalTags(id);
// Desired settings, with AWS defaults made explicit so removing a
// prop converges back to the default.
const desired = {
S3BucketName: news.s3BucketName,
S3KeyPrefix: news.s3KeyPrefix,
IncludeGlobalServiceEvents: news.includeGlobalServiceEvents ?? true,
IsMultiRegionTrail: news.isMultiRegionTrail ?? false,
EnableLogFileValidation: news.enableLogFileValidation ?? false,
CloudWatchLogsLogGroupArn: news.cloudWatchLogsLogGroupArn,
CloudWatchLogsRoleArn: news.cloudWatchLogsRoleArn,
KmsKeyId: news.kmsKeyId,
SnsTopicName: news.snsTopicName,
IsOrganizationTrail: news.isOrganizationTrail ?? false,
};
// 1. OBSERVE — cloud state is authoritative.
let trail = yield* readTrail(name);
// 2. ENSURE — create if missing; tolerate the AlreadyExists race.
if (trail === undefined) {
yield* session.note(`Creating CloudTrail trail ${name}`);
yield* retryThroughBucketPropagation(
cloudtrail.createTrail({
Name: name,
...desired,
TagsList: Object.entries({
...news.tags,
...internalTags,
}).map(([Key, Value]) => ({ Key, Value })),
}),
).pipe(Effect.catchTag("TrailAlreadyExistsException", () => Effect.void));
trail = yield* readTrail(name);
}
if (trail === undefined) {
// The trail vanished between create and re-read — surface the
// typed not-found from a direct get instead of inventing one.
trail = (yield* cloudtrail.getTrail({ Name: name })).Trail!;
}
// 3. SYNC settings — diff observed against desired, push only the
// fields that actually changed (UpdateTrail leaves omitted fields
// untouched, except booleans which we always pin to desired).
const settingsDelta: Partial<Omit<cloudtrail.UpdateTrailRequest, "Name">> = {};
if (trail.S3BucketName !== desired.S3BucketName) {
settingsDelta.S3BucketName = desired.S3BucketName;
}
if ((trail.S3KeyPrefix ?? "") !== (desired.S3KeyPrefix ?? "")) {
settingsDelta.S3KeyPrefix = desired.S3KeyPrefix ?? "";
}
if ((trail.IncludeGlobalServiceEvents ?? true) !== desired.IncludeGlobalServiceEvents) {
settingsDelta.IncludeGlobalServiceEvents = desired.IncludeGlobalServiceEvents;
}
if ((trail.IsMultiRegionTrail ?? false) !== desired.IsMultiRegionTrail) {
settingsDelta.IsMultiRegionTrail = desired.IsMultiRegionTrail;
}
if ((trail.LogFileValidationEnabled ?? false) !== desired.EnableLogFileValidation) {
settingsDelta.EnableLogFileValidation = desired.EnableLogFileValidation;
}
if (
desired.CloudWatchLogsLogGroupArn !== undefined &&
trail.CloudWatchLogsLogGroupArn !== desired.CloudWatchLogsLogGroupArn
) {
settingsDelta.CloudWatchLogsLogGroupArn = desired.CloudWatchLogsLogGroupArn;
settingsDelta.CloudWatchLogsRoleArn = desired.CloudWatchLogsRoleArn;
}
if (desired.KmsKeyId !== undefined && trail.KmsKeyId !== desired.KmsKeyId) {
settingsDelta.KmsKeyId = desired.KmsKeyId;
}
if ((trail.IsOrganizationTrail ?? false) !== desired.IsOrganizationTrail) {
settingsDelta.IsOrganizationTrail = desired.IsOrganizationTrail;
}
if (desired.SnsTopicName !== undefined && trail.SnsTopicName !== desired.SnsTopicName) {
settingsDelta.SnsTopicName = desired.SnsTopicName;
}
if (Object.keys(settingsDelta).length > 0) {
yield* session.note(
`Updating trail settings: ${Object.keys(settingsDelta).join(", ")}`,
);
yield* retryThroughBucketPropagation(
cloudtrail.updateTrail({ Name: name, ...settingsDelta }),
);
trail = (yield* cloudtrail.getTrail({ Name: name })).Trail ?? trail;
}
const trailArn = trail.TrailARN!;
// 3b. SYNC logging state via Start/StopLogging.
const desiredLogging = news.isLogging ?? true;
const observedLogging = yield* cloudtrail
.getTrailStatus({ Name: trailArn })
.pipe(Effect.map((s) => s.IsLogging ?? false));
if (observedLogging !== desiredLogging) {
if (desiredLogging) {
yield* session.note(`Starting logging for trail ${name}`);
yield* retryWhileConflict(cloudtrail.startLogging({ Name: trailArn }));
} else {
yield* session.note(`Stopping logging for trail ${name}`);
yield* retryWhileConflict(cloudtrail.stopLogging({ Name: trailArn }));
}
}
// 3c. SYNC event selectors — only when declared (undefined leaves
// the trail's selectors untouched). Basic and advanced selectors
// are mutually exclusive in the API; observed cloud selectors are
// the diff baseline.
if (news.eventSelectors !== undefined || news.advancedEventSelectors !== undefined) {
const observedSelectors = yield* cloudtrail.getEventSelectors({
TrailName: trailArn,
});
if (news.advancedEventSelectors !== undefined) {
const desiredAdvanced = toWireAdvancedSelectors(news.advancedEventSelectors);
if (
JSON.stringify(observedSelectors.AdvancedEventSelectors ?? []) !==
JSON.stringify(desiredAdvanced)
) {
yield* session.note(`Updating advanced event selectors`);
yield* retryWhileConflict(
cloudtrail.putEventSelectors({
TrailName: trailArn,
AdvancedEventSelectors: desiredAdvanced,
}),
);
}
} else {
const desiredBasic = toWireEventSelectors(news.eventSelectors!);
if (
JSON.stringify(observedSelectors.EventSelectors ?? []) !==
JSON.stringify(desiredBasic)
) {
yield* session.note(`Updating event selectors`);
yield* retryWhileConflict(
cloudtrail.putEventSelectors({
TrailName: trailArn,
EventSelectors: desiredBasic,
}),
);
}
}
}
// 3d. SYNC Insights selectors — only when declared. `[]` disables
// Insights; a trail with Insights disabled reads as [] (the typed
// InsightNotEnabledException).
if (news.insightSelectors !== undefined) {
const observedInsights = yield* cloudtrail
.getInsightSelectors({ TrailName: trailArn })
.pipe(
Effect.map((r) => r.InsightSelectors ?? []),
Effect.catchTag("InsightNotEnabledException", () =>
Effect.succeed([] as cloudtrail.InsightSelector[]),
),
);
const desiredInsights = news.insightSelectors.map((s) => ({
InsightType: s.insightType,
}));
if (
JSON.stringify(
observedInsights
.map((s) => s.InsightType)
.sort((a, b) => ((a ?? "") < (b ?? "") ? -1 : (a ?? "") > (b ?? "") ? 1 : 0)),
) !==
JSON.stringify(
desiredInsights
.map((s) => s.InsightType)
.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
)
) {
yield* session.note(`Updating Insights selectors`);
yield* retryWhileConflict(
cloudtrail.putInsightSelectors({
TrailName: trailArn,
InsightSelectors: desiredInsights,
}),
);
}
}
// 3e. SYNC tags against OBSERVED cloud tags (adoption-safe).
const observedTags = yield* fetchObservedTags(trailArn);
const { upsert, removed } = diffTags(observedTags, {
...news.tags,
...internalTags,
});
if (upsert.length > 0) {
yield* cloudtrail.addTags({
ResourceId: trailArn,
TagsList: upsert.map((t) => ({ Key: t.Key, Value: t.Value })),
});
}
if (removed.length > 0) {
yield* cloudtrail.removeTags({
ResourceId: trailArn,
TagsList: removed.map((Key) => ({ Key })),
});
}
yield* session.note(trailArn);
return {
trailName: name,
trailArn,
homeRegion: trail.HomeRegion!,
s3BucketName: trail.S3BucketName!,
isLogging: desiredLogging,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* retryWhileConflict(cloudtrail.deleteTrail({ Name: output.trailArn })).pipe(
Effect.catchTags({
TrailNotFoundException: () => Effect.void,
// A stale ARN whose trail is already gone can also surface as an
// invalid-ARN complaint; both mean "nothing left to delete".
CloudTrailARNInvalidException: () => Effect.void,
}),
);
}),
});
}),
);