Monitoring API calls by AWS accounts using AWS CloudTrail logging

Amazon CodeCatalyst is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service. CloudTrail captures API calls made on behalf of CodeCatalyst in connected AWS accounts as events. If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for CodeCatalyst. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history.

CodeCatalyst supports logging the following actions as events in CloudTrail log files:

The space billing account is your AWS account that is charged for CodeCatalyst resources beyond the AWS Free tier. Multiple accounts can be connected to a space, while only one account can be the designated billing account. The billing account or additional connected accounts for the space can have IAM roles that are used for deploying AWS resources and infrastructure, such as an Amazon ECS cluster or S3 bucket, from CodeCatalyst workflows. You can use the workflow YAML to identify the AWS account that you deployed to.

CodeCatalyst logging in connected accounts includes the following considerations:

For more information about CloudTrail, see the AWS CloudTrail User Guide.

CodeCatalyst space events

Actions in CodeCatalyst for managing space-level and project-level resources are logged in the billing account for the space. For CloudTrail logging for a CodeCatalyst space, events are logged with the following considerations.

The following are examples of events in AWS that are related to actions in CodeCatalyst for managing space-level and project-level resources. The following APIs are released through the SDK and CLI. Events will be logged in the AWS account specified as the billing account for the CodeCatalyst space.

CodeCatalyst account connections and billing events

The following are examples of events in AWS that are related to actions in CodeCatalyst for account connections or billing:

CodeCatalyst information in CloudTrail

CloudTrail is enabled on an AWS account when you create that account. When you connect that AWS account to a CodeCatalyst space, events for that space that occur in that AWS account are logged in CloudTrail logs in that AWS account. Loggable events in CodeCatalyst are recorded as CloudTrail events in CloudTrail logs in the connected account and in Event history in the CloudTrail console, along with other loggable AWS events in that account.

Every event or log entry contains information about who generated the request. The identity information helps you determine the following:

For more information, see the CloudTrail userIdentity element.

Accessing CloudTrail events

For an ongoing record of events in your AWS account, including events for CodeCatalyst activity in the AWS account, create a trail. A trail enables CloudTrail to deliver log files to an S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:

A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order.

Example CodeCatalyst account connections event in AWS

The following example shows a CloudTrail log entry that demonstrates the ListConnections action. For an AWS account that is connected to the space, ListConnections is used to view all account connections to CodeCatalyst for this AWS account. The event will be logged in the AWS account specified in accountId, and the value of the arn will be the Amazon Resource Name (ARN) of the role used for the action.

{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AKIAI44QH8DHBEXAMPLE",
        "arn": "role-ARN",
        "accountId": "account-ID",
        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AKIAI44QH8DHBEXAMPLE",
                "arn": "role-ARN",
                "accountId": "account-ID",
                "userName": "user-name"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-09-06T15:04:31Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-09-06T15:08:43Z",
    "eventSource": "account-ID",
    "eventName": "ListConnections",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "192.168.0.1",
    "userAgent": "aws-cli/1.18.147 Python/2.7.18 Linux/5.4.207-126.363.amzn2int.x86_64 botocore/1.18.6",
    "requestParameters": null,
    "responseElements": null,
    "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ",
    "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ",
    "readOnly": true,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "account-ID",
    "eventCategory": "Management"
}
      

Example CodeCatalyst project resource event in AWS

The following example shows a CloudTrail log entry that demonstrates the CreateDevEnvironment action. An AWS account that is connected to the space and is the designated billing account for the space is used for project-level events in the space, such as creating a Dev Environment.

Under userIdentity, in the accountId field, this is the IAM Identity Center account ID (432677196278) that hosts the identity pool for all AWS Builder ID identities. This account ID contains the following information about the CodeCatalyst user for the event.

The recipientAccountId field contains the account ID for the billing account for the space, with an example value here of 111122223333.

For more information, see the CloudTrail userIdentity element.

{
	"eventVersion": "1.09",
	"userIdentity": {
		"type": "IdentityCenterUser",
		"accountId": "432677196278",
		"onBehalfOf": {
			"userId": "user-ID",
			"identityStoreArn": "arn:aws:identitystore::432677196278:identitystore/d-9067642ac7"
		},
		"credentialId": "ABCDefGhiJKLMn11Lmn_1AbCDEFgHijk-AaBCdEFGHIjKLmnOPqrs11abEXAMPLE"
	},
	"eventTime": "2023-05-18T17:10:50Z",
	"eventSource": "codecatalyst.amazonaws.com",
	"eventName": "CreateDevEnvironment",
	"awsRegion": "us-west-2",
	"sourceIPAddress": "192.168.0.1",
	"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0",
	"requestParameters": {
		"spaceName": "MySpace",
		"projectName": "MyProject",
		"ides": [{
			"runtime": "public.ecr.aws/q6e8p2q0/cloud9-ide-runtime:2.5.1",
			"name": "Cloud9"
		}],
		"instanceType": "dev.standard1.small",
		"inactivityTimeoutMinutes": 15,
		"persistentStorage": {
			"sizeInGiB": 16
		}
	},
	"responseElements": {
		"spaceName": "MySpace",
		"projectName": "MyProject",
		"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 "
	},
	"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
	"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
	"readOnly": false,
	"eventType": "AwsApiCall",
	"managementEvent": true,
	"recipientAccountId": "111122223333",
	"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
	"eventCategory": "Management"
}

Querying your CodeCatalyst event trails

You can create and manage queries for your CloudTrail logs using a query table in Amazon Athena. For more information about creating a query, see Querying AWS CloudTrail logs in the Amazon Athena User Guide.