# NEXUS OSINT Tool

🔍 **Advanced terminal-based Open Source Intelligence (OSINT) tool for comprehensive investigation.**

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()

## ✨ Features

- **👤 Username Search**: 200+ social media platforms
- **📧 Email Investigation**: Breach checking, validation, social associations
- **🌐 Domain Analysis**: DNS enumeration, WHOIS, technology detection
- **🖥️ IP Analysis**: Geolocation, port scanning, VPN detection
- **🌍 Web Scraping**: AI-powered content analysis
- **🖥️ Web Interface**: Modern web-based investigation dashboard
- **⚙️ Configuration**: Interactive API key and settings management

## 🚀 Quick Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install nexus-osint
nexus --help
```

### Option 2: Install from GitHub

```bash
pip install git+https://github.com/yourusername/nexus-osint.git
nexus --help
```

### Option 3: Manual Installation

```bash
git clone https://github.com/yourusername/nexus-osint.git
cd nexus-osint
pip install -e .
nexus --help
```

## 📖 Usage

### Basic Commands

```bash
# Configure API keys and settings
nexus --config

# Username search
nexus --username john_doe

# Email investigation  
nexus --email example@domain.com

# Domain analysis
nexus --domain example.com

# IP analysis
nexus --ip 192.168.1.1

# Web scraping with AI analysis
nexus --scrape https://example.com

# Launch web interface
nexus --web

# Save results
nexus --username john_doe --output results.json

# Verbose output
nexus --email test@example.com --verbose
```

### Advanced Usage

```bash
# Multiple usernames
nexus --username user1 user2 user3 --output batch_results.json

# Chain investigations
nexus --email target@example.com --domain example.com --ip 192.168.1.1

# Web interface for visual investigations
nexus --web
# Visit http://localhost:5000
```

## ⚙️ Configuration

### Interactive Configuration

```bash
nexus --config
```

This will open an interactive menu to configure:
- **API Keys**: Shodan, AbuseIPDB, Hunter, HaveIBeenPwned
- **Output Settings**: Format, verbosity, auto-save
- **Search Settings**: Concurrency, timeouts, delays

### Manual Configuration

Edit `config.json` directly:

```json
{
  "api_keys": {
    "shodan": "your_shodan_api_key",
    "abuseipdb": "your_abuseipdb_api_key", 
    "hunter": "your_hunter_api_key",
    "haveibeenpwned": "your_hibp_api_key"
  },
  "output": {
    "format": "json",
    "verbose": true,
    "save_results": true,
    "output_dir": "results"
  }
}
```

### Getting API Keys

| Service | Free Tier | Link |
|---------|-----------|------|
| Shodan | ✅ Limited | https://account.shodan.io/ |
| AbuseIPDB | ✅ Free | https://www.abuseipdb.com/ |
| Hunter | ❌ Paid | https://hunter.io/ |
| HaveIBeenPwned | ❌ Paid | https://haveibeenpwned.com/API/Key |

## 🏗️ Project Structure

```
nexus-osint/
├── main.py                 # Main CLI entry point
├── modules/                # Core modules
│   ├── username_search.py   # Social media detection
│   ├── email_investigator.py # Email analysis
│   ├── domain_analyzer.py   # DNS/WHOIS analysis
│   ├── ip_analyzer.py       # IP geolocation & scanning
│   ├── web_scraper.py       # Web scraping & AI analysis
│   └── web_interface.py     # Flask web interface
├── templates/              # Web interface templates
├── config.json            # Configuration file
├── requirements.txt        # Dependencies
└── README.md              # This file
```

## 🌐 Web Interface

Launch the modern web interface for visual investigations:

```bash
nexus --web
```

Features:
- 🎨 Modern dark/light theme
- 📊 Real-time investigation results
- 💾 JSON download functionality
- 📱 Responsive design
- 🔄 Live status updates

## 📊 Example Output

```bash
$ nexus --username elonmusk

=== USERNAME SEARCH SUMMARY ===
Usernames checked: 1
Platforms searched: 124
Accounts found: 67

=== TOP FINDINGS ===

elonmusk:
  * twitter: https://twitter.com/elonmusk (confidence: 0.95)
  * instagram: https://instagram.com/elonmusk (confidence: 0.87)
  * youtube: https://youtube.com/elonmusk (confidence: 0.82)
```

## 🔧 Development

### Setup Development Environment

```bash
git clone https://github.com/yourusername/nexus-osint.git
cd nexus-osint
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black .
flake8 .
mypy .
```

## 📋 Requirements

- Python 3.8+
- Internet connection
- Optional API keys for enhanced features

See [requirements.txt](requirements.txt) for full dependency list.

## ⚠️ Legal & Ethics

- ⚖️ Use responsibly and only on targets you have permission to investigate
- 🔒 Respect privacy and terms of service of all platforms
- 📚 Educational and authorized security testing purposes only
- 🛡️ Users are responsible for compliance with applicable laws

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- [Documentation](https://github.com/yourusername/nexus-osint/wiki)
- [Bug Reports](https://github.com/yourusername/nexus-osint/issues)
- [Feature Requests](https://github.com/yourusername/nexus-osint/issues)
- [Discussions](https://github.com/yourusername/nexus-osint/discussions)

## 🙏 Acknowledgments

- Inspired by Sherlock and other OSINT tools
- Thanks to all contributors and the open-source community
- Built with ❤️ for the security research community

---

**⚡ Made with NEXUS OSINT - Intelligence Gathering Platform**
