Metadata-Version: 2.4
Name: user-scanner
Version: 1.3.6
Summary: Check username availability across multiple popular platforms
Keywords: username,checker,availability,social,tech,python,user-scanner
Author-email: Kaif <kaifcodec@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]>=0.27,<0.29
Requires-Dist: socksio>=1.0,<2
Requires-Dist: colorama>=0.4,<1
Project-URL: Homepage, https://github.com/kaifcodec/user-scanner

# User Scanner

![User Scanner Logo](https://github.com/user-attachments/assets/49ec8d24-665b-4115-8525-01a8d0ca2ef4)
<p align="center">
  <img src="https://img.shields.io/badge/Version-1.3.6-blueviolet?style=for-the-badge&logo=github" />
  <img src="https://img.shields.io/github/issues/kaifcodec/user-scanner?style=for-the-badge&logo=github" />
  <img src="https://img.shields.io/badge/Tested%20on-Termux-black?style=for-the-badge&logo=termux" />
  <img src="https://img.shields.io/badge/Tested%20on-Windows-cyan?style=for-the-badge&logo=Windows" />
  <img src="https://img.shields.io/badge/Tested%20on-Linux-black?style=for-the-badge&logo=Linux" />
  <img src="https://img.shields.io/pypi/dm/user-scanner?style=for-the-badge" />
</p>

---
A powerful **2-in-1 OSINT suite** combining deep **Email OSINT** with comprehensive **Username Scanning**. 

With **195+ total scan vectors**—including **95+ email-integrated sites** and **100+ username platforms**—you can identify digital footprints or verify account registrations in seconds.

The ultimate tool for finding a **unique username** across GitHub, X, Reddit, Instagram, and more in a single command.


## Features

- ✅ Email & username OSINT: check email registrations and username availability across social, developer, creator, and other platforms  
- ✅ Dual-mode usage: works as an email scanner, username scanner, or username-only tool  
- ✅ Clear results: `Registered` / `Not Registered` for emails and `Not Found` / `Found` / `Error` for usernames with precise failure reasons  
- ✅ Fully modular architecture for easy addition of new platform modules  
- ✅ Bulk scanning support for usernames and emails via input files  
- ✅ Wildcard-based username permutations with automatic variation generation  
- ✅ Multiple output formats: console, **JSON**, and **CSV**, with file export support  
- ✅ Proxy support with rotation and pre-scan proxy validation  
- ✅ Smart auto-update system with interactive upgrade prompts via PyPI  

## Virtual Environment (optional but recommended)

```bash
# create venv
python -m venv .venv
````
## Activate venv
```bash
# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
```
## Installation
```bash
# upgrade pip
python -m pip install --upgrade pip

# install
pip install user-scanner
```
---
### Important Flags

See [Important flags](docs/FLAGS.md) here and use the tool powerfully


## Usage

### Basic username/email scan

Scan a single email or username across **all** available modules/platforms:

```bash
user-scanner -e johndoe@gmail.com   # single email scanning 
user-scanner -u johndoe             # single username scanning 
```
### Verbose mode 

Use `-v` flag to show the url of the sites being checked
```bash
user-scanner -v -e johndoe@gmail.com -c dev
```
Output:
```sh
  ...
  [✔] Huggingface [https://huggingface.co] (johndoe@gmail.com): Registered
  [✔] Envato [https://account.envato.com] (johndoe@gmail.com): Registered
  [✔] Replit [https://replit.com] (johndoe@gmail.com): Registered
  [✔] Xda [https://xda-developers.com] (johndoe@gmail.com): Registered
  ...
```

### Selective scanning

Scan only specific categories or single modules:

```bash
user-scanner -u johndoe -c dev                # developer platforms only
user-scanner -e johndoe@gmail.com -m github   # only GitHub
```

### Bulk email/username scanning

Scan multiple emails/usernames from a file (one email/username per line):
- Can also be combined with categories or modules using `-c` , `-m` and other flags

```bash
user-scanner -ef emails.txt     # bulk email scan
user-scanner -uf usernames.txt  # bulk username scan
```

### Pattern generation
See [Pattern Syntax](docs/PATTERNS.md) for more details

---
### Library mode for email_scan
Only available for `user-scanner>=1.2.0`

See full usage (eg. category checks, full scan) guide [library usage](docs/USAGE.md)

- Email scan example (single module):

```python

import asyncio
from user_scanner.core import engine
from user_scanner.email_scan.learning import vedantu

async def main():
    # Engine detects 'email_scan' path -> returns "Registered" status
    result = await engine.check(vedantu, "test@gmail.com")
    json_data = result.to_json() # returns JSON output
    csv_data = result.to_csv()   # returns CSV output
    print(json_data)             # prints the json data

asyncio.run(main())

```
Output:

```json

{
        "email": "test@gmail.com",
        "category": "Learning",
        "site_name": "Vedantu",
        "status": "Registered",
        "url": "https://www.vedantu.com",
        "extra": "Phone: +9121****83",
        "reason": ""
}
```
---


### Using Proxies

Validate proxies before scanning (tests each proxy against google.com):

```bash
user-scanner -u johndoe -P proxies.txt --validate-proxies # recommended
```

This will:
1. Filter out non-working proxies
2. Save working proxies to `validated_proxies.txt`
3. Use only validated proxies for scanning

### Screenshots:
**Note**: Screenshots might be outdated

---
<img width="1080" height="1350" alt="1000175086" src="https://github.com/user-attachments/assets/c90396d6-b8d9-4ea3-aac4-d2086f9b5756" />


---
<img width="1080" height="730" alt="1000175084" src="https://github.com/user-attachments/assets/b399b924-6c4a-4b5b-af0d-67f7c0b39436" />

---

- Use the `--hudson` flag to check if a **username** or **email** has been exposed in **infostealer malware logs**.

```bash
user-scanner -e johndoe@gmail.com --hudson   # for email check
user-scanner -u johndoe --hudson             # for username check
```
<img width="1080" height="844" alt="1000183041" src="https://github.com/user-attachments/assets/366d4697-b94b-40b2-9844-f936b6fcea7f" />

---
## ❤️ Support the project

If this project helps you, consider supporting its development:

**BTC (SegWit):** `bc1q0dzkuav8lq9lwu7gc457vwlda4utfcr5hpv7ka`


---
## Contributing

See detailed [Contributing guidelines](CONTRIBUTING.md)

---

## ⚠️ Disclaimer

This tool is provided for **educational purposes** and **authorized security research** only.

- **User Responsibility:** Users are solely responsible for ensuring their usage complies with all applicable laws and the Terms of Service (ToS) of any third-party providers.
- **Methodology:** The tool interacts only with **publicly accessible, unauthenticated web endpoints**. It does not bypass authentication, security controls, or access private user data.
- **No Profiling:** This software performs only basic **yes/no availability checks**. It does not collect, store, aggregate, or analyze user data, behavior, or identities.
- **Limitation of Liability:** The software is provided **“as is”**, without warranty of any kind. The developers assume no liability for misuse or any resulting damage or legal consequences.

---

## 🛠️ Troubleshooting

Some sites may return **403 Forbidden** or **connection timeout** errors, especially if they are blocked in your region (this is common with some adult sites).

- If a site is blocked in your region, use a VPN and select a region where you know the site is accessible.
- Then run the tool again.

These issues are caused by regional or network restrictions, not by the tool itself. If it still fails, report the error by opening an issue.

