IG-Detective 🕵️‍♂️📸

Created by @shredzwho | 💖 Sponsor this project

IG-Detective is a high-performance, Python-based Open Source Intelligence (OSINT) tool for Instagram. It offers a premium interactive shell to perform deep analysis on Instagram accounts, extract location history, mapping interactions, and generating automated investigative reports.

[!WARNING]
Disclaimer: This tool is for educational and research purposes only. Use it responsibly and in accordance with Instagram's Terms of Service. The author is not responsible for any misuse.

⚡ Features

🛡️ Evasion & Stealth (Advanced)

TLS Fingerprint Spoofing: Uses a headless Playwright chromium browser with playwright-stealth to mimic a real environment, completely bypassing Cloudflare and CDN rate-limiting.
Deep Evasion Fallback: Automatically cascades to an unauthenticated headless browser fetch if an authenticated session is shadowbanned (e.g., HTTP 401/429/400 blocks), omitting cookies and forging headers to emulate a pristine pristine connection.
Poisson Jitter: Human-like randomized delays between requests to mimic natural user behavior.

⚡ Performance & Optimization

Headless Memory Tuning: Stripped-down Playwright browser configuration that explicitly drops heavy visual assets (images, fonts, stylesheets) via route interception to achieve ultra-fast query speeds.
Asynchronous Data Export: Utilizes ThreadPool parallel downloading for the data archival command, drastically speeding up complete profile media replication.

🔍 Core Reconnaissance

User Info: Comprehensive profile details (ID, Bio, Followers, Business status).
Followers/Following: List and export target's social network.
Post Analysis: Detailed breakdown of recent content, likes, and comments.

📍 Advanced OSINT

Interactive Geospatial Mapping: Extracts GPS coordinates from posts and generates a Folium interactive_map.html with readable addresses and clickable pins.
Social Network Analysis (sna): Maps interactions to identify the "Inner Circle"—the top 10 users most highly connected to the target.
Temporal Activity Profiling (temporal): Uses DBSCAN clustering to identify the target's "sleep gap" and predict their primary Time Zone.
Story Extraction (stories): Fetch active story URLs.

🔬 Research-Driven Forensic Modules (Bleeding-Edge)

Account Recovery Enumeration (recovery): Trigger password reset flow to reveal masked contact tips for administrative email verification.
Co-Visitation Analysis (intersect): Identify physical physical meeting points by cross-referencing GPS/Time intersections between two targets.
Stylometry (stylometry): Generate a digital "Linguistic Signature" to link multiple accounts based on bigram and emoji distribution.
Engagement Audit (audit): Statistical detection of inauthentic bot activity via temporal jitter variance.

📦 Investigation Management

One-Click Export (data): Automatically download a target's followers list, following list, and timeline media (with metadata JSON), packaged into a single ZIP archive.
Automated Reporting: Every command automatically saves results to JSON and TXT reports in data/<target>/.
Autonomous Batch Mode: Process multiple targets sequentially from a text file.
Intelligent Caching: Lightning-fast repeated queries via TTL-based caching.

🚀 Installation

Clone the repository

bash
git clone https://github.com/shredzwho/IG-Detective.git
cd IG-Detective

Set up Virtual Environment

bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies
```
bash
pip install -r requirements.txt
```

🐳 Run with Docker (Recommended)

You can run IG-Detective entirely within Docker to avoid dependency issues. The container requires an interactive TTY (-it) and a volume mount to save your forensic reports.

Using Docker Compose (Easiest)

bash
docker-compose run --rm detective

Using standard Docker

bash
docker build -t ig-detective .
docker run -it -v $(pwd)/data:/app/data ig-detective

🛠 Usage

Launch the Shell

bash
python3 main.py
# or use the provided wrapper:
./run.sh

Core Commands
Once inside the shell, you must first set a target before running analysis modules:

Command	Description
`target <user>`	Set the investigation target (Required first step)
`info`	View basic profile OSINT (bio, external links, metadata)
`posts`	Fetch the target's recent timeline activity & stats
`addrs`	Extract geographical targets from embedded GPS
`data`	Export target footprints (media, followers) to a ZIP File
`surveillance`	Continuously monitor and trace target metrics/bio changes live
`sna`	Perform Social Network Analysis to map the "Inner Circle"
`temporal`	Calculate timezone and sleep behavior via DBSCAN
`stylometry`	NLP linguistic profiling on captions (Emojis & N-grams)
`recovery`	Trigger password reset flow to reveal masked contacts
`intersect`	Cross-reference GPS/Time intersections between two targets
`audit`	Statistical detection of inauthentic bot activity
`help`	Display the interactive help menu
`exit`	Exit the CLI cleanly

📑 Detailed Documentation

For a deep dive into the system architecture, forensic methodologies, and evasion logic, see:
👉 DOCUMENTATION.md

📂 Project Structure

main.py: Main entrypoint for the shell.
run.sh: Launch wrapper script.
src/api/: Network layer containing the Playwright stealth client and auth manager.
src/core/: Foundation layer with data models and config.
src/modules/: Business logic layer with scrapers and deep analytics tools.
src/cli/: Presentation layer with the interactive prompt and Rich formatters.
data/: Automated investigative reports (git-ignored).