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.

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

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.

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.

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

For a full list of available matchers, see our Universal Matchers page.

This resource has the following special matchers.

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

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

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

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

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

Your Principal will need the CloudTrail:Client:DescribeTrailsResponse action with Effect set to Allow.