Osintgraph (Open Source Intelligence Graph)

Osintgraph is a tool for deep social analysis and OSINT investigations focused on Instagram targets. It uses Neo4j to map a target’s network — revealing connections, interests, and affiliations — and an interactive AI Agent to speed up investigations and simplify analysis.

⚡ What OSINTGraph Does

OSINTGraph CLI gathers all public Instagram data from a target and maps their social connections, including profiles, followers, followees, posts, comments, and likes. It helps you thoroughly examine your target by gathering all relevant data and analyzing it for investigations.

See how it works ↗

Data collection via CLI:

| | |-----------------| | Overview of CLI Interface for data collection |

Explore and analyze your target's data via two ways:

1. Osintgraph AI Agent

Use natural language to query about your target. The AI Agent supports data retrieval, keyword and semantic searches, relationship queries, and template-driven analyses — helping you get focused answers without manually digging through data. | | |-----------------| | Overview of interacting with the agent performing data retrieval, keyword and semantic searches, and template-based analyses. |

2. Neo4j Visualization

Visualize your target’s social network, trace interactions, and query relationships directly.

| Example of tracing a target user’s close connection through their most commented post, then investigating mutual followers and all interactions between them. | |-----------------|

📚 Table of Contents

• ✨ About OSINTGraph
• ⚡ What OSINTGraph Does
• 🚀 Getting Started
  • 1. Install OSINTGraph
  • 2. Setup Configuration
  • 3. Start Collecting Instagram Data
  • 4. Analyze & Investigate
  • 5. Visualize in Neo4j
• ⚡ How OSINTGraph Works
  • Phase 1: Reconnaissance
  • Phase 2: Analysis & Investigation
• ⚙ Commands Reference
  • setup
  • reset
  • discover
  • explore
  • agent
• 🧩 Data Model (Neo4j Schema)
  • 👤 Person Node
  • 📷 Post Node
  • 💬 Comment Node
  • 🕸️ Relationships
• 🕵️ OSINTGraph AI Agent – Getting Started Guide
  • 1. 🔧 Data Retrieval
    • Approach 1: Basic Data Retrieval
    • Approach 2: Relationship Traversal
    • Approach 3: Content Search
    • Combining Approaches
    • Best Practices – How to Ask Questions for Best Results
  • 2. 📝 Template-Based Analysis
    • ⚡How Templates Work
    • 🛠 How to Create Custom Templates
• 🚫 How to Avoid Account Suspension
• 📦 Dependencies

🚀 Getting Started

1. Install OSINTGraph

pipx install osintgraph

or

pip install osintgraph

[!NOTE] When using pip, it’s recommended to install inside a Python virtual environment to avoid dependency conflicts.

2. Setup Configuration

Before running osintgraph setup, make sure you have the following ready:

• Instagram Account: Preferably not your main account

• Neo4j Database: For storing and visualizing data.

  (Sign up at Neo4j → Create an instance for free → Download admin credentials) — you’ll need these for connection.

• Gemini API Key: Enables data pre-analyses and the AI agent.

  (Sign up at Google AI Studio → Create or select a Google Cloud project → Get API Key for free)

• User Agent (Optional): Helps reduce Instagram detection risk. (Open your Firefox browser where you log in to Instagram, search “my user agent” on Google, and copy it)

Then run

osintgraph setup

3. Start collecting Instagram data

Start gathering data on your target:

osintgraph discover TARGET_INSTAGRAM_USERNAME --limit follower=100 followee=100 post=2 

4. Analyze & Investigate

Launch the AI Agent to explore and analyze collected data:

osintgraph agent

Once the agent starts, try asking it: Show the target user’s profile info

5. Visualize in Neo4j

Explore your target’s network graph interactively.

• Go to the Neo4j Console.
• Click the Explore tab, then Connect.
• In the search bar, type "Show me a graph".
• You should now see the person you just collected, along with their relationships.

⚡ How OSINTGraph Works

OSINTGraph run in two main phases: Reconnaissance and Analysis & Investigation.

   ⚡PHASE 1: RECONNAISSANCE                                           ⚡PHASE 2: ANALYSIS & INVESTIGATION
   ──────────────────────────                                           ───────────────────────────────────
   [ Data Collection ] (osintgraph discover <target>)                    [ Investigation ] 
     ├─ Profile Metadata                                                   ├─ [AI Agent] (osintgraph agent)
     ├─ Followers                                                          │    • Retrieve Data    
     ├─ Followees                                                          │    • Keyword Search
     └─ Posts (with Comments)                                              │    • Semantic Search
           ↓                                                               │    • Graph Relationship Search
   Posts Pre-Analysis                                                      │    • Run Template Analyses
     ├─ Uses:                                                              └─ [Neo4j Visualization]
     │    • Post Metadata
     │    • Comments
     │    • Image Pre-Analyses
     │         ├─ Uses:
     │         │    • Post media (thumbnails & images)
     │         └─ Generates:
     │              • Structured Image Analysis Report
     └─ Generates:
          • Structured Post Analysis Report
            ↓
    Account Pre-Analysis
      ├─ Uses:
      │    • All Post Analyses
      │    • Profile Metadata
      └─ Generates:
           • Structured Account Analysis Report

Phase 1: Reconnaissance

In this phase, you collect all public Instagram data for a target and their network. You’re building the raw intelligence database that you’ll investigate later.

What you do:

Run one of these commands to collect all public Instagram data for a target and their network:

• osintgraph discover <target> — Collect and (optionally) pre-analyze the target account’s data.

• osintgraph explore <target> — Recursively run discover on each followee of the target, prioritizing followees with the largest follower base in the Neo4j database.

What OSINTGraph does in the background:

1. Scrapes the target’s profile, followers, followees, posts, and comments.
2. If Gemini API is enabled, pre-analyzes:
   • Image Analysis: Each post’s media is examined for visual clues and details.
   • Post Analysis: Combines image findings, post metadata, and comments into a structured OSINT report.
   • Account Analysis: Summarizes patterns and behaviors across all posts for the account.

   Pre-analysis quickly examines posts and account data to give you early insights. It’s also useful for template-based investigations, because templates can use the pre-analyzed data immediately for deeper analysis.

3. Maps all relationships (likes, follows, replies, etc.) into Neo4j. See how Instagram data is stored in Neo4j ↗

Phase 2: Analysis & Investigation

In this phase, you search, analyze, and visualize the intelligence gathered in Phase 1. Now you’re making sense of the network, activities, and patterns.

What you do:

• Query data using natural language, keyword/semantic search, and graph-relationship queries.
• Run analyses using predefined or custom templates.
• Explore and Visualize social networks interactively.

You have two main ways to do this:

1. AI Agent osintgraph agent

• Ask questions for data retrieval, keyword and semantic searches, graph-relationship based queries, and analyses using predefined or custom templates. Learn more about Agent ↗

2. Neo4j Visualization (Neo4j Console Browser)

• Explore visualize the social network map interactively.
• See how people, posts, and interactions are connected.

⚙ Commands Reference

Below is a breakdown of each command, what it does, and when to use it.

🔧 `