Scan data for secrets

AWS S3

13min


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:

  1. An AWS account with at least one S3 bucket to be scanned.
  2. An IAM identity that has the correct access and authorization to list the bucket and download objects from it.

Configuration options



Local configuration

There are four different authentication options for AWS S3:

  • IAM credentials
  • IAM role assumptions
  • IAM role assumption with instance profile
  • Static credentials

IAM credentials

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.

IAM Credentials

Example IAM policy


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.

IAM role assumption

IAM Role Assumption


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.

Document image


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

Example IAM policy


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.

Example trust policy


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.

IAM role assumption with instance profile

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.

IAM Role Assumption with Instance Profile


Static credentials

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.

Static Credentials


Options

Key

Description

Required

buckets

List of names of the S3 buckets to be accessed. Omitting this will enumerate instead.

No

maxObjectSize

Maximum object size (in bytes) that can be processed. If an object is larger than this value, it will be skipped

No

roles

List of roles associated with the S3 buckets

No

ignoreBuckets

List of buckets that should be ignored

No

Capabilities

Feature

Supported

Scan archive files

Scan attachments

Scan base64 encoded data

Scan binaries

Exclude Filter

History

Include Filter

Progress info

Auto resume

Versions

Scan Glacier cold storage



Updated 17 Oct 2024
Doc contributor
Doc contributor
Doc contributor
Doc contributor
Doc contributor
Did this page help you?