RavenTrace

Advanced OSINT Intelligence Tool

Powerful OSINT reconnaissance tool for Email, Phone, and Username investigations

Features • Installation • Usage • Documentation • Contributing

🎯 Overview

RavenTrace is a comprehensive Open Source Intelligence (OSINT) gathering tool designed for cybersecurity professionals, researchers, and investigators. It provides deep reconnaissance capabilities across multiple data sources to gather intelligence on email addresses, phone numbers, and usernames.

🌟 Key Highlights

🔍 Multi-Vector Search: Simultaneous investigation across emails, phones, and usernames
⚡ Real-Time Data: Live queries to 20+ platforms and APIs
🛡️ Privacy-Focused: Responsible data gathering with rate limiting
📊 Smart Caching: SQLite-based intelligent caching system
🎨 Beautiful CLI: Rich terminal interface with interactive mode
📈 Confidence Scoring: AI-powered result reliability assessment

✨ Features

📧 Email Intelligence

✅ Reputation Analysis (EmailRep.io integration)
✅ DNS Records Investigation (MX, SPF, DMARC verification)
✅ Data Breach Detection (Have I Been Pwned API)
✅ Social Media Discovery (LinkedIn, GitHub, Twitter)
✅ Domain WHOIS Lookup
✅ Email Pattern Analysis

📱 Phone Intelligence

✅ Carrier Identification (Global carrier detection)
✅ Geographic Location (Country, region, timezone)
✅ Reputation Checking (TrueCaller, NumVerify)
✅ VoIP Detection (Identify virtual numbers)
✅ Data Broker Search (WhitePages, Spokeo)
✅ Spam Report Analysis

👤 Username Intelligence

✅ 20+ Platform Search (Social media presence)
✅ GitHub Deep Dive (Repos, followers, activity)
✅ Reddit Analysis (Karma, posts, communities)
✅ Developer Platforms (StackOverflow, Dev.to, Medium)
✅ Gaming Platforms (Steam, Discord, Twitch)
✅ Professional Networks (LinkedIn, GitLab)

🔧 Advanced Features

🚀 Parallel Processing (ThreadPoolExecutor optimization)
💾 Smart Cache System (24-hour TTL, SQLite backend)
📊 Multiple Export Formats (JSON, CSV, HTML reports)
🎯 Confidence Scoring (Result reliability metrics)
📝 Detailed Reporting (Professional HTML reports)
🔄 Rate Limit Protection (Respectful API usage)
🎭 User-Agent Rotation (Anti-detection measures)

🚀 Installation

Prerequisites

Python 3.8 or higher
pip package manager
Git
Kali Linux (recommended) or similar Linux distribution

Quick Install

Run the automated installation script:

# Clone the repository
git clone https://github.com/Nyx-Off/RavenTrace.git
cd RavenTrace

# Run the complete installation script
./install.sh

The script will automatically:

✅ Install system dependencies and Kali tools
✅ Create a Python virtual environment
✅ Install all Python dependencies
✅ Install OSINT tools (theHarvester, Sherlock, holehe, maigret, PhoneInfoga)
✅ Set up the environment for immediate use

Manual Installation

If you prefer manual setup:

# 1. Install system dependencies
sudo apt update
sudo apt install python3-pip python3-venv git curl whois dnsutils nmap dmitry whatweb pipx

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Install OSINT tools (optional)
pipx install sherlock-project
pipx install holehe
pipx install maigret

Dependencies

Core dependencies include:

requests - HTTP library
beautifulsoup4 - HTML parsing
phonenumbers - Phone number validation
email-validator - Email validation
rich - Terminal formatting
click - CLI framework
dnspython - DNS lookups

📖 Usage

Command Line Interface

Basic Commands

# Email search
raven-trace email user@example.com

# Phone search
raven-trace phone +33612345678 --country FR

# Username search
raven-trace username john_doe

# Batch search
raven-trace batch user@example.com john_doe +33612345678

Advanced Options

# Deep scan with all sources
raven-trace email user@example.com --deep

# Export results
raven-trace username john_doe --export json
raven-trace email user@example.com --export html

# Interactive mode
raven-trace interactive

Interactive Mode

Launch the interactive terminal UI:

raven-trace interactive

Features:

🎨 Beautiful menu interface
🔍 Guided search workflows
📊 Real-time results display
💾 Automatic result saving
⚙️ Configuration management

Python API

from core.engine import SearchEngine

# Initialize engine
engine = SearchEngine()

# Email search
email_results = engine.search_email("target@example.com", deep_scan=True)
print(f"Confidence: {email_results['confidence']}%")
print(f"Breaches found: {len(email_results['breaches'])}")

# Username search
username_results = engine.search_username("john_doe")
print(f"Profiles found: {username_results['profiles_found']}")

# Phone search
phone_results = engine.search_phone("+33612345678", country="FR")
print(f"Carrier: {phone_results['carrier_info']['carrier']}")

# Export results
engine.export_results(email_results, format_type='html', filepath='report.html')

📁 Project Structure

.
├── cli
│   ├── __init__.py
│   └── interface.py
├── config.py
├── config.yaml
├── core
│   ├── engine.py
│   ├── __init__.py
│   ├── scrapers.py
│   └── validators.py
├── __init__.py
├── install.sh
├── LICENSE
├── main.py
├── modules
│   ├── advanced_osint.py
│   ├── breaches.py
│   ├── email_lookup.py
│   ├── __init__.py
│   ├── kali_tools.py
│   ├── phone_lookup.py
│   ├── reporting.py
│   └── username_lookup.py
├── README.md
├── requirements.txt
├── setup.py
├── sources
│   ├── data_aggregators.py
│   ├── __init__.py
│   ├── public_apis.py
│   └── social_media.py
├── storage
│   ├── database.py
│   └── __init__.py
├── utils
│   ├── formatter.py
│   ├── helpers.py
│   ├── __init__.py
│   └── logger.py
└── venv
    ├── bin
    │   ├── python -> python3
    │   ├── python3 -> /usr/bin/python3
    │   └── python3.13 -> python3
    └── lib64 -> lib

🔍 Data Sources

Integrated APIs & Platforms

Category	Sources
Email	EmailRep.io, Have I Been Pwned, DNS Records, WHOIS
Phone	TrueCaller, NumVerify, WhitePages, Spokeo
Social	GitHub, LinkedIn, Twitter, Instagram, Facebook
Forums	Reddit, StackOverflow, Medium, Dev.to
Gaming	Steam, Discord, Twitch
Professional	GitLab, Patreon, Behance

🛠️ Configuration

Environment Variables

# Optional API keys for enhanced results
export SHODAN_API_KEY="your_key"
export HUNTER_API_KEY="your_key"
export CLEARBIT_API_KEY="your_key"

Configuration File

Create config.yaml:

search:
  timeout: 10
  workers: 5
  rotate_user_agent: true
  rate_limit: 30

cache:
  ttl_hours: 24
  auto_cleanup: true

output:
  default_format: table
  show_confidence: true

📊 Output Examples

Email Search Result

{
  "email": "user@example.com",
  "confidence": 85.5,
  "reputation": {
    "score": "high",
    "suspicious": false
  },
  "breaches": [
    {
      "name": "Example Breach",
      "date": "2023-01-01",
      "severity": "HIGH"
    }
  ],
  "social_profiles": ["github", "linkedin"],
  "dns": {
    "mx_records": 3,
    "spf_configured": true,
    "dmarc_configured": false
  }
}

🔒 Security & Privacy

Ethical Guidelines

✅ Legal Use Only - Comply with local laws and regulations
✅ Respect Privacy - Only investigate with proper authorization
✅ Rate Limiting - Respectful API usage to prevent server overload
✅ No Illegal Access - No hacking or unauthorized access attempts
✅ GDPR Compliant - Respect data protection regulations

Best Practices

Always obtain permission before investigating individuals
Use for legitimate security research only
Respect platform Terms of Service
Implement proper data handling procedures
Maintain audit logs of searches

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone and setup development environment
git clone https://github.com/yourusername/raven-trace.git
cd raven-trace
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Tests have been removed for production deployment

# Code formatting
black .
flake8 .

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Have I Been Pwned - Data breach information
EmailRep.io - Email reputation data
phonenumbers - Phone number parsing
Rich - Beautiful terminal formatting

⚠️ Disclaimer

RavenTrace is designed for educational and legitimate security research purposes only.

The developers assume no liability and are not responsible for any misuse or damage caused by this tool. Users are solely responsible for complying with all applicable laws and regulations in their jurisdiction.

This tool should only be used:

With explicit permission from the target
For legitimate security assessments
In compliance with all applicable laws
Following ethical guidelines

📞 Contact

Author: Samy - Nyx
Email: Samy.bensalem@etik.com
Project Link: https://github.com/yourusername/raven-trace

RavenTrace - Intelligence at Your Fingertips 🐦

Made with ❤️ by ME

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
cli		cli
core		core
modules		modules
sources		sources
storage		storage
utils		utils
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
config.py		config.py
config.yaml		config.yaml
install.sh		install.sh
main.py		main.py
requirements.txt		requirements.txt
setup.py		setup.py

License

Nyx-Off/RavenTrace

Folders and files

Latest commit

History

Repository files navigation