Framework open source per l'analisi dei collegamenti e OSINT
<div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/12241/4d60ae367bb5f1d9b7d1d95df2b16186f01454c9610e40703f636923a0a70ced.png" alt="Mascotte OGI" width="200" /> # OpenGraph Intel (OGI) **Framework OSINT e di analisi visiva dei collegamenti open-source.** **Gratuito, auto-ospitabile e guidato dalla comunità.** [](https://www.gnu.org/licenses/agpl-3.0) [](https://github.com/khashashin/ogi/actions/workflows/ci.yml) [](https://github.com/khashashin/ogi/actions/workflows/docker-publish.yml) [](https://www.python.org) [](https://www.typescriptlang.org) [](https://react.dev) [](https://fastapi.tiangolo.com)  [Funzionalità](#features) • [Screenshot](#screenshots) • [Avvio rapido](#quick-start) • [Docker](#docker) • [Hub dei Trasform](#transform-hub) • [Architettura](#architecture) • [Contribuire](#contributing) </div> --- > **Attenzione:** Questo progetto è in evoluzione attiva. Dispone di solide capacità principali e copertura dei test, e continuiamo a migliorare la documentazione, l'irrobustimento e la profondità delle funzionalità con ogni release. Contributi, segnalazioni di bug e feedback sono molto graditi. ## Funzionalità - **Investigazione visiva a grafo** — entità drag-and-drop, esplora connessioni in modo interattivo - **20+ trasformazioni integrate** — DNS, WHOIS, certificati SSL, geolocalizzazione, arricchimento web/email/hash/social e altro - **Hub dei Trasform** — esplora e installa trasformazioni della comunità dal [registry](https://github.com/opengraphintel/ogi-transforms) - **Investigatore AI** — investigazioni agentive guidate da prompt che pianificano esecuzioni di trasformazioni, trasmettono l'avanzamento in tempo reale e riassumono i risultati con verificabilità - **Importa / Esporta** — importazione in formato JSON, CSV, GraphML e MTGX - **Analisi del grafo** — centralità, rilevamento di comunità, percorsi più brevi - **Collaborazione in tempo reale** — progetti, condivisione e sincronizzazione live tramite Supabase Realtime - **Job di trasformazione asincroni** — coda Redis/RQ con aggiornamenti di avanzamento via WebSocket - **Sistema di plugin** — rilevamento plugin basato su directory con manifest YAML - **Strumento CLI** — cerca, installa e gestisci trasformazioni dal terminale - **Funziona ovunque** — modalità SQLite locale (zero configurazione) o PostgreSQL + Supabase per configurazioni team/cloud - **Pronto per Docker** — distribuzione con un comando con `docker compose up` ## Screenshot <div align="center"> | Investigazione a grafo | Arricchimento entità | | :-------------------------------------------: | :-----------------------------------------: | |  |  | | Hub dei Trasform | Esporta / Importa | | :-------------------------------------: | :-------------------------------------: | |  |  | </div> ## Avvio rapido ### Prerequisiti | Strumento | Versione | | ------------------------------- | -------- | | [Python](https://www.python.org) | 3.14+ | | [uv](https://docs.astral.sh/uv/) | ultima | | [Node.js](https://nodejs.org) | 20+ | | [pnpm](https://pnpm.io) | ultima | ### Backend```bash cd backend uv sync uv run uvicorn ogi.main:app --reload ``` L'API sarà disponibile all'indirizzo `http://localhost:8000`. Per l'esecuzione locale delle trasformazioni, devono essere in esecuzione anche Redis e il worker di trasformazione. Redis da solo non basta. Avvia Redis:```bash docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine ``` Avvia il worker di trasformazione in un secondo terminale:```bash cd backend uv run python -m ogi.worker.run_worker ``` Se vedi `Job queue not available` o `Redis not available`, verifica che: - `OGI_REDIS_URL` punti a `redis://localhost:6379/0` per esecuzioni locali basate su host - il backend sia stato riavviato dopo l'avvio di Redis - il processo worker separato sia in esecuzione - non stai usando il nome host Docker-only `redis` al di fuori di Docker Compose Se esegui il backend con PostgreSQL (`OGI_USE_SQLITE=false`), l'avvio applicherà automaticamente le migrazioni di Alembic prima di servire le richieste. Le distribuzioni Docker fanno lo stesso nel punto di ingresso del container backend. Le esecuzioni di AI Investigator sono elaborate da un altro worker separato:```bash cd backend uv run python -m ogi.agent.run_worker ``` ### Frontend```bash cd frontend pnpm install pnpm dev ``` Apri http://localhost:5173. Tutto qui. ### AI Investigator AI Investigator è un flusso di lavoro opzionale basato su provider che può pianificare sequenze di trasformazione, richiedere approvazioni e riassumere i progressi dell'investigazione all'interno del workspace. - Apri la scheda `AI Investigator` all'interno di un progetto - Configura un provider e un modello nella finestra di dialogo delle impostazioni dell'investigatore - Conserva le chiavi API del provider in `API Keys` - Esegui il processo separato `agent-worker` insieme al backend L'implementazione attuale supporta la configurazione del provider per utente e un worker dedicato che esegue i passaggi dell'investigazione in modo indipendente dal server API principale. ### CLI Due modalità supportate per eseguire la CLI: **Consigliato** (nessuna attivazione richiesta):```bash cd backend uv sync uv run ogi --help ``` **Virtualenv attivato** (comando `ogi` semplice):```bash cd backend uv venv # PowerShell: .\.venv\Scripts\Activate.ps1 uv pip install -e . ogi --help ``` ## Docker ### Sviluppo```bash cp .env.example .env docker compose up ``` ### Produzione Utilizza le immagini GHCR precompilate. Importante: [docker-compose.prod.yml](https://github.com/khashashin/ogi/blob/main/docker-compose.prod.yml) richiede un database PostgreSQL esterno. Non include un servizio `db`. Se desideri lo stack Docker locale tutto-in-uno con Postgres e Redis integrati, usa:```bash docker compose up -d ``` Usa il file compose di produzione solo quando hai già un'istanza PostgreSQL raggiungibile e hai impostato `OGI_DATABASE_URL` di conseguenza:```bash docker compose -f docker-compose.prod.yml pull docker compose -f docker-compose.prod.yml up -d ``` Set `OGI_IMAGE_TAG` in `.env` per fissare un tag specifico di release dell'immagine (ad es. `v0.2.6`). L'impostazione predefinita è `latest`. ### Hetzner Cloud [](https://hetzner.cloud/?ref=LspEGc99USBa) [](https://console.hetzner.com/deploy/docker-ce) I nuovi utenti Hetzner possono usare il primo link per registrarsi con crediti Hetzner Cloud. È un link di referral, quindi il manutentore di OGI potrebbe anche ricevere crediti Hetzner Cloud se il referral è qualificato. Dopo aver creato un server, usa i comandi di distribuzione Docker sopra per eseguire OGI. ### Limiti di trasformazione configurabili OGI viene fornito con valori massimi ragionevoli per ogni trasformazione per cose come `max_results`, `max_links`, `max_urls` e `max_content_chars`, ma questi limiti sono ora sovrascrivibili centralmente in modo che le distribuzioni cloud possano imporli senza codificare limiti locali. Usa `OGI_TRANSFORM_SETTING_MAX_OVERRIDES` in `.env`:```env OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=50,max_urls=25,max_links=40,max_content_chars=20000 ``` Per rimuovere limiti specifici in una distribuzione local-first:```env OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none ``` La sostituzione è associata al nome dell'impostazione della trasformazione e si applica alle trasformazioni integrate e ai plugin della community che utilizzano la base/runtime di trasformazione condivisa di OGI. ### Istanza cloud ospitata e piano Supporter La versione cloud ospitata su [ogi.khas.app](https://ogi.khas.app) è stata inizialmente creata per permettere agli utenti di provare rapidamente OGI prima di decidere se auto-ospitarlo. Da allora è diventata il modo più popolare di utilizzare il progetto, con oltre 350 utenti cloud attivi. Questo utilizzo ha anche aumentato i costi dell'infrastruttura per questo progetto secondario. Il repository include quindi un abbonamento Supporter solo cloud e un sistema di cooldown per l'esecuzione delle trasformazioni. Sull'istanza cloud pubblica, gli utenti gratuiti possono essere limitati da un timeout tra le esecuzioni delle trasformazioni, mentre gli utenti Supporter possono abbonarsi per un simbolico USD 3/mese per contribuire a coprire i costi di Supabase e VPS. Gli abbonamenti Supporter possono essere cancellati dai controlli di fatturazione del profilo o dal portale di fatturazione Stripe. La cancellazione interrompe la fatturazione futura, ma i periodi di abbonamento pagati non vengono rimborsati né riproporzionati. Questo codice di fatturazione è intenzionalmente protetto dalla configurazione: ha effetto solo quando `OGI_DEPLOYMENT_MODE=cloud` e `OGI_CLOUD_BILLING_ENABLED=true`. Le distribuzioni auto-ospitate devono lasciare la fatturazione disabilitata e non dovrebbero vedere alcun comportamento di fatturazione o paywall. ### Telemetria OGI include telemetria del prodotto a livello di installazione, progettata per aiutarci a comprendere l'utilizzo nel mondo reale, specialmente tra le distribuzioni auto-ospitate. - `OGI_TELEMETRY_ENABLED=true` abilita la raccolta di telemetria - `OGI_TELEMETRY_LEVEL=full` è il livello di raccolta predefinito - impostare `OGI_TELEMETRY_ENABLED=false` per disabilitare completamente la telemetria - impostare `OGI_TELEMETRY_LEVEL=basic` per ridurre ciò che viene inviato `basic` invia: - versione di OGI - un ping giornaliero di installazione attiva `full` invia inoltre: - data di creazione dell'istanza - conteggi aggregati per progetti, entità, archi, esecuzioni di trasformazioni, esecuzioni di Investigator e utenti attivi per il periodo - trasformazioni installate con le loro versioni La telemetria è progettata per evitare di inviare contenuti dei grafi, valori delle entità, chiavi API, prompt o altri dati di investigazione. I dettagli della politica corrente sono pubblicati anche nell'[Informativa sulla privacy](https://ogi.khas.app/privacy#telemetry). <details> <summary><strong>Servizi di sviluppo con Compose</strong></summary> | Servizio | Descrizione | Porta | | -------------- | ----------------------------------- | ----- | | `backend` | Server applicativo FastAPI | 8000 | | `worker` | Worker job asincroni RQ | - | | `agent-worker` | Worker Investigator AI | - | | `frontend` | App React servita tramite nginx | 80 | | `db` | PostgreSQL 16 | 5432 | | `redis` | Redis 7 (coda dei job) | 6379 | </details> <details> <summary><strong>Servizi di produzione con Compose</strong></summary> | Servizio | Descrizione | Porta | | -------------- | ----------------------------------- | ----- | | `backend` | Server applicativo FastAPI | 8000 | | `worker` | Worker job asincroni RQ | - | | `agent-worker` | Worker Investigator AI | - | | `frontend` | App React servita tramite nginx | 80 | | `redis` | Redis 7 (coda dei job) | 6379 | `docker-compose.prod.yml` si aspetta un database PostgreSQL esterno tramite `OGI_DATABASE_URL`. </details> --- <details> <summary><strong>Dipendenze dei plugin all'avvio</strong></summary> Se utilizzi immagini precompilate e un plugin necessita di librerie Python aggiuntive, OGI installa le dipendenze del plugin all'avvio del contenitore da: 1. `plugins/requirements.txt` (preferito), oppure 2. requisiti generati automaticamente da `plugins/ogi-lock.json` quando `requirements.txt` è assente. **Variabili d'ambiente:** | Variabile | Predefinito | Descrizione | | ----------------------------------- | -------------------------------- | ------------------------------------------ | | `OGI_BOOT_REQUIREMENTS_ENABLE` | `true` | Abilita/disabilita installazione all'avvio | | `OGI_BOOT_REQUIREMENTS_FILE` | `/app/plugins/requirements.txt` | Percorso del file dei requisiti | | `OGI_BOOT_LOCK_FILE` | `/app/plugins/ogi-lock.json` | Percorso del file di lock | | `OGI_BOOT_REQUIREMENTS_STRICT` | `false` | Interrompi avvio se requisiti mancanti | | `OGI_BOOT_REQUIREMENTS_CACHE_DIR` | `/tmp/ogi-boot` | Directory temporanea/cache per requisiti | </details> --- ## Transform Hub OpenGraph Intel dispone di un mercato di trasformazioni integrato. Sfoglia, installa e gestisci le trasformazioni dal [registro della community](https://github.com/opengraphintel/ogi-transforms). > **Nota di sicurezza:** I plugin che richiedono chiavi API devono essere considerati codice privilegiato. Se un plugin può accedere ai tuoi segreti ed effettuare richieste di rete in uscita, può abusare o esfiltrare tali segreti. Esamina il livello di fiducia, le autorizzazioni e i servizi richiesti prima di installare o eseguire plugin di terze parti.```bash # Search for transforms uv run ogi transform search dns # Install a transform uv run ogi transform install shodan-host-lookup ``` ### Categorie di trasformazione integrate | Categoria | Esempi | | --------- | ----------------------------------- | | DNS | Record A, AAAA, MX, NS, CNAME | | IP & ASN | GeoIP, IP inverso, informazioni ASN | | SSL/TLS | Trasparenza dei certificati, SSL labs | | Email | Validazione mailserver, controlli violazioni | | Web | WHOIS, informazioni dominio, estrazione web | | Social | Enumerazione username, profili social | | Hash | Ricerche MD5, SHA1, SHA256 | | Location | Geocodifica, meteo, dati ASN nelle vicinanze | ### Tipi di entità supportati `Person` • `Username` • `Domain` • `IPAddress` • `EmailAddress` • `PhoneNumber` • `Organization` • `URL` • `SocialMedia` • `Hash` • `Document` • `Location` • `ASNumber` • `Network` • `MXRecord` • `NSRecord` • `Nameserver` • `SSLCertificate` • `Subdomain` • `HTTPHeader` ### Creare le proprie trasformazioni Vuoi crearne una tua? Consulta la [guida per contribuire](https://github.com/opengraphintel/ogi-transforms/blob/main/CONTRIBUTING.md). Se la tua trasformazione necessita di credenziali per servizi esterni, dichiarale in `api_keys_required`. Non memorizzare segreti nelle impostazioni della trasformazione. OGI li gestisce in `API Keys`, e i plugin che utilizzano segreti sono considerati codice privilegiato. Se la tua trasformazione espone impostazioni limitate come `max_results` o `max_content_chars`, preferisci nomi di impostazioni stabili piuttosto che nomi personalizzati occasionali quando possibile. OGI può sovrascrivere centralmente i valori massimi con `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`, il che aiuta le distribuzioni cloud ad applicare limiti mentre gli utenti locali possono rimuoverli. Ogni plugin è una directory con un manifesto `plugin.yaml`:```yaml 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 ``` ## Architettura ### Stack Tecnologico | Livello | Tecnologia | | --------------------- | --------------------------------------------------------------------------- | | Backend | Python 3.14+, FastAPI, SQLModel, asyncpg / aiosqlite | | Frontend | React 19, TypeScript 5.9, Sigma.js (graphology), Zustand, Tailwind CSS 4 | | Database | PostgreSQL 16 (primario) / SQLite (fallback locale) | | Autenticazione e Real-time | Supabase Auth + JWT + Realtime (opzionale in modalità locale) | | Coda di job | Redis 7 + RQ (trasformazioni asincrone) | | Runtime AI | Worker AI Investigator basato su provider con orchestrazione delle trasformazioni verificata | | Gestori pacchetti | uv (backend), pnpm (frontend) | | Deploy | Docker, nginx, GHCR | ### Struttura del Progetto``` 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 ``` ### Configurazione OGI utilizza [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) con supporto per file `.env`. Le variabili di runtime/backend sono prefissate con `OGI_`. Le impostazioni di tipo lista accettano: - array JSON, per esempio `["plugins","../plugins"]` - stringhe separate da virgola, per esempio `plugins,../plugins` <details> <summary><strong>Variabili d'ambiente principali</strong></summary> | Variabile | Descrizione | Predefinito | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `OGI_APP_NAME` | Nome dell'applicazione | `OGI` | | `OGI_HOST` | Host di bind del backend | `0.0.0.0` | | `OGI_PORT` | Porta del backend | `8000` | | `OGI_CORS_ORIGINS` | Origini frontend consentite | `http://localhost:5173,http://localhost:3000` | | `OGI_USE_SQLITE` | Usa SQLite al posto di PostgreSQL | `true` | | `OGI_DB_PATH` | Percorso del file del database SQLite | `ogi.db` | | `OGI_DATABASE_URL` | Stringa di connessione PostgreSQL | `postgresql://postgres:postgres@localhost:5432/ogi` | | `OGI_REDIS_URL` | Stringa di connessione Redis per RQ/jobs | `redis://localhost:6379/0` | | `OGI_RQ_QUEUE_NAME` | Nome della coda per i job di trasformazione | `transforms` | | `OGI_TRANSFORM_TIMEOUT` | Timeout per singolo job di trasformazione in secondi | `300` | | `OGI_AGENT_WORKER_POLL_INTERVAL_SEC` | Intervallo di polling per il worker AI Investigator | `2.0` | | `OGI_AGENT_CLAIM_TIMEOUT_SEC` | Timeout di claim scaduto per il recupero passo AI Investigator | `120` | | `OGI_AUTO_RUN_MIGRATIONS` | Esegue automaticamente Alembic all'avvio locale non-SQLite dell'app | `true` | | `OGI_RUN_DB_MIGRATIONS` | Esegue le migrazioni DB nell'entrypoint del container | `false` | | `OGI_DB_MIGRATION_RETRIES` | Numero di tentativi di migrazione all'entrypoint | `30` | | `OGI_DB_MIGRATION_DELAY_SECONDS` | Ritardo tra i tentativi di migrazione all'entrypoint | `2` | | `OGI_PLUGIN_DIRS` | Directory di ricerca dei plugin | `plugins,../plugins` | | `OGI_DEPLOYMENT_MODE` | Modalità di deployment (`self-hosted` o `cloud`) | `self-hosted` | | `OGI_CLOUD_BILLING_ENABLED` | Abilita la fatturazione Supporter solo cloud e l'applicazione del cooldown delle trasformazioni | `false` | | `OGI_FREE_TRANSFORM_COOLDOWN_SECONDS` | Cooldown tra esecuzioni di trasformazione per utenti cloud gratuiti | `1800` | | `OGI_PAID_TRANSFORM_COOLDOWN_SECONDS` | Cooldown tra esecuzioni di trasformazione per utenti cloud a pagamento | `0` | | `OGI_STRIPE_SECRET_KEY` | Chiave segreta lato server Stripe per sessioni Checkout e portale | non impostato | | `OGI_STRIPE_WEBHOOK_SECRET` | Segreto di firma del webhook Stripe | non impostato | | `OGI_STRIPE_SUPPORTER_PRICE_ID` | ID prezzo ricorrente Stripe per il piano Supporter | non impostato | | `OGI_STRIPE_SUPPORTER_AMOUNT_CENTS` | Importo visualizzato per il piano Supporter | `300` | | `OGI_STRIPE_SUPPORTER_CURRENCY` | Valuta visualizzata per il piano Supporter | `usd` | | `OGI_BILLING_SUCCESS_URL` | Reindirizzamento facoltativo di successo per Stripe Checkout | derivato dalla richiesta | | `OGI_BILLING_CANCEL_URL` | Reindirizzamento facoltativo di annullamento per Stripe Checkout | derivato dalla richiesta | | `OGI_BILLING_PORTAL_RETURN_URL` | URL facoltativo di ritorno al portale di fatturazione Stripe | derivato dalla richiesta | | `OGI_REGISTRY_REPO` | Repository GitHub del registro trasformazioni | `opengraphintel/ogi-transforms` | | `OGI_REGISTRY_CACHE_TTL` | TTL della cache del registro in secondi | `3600` | | `OGI_TRANSFORM_SETTING_MAX_OVERRIDES` | Mappa massima globale facoltativa di override per le impostazioni di trasformazione | vuota | | `OGI_GITHUB_TOKEN` | Token GitHub facoltativo per limiti di rate API/registro | non impostato | | `OGI_SUPABASE_URL` | URL del progetto Supabase | non impostato | | `OGI_SUPABASE_ANON_KEY` | Chiave anonima/pubblica Supabase | non impostato | | `OGI_SUPABASE_SERVICE_ROLE_KEY` | Chiave ruolo servizio Supabase | non impostato | | `OGI_SUPABASE_JWT_SECRET` | Segreto JWT Supabase | non impostato | | `OGI_SUPABASE_REDIRECT_URL` | URL di reindirizzamento utilizzato dai flussi di autenticazione frontend | non impostato | | `OGI_ADMIN_EMAILS` | Utenti amministratori per la gestione di registro/plugin | non impostato | | `OGI_TELEMETRY_ENABLED` | Abilita o disabilita la telemetria a livello di installazione | `true` | | `OGI_TELEMETRY_LEVEL` | Livello di telemetria (`basic` o `full`) | `full` | | `OGI_API_KEY_ENCRYPTION_KEY` | Chiave Fernet per la memorizzazione crittografata delle chiavi API | non impostato ma fortemente raccomandato | | `OGI_API_KEY_INJECTION_ALLOW_COMMUNITY_PLUGINS` | Consente ai plugin della community di ricevere le chiavi API memorizzate | `true` | | `OGI_API_KEY_INJECTION_TRUSTED_TIERS_ONLY` | Limita l'iniezione delle chiavi memorizzate ai soli tier fidati | `false` | | `OGI_API_KEY_INJECTION_ALLOWED_TIERS` | Tier consentiti quando è attiva la modalità solo fidati | `official,verified` | | `OGI_API_KEY_SERVICE_ALLOWLIST` | Servizi consentiti facoltativi per l'iniezione delle chiavi memorizzate | vuota | | `OGI_API_KEY_SERVICE_BLOCKLIST` | Servizi bloccati facoltativi per l'iniezione delle chiavi memorizzate | vuota | | `OGI_LLM_PROVIDER` | Provider predefinito di fallback per AI Investigator | `openai` | | `OGI_LLM_MODEL` | Modello predefinito di fallback per AI Investigator | `gpt-4.1-mini` | | `OGI_EXPOSE_ERROR_DETAILS` | Includi dettagli interni nelle risposte 500 | `false` | | `OGI_SANDBOX_ENABLED` | Abilita la modalità di esecuzione sandbox | `false` | | `OGI_SANDBOX_TIMEOUT` | Timeout della sandbox in secondi | `30` | ``` --- [Read more](https://github.com/khashashin/ogi)
