AWS.CloudTrail reference

CancelQuery

Source: packages/aws/src/CloudTrail/CancelQuery.ts

Runtime binding for cloudtrail:CancelQuery.

Cancels a running CloudTrail Lake query. Cancelling a query that already finished fails with the typed InactiveQueryException. Provide the implementation with Effect.provide(AWS.CloudTrail.CancelQueryHttp).

CancelQuery: Querying CloudTrail Lake

// init — bind the operation to the event data store
const cancelQuery = yield* AWS.CloudTrail.CancelQuery(store);

// runtime
const result = yield* cancelQuery({ QueryId: queryId });
console.log(result.QueryStatus); // CANCELLED

DescribeQuery

Source: packages/aws/src/CloudTrail/DescribeQuery.ts

Runtime binding for cloudtrail:DescribeQuery.

Reads a CloudTrail Lake query’s status, statistics, and error message by QueryId — the polling half of the start/poll/results flow. Provide the implementation with Effect.provide(AWS.CloudTrail.DescribeQueryHttp).

DescribeQuery: Querying CloudTrail Lake

// init — bind the operation to the event data store
const describeQuery = yield* AWS.CloudTrail.DescribeQuery(store);

// runtime
const status = yield* describeQuery({ QueryId: queryId });
console.log(status.QueryStatus); // QUEUED | RUNNING | FINISHED | ...

EventDataStore

Source: packages/aws/src/CloudTrail/EventDataStore.ts

A CloudTrail Lake event data store — an immutable collection of events that can be queried with SQL via CloudTrail Lake.

Deleting an event data store schedules it for deletion (PENDING_DELETION); AWS purges it after a seven-day wait period during which it incurs no cost. If a store with the same name is still pending deletion, the reconciler restores it instead of creating a duplicate.

EventDataStore: Creating Event Data Stores

Basic Event Data Store

import * as AWS from "@alchemy.run/aws";

const store = yield* AWS.CloudTrail.EventDataStore("Lake", {
  retentionPeriod: "7 days",
  terminationProtectionEnabled: false,
});

Single-Region Store with Custom Selectors

const store = yield* AWS.CloudTrail.EventDataStore("S3DataEvents", {
  multiRegionEnabled: false,
  retentionPeriod: "30 days",
  terminationProtectionEnabled: false,
  advancedEventSelectors: [
    {
      name: "S3 data events",
      fieldSelectors: [
        { field: "eventCategory", equals: ["Data"] },
        { field: "resources.type", equals: ["AWS::S3::Object"] },
      ],
    },
  ],
});

EventDataStore: Looking up an existing event data store

EventDataStore.lookup references an event data store Alchemy doesn’t manage (created in the console or by another stack), found by eventDataStoreArn. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.CloudTrail.EventDataStore.lookup({ eventDataStoreArn: "..." });

GenerateQuery

Source: packages/aws/src/CloudTrail/GenerateQuery.ts

Runtime binding for cloudtrail:GenerateQuery.

Generates a CloudTrail Lake SQL statement from a natural-language prompt against the bound EventDataStore (the store list is injected from the binding). Provide the implementation with Effect.provide(AWS.CloudTrail.GenerateQueryHttp).

GenerateQuery: Querying CloudTrail Lake

// init — bind the operation to the event data store
const generateQuery = yield* AWS.CloudTrail.GenerateQuery(store);

// runtime
const result = yield* generateQuery({
  Prompt: "What are my top errors in the past month?",
});
console.log(result.QueryStatement);

GetQueryResults

Source: packages/aws/src/CloudTrail/GetQueryResults.ts

Runtime binding for cloudtrail:GetQueryResults.

Reads one page of a finished CloudTrail Lake query’s result rows — use NextToken/MaxQueryResults to paginate large results. Provide the implementation with Effect.provide(AWS.CloudTrail.GetQueryResultsHttp).

GetQueryResults: Querying CloudTrail Lake

// init — bind the operation to the event data store
const getQueryResults = yield* AWS.CloudTrail.GetQueryResults(store);

// runtime
const page = yield* getQueryResults({ QueryId: queryId });
console.log(page.QueryResultRows?.length);

ListInsightsData

Source: packages/aws/src/CloudTrail/ListInsightsData.ts

Runtime binding for cloudtrail:ListInsightsData.

An account-level operation (no resource argument) that reads the raw Insights events recorded for an insight source — empty when Insights has recorded no anomalies. Rate-limited by AWS to two requests per second, per account, per Region. Provide the implementation with Effect.provide(AWS.CloudTrail.ListInsightsDataHttp).

ListInsightsData: Reading Insights Events

// init — account-level binding takes no resource
const listInsightsData = yield* AWS.CloudTrail.ListInsightsData();

// runtime
const result = yield* listInsightsData({
  InsightSource: "s3.amazonaws.com",
  DataType: "InsightsEvents",
  MaxResults: 10,
});
console.log((result.Events ?? []).map((e) => e.EventName));

ListInsightsMetricData

Source: packages/aws/src/CloudTrail/ListInsightsMetricData.ts

Runtime binding for cloudtrail:ListInsightsMetricData.

An account-level operation (no resource argument) that reads the Insights metric time series (API call rate / error rate) for a given event source and event name — empty when Insights has recorded no anomalies. Provide the implementation with Effect.provide(AWS.CloudTrail.ListInsightsMetricDataHttp).

ListInsightsMetricData: Reading Insights Metrics

// init — account-level binding takes no resource
const listInsightsMetricData =
  yield* AWS.CloudTrail.ListInsightsMetricData();

// runtime
const result = yield* listInsightsMetricData({
  EventSource: "s3.amazonaws.com",
  EventName: "PutObject",
  InsightType: "ApiCallRateInsight",
});
console.log(result.Timestamps?.length, result.Values?.length);

ListPublicKeys

Source: packages/aws/src/CloudTrail/ListPublicKeys.ts

Runtime binding for cloudtrail:ListPublicKeys.

An account-level operation (no resource argument) that returns the public keys used to sign CloudTrail digest files in the region — the building block for verifying log-file integrity at runtime. Provide the implementation with Effect.provide(AWS.CloudTrail.ListPublicKeysHttp).

ListPublicKeys: Verifying Log Integrity

// init — account-level binding takes no resource
const listPublicKeys = yield* AWS.CloudTrail.ListPublicKeys();

// runtime
const result = yield* listPublicKeys();
console.log(result.PublicKeyList?.map((k) => k.Fingerprint));

ListQueries

Source: packages/aws/src/CloudTrail/ListQueries.ts

Runtime binding for cloudtrail:ListQueries.

Lists the CloudTrail Lake queries that ran against the bound EventDataStore in the last seven days — the store is injected from the binding. Provide the implementation with Effect.provide(AWS.CloudTrail.ListQueriesHttp).

ListQueries: Querying CloudTrail Lake

// init — bind the operation to the event data store
const listQueries = yield* AWS.CloudTrail.ListQueries(store);

// runtime
const result = yield* listQueries({ MaxResults: 10 });
console.log(result.Queries?.map((q) => q.QueryId));

LookupEvents

Source: packages/aws/src/CloudTrail/LookupEvents.ts

Runtime binding for cloudtrail:LookupEvents.

An account-level operation (no resource argument) that searches the last 90 days of management events recorded in the region — the classic “who did what” audit read, available without any trail or event data store. Provide the implementation with Effect.provide(AWS.CloudTrail.LookupEventsHttp).

LookupEvents: Reading Event History

// init — account-level binding takes no resource
const lookupEvents = yield* AWS.CloudTrail.LookupEvents();

// runtime
const result = yield* lookupEvents({
  LookupAttributes: [
    { AttributeKey: "EventName", AttributeValue: "CreateBucket" },
  ],
  MaxResults: 10,
});
console.log(result.Events?.map((e) => e.EventName));

StartQuery

Source: packages/aws/src/CloudTrail/StartQuery.ts

Runtime binding for cloudtrail:StartQuery.

Starts a CloudTrail Lake SQL query against the bound EventDataStore and returns the QueryId to poll with DescribeQuery / GetQueryResults. Provide the implementation with Effect.provide(AWS.CloudTrail.StartQueryHttp).

StartQuery: Querying CloudTrail Lake

// init — bind the operation to the event data store
const startQuery = yield* AWS.CloudTrail.StartQuery(store);

// runtime — the callback receives the store's ID for the FROM clause
const { QueryId } = yield* startQuery({
  QueryStatement: (id) =>
    `SELECT eventID, eventName FROM ${id} LIMIT 10`,
});

Trail

Source: packages/aws/src/CloudTrail/Trail.ts

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.

Trail: Creating Trails

Basic Trail

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,
});

Multi-Region Trail with Log File Validation

const trail = yield* AWS.CloudTrail.Trail("Audit", {
  trailName: "org-audit-trail",
  s3BucketName: bucket.bucketName,
  isMultiRegionTrail: true,
  enableLogFileValidation: true,
});

Trail: Controlling Logging

const trail = yield* AWS.CloudTrail.Trail("Audit", {
  trailName: "audit-trail",
  s3BucketName: bucket.bucketName,
  isLogging: false,
});

Trail: Selecting Events

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" }],
});

Trail: Looking up an existing trail

Trail.lookup references a trail Alchemy doesn’t manage (created in the console or by another stack), found by trailName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.CloudTrail.Trail.lookup({ trailName: "my-trail" });