aws_ebs_snapshot Resource

[edit on GitHub]

Use the aws_ebs_snapshot InSpec audit resource to test properties of a single AWS EBS Snapshot. These are point-in-time incremental backups of AWS EBS volumes that are saved to AWS S3.

For additional information, including details on parameters and properties, see the AWS documentation on EBS Snapshots.

Installation

This resource is available in the Chef InSpec AWS resource pack.

See the Chef InSpec documentation on cloud platforms for information on configuring your AWS environment for InSpec and creating an InSpec profile that uses the InSpec AWS resource pack.

Syntax

Ensure an EBS Snapshot exists:

describe aws_ebs_snapshot(snapshot_id: 'SNAPSHOT_ID') do
  it { should exist }
end

You may also use hash syntax to pass the EBS volume name:

describe aws_ebs_snapshot(name: 'SNAPSHOT_ID') do
  it { should exist }
end

Parameters

This resource accepts a single parameter, either the EBS Snapshot ID or name (from the Name tag). At least one must be provided.

snapshot_id

The EBS Snapshot ID which uniquely identifies the volume. This can be passed as either a string or an snapshot_id: 'value' key-value entry in a hash.

name (required if snapshot_id not provided)

The EBS volume name from the name tag. This must be passed as a name: 'value' key-value entry in a hash. It is not advised to use this parameter if your Name tags for your snapshots are not unique, as at most one entry is returned.

Properties

snapshot_id

The unique ID for the EBS Snapshot.

encrypted

A boolean indicating whether the EBS Snapshot is encrypted.

data_encryption_key_id

The data encryption key identifier for the EBS Snapshot.

description

The description for the EBS Snapshot.

group

Either set to 'all' if the EBS Snapshot is public (anyone can create a volume from the EBS Snapshot), or nil.

kms_key_id

The ARN of the AWS KMS customer master key that was used to protect the volume encryption key for the parent volume.

outpost_arn

The ARN of the AWS Outpost on which the EBS Snapshot is stored.

owner_alias

The AWS owner alias, from an Amazon-maintained list.

owner_id

The AWS account ID of the EBS Snapshot owner.

progress

The progress of the EBS Snapshot, as a percentage, e.g. '100%'.

start_time

The time stamp when the EBS Snapshot was initiated.

state

The EBS Snapshot state.

state_message

A message about the EBS Snapshot state.

tags

A hash of tags for the EBS Snapshot, e.g. {'Name' => 'snapshot-name'} .

user_ids

An array of user_ids (account numbers) that have been granted permission to create a volume from this EBS Snapshot.

volume_id

The ID of the volume that was used to create the EBS Snapshot.

volume_size

The size of the volume, in GiB.

Examples

Test that an EBS Snapshot is encrypted.

describe aws_ebs_snapshot(id: 'SNAPSHOT_ID')do
  its('encrypted') { should eq true }
end

Test that an EBS Snapshot has the expected Name tag.

describe aws_ebs_snapshot(id: 'SNAPSHOT_ID') do
  its('tags') { should include(key: 'Name', value: 'SNAPSHOT_NAME') }
end

Tests that no specified accounts have been given access to create volumes from this EBS Snapshot.

describe aws_ebs_snapshot(id: 'SNAPSHOT_ID') do
  its('user_ids') { should be_empty }
end

Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our matchers page.

exist

The control will pass if the describe returns at least one result.

describe aws_ebs_snapshot(name: 'SNAPSHOT_ID') do
  it { should exist }
end

Use should_not to test the entity should not exist.

describe aws_ebs_snapshot(id: 'SNAPSHOT_ID') do
  it { should_not exist }
end

be_encrypted

The be_encrypted matcher tests whether the described EBS Snapshot is encrypted.

it { should be_encrypted }

be_public

The be_public matcher tests whether the described EBS Snapshot is public, i.e. if anyone may create a volume from the EBS Snapshot.

it { should be_public }

be_private

The be_private matcher tests whether the described EBS Snapshot is private, i.e. not open for anyone to create a volume from the EBS Snapshot. It does not check whether specific user_ids (AWS accounts) have been given access to create a volume from the EBS Snapshot). To check permissions for specific user_ids, see the last example in the previous section.

it { should be_private }

AWS Permissions

Your Principal will need the EC2:Client::DescribeSnapshotsResult and EC2:Client:DescribeSnapshotAttributeResult actions with Effect set to Allow.

You can find detailed documentation at Actions, Resources, and Condition Keys for Amazon EC2, and Actions, Resources, and Condition Keys for Identity And Access Management.