jsbucket 2.7.5
A tool to discover S3 buckets from subdomains by analyzing JavaScript files.
Requires Python: >=3.6
Keywords: security, s3, bucket, discovery, javascript, subdomain, bugbounty, pentest

# JSBucket: S3 Bucket Discovery Tool From JavaScript Files

`JSBucket` is a Python-based tool designed to analyze subdomains for Amazon S3 bucket references in JavaScript files. It extracts S3 bucket names and URLs from subdomains and outputs them in a structured JSON format. The tool supports multi-threading, progress tracking, and silent mode for seamless integration with other tools like `jq`, `s3scanner`, etc. This tool is specifically designed for **Bug Bounty Hunters** and **Pentesters**.

---

## Features ⚙️

```shell
usage: jsbucket [-h] [-u SUBDOMAIN] [-d DOMAIN] [-l LIST] [-t THREADS] [-timeout TIMEOUT] [-o OUTPUT] [-header HEADER] [-silent] [-resume]

Analyze JavaScript files from given subdomain(s) for S3 buckets.

options:
  -h, --help            Show this help message and exit
  -u SUBDOMAIN, --subdomain SUBDOMAIN
                        Analyze a single subdomain (e.g., `sub.example.com`)
  -d DOMAIN, --domain DOMAIN
                        Base/root domain (optional, will auto-detect if not provided)
  -l LIST, --list LIST  File containing a list of subdomains (one per line)
  -t THREADS, --threads THREADS
                        Number of threads for concurrent analysis (default: 10)
  -timeout TIMEOUT      Timeout for HTTP requests (default: 10 seconds)
  -o OUTPUT, --output OUTPUT
                        Save results to a JSON file (e.g., `output.json`)
  -header HEADER        Custom header to include in requests (can be used multiple times). Format: 'Header: value'
  -silent               Suppress all output except raw JSON (useful for piping into tools like `jq` or `grep`)
  -resume               Resume previous scan from jsbucket.info file
```
---

## Installation 🚀

### Prerequisites
1. **Python 3.6+**: Ensure Python is installed on your system.
2. **Dependencies**: Install the required libraries using `pip`.

### Steps
```bash
git clone https://github.com/saeed0xf/jsbucket.git
cd jsbucket
pip install -r requirements.txt
```

Alternatively, you can install the tool directly from PyPI:
```bash
pip install jsbucket
```

---

## Usage 📝

### Command Line Interface

Run the script with the desired flags:

```bash
jsbucket [FLAGS]
```

Or if running from source:

```bash
python -m jsbucket [FLAGS]
```

### Python Package

JSBucket can also be used as a Python package in your own scripts:

```python
from jsbucket import analyze_subdomain_for_s3_buckets, analyze_multiple_subdomains

# Analyze a single subdomain
result = analyze_subdomain_for_s3_buckets('example.com')
print(f"Found {len(result['s3_buckets'])} S3 buckets")

# Analyze with custom headers for authenticated scanning
headers = {'Authorization': 'Bearer YOUR_TOKEN', 'User-Agent': 'MyApp/1.0'}
result = analyze_subdomain_for_s3_buckets('api.example.com', headers=headers)

# Analyze multiple subdomains
subdomains = ['api.example.com', 'cdn.example.com']
results = analyze_multiple_subdomains(subdomains, max_threads=5, headers=headers)
```

For detailed package API documentation, see [PACKAGE_API.md](PACKAGE_API.md).

---

## Flags

| Flag            | Description                                                                                   |
|------------------|-----------------------------------------------------------------------------------------------|
| `-u SUBDOMAIN`   | Analyze a single subdomain (e.g., `sub.example.com`).                                          |
| `-d DOMAIN`      | Base/root domain (**optional**, auto-detects if not provided).                                |
| `-l FILE`        | File containing a list of subdomains (one per line).                                           |
| `-t THREADS`     | Number of threads for concurrent analysis (default: 10).                                      |
| `-timeout SECS`  | Timeout for HTTP requests (default: 10 seconds).                                              |
| `-o OUTPUT`      | Save results to a JSON file (e.g., `output.json`).                                            |
| `-header HEADER` | Custom header to include in requests. Can be used multiple times for multiple headers.        |
| `-silent`        | Suppress all output except raw JSON (useful for piping into tools like `jq` or `grep`).       |
| `-resume`        | Resume previous scan from `jsbucket.info` file (continues from last processed subdomain).     |

---

## Examples 🕵️‍♀️

### 1. Analyze a Single Subdomain
```bash
jsbucket -u sub.example.com
```
*Note: Domain is auto-detected as `example.com`*

With explicit domain:
```bash
jsbucket -u sub.example.com -d example.com
```

Or from source:
```bash
python -m jsbucket -u sub.example.com
```

### 2. Analyze a List of Subdomains
```bash
jsbucket -l subdomains.txt
```
*Note: Base domain is auto-detected from the subdomain list*

With explicit domain:
```bash
jsbucket -l subdomains.txt -d example.com
```

### 3. Save Results to a JSON File
```bash
jsbucket -l subdomains.txt -o results.json
```

### 4. Use Silent Mode for Piping
```bash
jsbucket -l subdomains.txt -silent | jq '.[].s3_buckets[].bucket_name'
```

### 5. Customize Threads and Timeout
```bash
jsbucket -l subdomains.txt -t 20 -timeout 30
```

### 6. Custom Headers for Authenticated Scanning
```bash
# Single custom header
jsbucket -u api.example.com -header "Authorization: Bearer YOUR_TOKEN"

# Multiple custom headers
jsbucket -l subdomains.txt -header "Cookie: session=abc123" -header "User-Agent: MyScanner/1.0"

# For authenticated endpoints behind basic auth
jsbucket -u secure.example.com -header "Authorization: Basic dXNlcjpwYXNz"
```

### 7. Resume Interrupted Scans
```bash
# Start a scan (gets interrupted)
jsbucket -l large_subdomains.txt -o results.json

# Resume from where it left off
jsbucket -resume

# Resume works with all original flags
jsbucket -resume  # Will continue with same timeout, threads, headers, etc.
```

### 8. Auto-Detection Examples
```bash
# Single subdomain - auto-detects 'example.com'
jsbucket -u api.example.com

# Multiple subdomains - auto-detects most common domain
jsbucket -l mixed_subdomains.txt
```
---

## Notes 📌

1. **Silent Mode**: Use the `-silent` flag when integrating with tools like `jq` or `s3scanner`. This ensures only raw JSON is printed to `stdout`.
2. **Timeout**: Adjust the `-timeout` value if subdomains take longer to respond.
3. **Threads**: Increase the `-t` value for faster analysis, but be cautious with high thread counts to avoid overwhelming the network or server.

---

## Contributing 🤝

Contributions are welcome! If you find any issues or have suggestions for improvements, feel free to:
- Open an issue.
- Submit a pull request.

---

## License 📜

This project is licensed under the MIT License. See the [LICENSE](https://github.com/saeed0xf/jsbucket/blob/main/LICENSE) file for details.

---

## Contact 💻

For questions, suggestions, or feedback, feel free to reach out:

- Twitter/X: [Saeed0x1](https://x.com/saeed0x1)
- LinkedIn: [Saeed0x1](https://www.linkedin.com/in/saeed0x1)
- GitHub: [saeed0xf](https://github.com/saeed0xf)