Metadata-Version: 2.4
Name: cyber-find
Version: 0.3.5
Summary: Advanced OSINT tool for searching users across 200+ platforms
Author-email: vazor <vazorcode@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/VAZlabs/cyber-find
Project-URL: Documentation, https://github.com/VAZlabs/cyber-find/wiki
Project-URL: Repository, https://github.com/VAZlabs/cyber-find.git
Project-URL: Issues, https://github.com/VAZlabs/cyber-find/issues
Keywords: osint,cybersecurity,search,social-media,reconnaissance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: cloudscraper>=1.2.71
Requires-Dist: fake-useragent>=1.4.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: customtkinter>=5.2.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: dnspython>=2.4.0
Requires-Dist: validators>=0.22.0
Requires-Dist: tqdm>=4.66.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.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: advanced
Requires-Dist: python-whois>=0.8.0; extra == "advanced"
Requires-Dist: selenium>=4.15.0; extra == "advanced"
Requires-Dist: waybackpy>=3.0.6; extra == "advanced"
Dynamic: license-file

# 🕵️ CyberFind

<p align="center">
  <strong>Production-ready OSINT toolkit for digital footprint discovery</strong><br>
  <em>Search by username, email, or phone across 200+ platforms</em>
</p>

<p align="center">

[![PyPI version](https://img.shields.io/pypi/v/cyber-find?style=for-the-badge&logo=pypi&label=PyPI&color=blue)](https://pypi.org/project/cyber-find/)
[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-2ea44f?style=for-the-badge)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/VAZlabs/cyber-find/tests.yml?style=for-the-badge&label=CI&logo=github)](https://github.com/VAZlabs/cyber-find/actions)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000?style=for-the-badge)](https://github.com/psf/black)

</p>

<p align="center">
  <a href="#-quick-start"><strong>Quick Start</strong></a> ·
  <a href="#-features"><strong>Features</strong></a> ·
  <a href="#-documentation"><strong>Documentation</strong></a> ·
  <a href="#-api"><strong>API</strong></a> ·
  <a href="#-gui"><strong>GUI</strong></a>
</p>

---

## 🎯 What is CyberFind?

**CyberFind** is a comprehensive OSINT (Open Source Intelligence) tool designed for security researchers, investigators, and analysts. It automates the process of searching for user accounts across hundreds of websites, helping you map digital presence efficiently.

```
┌─────────────────────────────────────────────────────────────┐
│                    CYBERFIND v0.3.5                         │
│              Advanced OSINT Search Tool                     │
├─────────────────────────────────────────────────────────────┤
│  🔍 Username Search    |  📧 Email Lookup    |  📱 Phone   │
│  🌐 Domain Analysis    |  🔐 Verification    |  💾 Cache   │
│  📊 Multi-format Export|  🖥️ CLI • API • GUI               │
└─────────────────────────────────────────────────────────────┘
```

### ✨ Why Choose CyberFind?

| Feature | Benefit |
|---------|---------|
| ⚡ **Lightning Fast** | Async engine with configurable concurrency (up to 100+ threads) |
| 🎯 **Precise** | Account verification to confirm found profiles still exist |
| 💾 **Smart Caching** | SQLite-based caching avoids redundant searches |
| 📊 **Rich Exports** | 7 output formats: JSON, CSV, HTML, Excel, SQLite, TXT, Markdown |
| 🔧 **Flexible** | 4 search modes, custom headers, proxy support (via config) |
| 🖥️ **Multi-Interface** | CLI for automation, API for integration, GUI for analysts |

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install cyber-find
```

**Commands available after installation:**

| Command | Description |
|---------|-------------|
| `cyberfind` | Main CLI tool |
| `cyberfind-api` | REST API server |
| `cyberfind-gui` | Desktop graphical interface |

### From Source

```bash
git clone https://github.com/VAZlabs/cyber-find.git
cd cyber-find
pip install -e .
```

### Verify Installation

```bash
cyberfind --version
cyberfind --help
```

---

## ⚡ Quick Start

### Basic Username Search

```bash
# Search single username (uses 'quick' list - 25 popular sites)
cyberfind john_doe

# Search multiple usernames
cyberfind user1 user2 user3

# Search with specific site list
cyberfind username --list social_media
```

### Email & Phone Search

```bash
# Search by email
cyberfind --email target@example.com --list email

# Search by phone (E.164 format)
cyberfind --phone +1234567890 --list phone
```

### Save Results

```bash
# Save as HTML report
cyberfind username --format html -o report

# Save as Excel spreadsheet
cyberfind username --format excel -o results

# Save as Markdown
cyberfind username --format md -o report
```

---

## 📖 Documentation

### CLI Reference

<details>
<summary><strong>View all CLI options</strong></summary>

```bash
cyberfind --help

# Show built-in site lists
cyberfind --show-lists

# Search modes
cyberfind username --mode standard   # Balanced (default)
cyberfind username --mode deep       # Thorough investigation
cyberfind username --mode stealth    # Low-profile requests
cyberfind username --mode aggressive # Maximum speed

# Performance tuning
cyberfind username --threads 50 --timeout 15

# Custom sites file
cyberfind username -f sites/my_sites.txt

# CI/log friendly output
cyberfind username --format json --no-color -o results
```

</details>

### 🔍 Search Modes

| Mode | Speed | Coverage | Stealth | Use Case |
|------|-------|----------|---------|----------|
| `standard` | ⚡⚡⚡ | 📊📊📊 | 🥷🥷🥷 | Everyday searches |
| `deep` | ⚡⚡ | 📊📊📊📊 | 🥷🥷 | Comprehensive investigations |
| `stealth` | ⚡ | 📊📊 | 🥷🥷🥷🥷🥷 | Covert operations |
| `aggressive` | ⚡⚡⚡⚡⚡ | 📊📊📊 | 🥷 | Time-critical tasks |

### 📋 Built-in Site Lists

| List | Sites | Category |
|------|-------|----------|
| `quick` | 25 | Most popular platforms |
| `social_media` | 55+ | Facebook, Twitter, Instagram, LinkedIn, etc. |
| `programming` | 25+ | GitHub, GitLab, StackOverflow, etc. |
| `gaming` | 20+ | Steam, Xbox, PlayStation, etc. |
| `blogs` | 20+ | Medium, WordPress, Blogger, etc. |
| `ecommerce` | 20+ | Amazon, eBay, Etsy, etc. |
| `forums` | 12+ | Reddit, Quora, etc. |
| `russian` | 18+ | VK, Odnoklassniki, Yandex, etc. |
| `email` | 31+ | Gmail, Outlook, Yahoo, etc. |
| `phone` | 31+ | Phone directories |

### 📊 Output Formats

| Format | Extension | Best For |
|--------|-----------|----------|
| `json` | `.json` | Automation & integrations |
| `csv` | `.csv` | Spreadsheet processing |
| `html` | `.html` | Human-readable reports |
| `excel` | `.xlsx` | Analyst workflows |
| `sqlite` | `.db` | Local database & queries |
| `txt` | `.txt` | Lightweight logs |
| `markdown` | `.md` | Documentation |

---

## 🆕 New Features in v0.3.5

### 🔐 Account Verification

Re-verify found accounts to confirm they still exist:

```bash
cyberfind username --verify
```

**Output:**
```
Verifying found accounts...
Verification complete: 12 still exist, 3 not found, 1 errors
```

### 💾 Result Caching

Cache search results to avoid redundant searches (TTL: 1 hour):

```bash
# Search with caching enabled (default)
cyberfind username

# Disable caching
cyberfind username --no-cache

# Clear old cache entries
cyberfind --clear-cache
```

### 🏷️ Custom HTTP Headers

Use custom headers for authenticated requests:

```bash
cyberfind username --custom-headers '{"Authorization": "Bearer token"}'
```

### 🌐 Domain Analysis

Analyze domains and discover subdomains:

```bash
# Full domain analysis with security score
cyberfind --domain example.com

# Find subdomains
cyberfind --domain example.com --subdomains

# Save domain report
cyberfind --domain example.com -o domain_report
```

**Domain Report Includes:**
- ✅ Domain existence & IP address
- 🔒 SSL certificate validation
- 🤖 robots.txt analysis
- 📜 security.txt (RFC 9116)
- 🛡️ Security score (0-100) with recommendations

---

## 🔌 API

### Start the API Server

```bash
cyberfind --api
# or
cyberfind-api
```

**Default address:** `http://localhost:8080`

### Available Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Service metadata |
| `/search` | POST | Run search |
| `/stats` | GET | SQLite statistics |

### Example Request

```python
import requests

response = requests.post("http://localhost:8080/search", json={
    "usernames": ["target_user"],
    "builtin_list": "social_media",
    "mode": "standard",
    "output_format": "json",
    "max_concurrent": 50,
})

print(response.json())
```

### Example Response

```json
{
  "status": "success",
  "results": {
    "target_user": {
      "found": [
        {
          "site": "twitter",
          "url": "https://twitter.com/target_user",
          "status_code": 200,
          "metadata": {"category": "social_media"}
        }
      ],
      "errors": []
    }
  },
  "statistics": {
    "total_checks": 55,
    "found_accounts": 12,
    "errors": 2
  }
}
```

---

## 🖼️ GUI

Launch the graphical interface for manual investigations:

```bash
cyberfind --gui
# or
cyberfind-gui
```

**GUI Features:**
- 🎯 Easy target input
- ▶️ One-click search
- 📊 Real-time progress
- 🔍 Interactive results browser
- 💾 Export buttons

---

## ⚙️ Configuration

Create `config.yaml` for custom settings:

```yaml
general:
  timeout: 30
  max_threads: 50
  retry_attempts: 3
  retry_delay: 2
  user_agents_rotation: true
  rate_limit_delay: 0.5

proxy:
  enabled: false
  list: []
  rotation: true

database:
  sqlite_path: "cyberfind.db"

output:
  default_format: "json"
  save_all_results: true

advanced:
  metadata_extraction: true
  cache_results: true
  verify_ssl: true
```

Use custom config:
```bash
cyberfind username --config /path/to/config.yaml
```

---

## 🛠️ Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/VAZlabs/cyber-find.git
cd cyber-find

# Install dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install
```

### Code Quality

```bash
# Format code
black cyber_find tests
isort cyber_find tests

# Linting
flake8 cyber_find tests

# Type checking
mypy -p cyber_find --ignore-missing-imports

# Tests
pytest tests/ -v --cov=cyber_find
```

---

## ❓ FAQ

<details>
<summary><strong>How many sites does CyberFind search?</strong></summary>

CyberFind includes 10+ built-in lists ranging from 25 sites (`quick`) to 55+ sites (`social_media`). You can also create custom site lists by combining multiple lists or creating your own `.txt` file.
</details>

<details>
<summary><strong>Is CyberFind legal to use?</strong></summary>

Yes, CyberFind only searches publicly available information. However, you are responsible for using it lawfully and ethically. Always comply with terms of service and applicable laws.
</details>

<details>
<summary><strong>Why are some searches slow?</strong></summary>

Search speed depends on network conditions, target site response times, and concurrency settings. Use `--threads` to increase parallelism and `--timeout` to limit wait time.
</details>

<details>
<summary><strong>Can I use proxies?</strong></summary>

Yes, configure proxies in `config.yaml`. Proxy rotation is supported.
</details>

---

## ⚠️ Troubleshooting

### Unicode Banner Issues on Windows

```powershell
$env:PYTHONIOENCODING='utf-8'
python -m cyber_find.cli --help
```

Or disable colors:
```bash
cyberfind username --no-color
```

### Import Errors

```bash
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Use module directly
python -m cyber_find.cli
```

---

## ⚖️ Legal & Ethics

> **⚠️ Important:** Use CyberFind only for lawful and ethical OSINT activities. This tool is designed for security research, threat intelligence, and authorized investigations. You are solely responsible for how you use this tool.

**Recommended Use Cases:**
- ✅ Security audits (with authorization)
- ✅ Threat intelligence gathering
- ✅ Personal digital footprint analysis
- ✅ Missing person investigations (authorized)
- ✅ Brand protection & impersonation detection

**Prohibited Use Cases:**
- ❌ Stalking or harassment
- ❌ Unauthorized surveillance
- ❌ Doxxing
- ❌ Violation of terms of service

---

## 📊 Project Stats

| Metric | Value |
|--------|-------|
| **Total Sites** | 200+ |
| **Search Modes** | 4 |
| **Output Formats** | 7 |
| **Python Versions** | 3.9, 3.10, 3.11, 3.12 |
| **License** | MIT |

---

## 🔗 Links

| Resource | Link |
|----------|------|
| 📦 **Repository** | https://github.com/VAZlabs/cyber-find |
| 🐛 **Issues** | https://github.com/VAZlabs/cyber-find/issues |
| 📦 **PyPI** | https://pypi.org/project/cyber-find/ |
| 📝 **Changelog** | [CHANGELOG.md](CHANGELOG.md) |
| 📜 **License** | [LICENSE](LICENSE) |

---

<p align="center">
  <strong>Made with ❤️ by VAZlabs</strong><br>
  <em>Empowering security researchers with open-source tools</em>
</p>

<p align="center">
  <a href="https://github.com/VAZlabs/cyber-find/stargazers">⭐ Star this project</a>
  ·
  <a href="https://github.com/VAZlabs/cyber-find/issues">🐛 Report a bug</a>
  ·
  <a href="https://github.com/VAZlabs/cyber-find/discussions">💬 Start a discussion</a>
</p>
