📋 Table of Contents

• Overview
• Why OSINT-Nexus?
• Features
• Screenshots
• Installation
• Usage
• Architecture
• System Design Diagrams
• OSINT Modules
• AI-Powered Features
• Graph Analytics
• Configuration
• Report Generation
• Keyboard Shortcuts
• Contributing
• License & Contact

🎯 Overview

OSINT-Nexus is a powerful, cross-platform Open Source Intelligence (OSINT) gathering and visualization application. It combines the passive reconnaissance capabilities of tools like TheHarvester and SpiderFoot with the powerful visual link analysis of Maltego — enhanced with AI-powered analysis using Google Gemini and advanced graph analytics using cutting-edge algorithms.

💡 Built for security researchers, penetration testers, and intelligence analysts who need comprehensive, actionable insights from public data.

🏆 Why OSINT-Nexus?

✨ Features

🔍 Intelligence Gathering

🤖 AI-Powered Analysis

• Entity Correlation - Automatically discover hidden relationships
• Threat Assessment - AI-generated risk scores and narratives
• Natural Language Queries - Ask questions in plain English
• Executive Summaries - Auto-generate professional reports

📊 Advanced Analytics

• Community Detection - Louvain algorithm for clustering
• Centrality Analysis - PageRank, betweenness, closeness
• Anomaly Detection - Statistical outlier identification
• Path Finding - Shortest paths between entities

📄 Professional Reporting

• HTML Reports - Beautiful, dark-themed interactive reports
• PDF Reports - Print-ready professional documents
• STIX 2.1 Export - CTI standard for threat sharing

📸 Screenshots

🚀 Installation

Prerequisites

Quick Start

# Clone the repository
git clone https://github.com/Muhib-Mehdi/OSINT-NEXUS.git
cd OSINT-NEXUS

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python src/main.py

# Install PyInstaller
pip install pyinstaller

# Build executable
pyinstaller build.spec

# The executable will be in dist/OSINT-Nexus/

# Install PyInstaller
pip install pyinstaller

# Build executable
pyinstaller build.spec

# Run installer (optional)
sudo ./installers/installer_linux.sh

📖 Usage

Workflow Overview

flowchart LR
    A[🎯 Enter Target] --> B[📡 Select Modules]
    B --> C[🚀 Run Scan]
    C --> D[🔗 View Graph]
    D --> E[🤖 AI Analysis]
    E --> F[📄 Export Report]
    
    style A fill:#58a6ff,color:#fff
    style B fill:#3fb950,color:#fff
    style C fill:#f0883e,color:#fff
    style D fill:#a371f7,color:#fff
    style E fill:#db61a2,color:#fff
    style F fill:#79c0ff,color:#fff

Step-by-Step Guide

1. Create/Open Project

   • File → New Project or Ctrl+N
   • Enter project name and description

2. Configure Target

   • Select target type (Username, Domain, Email, IP, Phone)
   • Enter target value
   • Choose data sources (Google, GitHub, Shodan, etc.)

3. Run Scan

   • Click 🚀 Run Full Scan
   • Monitor progress in the log panel
   • Modules run in parallel for speed

4. Explore Results

   • Switch to Graph View tab
   • Click nodes to inspect entities
   • Right-click for transforms and actions

5. Analyze with AI

   • Configure Gemini API in Settings
   • Use natural language queries
   • Generate threat assessments

6. Export Report

   • File → Export → HTML/PDF/STIX
   • Professional reports ready for sharing

🏗️ Architecture

graph TB
    subgraph UI["🖥️ User Interface (PyQt6)"]
        MW[Main Window]
        ST[Scan Tab]
        GT[Graph Tab]
        SD[Settings Dialog]
    end
    
    subgraph Core["⚙️ Core Engine"]
        OE[OSINT Engine]
        TP[Thread Pool]
        DB[(SQLite DB)]
    end
    
    subgraph Modules["🔌 OSINT Modules"]
        EH[Email Harvester]
        SL[Social Lookup]
        BI[Breach Intel]
        IF[Image Forensics]
        TR[Transforms]
    end
    
    subgraph Advanced["🧠 Advanced Features"]
        AI[AI Engine<br/>Gemini]
        GA[Graph Analytics<br/>NetworkX]
        RG[Report Generator]
    end
    
    MW --> ST
    MW --> GT
    MW --> SD
    ST --> OE
    OE --> TP
    TP --> Modules
    OE --> DB
    GT --> GA
    GT --> AI
    MW --> RG
    
    style UI fill:#21262d,color:#e6edf3
    style Core fill:#161b22,color:#e6edf3
    style Modules fill:#0d1117,color:#e6edf3
    style Advanced fill:#30363d,color:#e6edf3

📐 System Design Diagrams

To better understand the internal workings of OSINT-Nexus, here are some additional architectural diagrams.

🔄 Data Flow Sequence

This sequence diagram illustrates how data flows from the user input through the system components during a scan operation.

sequenceDiagram
    participant User
    participant GUI as Main Window
    participant Engine as OSINT Engine
    participant Module as Data Module
    participant DB as SQLite DB
    participant Graph as Graph View

    User->>GUI: Initiates Scan
    GUI->>Engine: start_scan(target)
    Engine->>DB: create_scan_record()
    Engine->>Module: run(target)
    activate Module
    Module->>Module: Fetch External Data
    Module-->>Engine: return ScanResult
    deactivate Module
    Engine->>DB: save_entities(results)
    Engine->>GUI: signal_scan_complete()
    GUI->>Graph: update_graph()
    Graph->>User: Display Network Visualization

🧩 Class Structure

A high-level view of the core class relationships and inheritance hierarchy.

classDiagram
    class MainWindow {
        +init_ui()
        +setup_tabs()
    }
    class OSINTEngine {
        +start_scan()
        +register_module()
    }
    class BaseModule {
        <<Abstract>>
        +run()
        +process()
    }
    class Database {
        +get_entities()
        +save_project()
    }
    class GraphView {
        +add_node()
        +apply_layout()
    }

    MainWindow *-- OSINTEngine
    MainWindow *-- Database
    MainWindow *-- GraphView
    OSINTEngine o-- BaseModule
    BaseModule <|-- EmailHarvester
    BaseModule <|-- SocialLookup
    BaseModule <|-- BreachIntel

🚦 Scan Lifecycle State Machine

The states a scan operation goes through from initiation to completion.

stateDiagram-v2
    [*] --> Idle
    Idle --> Initializing : Start Scan
    Initializing --> Running : Modules Loaded
    state Running {
        [*] --> FetchingData
        FetchingData --> Processing
        Processing --> SavingResults
        SavingResults --> FetchingData : More Targets
        SavingResults --> [*]
    }
    Running --> Completed : All Tasks Done
    Running --> Failed : Error Occurred
    Running --> Cancelled : User Abort
    Completed --> Idle
    Failed --> Idle
    Cancelled --> Idle

🔌 OSINT Modules

🤖 AI-Powered Features

⚠️ Requires Google Gemini API Key — Get yours free at aistudio.google.com

Entity Correlation

🧠 AI Analysis: "Found connection between target email and 
3 GitHub repositories. High likelihood of same individual 
based on commit patterns and timezone analysis."

Threat Assessment

Natural Language Queries

Ask questions like:

• "Show me all emails from gmail.com"
• "Find connections between domain and GitHub accounts"
• "What entities have the highest risk score?"

📊 Graph Analytics

Algorithms Implemented

Anomaly Detection

Automatically identifies:

• 🔴 Outliers - Unusually connected entities
• 🟡 Hubs - Central connection points
• 🟠 Bridges - Entities connecting communities
• ⚪ Isolated - Disconnected nodes

⚙️ Configuration

API Keys Setup

Navigate to Tools → Settings → API Keys

📄 Report Generation

Export Formats

Report Contents

• 📊 Executive Summary with statistics
• 🔍 Entity breakdown by type
• 🔗 Relationship mapping
• 📈 Analytics insights
• 🤖 AI-generated narratives (if enabled)

⌨️ Keyboard Shortcuts

🤝 Contributing

Contributions are welcome! Here's how you can help:

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/OSINT-NEXUS.git
cd OSINT-NEXUS

# Install dev dependencies
pip install -r requirements.txt

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
python src/main.py

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

Contribution Guidelines

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. 💻 Write clean, documented code
4. ✅ Test your changes
5. 📝 Update documentation if needed
6. 🔄 Submit a Pull Request

Areas for Contribution

• 🔌 New OSINT modules
• 🤖 AI analysis improvements
• 📊 Additional graph algorithms
• 🌍 Internationalization
• 📱 Mobile responsiveness
• 🧪 Test coverage

⚖️ Legal Disclaimer

⚠️ IMPORTANT: This tool is designed for legitimate security research and authorized penetration testing only.

By using OSINT-Nexus, you agree to:

• ✅ Only gather information you are authorized to access
• ✅ Comply with all applicable laws and regulations
• ✅ Use gathered information responsibly and ethically
• ✅ Respect privacy and data protection requirements

The developers are not responsible for any misuse of this tool.

📜 License & Contact