AI-Powered S3 Bucket Enumeration Tool

Documentation • Installation • Quick Start • Features

A high-performance CLI tool for discovering AWS S3 buckets using intelligent name generation. Decouples input sources for precise control: permutations only apply to the provided seed, while wordlists and CT logs are processed as raw inputs.

• Decoupled Input Sources Independent handling of seeds, wordlists, and domains (no cross-contamination)
• Optional Seed Scan using only a wordlist or domain without requiring a seed keyword
• High-Concurrency Scanning Worker pool architecture handles thousands of requests simultaneously
• CT Log Reconnaissance Discover subdomains via Certificate Transparency logs (crt.sh) with automatic word extraction
• AI-Powered Generation OpenAI, Ollama, Anthropic, or Gemini generate context-aware bucket name variations
• Permutation Engine 780+ automatic variations per seed (suffixes, prefixes, years, regions)
• Adaptive Rate Limiting AIMD algorithm auto-adjusts to avoid throttling and IP blocks
• Deep Inspection AWS SDK integration reveals region, ACL status, and sample objects
• Live Progress Bar Real-time TUI showing scanned count, RPS, ETA, and discovery stats
• HTTP/2 & Connection Pooling Optimized networking with keep-alives and connection reuse
• Smart Retry Logic Automatic retries with exponential backoff for transient failures
• Custom DNS Resolver Uses Google/Cloudflare DNS to prevent local resolver saturation
• Multiple Formats Export results as JSON or TXT for post-processing
• Cross-Platform Native binaries for Linux, macOS, and Windows (amd64 & arm64)

Download the latest release for your platform:

brew install xeloxa/tap/s3finder

go install github.com/xeloxa/s3finder/cmd/s3finder@latest

git clone https://github.com/xeloxa/s3finder.git
cd s3finder

# Build for current platform
make build

# Build for all platforms
make build-all

# Or use go directly
go build -o s3finder ./cmd/s3finder

# Basic scan with permutations of a seed
s3finder -s acme-corp

# Scan using ONLY a wordlist (no permutations)
s3finder -w wordlist.txt

# Scan using ONLY a domain (CT log discovery)
s3finder -d acme.com

# Combined independent sources
s3finder -s acme -w custom.txt -d acme.com

# High-speed scan
s3finder -s acme-corp -t 200 --rps 1000

# Scan with 780+ permutations of a seed keyword
s3finder -s acme-corp

# Multi-word or mixed-case seeds are automatically split into variants
s3finder -s "Acme Corp"        # → acme-corp, acmecorp, acme, corp, ...
s3finder -s "My Company Name"  # → my-company-name, mycompanyname, my, company, name, ...

# Quotes are required when the seed contains spaces
# Single word or hyphenated seeds don't need quotes
s3finder -s acme-corp
s3finder -s acmecorp

Wordlists are now processed as raw inputs. They are not combined with the seed or permuted, giving you exact control over what is scanned.

# Scan exactly what is in the wordlist
s3finder -w wordlists/common.txt

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

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

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

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

Discovered subdomains are scanned exactly as they appear in Certificate Transparency logs. Unique words are extracted from subdomains and used to generate additional permutations for deeper scanning.

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

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

AI generation analyzes CT log patterns and generates bucket names matching organizational naming conventions.

# OpenAI (default: gpt-4o-mini)
export OPENAI_API_KEY=sk-xxxxx
s3finder -s acme-corp --ai

# Anthropic Claude (default: claude-3-5-haiku-20241022)
export ANTHROPIC_API_KEY=sk-ant-xxxxx
s3finder -s acme-corp --ai --ai-provider anthropic

# Google Gemini (default: gemini-3-flash-preview)
export GEMINI_API_KEY=xxxxx
s3finder -s acme-corp --ai --ai-provider gemini

# Ollama local (default: llama3.2)
s3finder -s acme-corp --ai --ai-provider ollama

# Context-aware: combine with CT logs for pattern discovery
s3finder -s acme -d acme.com --ai

# Aggressive scan with 200 workers and 1000 RPS
s3finder -s acme-corp -t 200 --rps 1000

# JSON report (default)
s3finder -s acme-corp -o results.json

# Plain text report
s3finder -s acme-corp -o results.txt -f txt

# Disable colors (for piping)
s3finder -s acme-corp --no-color

# Build for current platform
make build

# Build for all platforms (Linux, macOS, Windows × amd64, arm64)
make build-all

# Build for specific platform
make build-linux
make build-darwin
make build-windows

# Run tests
make test

# Run tests with coverage
make test-cover

# Create release archives
make release

# Clean build artifacts
make clean

# Show all available commands
make help

     ____  _____  __ _           _
    / ___|___ / / _(_)_ __   __| | ___ _ __
    \___ \ |_ \| |_| | '_ \ / _` |/ _ \ '__|
     ___) |__) |  _| | | | | (_| |  __/ |
    |____/____/|_| |_|_| |_|\__,_|\___|_|
                                        v1.2.4
    AI-Powered S3 Bucket Enumeration Tool
    ─────────────────────────────────────────

Permutation engine generated 780 names
AI (openai) generated 48 names
Generated 828 unique bucket names to scan

[PUBLIC] acme-corp-backup (objects: 1547, region: us-east-1)
         https://acme-corp-backup.s3.amazonaws.com
[PRIVATE] acme-corp-internal (region: eu-west-1)
[PUBLIC] acme-corp-assets-2024 (objects: 100+, region: us-west-2)
         https://acme-corp-assets-2024.s3.amazonaws.com

[████████████████████████████████] 100.0% [828/828] Public:2 Private:1 Err:0 145 r/s ETA:0s [2m34s]

────────────────────────────────────────
Scan completed in 2m34s
Scanned: 828 | Found: 3 | Public: 2 | Private: 1 | Errors: 0
Results saved to: results.json

During scanning, a live TUI progress bar displays real-time statistics:

• Visual progress - Fill bar showing scan completion percentage
• Scanned count - Current/total buckets scanned
• Public/Private/Errors - Real-time discovery counts
• RPS - Current requests per second
• ETA - Estimated time remaining
• Elapsed time - Total time since scan started

{
  "generated_at": "2025-01-12T15:30:00Z",
  "scan_duration": "2m34s",
  "total_found": 3,
  "public_buckets": 2,
  "private_buckets": 1,
  "results": [
    {
      "bucket": "acme-corp-backup",
      "probe_result": "public",
      "inspect": {
        "bucket": "acme-corp-backup",
        "exists": true,
        "is_public": true,
        "acl": "public-read",
        "region": "us-east-1",
        "object_count": 1547,
        "sample_keys": ["db-dump.sql", "config.yml", "backup-2024.tar.gz"]
      }
    }
  ]
}

Windows:

• ANSI colors are enabled automatically on Windows 10+
• Use PowerShell or Windows Terminal for best experience
• Legacy cmd.exe may not display colors correctly

macOS:

• Both Intel and Apple Silicon are natively supported
• No Rosetta required for M1/M2/M3 Macs

Linux:

• Works on all major distributions
• ARM64 builds for Raspberry Pi and AWS Graviton

┌─────────────────────────────────────────────────────────────────┐
│                         SCANNER ORCHESTRATOR                     │
├─────────────────────────────────────────────────────────────────┤
│  Wordlist → AI Generator → Permutation Engine                   │
│                             │                                    │
│                             ▼                                    │
│                   ┌──────────────────┐                          │
│                   │   names channel   │                          │
│                   └────────┬─────────┘                          │
│         ┌──────────────────┼──────────────────┐                 │
│         ▼                  ▼                  ▼                 │
│   ┌──────────┐       ┌──────────┐       ┌──────────┐           │
│   │ Worker 1 │       │ Worker 2 │       │ Worker N │           │
│   └────┬─────┘       └────┬─────┘       └────┬─────┘           │
│        └──────────────────┼──────────────────┘                  │
│                           ▼                                     │
│              ┌───────────────────────────┐                      │
│              ▼                           ▼                      │
│     ┌─────────────┐              ┌─────────────┐                │
│     │  Inspector  │              │   Output    │                │
│     │ (AWS SDK)   │              │   Writer    │                │
│     └─────────────┘              └─────────────┘                │
└─────────────────────────────────────────────────────────────────┘

s3finder/
├── cmd/s3finder/          # CLI entrypoint
├── pkg/
│   ├── scanner/           # Worker pool, prober, inspector
│   ├── ai/                # LLM providers (OpenAI, Ollama, Anthropic, Gemini)
│   ├── recon/             # CT log reconnaissance (crt.sh)
│   ├── permutation/       # Name generation engine
│   ├── ratelimit/         # Adaptive AIMD rate limiter
│   └── output/            # Real-time + report writers
├── internal/config/       # Configuration management
├── wordlists/             # Default wordlists
├── Makefile               # Build automation
└── .goreleaser.yaml       # Release automation

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (make test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

This tool is intended for authorized security testing and research purposes only. Only scan buckets belonging to organizations you have explicit permission to test. Unauthorized access to AWS resources is illegal.

Apache License 2.0 - see LICENSE for details.