Basic Usage

Command Syntax

s3finder [flags]
s3finder [command]

Required Flags

At least one input source must be provided. All sources are decoupled and independent.

Flag	Short	Description
--seed	-s	Target keyword for bucket name generation (permuted)
--wordlist	-w	Path to wordlist file (raw mode)
--permlist	-p	Path to seed list file (each line permuted like --seed)
--perm-suffixes		Path to custom suffix list (replaces default suffixes)
--perm-prefixes		Path to custom prefix list (replaces default prefixes)
--perm-years		Path to custom year list (replaces default years)
--perm-regions		Path to custom region list (replaces default regions)
--domain	-d	Target domain for CT log discovery (as-is mode)

Input Options

s3finder features Decoupled Input Sources. Seeds, wordlists, and domains are processed independently to ensure precise scanning without unwanted combinations.

Seed Keyword (Permuted)

The seed is used to generate 780+ automatic name variations (prefixes, suffixes, regions, etc.). Multi-word or mixed-case seeds are automatically split into variants and each variant is permuted independently.

# Single word or hyphenated — no quotes needed
s3finder -s acme-corp
s3finder -s acmecorp

# Multi-word or mixed-case — quotes required
s3finder -s "Acme Corp"        # → acme-corp, acmecorp, acme, corp, ...
s3finder -s "My Company Name"  # → my-company-name, mycompanyname, my, company, name, ...

# Domain without TLD
s3finder -s example

Note: Quotes are required when the seed contains spaces. Without quotes, the shell treats each word as a separate argument and the command will fail.

Wordlist (Raw Mode)

Wordlists are processed in raw mode. Entries are scanned exactly as they appear in the file, without permutations or seed mixing:

# Use included wordlist
s3finder -w wordlists/common.txt

# Use custom wordlist
s3finder -w /path/to/custom-wordlist.txt

Seed List / PermList

Use --permlist to provide a file where each line is treated as a seed and fully permuted — identical to running --seed for each line.

# Each line in seeds.txt is permuted like --seed
s3finder -p seeds.txt

# seeds.txt example:
acme-corp
MyCompany
amazon web services

Custom Permutation Suffixes

Use --perm-suffixes to replace the default suffix list with your own. This gives you full control over what variations are generated for a seed.

# Use a custom suffix list
s3finder -s acme --perm-suffixes suffixes.txt

# Combine with permlist
s3finder -p seeds.txt --perm-suffixes suffixes.txt

# suffixes.txt example:
-backup
-prod
-tr
-2026
-internal

Note: --perm-suffixes replaces the default suffix list entirely. If you want to keep the defaults, include them in your file.

CT Log Subdomain Discovery (As-Is Mode)

Discovered subdomains are scanned exactly as found in Certificate Transparency logs. Additionally, unique words are extracted from subdomains to generate permutations for deeper scanning:

# Fetch and scan subdomains from CT logs
s3finder -d acme.com

# Combine with a seed for even more coverage
s3finder -s acme -d acme.com

# Limit CT results (default: 100)
s3finder -d acme.com --ct-limit 50

CT logs query crt.sh to find subdomains like dev.acme.com and staging.acme.com. Each subdomain is scanned directly, and unique words (e.g., "dev", "staging") are extracted for additional permutation-based scanning.

Performance Options

Flag	Default	Description
--threads, -t	50	Number of concurrent workers
--rps	150	Maximum requests per second
--timeout	15	Request timeout in seconds

# Conservative scan (slower, less rate limiting)
s3finder -s acme -t 50 --rps 100

# Aggressive scan (faster, may trigger rate limiting)
s3finder -s acme -t 200 --rps 1000

# Custom timeout for slow networks
s3finder -s acme --timeout 30

Inspection Options

Flag	Default	Description
--deep	true	Perform deep inspection on found buckets

Deep inspection uses AWS SDK to gather:

• Bucket region
• ACL status (public-read, private)
• Object count (for public buckets)
• Sample object keys (first 10)

# Disable deep inspection for faster scans
s3finder -s acme --deep=false

Output Options

Flag	Short	Default	Description
--output	-o	results.json	Output file path
--format	-f	json	Output format (json, txt)
--no-color		false	Disable colored output
--verbose	-v	false	Verbose output

# Save as JSON
s3finder -s acme -o scan-results.json

# Save as plain text
s3finder -s acme -o scan-results.txt -f txt

# Pipe-friendly output (no colors)
s3finder -s acme --no-color | tee output.log

# Verbose mode (shows errors)
s3finder -s acme -v

AI Options

See AI Providers for detailed configuration.

Flag	Default	Description
--ai	false	Enable AI-powered name generation
--ai-provider	openai	AI provider (openai, ollama, anthropic, gemini)
--ai-model	gpt-4o-mini	AI model name
--ai-count	50	Number of AI-generated names

Commands

# Show version
s3finder version

# Show help
s3finder --help

# Generate shell completions
s3finder completion bash > /etc/bash_completion.d/s3finder

Examples

Basic Penetration Test

s3finder -s target-corp -w wordlists/common.txt -o pentest-results.json

Bug Bounty Hunting

export OPENAI_API_KEY=sk-xxxxx
s3finder -s bugbounty-target --ai -t 200 --rps 800

Quiet Background Scan

s3finder -s target --no-color -o results.json 2>/dev/null &