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

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

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

## Docker

### Sviluppo```bash
cp .env.example .env
docker compose up

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

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

### 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

### 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`                                                |
| `OGI_SANDBOX_MEMORY_MB`                         | Limite di memoria della sandbox in MB                                                                            | `256`                                               |
| `OGI_SANDBOX_ALLOWED_TIERS`                     | Tier consentiti in modalità sandbox cloud                                                                        | `official,verified`                                 |
| `OGI_BOOT_REQUIREMENTS_ENABLE`                  | Abilita l'installazione delle dipendenze dei plugin all'avvio                                                    | `true`                                              |
| `OGI_BOOT_REQUIREMENTS_FILE`                    | Percorso del file dei requisiti di avvio                                                                         | `/app/plugins/requirements.txt`                     |
| `OGI_BOOT_LOCK_FILE`                            | Percorso del file di blocco di avvio                                                                             | `/app/plugins/ogi-lock.json`                        |
| `OGI_BOOT_REQUIREMENTS_STRICT`                  | Interrompi l'avvio se i requisiti del plugin sono mancanti                                                       | `false`                                             |
| `OGI_BOOT_REQUIREMENTS_CACHE_DIR`               | Directory temporanea/cache per la generazione dei requisiti di avvio                                             | `/tmp/ogi-boot`                                     |
| `OGI_FRONTEND_PORT`                             | Mappatura porta frontend locale Docker                                                                           | `3000`                                              |
| `OGI_IMAGE_TAG`                                 | Tag immagine di produzione per deploy compose/Coolify-style                                                      | `latest`                                            |
| `OGI_BACKEND_IMAGE`                             | Override facoltativo dell'immagine backend                                                                       | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_WORKER_IMAGE`                              | Override facoltativo dell'immagine worker. Predefinito all'immagine backend perché worker e backend condividono la stessa build. | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_FRONTEND_IMAGE`                            | Override facoltativo dell'immagine frontend                                                                      | `ghcr.io/khashashin/ogi-frontend`                   |
| `OGI_CLI_BEARER_TOKEN`                          | Token bearer CLI facoltativo per backend con autenticazione                                                      | non impostato                                       |

Consulta [`.env.example`](https://github.com/khashashin/ogi/blob/HEAD/.env.example) per la lista completa.

</details>

## Sviluppo

### Esecuzione dei test```bash
# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest

# Frontend
cd frontend
pnpm test

### Pipeline CI

Il [workflow CI](https://github.com/khashashin/ogi/blob/HEAD/.github/workflows/ci.yml) viene eseguito per ogni pull request:

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

## Contribuire

PR benvenuti! Se trovi un bug o hai un'idea, [apri un issue](https://github.com/khashashin/ogi/issues).

Per nuove trasformazioni, contribuisci a [ogi-transforms](https://github.com/opengraphintel/ogi-transforms).

### Per Iniziare

1. Fai il fork del repository
2. Crea un branch per la funzionalità (`git checkout -b feature/my-feature`)
3. Apporta le tue modifiche
4. Esegui test e linting
5. Invia una pull request

## Utilizzo Legale e Responsabile

OGI è uno strumento di OSINT e analisi dei grafi per uso generale. **Sei l'unico responsabile per come lo utilizzi.** Vedi [LEGAL.md](https://github.com/khashashin/ogi/blob/HEAD/LEGAL.md) per l'avviso legale completo.

- **Rispetta i Termini di Servizio di terze parti.** Le trasformazioni che interrogano servizi esterni (DNS, WHOIS, web scraping, ricerche di username, ecc.) devono essere utilizzate in conformità con i ToS di tali servizi. L'interrogazione automatica o massiva di siti che la proibiscono potrebbe violare i loro termini.
- **Rispetta le leggi sulla protezione dei dati.** Se sei nell'UE o tratti dati di residenti UE, il GDPR si applica a te come titolare del trattamento. La raccolta, l'archiviazione o l'elaborazione di dati personali (nomi, indirizzi email, indirizzi IP, ecc.) richiede una base giuridica. OGI stesso non memorizza dati oltre la tua istanza locale — sei responsabile di ciò che raccogli e conservi.
- **Utilizzo solo per scopi leciti.** OGI è destinato a ricerca legittima sulla sicurezza, indagini, threat intelligence e uso educativo. Non utilizzarlo per molestare individui, effettuare accessi non autorizzati o violare la legge applicabile.
- **Compatibilità dei formati di file.** OGI supporta l'importazione del formato di scambio grafico MTGX. Questo è fornito puramente per l'interoperabilità dei dati e non implica alcuna affiliazione o approvazione da parte dei creatori di strumenti che usano questo formato.

> **Disclaimer:** OGI è fornito "così com'è" senza alcuna garanzia. Gli autori non sono responsabili per qualsiasi uso improprio o danni derivanti dall'uso di questo software.

## Licenza

Questo progetto è concesso in licenza ai sensi della [GNU Affero General Public License v3.0](https://github.com/khashashin/ogi/blob/HEAD/LICENSE).

---

<div align="center">

**[Segnala Bug](https://github.com/khashashin/ogi/issues) &bull; [Richiedi Funzionalità](https://github.com/khashashin/ogi/issues) &bull; [Discussioni](https://github.com/opengraphintel/ogi-transforms/discussions)**

Realizzato con 💜 dalla comunità OGI

</div>