AWS.CloudTrail reference

CancelQuery

Source: src/AWS/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: src/AWS/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: src/AWS/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/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"] },
      ],
    },
  ],
});

GenerateQuery

Source: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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/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" }],
});