aws_cloudtrail_trail Resource
Use the aws_cloudtrail_trail
Chef InSpec audit resource to test properties of a single AWS CloudTrail trail.
Install
This resource is available in the Chef InSpec AWS resource pack.
For information on configuring your AWS environment for Chef InSpec and creating an InSpec profile that uses the InSpec AWS resource pack, see the Chef InSpec documentation on the AWS cloud platform.
Syntax
An aws_cloudtrail_trail
resource block identifies a trail by TRAIL_NAME
.
Find a trail by name:
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should exist }
end
Use hash syntax to find a trail by trail name:
describe aws_cloudtrail_trail(trail_name: 'TRAIL_NAME') do
it { should exist }
end
Parameters
trail_name
(required)- This resource expects a single parameter, the CloudTrail name which uniquely identifies it.
This can be passed either as a string or as a
trail_name: 'value'
key-value entry in a hash.
See the AWS documentation on CloudTrail.
Properties
trail_arn
- Specifies the ARN of the trail.
TRAIL_NAME
- Name of the trail.
home_region
- The region in which the trail was created.
s3_bucket_name
- Name of the Amazon S3 bucket into which CloudTrail delivers your trail files.
cloud_watch_logs_role_arn
- Specifies the role for the CloudWatch Logs endpoint to assume to write to a user’s log group.
cloud_watch_logs_log_group_arn
- Specifies an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered.
kms_key_id
- Specifies the KMS key ID that encrypts the logs delivered by CloudTrail.
s3_key_prefix
- Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery.
is_organization_trail
- Specifies whether the trail is an organization trail. It returns boolean value.
Examples
Test that the specified trail does exist.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should exist }
end
describe aws_cloudtrail_trail(trail_name: 'TRAIL_NAME') do
it { should exist }
end
Check the KMS key used to encrypt.
describe aws_cloudtrail_trail('TRAIL_NAME') do
its('kms_key_id') { should eq "KMS_KEY_ID" }
end
Check the home region is correct.
describe aws_cloudtrail_trail('TRAIL_NAME') do
its('home_region') { should eq 'us-east-1' }
end
Test that the specified trail is a multi-region trail.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should be_multi_region_trail }
end
Test that the specified trail is an organization trail.
describe aws_cloudtrail_trail('TRAIL_NAME') do
its("is_organization_trail") { should eq true }
it { should be_organization_trail }
end
Test that the specified trail has a S3 Key Prefix.
describe aws_cloudtrail_trail('TRAIL_NAME') do
its("s3_key_prefix") { should eq 'S3_KEY_PREFIX_NAME' }
end
Matchers
For a full list of available matchers, see our Universal Matchers page.This resource has the following special matchers.
exist
Use should
with the exist
matcher to verify that the CloudTrail trail exists.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should exist }
end
Use should_not
to verify that a CloudTrail trail does not exists.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should_not exist }
end
be_multi_region_trail
The test will pass if the identified trail is a multi-region trail.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should be_multi_region_trail }
end
be_encrypted
The test will pass if the logs delivered by the identified trail are encrypted.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should be_encrypted }
end
be_log_file_validation_enabled
The test will pass if the identified trail has log file integrity validation enabled.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should be_log_file_validation_enabled }
end
be_organization_trail
The test will pass if the identified trail has organization trail is enabled.
describe aws_cloudtrail_trail('TRAIL_NAME') do
it { should be_organization_trail }
end
AWS Permissions
Your Principal will need the CloudTrail:Client:DescribeTrailsResponse
action with Effect
set to Allow
.
You can find detailed documentation at Actions, Resources, and Condition Keys for AWS CloudTrail.