Osintgraph

The Problem

Osintgraph is an Instagram OSINT tool that collects social graph data and stores it in Neo4j for network analysis and investigation. The tool maps a target's connections, interests, and affiliations through follower/followee data, posts, comments, and likes. For a technical client, the core question is whether this codebase is maintainable and safe to integrate or extend.

What This Does

Osintgraph collects Instagram data via a CLI interface and stores it in a Neo4j graph database. The system uses an AI agent for natural language queries about targets, with template-driven analysis capabilities. Data flows from Instagram collection through the insta_manager.py module into Neo4j via neo4j_manager.py, where it can be queried through the AI agent in osintgraph_agent/osint_graph_agent.py. The CLI entry point at src/osintgraph/cli.py:23 orchestrates the setup and execution flow, reaching 40 functions total. The system makes outbound network calls to Instagram, writes to the Neo4j database, and calls a model for inference through the LLM analyzer service.

How It Is Wired

Execution starts at main in src/osintgraph/cli.py:23, which calls run_setup to initialize configuration. From there, choose_login_method is invoked to handle authentication, and import_session reads cookie data from the filesystem via get_session.py. The traced path reaches the database through execute_write and execute_read functions in neo4j_manager.py — execute_read is called from 12 places, execute_write from 9, giving these functions wide blast radius. The internal call graph shows 131 resolved call edges; _fetch_and_map calls execute_write 11 times, and discover calls it 8 times, making the write path a high-change-risk area. The most connected modules are osint_graph_agent (instability 0.89) and cli (instability 0.88), meaning changes to these hubs ripple widely through the call graph. The system touches 2 outbound network functions, 1 file I/O function, 1 database function, and 2 model inference calls.

How To Use It

Setup: The repository uses pyproject.toml for configuration and dependencies. No lockfile is committed, so dependency versions may vary between installs. Install with pip install -e . from the repository root, which will resolve dependencies declared in pyproject.toml.

Configuration: Instagram credentials and Neo4j connection details are managed through credential_manager.py. The Insta_Config function is called from 3 places and handles login configuration. Environment variables or config files for Instagram API access and Neo4j connection string are required but their exact names are not explicitly documented in the repository structure — a client should expect credential configuration via the credential_manager module.

Running it: Invoke the CLI with python -m src.osintgraph or python src/osintgraph/cli.py to reach the main entry point. Available commands include setup, reset, discover <username>, explore <username>, and agent, as documented in the README.

Real-World Use

A practical scenario: an investigator wants to map the network of a target Instagram account. They run osintgraph discover target_handle to collect followers and followees, which stores person nodes and follower/followee relationships in Neo4j. Then they use the AI agent with osintgraph agent "Find mutual followers between target and known associate" to traverse the graph and identify connections of interest. The template-driven analysis in template_tools.py can further structure this inquiry. The resulting Neo4j graph reveals interests, affiliations, and secondary connections that would be difficult to assemble manually.

Code Health & Issues

• CRITICAL - Upgrade the pinned dependency carrying a critical advisory: langchain-core@0.3.72 CVE-2025-68664 (and +11 more). The manifest pins the exact vulnerable version, so this is reachable over the network without credentials or user interaction. Fix: upgrade to the fixed version and commit the lockfile.
• HIGH - Upgrade the pinned dependency carrying a published advisory: langchain@0.3.27 CVE-2026-45134, langgraph@0.6.2 CVE-2026-28277, protobuf@6.31.1 CVE-2026-0994. The pinned versions are the ones that install, so these advisories describe the actual deployment. Fix: upgrade and commit lockfile.
• HIGH - Add a test suite; this repository has none. 28 source files with zero test files means any change ships with no signal that existing behavior holds. Fix: add one test per public entry point, then CI step to run them.
• HIGH - Commit a lockfile beside the manifest (pyproject.toml). No lockfile means the artifact tested and the artifact shipped can contain different transitive code. Fix: run the package manager once and commit the generated lockfile.
• HIGH - Add a workflow that builds and tests this repository. No CI configuration exists across 28 source files. Fix: add a workflow running the project build and test command on push and pull_request.
• MEDIUM - Enable Dependabot or Renovate. No update bot configured; a published advisory sits unpatched until manual audit. Fix: commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Beyond the measured findings: no CI/CD pipeline detected (/.github/ or CI config absent), no Dockerfile present, and the pyproject.toml has no lockfile, meaning builds are non-reproducible across environments.

The Bottom Line

This repo functions as a working Instagram OSINT tool with a Neo4j-backed graph and AI agent layer, but it carries significant operational risk. Three pinned dependencies have published critical/high CVEs, there is no lockfile or CI gate, and the codebase has no test coverage across 28 files. The architectural hubs in neo4j_manager.py and osintgraph_agent.py have high instability scores, meaning changes ripple widely. A client should treat this as production-ready only after upgrading dependencies, adding a lockfile, and establishing test coverage — otherwise, each change risks introducing undetected regressions or security vulnerabilities.