Metadata-Version: 2.4
Name: totalrecon
Version: 0.1.0
Summary: Passive recon extractor and AI summarizer for CTFs, red teams, and open-source recon tooling.
Home-page: https://github.com/josh1643/totalrecon
Author: Joshua Wasserman
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: transformers>=4.25.1
Requires-Dist: torch>=1.10.0
Requires-Dist: requests>=2.28.0
Requires-Dist: PyMuPDF>=1.22.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# totalrecon

[![PyPI version](https://img.shields.io/pypi/v/totalrecon?color=brightgreen)](https://pypi.org/project/totalrecon/)

**totalrecon** is a lightweight Python library for passive reconnaissance. It extracts subdomains, emails, and S3 buckets from text and PDF files, and uses a fine-tuned AI model to summarize sensitive infrastructure mentions.

>  Built for red teamers, bug bounty hunters, CTF players, and cyber analysts.

---

## Features

- Extract intelligence from plaintext and PDF files  
- Detect subdomains, emails, and AWS S3 buckets  
- Summarize recon info with a fine-tuned `flan-t5-small` model  
- Offline and lightweight — no OpenAI key required  
- Trained on synthetic recon examples tailored for real-world use  

---

## Installation

```bash
pip install totalrecon
```

Or from source:

```bash
git clone https://github.com/josh1643/totalrecon.git
cd totalrecon
pip install .
```

---

## Quick Start

### Python Example

```python
from totalrecon.extract import extract_from_text

text = '''
Found subdomain: api.dev.example.com
Email: admin@example.com
S3 bucket: s3://backup-prod-private
'''

results = extract_from_text(text)

print(results["domains"])          # ['api.dev.example.com']
print(results["emails"])           # ['admin@example.com']
print(results["s3_buckets"])       # ['s3://backup-prod-private']
print(results["recon_summaries"])  # ['Possible backup S3 bucket exposed via dev subdomain.']
```

---

## About the Model

This project uses a fine-tuned `FLAN-t5-small` model hosted on the Hugging Face Hub:

🔗 https://huggingface.co/wassermanrjoshua/totalrecon-flan-t5

- Summarizes cyber recon and passive intel  
- Runs **entirely offline** after first load  
- No setup required — model is automatically downloaded on first use

This means:
- You don’t need to clone or manually download any model files
- Just `pip install totalrecon` and run it — the model loads when needed


---

## Contributing

Contributions welcome!  
1. Fork the repo  
2. Create a feature branch  
3. Open a pull request  

---

## License

MIT License — see [`LICENSE`](LICENSE) for full terms.

---

## Author

Created by Joshua Wasserman for real-world recon workflows and open-source tooling.

- GitHub Repository: [https://github.com/josh1643/totalrecon](https://github.com/josh1643/totalrecon)

---
