# AWS CloudTrail Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
## Trail
AWS CloudTrail enables governance, compliance, and operational and risk auditing of your AWS account. Actions taken by
a user, role, or an AWS service are recorded as events in CloudTrail. Learn more at the [CloudTrail
documentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html).
The `Trail` construct enables ongoing delivery of events as log files to an Amazon S3 bucket. Learn more about [Creating
a Trail for Your AWS Account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html).
The following code creates a simple CloudTrail for your account -
```python
trail = cloudtrail.Trail(self, "CloudTrail")
```
By default, this will create a new S3 Bucket that CloudTrail will write to, and choose a few other reasonable defaults
such as turning on multi-region and global service events.
The defaults for each property and how to override them are all documented on the `TrailProps` interface.
## Log File Validation
In order to validate that the CloudTrail log file was not modified after CloudTrail delivered it, CloudTrail provides a
digital signature for each file. Learn more at [Validating CloudTrail Log File
Integrity](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-validation-intro.html).
This is enabled on the `Trail` construct by default, but can be turned off by setting `enableFileValidation` to `false`.
```python
trail = cloudtrail.Trail(self, "CloudTrail",
enable_file_validation=False
)
```
## Notifications
Amazon SNS notifications can be configured upon new log files containing Trail events are delivered to S3.
Learn more at [Configuring Amazon SNS Notifications for
CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html).
The following code configures an SNS topic to be notified -
```python
topic = sns.Topic(self, "TrailTopic")
trail = cloudtrail.Trail(self, "CloudTrail",
sns_topic=topic
)
```
## Service Integrations
Besides sending trail events to S3, they can also be configured to notify other AWS services -
### Amazon CloudWatch Logs
CloudTrail events can be delivered to a CloudWatch Logs LogGroup. By default, a new LogGroup is created with a
default retention setting. The following code enables sending CloudWatch logs but specifies a particular retention
period for the created Log Group.
```python
import aws_cdk.aws_logs as logs
trail = cloudtrail.Trail(self, "CloudTrail",
send_to_cloud_watch_logs=True,
cloud_watch_logs_retention=logs.RetentionDays.FOUR_MONTHS
)
```
If you would like to use a specific log group instead, this can be configured via `cloudwatchLogGroup`.
### Amazon EventBridge
Amazon EventBridge rules can be configured to be triggered when CloudTrail events occur using the `Trail.onEvent()` API.
Using APIs available in `aws-events`, these events can be filtered to match to those that are of interest, either from
a specific service, account or time range. See [Events delivered via
CloudTrail](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html#events-for-services-not-listed)
to learn more about the event structure for events from CloudTrail.
The following code filters events for S3 from a specific AWS account and triggers a lambda function.
```python
my_function_handler = lambda_.Function(self, "MyFunction",
code=lambda_.Code.from_asset("resource/myfunction"),
runtime=lambda_.Runtime.NODEJS_14_X,
handler="index.handler"
)
event_rule = cloudtrail.Trail.on_event(self, "MyCloudWatchEvent",
target=targets.LambdaFunction(my_function_handler)
)
event_rule.add_event_pattern(
account=["123456789012"],
source=["aws.s3"]
)
```
## Multi-Region & Global Service Events
By default, a `Trail` is configured to deliver log files from multiple regions to a single S3 bucket for a given
account. This creates shadow trails (replication of the trails) in all of the other regions. Learn more about [How
CloudTrail Behaves Regionally](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-regional-and-global-services)
and about the [`IsMultiRegion`
property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-ismultiregiontrail).
For most services, events are recorded in the region where the action occurred. For global services such as AWS IAM,
AWS STS, Amazon CloudFront, Route 53, etc., events are delivered to any trail that includes global services. Learn more
[About Global Service Events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-global-service-events).
Events for global services are turned on by default for `Trail` constructs in the CDK.
The following code disables multi-region trail delivery and trail delivery for global services for a specific `Trail` -
```python
trail = cloudtrail.Trail(self, "CloudTrail",
# ...
is_multi_region_trail=False,
include_global_service_events=False
)
```
## Events Types
**Management events** provide information about management operations that are performed on resources in your AWS
account. These are also known as control plane operations. Learn more about [Management
Events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events).
By default, a `Trail` logs all management events. However, they can be configured to either be turned off, or to only
log 'Read' or 'Write' events.
The following code configures the `Trail` to only track management events that are of type 'Read'.
```python
trail = cloudtrail.Trail(self, "CloudTrail",
# ...
management_events=cloudtrail.ReadWriteType.READ_ONLY
)
```
**Data events** provide information about the resource operations performed on or in a resource. These are also known
as data plane operations. Learn more about [Data
Events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events).
By default, no data events are logged for a `Trail`.
AWS CloudTrail supports data event logging for Amazon S3 objects and AWS Lambda functions.
The `logAllS3DataEvents()` API configures the trail to log all S3 data events while the `addS3EventSelector()` API can
be used to configure logging of S3 data events for specific buckets and specific object prefix. The following code
configures logging of S3 data events for `fooBucket` and with object prefix `bar/`.
```python
import aws_cdk.aws_s3 as s3
# bucket: s3.Bucket
trail = cloudtrail.Trail(self, "MyAmazingCloudTrail")
# Adds an event selector to the bucket foo
trail.add_s3_event_selector([
bucket=bucket,
object_prefix="bar/"
])
```
Similarly, the `logAllLambdaDataEvents()` configures the trail to log all Lambda data events while the
`addLambdaEventSelector()` API can be used to configure logging for specific Lambda functions. The following code
configures logging of Lambda data events for a specific Function.
```python
trail = cloudtrail.Trail(self, "MyAmazingCloudTrail")
amazing_function = lambda_.Function(self, "AnAmazingFunction",
runtime=lambda_.Runtime.NODEJS_14_X,
handler="hello.handler",
code=lambda_.Code.from_asset("lambda")
)
# Add an event selector to log data events for the provided Lambda functions.
trail.add_lambda_event_selector([amazing_function])
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-cloudtrail",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0d/e5/e069ca51b6b745d4328bcd68e92e1e3652238ab9b706c30ae39ed5324fd1/aws-cdk.aws-cloudtrail-1.203.0.tar.gz",
"platform": null,
"description": "# AWS CloudTrail Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\n## Trail\n\nAWS CloudTrail enables governance, compliance, and operational and risk auditing of your AWS account. Actions taken by\na user, role, or an AWS service are recorded as events in CloudTrail. Learn more at the [CloudTrail\ndocumentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html).\n\nThe `Trail` construct enables ongoing delivery of events as log files to an Amazon S3 bucket. Learn more about [Creating\na Trail for Your AWS Account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html).\nThe following code creates a simple CloudTrail for your account -\n\n```python\ntrail = cloudtrail.Trail(self, \"CloudTrail\")\n```\n\nBy default, this will create a new S3 Bucket that CloudTrail will write to, and choose a few other reasonable defaults\nsuch as turning on multi-region and global service events.\nThe defaults for each property and how to override them are all documented on the `TrailProps` interface.\n\n## Log File Validation\n\nIn order to validate that the CloudTrail log file was not modified after CloudTrail delivered it, CloudTrail provides a\ndigital signature for each file. Learn more at [Validating CloudTrail Log File\nIntegrity](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-validation-intro.html).\n\nThis is enabled on the `Trail` construct by default, but can be turned off by setting `enableFileValidation` to `false`.\n\n```python\ntrail = cloudtrail.Trail(self, \"CloudTrail\",\n enable_file_validation=False\n)\n```\n\n## Notifications\n\nAmazon SNS notifications can be configured upon new log files containing Trail events are delivered to S3.\nLearn more at [Configuring Amazon SNS Notifications for\nCloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html).\nThe following code configures an SNS topic to be notified -\n\n```python\ntopic = sns.Topic(self, \"TrailTopic\")\ntrail = cloudtrail.Trail(self, \"CloudTrail\",\n sns_topic=topic\n)\n```\n\n## Service Integrations\n\nBesides sending trail events to S3, they can also be configured to notify other AWS services -\n\n### Amazon CloudWatch Logs\n\nCloudTrail events can be delivered to a CloudWatch Logs LogGroup. By default, a new LogGroup is created with a\ndefault retention setting. The following code enables sending CloudWatch logs but specifies a particular retention\nperiod for the created Log Group.\n\n```python\nimport aws_cdk.aws_logs as logs\n\n\ntrail = cloudtrail.Trail(self, \"CloudTrail\",\n send_to_cloud_watch_logs=True,\n cloud_watch_logs_retention=logs.RetentionDays.FOUR_MONTHS\n)\n```\n\nIf you would like to use a specific log group instead, this can be configured via `cloudwatchLogGroup`.\n\n### Amazon EventBridge\n\nAmazon EventBridge rules can be configured to be triggered when CloudTrail events occur using the `Trail.onEvent()` API.\nUsing APIs available in `aws-events`, these events can be filtered to match to those that are of interest, either from\na specific service, account or time range. See [Events delivered via\nCloudTrail](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html#events-for-services-not-listed)\nto learn more about the event structure for events from CloudTrail.\n\nThe following code filters events for S3 from a specific AWS account and triggers a lambda function.\n\n```python\nmy_function_handler = lambda_.Function(self, \"MyFunction\",\n code=lambda_.Code.from_asset(\"resource/myfunction\"),\n runtime=lambda_.Runtime.NODEJS_14_X,\n handler=\"index.handler\"\n)\n\nevent_rule = cloudtrail.Trail.on_event(self, \"MyCloudWatchEvent\",\n target=targets.LambdaFunction(my_function_handler)\n)\n\nevent_rule.add_event_pattern(\n account=[\"123456789012\"],\n source=[\"aws.s3\"]\n)\n```\n\n## Multi-Region & Global Service Events\n\nBy default, a `Trail` is configured to deliver log files from multiple regions to a single S3 bucket for a given\naccount. This creates shadow trails (replication of the trails) in all of the other regions. Learn more about [How\nCloudTrail Behaves Regionally](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-regional-and-global-services)\nand about the [`IsMultiRegion`\nproperty](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-ismultiregiontrail).\n\nFor most services, events are recorded in the region where the action occurred. For global services such as AWS IAM,\nAWS STS, Amazon CloudFront, Route 53, etc., events are delivered to any trail that includes global services. Learn more\n[About Global Service Events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-global-service-events).\n\nEvents for global services are turned on by default for `Trail` constructs in the CDK.\n\nThe following code disables multi-region trail delivery and trail delivery for global services for a specific `Trail` -\n\n```python\ntrail = cloudtrail.Trail(self, \"CloudTrail\",\n # ...\n is_multi_region_trail=False,\n include_global_service_events=False\n)\n```\n\n## Events Types\n\n**Management events** provide information about management operations that are performed on resources in your AWS\naccount. These are also known as control plane operations. Learn more about [Management\nEvents](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events).\n\nBy default, a `Trail` logs all management events. However, they can be configured to either be turned off, or to only\nlog 'Read' or 'Write' events.\n\nThe following code configures the `Trail` to only track management events that are of type 'Read'.\n\n```python\ntrail = cloudtrail.Trail(self, \"CloudTrail\",\n # ...\n management_events=cloudtrail.ReadWriteType.READ_ONLY\n)\n```\n\n**Data events** provide information about the resource operations performed on or in a resource. These are also known\nas data plane operations. Learn more about [Data\nEvents](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events).\nBy default, no data events are logged for a `Trail`.\n\nAWS CloudTrail supports data event logging for Amazon S3 objects and AWS Lambda functions.\n\nThe `logAllS3DataEvents()` API configures the trail to log all S3 data events while the `addS3EventSelector()` API can\nbe used to configure logging of S3 data events for specific buckets and specific object prefix. The following code\nconfigures logging of S3 data events for `fooBucket` and with object prefix `bar/`.\n\n```python\nimport aws_cdk.aws_s3 as s3\n# bucket: s3.Bucket\n\n\ntrail = cloudtrail.Trail(self, \"MyAmazingCloudTrail\")\n\n# Adds an event selector to the bucket foo\ntrail.add_s3_event_selector([\n bucket=bucket,\n object_prefix=\"bar/\"\n])\n```\n\nSimilarly, the `logAllLambdaDataEvents()` configures the trail to log all Lambda data events while the\n`addLambdaEventSelector()` API can be used to configure logging for specific Lambda functions. The following code\nconfigures logging of Lambda data events for a specific Function.\n\n```python\ntrail = cloudtrail.Trail(self, \"MyAmazingCloudTrail\")\namazing_function = lambda_.Function(self, \"AnAmazingFunction\",\n runtime=lambda_.Runtime.NODEJS_14_X,\n handler=\"hello.handler\",\n code=lambda_.Code.from_asset(\"lambda\")\n)\n\n# Add an event selector to log data events for the provided Lambda functions.\ntrail.add_lambda_event_selector([amazing_function])\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::CloudTrail",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9eee94edcc230202e3f5dbe872fc3a2e9481af45cd731c2ce17b2fa7c365bba7",
"md5": "1143dbbbe0a89e2482a45baf10ef2cd5",
"sha256": "61504fec58859535575ace5a8b507ab15f09c9d2e9f128824b92bd3f4d4fba86"
},
"downloads": -1,
"filename": "aws_cdk.aws_cloudtrail-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1143dbbbe0a89e2482a45baf10ef2cd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 160719,
"upload_time": "2023-05-31T22:53:27",
"upload_time_iso_8601": "2023-05-31T22:53:27.592849Z",
"url": "https://files.pythonhosted.org/packages/9e/ee/94edcc230202e3f5dbe872fc3a2e9481af45cd731c2ce17b2fa7c365bba7/aws_cdk.aws_cloudtrail-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0de5e069ca51b6b745d4328bcd68e92e1e3652238ab9b706c30ae39ed5324fd1",
"md5": "f55bdeba654265171bb95b6dab5437d7",
"sha256": "1e55c7c59213f455c9e5bb9b43b3827df819123a04536e86f76bfb7be6ae08a9"
},
"downloads": -1,
"filename": "aws-cdk.aws-cloudtrail-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "f55bdeba654265171bb95b6dab5437d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 162353,
"upload_time": "2023-05-31T23:01:15",
"upload_time_iso_8601": "2023-05-31T23:01:15.572150Z",
"url": "https://files.pythonhosted.org/packages/0d/e5/e069ca51b6b745d4328bcd68e92e1e3652238ab9b706c30ae39ed5324fd1/aws-cdk.aws-cloudtrail-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:01:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-cloudtrail"
}
JSON
