Skip to main content

aws_s3_bucket_object resource

[edit on GitHub]

Use the aws_s3_bucket_object InSpec audit resource to test properties of a single AWS bucket object.

Each S3 Object has a ‘key’ which can be thought of as the name of the S3 Object which uniquely identifies it.


An aws_s3_bucket_object resource block declares a bucket and an object key by name, and then lists tests to be performed.

describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_object_key') do
  it { should exist }
  it { should_not be_public }


bucket_name (required)

The S3 Bucket Name which uniquely identifies the bucket. This must be passed as a bucket_name: 'value' key-value entry in a hash.

key (required)

The S3 Bucket Key which uniquely identifies the bucket object. This must be passed as a key: 'value' key-value entry in a hash.

See also the AWS documentation on S3 Buckets.


Property Description
bucket_name The name of the bucket.
key The key within the bucket.
content_length Size of the body in bytes.
content_type A standard MIME type describing the format of the object data.
object_acl An array of AWS Grants detailing permission grants on the bucket object.

There are also additional properties available. For a comprehensive list, see the API reference documentation.


Test an object’s object-level ACL

describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
  its('object_acl.count') { should eq 1 }

Test an object’s size in bytes is less than 100000

describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
  its('content_length') { should be < 1_000_000 }

Test an object’s type is “image/jpeg”

describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
  its('content_type') { should eq "image/jpeg" }

Check to see if a object appears to be exposed to the public

describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
  it { should_not be_public }


This InSpec audit resource has the following special matchers. For a full list of available matchers (such as exist) please visit our matchers page.


The be_public matcher tests if the object has potentially insecure access controls. This high-level matcher detects several insecure conditions, which may be enhanced in the future. Currently, the matcher reports an insecure object if any of the following conditions are met:

  1. A object ACL grant exists for the ‘AllUsers’ group
  2. A object ACL grant exists for the ‘AuthenticatedUsers’ group


This resource does not detect insecure bucket ACLs.
it { should_not be_public }

AWS Permissions

Your Principal will need the s3:GetObject, and s3:GetObjectAcl actions set to allow.

You can find detailed documentation at Actions, Resources, and Condition Keys for Amazon S3.

Was this page helpful?


Search Results