# Sicurezza

> Credenziali, HTTPS, accesso ed esposizione di rete di un'installazione PentAGI.

## [Modifica le impostazioni predefinite](https://pentagi.com/it/docs/configuration/security/#change-the-defaults)

Una nuova installazione crea l'amministratore locale `admin@pentagi.com` con la password `admin`, che devi cambiare al primo accesso. Se perdi la password, il menu di manutenzione dell'installer la reimposta purché l'account utilizzi ancora l'indirizzo `admin@pentagi.com`.

Imposta questi valori in `.env` prima del primo avvio; l'installer genera il salt e le password per te. PostgreSQL e Neo4j leggono le credenziali solo quando creano i volumi dei dati, quindi modificarle in seguito interrompe la connessione:

| Variabile                                            | Scopo                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `COOKIE_SIGNING_SALT`                                | Firma i cookie di sessione e i token API — imposta un valore casuale                                         |
| `PENTAGI_POSTGRES_USER`, `PENTAGI_POSTGRES_PASSWORD` | Credenziali PostgreSQL                                                                                       |
| `NEO4J_PASSWORD`                                     | Password Neo4j per il [knowledge graph](https://pentagi.com/it/docs/glossary/#knowledge-graph); `NEO4J_USER` deve rimanere `neo4j` |
| `PUBLIC_URL`                                         | L'URL aperto dagli utenti, ad esempio `https://pentagi.example.com`                                          |

Su un'installazione in esecuzione, cambia prima la password del database all'interno di PostgreSQL o Neo4j, poi in `.env`.

## [HTTPS](https://pentagi.com/it/docs/configuration/security/#https)

PentAGI espone HTTPS sulla porta 8443 con un certificato autofirmato. Per usare il tuo certificato, imposta `SERVER_SSL_CRT` e `SERVER_SSL_KEY` e monta i file in `docker-compose.yml`.

## [Utenti e accesso](https://pentagi.com/it/docs/configuration/security/#users-and-sign-in)

Non è disponibile un modulo di registrazione. Gli amministratori gestiscono gli utenti locali tramite le API Users (`/api/v1/users/`) da una sessione del browser con accesso effettuato — un token API restituisce 403 in quel contesto — e i ruoli limitano ciò che ciascun utente può visualizzare e modificare. Gli utenti locali modificano la propria email e password sotto **Settings → Account**.

Se configuri l'accesso con GitHub o Google, un login il cui indirizzo email verificato dal provider corrisponde a un account esistente, inclusi gli account locali, accede a quell'account con il suo ruolo; qualsiasi altro login crea un nuovo account con il ruolo utente predefinito. Ogni installazione inizia con l'amministratore `admin@pentagi.com`, quindi spostalo su un indirizzo di tua proprietà in **Settings → Account** prima di abilitare l'accesso e abilitalo solo dove i nuovi account sono accettabili, ad esempio con un'app Google Workspace limitata al tuo dominio.

L'accesso con GitHub e Google è disponibile tramite OAuth. Registra un'app con callback `${PUBLIC_URL}/api/v1/auth/login-callback` e aggiungi le sue credenziali:

```bash
PUBLIC_URL=https://pentagi.example.com
OAUTH_GITHUB_CLIENT_ID=your_github_client_id
OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
```

## [Esposizione di rete](https://pentagi.com/it/docs/configuration/security/#network-exposure)

Per impostazione predefinita, l'interfaccia web di PentAGI ascolta solo su `127.0.0.1`. Per raggiungerla da altre macchine:

```bash
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443
PUBLIC_URL=https://192.168.1.100:8443
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443
```

Usa l'indirizzo reale in `PUBLIC_URL` e `CORS_ORIGINS`, mai `0.0.0.0`. Ricrea i container con `docker compose up -d --force-recreate` e apri la porta 8443 nel firewall.

Dietro un reverse proxy, imposta `TRUSTED_PROXIES` sull’indirizzo o sul CIDR del proxy, separati da virgola. Altrimenti ogni richiesta sembra provenire dal proxy e il limite di accessi per indirizzo — 30 tentativi falliti in cinque minuti, poi un blocco di 15 minuti — viene condiviso da tutti gli utenti.

Il container [sandbox](https://pentagi.com/it/docs/glossary/#sandbox) di ogni [flow](https://pentagi.com/it/docs/glossary/#flow) espone anche due porte per callback out-of-band, come le reverse shell. Provengono dalle 2000 porte che iniziano da `DOCKER_PORTS_BASE` (predefinito `28000`) e sono associate a `DOCKER_PUBLIC_IP`, l'indirizzo che gli [agent](https://pentagi.com/it/docs/glossary/#agent) forniscono anche ai target per effettuare il callback.

Per impostazione predefinita `DOCKER_PUBLIC_IP` è `0.0.0.0`: le porte ascoltano su ogni interfaccia dell'host Docker e gli agent cercano da soli il loro indirizzo pubblico. Impostalo su un indirizzo specifico solo se l'host possiede quell'indirizzo e i target possono raggiungerlo; dietro NAT, mantieni l'impostazione predefinita. Le porte pubblicate da Docker bypassano le regole di ufw e firewalld sull'host, quindi limita l'intervallo con un firewall davanti all'host, come un gruppo di sicurezza cloud, o con regole nella catena `DOCKER-USER` di Docker.

`PROXY_URL` instrada le chiamate del backend ai provider di modelli, al provider di embedding, alle API di ricerca e al controllo degli aggiornamenti attraverso un proxy, il che aiuta a isolare l'installazione dalle reti esterne. Anche gli endpoint self-hosted come Ollama, vLLM o SearXNG passano attraverso di esso, poiché non esiste un'eccezione `NO_PROXY`, quindi il proxy deve essere in grado di raggiungerli. I container sandbox dei flow, dove gli agent eseguono i loro comandi, lo scraper, che apre le pagine web per lo strumento browser, e il servizio Graphiti non lo utilizzano, quindi limita il loro traffico in uscita a livello di rete. Anche l'accesso con GitHub o Google e le chiamate a un endpoint Langfuse o OpenTelemetry esterno agli stack inclusi non lo utilizzano, e il demone Docker scarica le immagini con le proprie impostazioni proxy.

## [Controllo degli aggiornamenti](https://pentagi.com/it/docs/configuration/security/#update-check)

Entro due minuti dall'avvio e poi ogni tre ore, il server chiede a `update.pentagi.com` se è disponibile una build più recente. La richiesta include l'ID dell'installazione, la chiave di licenza se impostata, la versione e la piattaforma, e un riepilogo dell'installazione: il provider configurato e i tipi di accesso, alcuni interruttori di funzionalità, i conteggi di utenti, flow, [task](https://pentagi.com/it/docs/glossary/#task), container, prompt, token API e [tool call](https://pentagi.com/it/docs/glossary/#tool-call), e i totali di token e costi per tipo di provider — nessun nome, indirizzo, prompt o contenuto dei flow. `UPDATE_CHECK_INTERVAL=0` lo disattiva. Ogni volta che l'installer si avvia e dopo ogni azione che esegue, come Apply Changes, Update, Start o Stop, invia le immagini installate e lo stato di ciascuno stack, oltre allo stesso riepilogo mentre PentAGI è in esecuzione; `UPDATE_CHECK_INTERVAL` non lo influenza.

> [!WARNING]
> Il container `pentagi` viene eseguito come root perché gestisce i container tramite il socket Docker. Per un isolamento maggiore, esegui i [tools](https://pentagi.com/it/docs/glossary/#tool) su un [worker node](https://pentagi.com/it/docs/deployment/worker-node/) separato.