OpenGraph Intel (OGI)

Open-source visual link analysis and OSINT framework. Free, self-hostable, and community-driven.

Features • Screenshots • Quick Start • Docker • Transform Hub • Architecture • Contributing

Heads up: This project is actively evolving. It has solid core capabilities and test coverage, and we continue to improve documentation, hardening, and feature depth with each release. Contributions, bug reports, and feedback are very welcome.

Features

• Visual graph investigation — drag-and-drop entities, explore connections interactively
• 20+ built-in transforms — DNS, WHOIS, SSL certs, geolocation, web/email/hash/social enrichment, and more
• Transform Hub — browse and install community transforms from the registry
• AI Investigator — prompt-driven agentic investigations that plan transform runs, stream progress live, and summarize findings with auditability
• Import / Export — JSON, CSV, GraphML, and MTGX format import
• Graph analysis — centrality, community detection, shortest paths
• Real-time collaboration — projects, sharing, and live sync via Supabase Realtime
• Async transform jobs — Redis/RQ queue with WebSocket progress updates
• Plugin system — directory-based plugin discovery with YAML manifests
• CLI tool — search, install, and manage transforms from the terminal
• Runs anywhere — local SQLite mode (zero config) or PostgreSQL + Supabase for team/cloud setups
• Docker ready — one-command deployment with docker compose up

Screenshots

Graph Investigation	Entity Enrichment

Quick Start

Prerequisites

Backend

cd backend
uv sync
uv run uvicorn ogi.main:app --reload

The API will be available at http://localhost:8000.

For local transform execution, Redis and the transform worker must also be running. Redis alone is not enough.

Start Redis:

docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine

Start the transform worker in a second terminal:

cd backend
uv run python -m ogi.worker.run_worker

If you see Job queue not available or Redis not available, verify that:

• OGI_REDIS_URL points to redis://localhost:6379/0 for local host-based runs
• the backend was restarted after Redis came up
• the separate worker process is running
• you are not using the Docker-only hostname redis outside Docker Compose

If you run the backend against PostgreSQL (OGI_USE_SQLITE=false), startup will automatically apply Alembic migrations before serving requests. Docker deployments do the same in the backend container entrypoint.

AI Investigator runs are processed by another separate worker:

cd backend
uv run python -m ogi.agent.run_worker

Frontend

cd frontend
pnpm install
pnpm dev

Open http://localhost:5173. That's it.

AI Investigator

AI Investigator is an optional provider-backed workflow that can plan transform sequences, request approvals, and summarize investigation progress inside the workspace.

• Open the AI Investigator tab inside a project
• Configure a provider and model in the investigator settings dialog
• Store provider API keys in API Keys
• Run the separate agent-worker process alongside the backend

The current implementation supports per-user provider configuration and a dedicated worker that executes investigation steps independently from the main API server.

CLI

Two supported ways to run the CLI:

Recommended (no activation required):

cd backend
uv sync
uv run ogi --help

Activated virtualenv (plain ogi command):

cd backend
uv venv
# PowerShell:
.\.venv\Scripts\Activate.ps1
uv pip install -e .
ogi --help

Docker

Development

cp .env.example .env
docker compose up

Production

Use the prebuilt GHCR images.

Important: docker-compose.prod.yml requires an external PostgreSQL database. It does not include a db service.

If you want the all-in-one local Docker stack with built-in Postgres and Redis, use:

docker compose up -d

Use the production compose file only when you already have a reachable PostgreSQL instance and have set OGI_DATABASE_URL accordingly:

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Set OGI_IMAGE_TAG in .env to pin a specific release image tag (e.g. v0.2.6). Defaults to latest.

Hetzner Cloud

New Hetzner users can use the first link to sign up with Hetzner Cloud credits. It is a referral link, so the OGI maintainer may also receive Hetzner Cloud credits if the referral qualifies. After creating a server, use the Docker deployment commands above to run OGI.

Configurable transform caps

OGI ships with sensible per-transform max values for things like max_results, max_links, max_urls, and max_content_chars, but those caps are now centrally overridable so cloud deployments can enforce them without hardcoding local limits.

Use OGI_TRANSFORM_SETTING_MAX_OVERRIDES in .env:

OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=50,max_urls=25,max_links=40,max_content_chars=20000

To remove specific caps in a local-first deployment:

OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none

The override is keyed by transform setting name and applies to built-in transforms and community plugins that use OGI's shared transform base/runtime.

Hosted cloud instance and Supporter plan

The hosted cloud version at ogi.khas.app was initially built so users could try OGI quickly before deciding whether to self-host it. It has since become the most popular way to use the project, with over 350 active cloud users.

That usage also increased the infrastructure costs for this side project. The repository therefore includes a cloud-only Supporter subscription and transformer-run cooldown system. On the public cloud instance, free users may be limited by a timeout between transformer runs, while Supporter users can subscribe for a symbolic USD 3/month to help cover Supabase and VPS costs.

Supporter subscriptions can be cancelled from the profile billing controls or the Stripe billing portal. Cancellation stops future billing, but paid subscription periods are not refunded or prorated.

This billing code is intentionally guarded by configuration: it only has an effect when OGI_DEPLOYMENT_MODE=cloud and OGI_CLOUD_BILLING_ENABLED=true. Self-hosted deployments should leave billing disabled and should not see any billing or paywall behavior.

Telemetry

OGI includes installation-level product telemetry intended to help us understand real-world usage, especially across self-hosted deployments.

• OGI_TELEMETRY_ENABLED=true enables telemetry collection
• OGI_TELEMETRY_LEVEL=full is the default collection level
• set OGI_TELEMETRY_ENABLED=false to disable telemetry entirely
• set OGI_TELEMETRY_LEVEL=basic to reduce what is sent

basic sends:

• OGI version
• a daily active installation ping

full additionally sends:

• instance created date
• aggregate counts for projects, entities, edges, transform runs, investigator runs, and active users for the period
• installed transforms with their versions

Telemetry is designed to avoid sending graph contents, entity values, API keys, prompts, or other investigation data. The current policy details are also published in the Privacy Policy.

Transform Hub

OpenGraph Intel has a built-in transform marketplace. Browse, install, and manage transforms from the community registry.

Security note: Plugins that require API keys should be treated as privileged code. If a plugin can access your secrets and make outbound network requests, it can misuse or exfiltrate those secrets. Review trust tier, permissions, and required services before installing or running third-party plugins.

# Search for transforms
uv run ogi transform search dns

# Install a transform
uv run ogi transform install shodan-host-lookup

Built-in Transform Categories

Supported Entity Types

Person • Username • Domain • IPAddress • EmailAddress • PhoneNumber • Organization • URL • SocialMedia • Hash • Document • Location • ASNumber • Network • MXRecord • NSRecord • • • •

Building Your Own Transforms

Want to build your own? See the contributing guide.

If your transform needs external service credentials, declare them in api_keys_required. Do not store secrets in transform settings. OGI manages those under API Keys, and secret-using plugins are considered privileged code.

If your transform exposes capped settings such as max_results or max_content_chars, prefer stable setting names over bespoke one-off names where possible. OGI can centrally override max values with OGI_TRANSFORM_SETTING_MAX_OVERRIDES, which helps cloud deployments enforce limits while local users can remove them.

Each plugin is a directory with a plugin.yaml manifest:

name: my-transform
version: "1.0.0"
display_name: My Transform
description: What it does
author: Your Name
license: MIT
category: dns
input_types: [Domain]
output_types: [IPAddress]
permissions:
  network: true
  filesystem: false
  subprocess: false

Architecture

Tech Stack

Project Structure

ogi/
├── backend/
│   └── ogi/
│       ├── api/            # REST API routes
│       ├── cli/            # CLI tool (Typer)
│       ├── db/             # Database layer (asyncpg + aiosqlite)
│       ├── engine/         # Graph engine & transform engine
│       ├── models/         # SQLModel definitions
│       ├── store/          # Data stores
│       ├── transforms/     # Built-in transforms
│       │   ├── dns/        # DNS resolution transforms
│       │   ├── cert/       # SSL certificate transforms
│       │   ├── email/      # Email enrichment
│       │   ├── hash/       # Hash lookups
│       │   ├── ip/         # IP/ASN/geolocation
│       │   ├── org/        # Organization info
│       │   ├── social/     # Social media
│       │   └── web/        # Web scraping/extraction
│       ├── worker/         # Async job queue (RQ)
│       ├── config.py       # Pydantic settings
│       └── main.py         # FastAPI entry point
├── frontend/
│   └── src/
│       ├── api/            # API client
│       ├── components/     # React components
│       ├── hooks/          # Custom hooks (realtime sync, etc.)
│       ├── stores/         # Zustand state management
│       ├── types/          # TypeScript types
│       └── App.tsx         # Main application
├── plugins/                # Community plugins directory
├── docs/                   # Documentation & images
├── docker-compose.yml      # Development deployment
├── docker-compose.prod.yml # Production deployment
└── .env.example            # Environment template

Configuration

OGI uses pydantic-settings with .env file support. Runtime/backend variables are prefixed with OGI_.

List-style settings accept either:

• JSON arrays, for example ["plugins","../plugins"]
• comma-separated strings, for example plugins,../plugins

Development

Running Tests

# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest

# Frontend
cd frontend
pnpm test

Linting & Type Checking

# Backend
cd backend
uv run ruff check        # Linting
uv run mypy              # Type checking

# Frontend
cd frontend
pnpm lint                # ESLint

CI Pipeline

The CI workflow runs on every pull request:

• Backend: ruff lint, mypy type check, pytest
• Frontend: vitest, eslint, vite build

Contributing

PRs welcome! If you find a bug or have an idea, open an issue.

For new transforms, contribute to ogi-transforms.

Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Legal & Responsible Use

OGI is a general-purpose OSINT and graph analysis tool. You are solely responsible for how you use it. See LEGAL.md for the full legal notice.

• Comply with third-party Terms of Service. Transforms that query external services (DNS, WHOIS, web scraping, username lookups, etc.) must be used in accordance with the ToS of those services. Automated or bulk querying of sites that prohibit it may violate their terms.
• Respect data protection law. If you are in the EU or processing data about EU residents, GDPR applies to you as the data controller. Collecting, storing, or processing personal data (names, email addresses, IP addresses, etc.) requires a lawful basis. OGI itself does not store data beyond your local instance — you are responsible for what you collect and retain.
• Use for lawful purposes only. OGI is intended for legitimate security research, investigations, threat intelligence, and educational use. Do not use it to harass individuals, conduct unauthorized access, or violate applicable law.
• File format compatibility. OGI supports import of the MTGX graph exchange format. This is provided purely for data interoperability and does not imply any affiliation with or endorsement by the makers of tools that use this format.

Disclaimer: OGI is provided "as is" without warranty of any kind. The authors are not liable for any misuse or damages arising from use of this software.

License

This project is licensed under the GNU Affero General Public License v3.0.