AWS Simple Storage Service (S3) is a cloud-based object storage service that TruffleHog can scan for credentials. In AWS, access to an S3 bucket can be controlled through various IAM (Identity and Access Management) identities. These include IAM users, which are individual entities with specific permissions; IAM roles, which are sets of permissions that can be assumed by any authorized entity, such as an AWS service or an external user, and instance profiles, which are special-purpose IAM roles that are assumed by EC2 instances. TruffleHog supports any of these identities for access, although each will require specific configuration within TruffleHog as well as your AWS account.

To successfully configure an S3 source, you need at minimum:

There are four different authentication options for AWS S3:

This configuration assumes that valid AWS credentials are available in one of the standard locations. This can be used with IAM users, roles, or instance-profiles.

This is the basic IAM policy that needs to be attached to the IAM identity being used to access the S3 bucket. AWS also provides additional policy examples for more granular access control over S3.

This is generally the most secure option, and can be used to enable a single scanner instance to scan multiple buckets across different AWS accounts.

A common implementation pattern is to have the TruffleHog scanner in an administrative/security account, with a permissions policy attached that only permits the IAM identity (user, role, or instance profile) to assume IAM roles in accounts that contain S3 buckets that are the desired scanning targets.

The IAM roles in those accounts should be assigned permissions policies similar to this example:

IAM roles can be assumed by an IAM entity, such as a user or role, that is an allowed principal in an IAM trust policy attached to the role.

Please refer to AWS documentation for additional information on IAM roles, usage scenarios, and configuration.

Passing in a role ARN without specifying a bucket will result in all buckets that the role can list being scanned. Multiple roles can be specified as individual arguments.

If a bucket or buckets are supplied in addition to multiple roles, a scan will be attempted against each bucket by each role.

Using an instance-profile to perform role assumption is similar to the configuration for IAM role assumption in the previous section.

Note that this configuration does not use the sessionToken field.

While this configuration can be useful for testing, we generally don’t recommend this in a production environment, as the credentials will be exposed in plaintext. This configuration is compatible with IAM users and static credentials.