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

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.