Basic Usage

Complete guide to using s3finder command-line options.

Command Syntax

bash

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)
`--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.):

bash

# Company name
s3finder -s acme-corp

# Domain without TLD
s3finder -s example

Wordlist (Raw Mode)

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

bash

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

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

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:

bash

# 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

bash

# 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)

bash

# 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

bash

# 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

bash

# Show version
s3finder version

# Show help
s3finder --help

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

Examples

Basic Penetration Test

bash

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

Bug Bounty Hunting

bash

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

Quiet Background Scan

bash

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