Metadata-Version: 2.4
Name: reclaimor
Version: 0.1.0
Summary: Advanced subdomain takeover reconnaissance & safe-vulnerability-detection
Home-page: https://github.com/letchupkt/ReClaimor
Author: Lakshmikanthan
Author-email: 
License: MIT
Project-URL: Homepage, https://github.com/letchupkt/ReClaimor
Project-URL: Repository, https://github.com/letchupkt/ReClaimor
Project-URL: Issues, https://github.com/letchupkt/ReClaimor/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiodns>=3.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: dnspython>=2.4.0
Requires-Dist: certifi>=2023.0.0
Requires-Dist: colorama>=0.4.6
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: aioresponses>=0.7.6; extra == "dev"
Provides-Extra: exploit
Requires-Dist: boto3>=1.28.0; extra == "exploit"
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ReClaimor

**Advanced subdomain takeover reconnaissance & safe-vulnerability-detection — smart, fast, and responsibly built.**

Built by [@letchu](https://github.com/letchupkt)

## ⚠️ Legal & Ethical Notice

**BY USING RECLAIMOR YOU CONFIRM YOU HAVE EXPLICIT AUTHORIZATION TO SCAN THE TARGETS.**

This tool is designed for:
- Security researchers with proper authorization
- Bug bounty hunters testing in-scope assets
- Red teamers with client permission
- Organizations testing their own infrastructure

**The authors are not responsible for misuse. Unauthorized scanning is illegal.**

## 🎯 What is ReClaimor?

ReClaimor is a cross-platform Python tool for discovering, validating, and triaging potential subdomain takeover opportunities. It focuses on accurate detection with minimal false positives, comprehensive provider fingerprints, async scanning, and built-in verification capabilities.

## ✨ Features

- **Accurate Detection** - Multi-tier checks with heuristic scoring (DNS, HTTP, TLS analysis)
- **Fast Async Scanning** - Concurrent scanning with connection pooling
- **Multiple Input Modes** - Single URL, file input, or stdin pipe
- **20+ Provider Fingerprints** - AWS S3, Azure, GitHub Pages, Heroku, Netlify, Vercel, and more
- **Auto-Exploitation** - Optional safe verification by attempting takeover (use responsibly!)
- **Safe Mode** - Detection-only mode (default) for passive reconnaissance
- **Detailed Reporting** - JSON, CSV, HTML reports with confidence scores
- **TUI Interface** - Interactive terminal UI for manual triage
- **Webhook Integration** - Slack/Discord notifications for findings
- **Resume Support** - Checkpoint and resume interrupted scans
- **Extensible** - Plugin system for custom providers

## 🚀 Quick Start

### Installation Options

```bash
# Option 1: From source
git clone https://github.com/letchupkt/ReClaimor.git
cd ReClaimor
pip install -e .

# Option 2: From PyPI (when published)
pip install reclaimor

# Option 3: Using Docker
docker pull letchupkt/reclaimor:latest

# Option 4: Download executable
# Download from GitHub Releases
# https://github.com/letchupkt/ReClaimor/releases
```

### Basic Usage

```bash
# Single target scan
reclaimor --url sub.example.com

# Batch scan from file
reclaimor --file targets.txt --concurrency 50

# With auto-exploitation (requires explicit flag)
reclaimor --file targets.txt --auto-exploit --aggressive --output results.json

# Interactive TUI mode
reclaimor --file targets.txt --tui

# Self-check
reclaimor --self-check

# Docker usage
docker run -v $(pwd)/targets.txt:/targets.txt letchupkt/reclaimor --file /targets.txt
```

## 📦 Installation

```bash
# From source
git clone https://github.com/letchupkt/ReClaimor.git
cd ReClaimor
pip install -e .

# Or via pip (when published)
pip install reclaimor
```

**Requirements:** Python 3.10+

## 🔧 Usage Examples

```bash
# Scan single domain (safe mode)
reclaimor --url abandoned.example.com

# Scan from file with custom concurrency
reclaimor --file targets.txt --concurrency 100 --timeout 10

# Pipe from other tools
subfinder -d example.com | reclaimor --stdin

# Auto-exploit vulnerable targets (REQUIRES AUTHORIZATION)
reclaimor --file targets.txt --auto-exploit --aggressive

# Generate HTML report
reclaimor --file targets.txt --output report.html --format html

# With Slack notifications
reclaimor --file targets.txt --webhook https://hooks.slack.com/...

# Resume interrupted scan
reclaimor --file targets.txt --resume scan_checkpoint.json

# Debug mode
reclaimor --url test.example.com --debug --verbose
```

## 📊 Output Formats

- **Console** - Colorized summary with confidence scores
- **JSON** - Machine-readable results
- **CSV** - Spreadsheet-compatible format
- **HTML** - Interactive sortable report

## 🎨 Configuration

Create `~/.reclaimor/config.yaml`:

```yaml
concurrency: 50
timeout: 15
retries: 3
user_agent: "ReClaimor/0.1.0"
safe_mode: true
rate_limit: 10  # requests per second
webhook_url: ""
fingerprints_dir: "~/.reclaimor/fingerprints"
```

## 🔌 Plugins

Add custom provider checks in `~/.reclaimor/plugins/`:

```python
# custom_provider.py
from reclaimor.plugins import BaseProvider

class MyProvider(BaseProvider):
    name = "CustomCloud"
    
    async def check(self, domain, response):
        if "custom error" in response.text:
            return {"vulnerable": True, "confidence": 85}
        return {"vulnerable": False}
```

## 🧪 Testing

```bash
# Run tests
pytest

# With coverage
pytest --cov=reclaimor

# Integration tests (CI only)
pytest --integration
```

## 🐳 Docker

```bash
# Build
docker build -t reclaimor .

# Run
docker run -v $(pwd)/targets.txt:/targets.txt reclaimor --file /targets.txt
```

## 📚 Provider Support

Currently supports 20+ providers including:
- AWS S3, CloudFront
- Azure Blob Storage, CDN
- GitHub Pages
- Heroku
- Netlify
- Vercel
- Fastly
- Shopify
- Tumblr
- WordPress.com
- And more...

## 🛡️ Safety Features

- **Safe Mode (Default)** - Detection only, no exploitation
- **Explicit Flags Required** - `--auto-exploit` and `--aggressive` must be set
- **Rate Limiting** - Prevents accidental DoS
- **Permission Checklist** - Prints before scanning
- **No Destructive Actions** - Even in exploit mode, only safe verification

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 Responsible Disclosure

If you find vulnerabilities using ReClaimor, please follow responsible disclosure:
1. Notify the asset owner privately
2. Allow reasonable time for remediation (90 days recommended)
3. Do not publicly disclose until fixed

## 📄 License

MIT License - see [LICENSE](LICENSE)

## 👤 Author

**Lakshmikanthan (@letchu)**
- GitHub: [@letchupkt](https://github.com/letchupkt)
- Issues: [GitHub Issues](https://github.com/letchupkt/ReClaimor/issues)

## 🙏 Acknowledgments

Built with security research community best practices in mind.

---

**Version:** 0.1.0  
**Status:** Active Development
