S3Scanner Documentation

The project includes a docker compose configuration that spins up four containers: rabbitmq, postgres, app, and mitm.

Two profiles are available:

• dev: Standard development environment.
• dev-mitm: Environment configured with mitmproxy to observe and manipulate HTTP traffic, useful for debugging or adding new providers.

To start the environment, use make dev or make dev-mitm. To run the application within the container, use docker exec to enter the app container and then run the application via Go.

S3Scanner can be installed on various platforms using the following commands:

• Go: go install -v github.com/sa7mon/s3scanner@latest
• Docker: docker run ghcr.io/sa7mon/s3scanner
• Kali Linux / Parrot OS: apt install s3scanner
• MacOS: brew install s3scanner
• BlackArch: pacman -S s3scanner
• Windows (winget): winget install s3scanner
• NixOS: nix-shell -p s3scanner
• Build from source: Clone the repository and use go build -o s3scanner .

S3Scanner is used to find open S3 buckets across multiple cloud providers (AWS, DigitalOcean, DreamHost, GCP, Linode, Scaleway, or Custom).

Input Methods

You must provide exactly one of the following:

• -bucket <name>: Scan a single bucket.
• -bucket-file <path>: Scan all bucket names listed in a file (one per line).
• -mq: Connect to RabbitMQ to consume bucket names from a queue (requires mq configuration).

Common Usage Examples

Scan AWS buckets from a file and enumerate objects:

s3scanner -bucket-file names.txt -enumerate

Scan a GCP bucket and save results to a database:

s3scanner -provider gcp -db -bucket my-bucket -enumerate

Output results in JSON format for piping to tools like jq:

s3scanner -bucket images -json

S3Scanner searches for a config.yml file in the following locations:

1. Current directory (. )
2. /etc/s3scanner/
3. $HOME/.s3scanner/

Certain flags require specific keys in this configuration file:

• -db requires db.uri.
• -mq requires mq.uri and mq.queue_name.
• -provider custom requires keys under providers.custom.

When using the -provider custom flag, you must define the provider settings in the config.yml file under providers.custom.

Key fields for custom providers:

• address_style: The addressing style used by endpoints. Values: "path" or "vhost".
• endpoint_format: The format of endpoint URLs. You must include the $REGION placeholder, which s3scanner will replace with each entry in the regions list.
• insecure: A boolean to ignore SSL errors.
• regions: A list of region strings. At least one region must be provided.

providers:
  custom: 
    address_style: "path"
    endpoint_format: "https://$REGION.vultrobjects.com"
    insecure: false
    regions:
      - "ewr1"

When using flags that require configuration options, s3scanner searches for a config.yml file in the following locations (in order):

1. The current working directory
2. /etc/s3scanner/
3. $HOME/.s3scanner/

Required configuration keys include db (for the -db flag), mq (for the -mq flag), and providers.custom (if using the -provider custom flag).

# Required by -db
db:
  uri: "postgresql://user:pass@db.host.name:5432/schema_name"

# Required by -mq
mq:
  queue_name: "aws"
  uri: "amqp://user:pass@localhost:5672"

# providers.custom required by `-provider custom`
providers:
  custom: 
    address_style: "path"
    endpoint_format: "https://$REGION.vultrobjects.com"
    insecure: false
    regions:
      - "ewr1"

Certain flags require specific keys to be present in your configuration file (loaded via viper). If these flags are used without the corresponding configuration keys, the application will fail validation.

Required Keys by Flag

Input Flags

• -bucket <string>: Name of bucket to check.
• -bucket-file <string>: File of bucket names to check.
• -mq: Connect to RabbitMQ to get buckets. Requires config file key mq. Default: false.

Output Flags

• -db: Save results to a Postgres database. Requires config file key db.uri. Default: false.
• -json: Print logs to stdout in JSON format instead of human-readable. Default: false.

Options

• -enumerate: Enumerate bucket objects (can be time-consuming). Default: false.
• -provider <string>: Object storage provider: aws, custom, digitalocean, dreamhost, gcp, linode, scaleway. Default: aws.
• -threads <int>: Number of threads to scan with. Default: 4.

Debug Flags

• -verbose: Enable verbose logging. Default: false.
• -version: Print version. Default: false.

S3Scanner attempts to identify available permissions for a bucket. Note that S3Scanner currently only supports scanning for anonymous user permissions of non-AWS services.

Permissions identified may include:

• Read: List and view all files.
• Write: Write files to bucket.
• Read ACP: Read all Access Control Policies attached to bucket.
• Write ACP: Write Access Control Policies to bucket.
• Full Control: All of the above.

These permissions apply to user groups such as Authenticated Users or Public Users (those without AWS credentials). Note that permission to read/write ACLs is independent of the permission to read/write files.