Configurazione
Tutta la configurazione è gestita tramite variabili d'ambiente definite in .env. Copia .env.example in .env e adatta i valori al tuo ambiente.
Ambiente Applicativo
| Variabile | Predefinito | Descrizione |
|---|---|---|
ENVIRONMENT | development | Impostare a production per attivare la validazione JWT, il CORS restrittivo e i controlli RLS all'avvio, e per disattivare la casella email di sviluppo |
Database
| Variabile | Default | Descrizione |
|---|---|---|
DATABASE_URL | postgresql+asyncpg://nis2:nis2secret@postgres:5432/nis2 | Stringa di connessione asincrona al database (usata da FastAPI) |
DATABASE_URL_SYNC | postgresql://nis2:nis2secret@postgres:5432/nis2 | Stringa di connessione sincrona (usata dalle migrazioni Alembic) |
POSTGRES_USER | nis2 | Utente PostgreSQL |
POSTGRES_PASSWORD | nis2secret | Password PostgreSQL |
POSTGRES_DB | nis2 | Nome del database PostgreSQL |
MIGRATION_DATABASE_URL | (ricade su DATABASE_URL) | Identità privilegiata usata SOLO per Alembic e per il setup RLS all'avvio. DATABASE_URL deve puntare a un ruolo NOSUPERUSER NOBYPASSRLS, altrimenti ogni policy RLS è decorativa — l'API lo verifica all'avvio e si rifiuta di servire |
MIGRATION_DATABASE_URL_SYNC | (ricade su DATABASE_URL_SYNC) | Variante sincrona della precedente |
NIS2_APP_PASSWORD | — | Password del ruolo di runtime nis2_app, creato alla prima inizializzazione del volume da infra/docker/initdb/01-create-app-role.sh |
DB_POOL_SIZE | 10 | Connessioni per pool, per worker gunicorn — gunicorn fa prefork, quindi ogni worker costruisce il proprio |
DB_MAX_OVERFLOW | 5 | Overflow per worker. La domanda totale è worker × (pool + overflow): tienila sotto il max_connections del server (100 nell'immagine standard) |
Redis
| Variabile | Default | Descrizione |
|---|---|---|
REDIS_URL | redis://redis:6379/0 | Connessione Redis per caching e sessioni |
Autenticazione (JWT)
| Variabile | Default | Descrizione |
|---|---|---|
JWT_SECRET | (cambiare in produzione) | Chiave segreta per firmare i token JWT. Generare con openssl rand -hex 32 |
JWT_ALGORITHM | HS256 | Algoritmo di firma JWT |
ACCESS_TOKEN_EXPIRE_MINUTES | 30 | Durata del token di accesso in minuti |
REFRESH_TOKEN_EXPIRE_DAYS | 7 | Durata del token di aggiornamento in giorni |
Generazione delle chiavi RS256
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in private_key.pem -out public_key.pemImposta JWT_PRIVATE_KEY e JWT_PUBLIC_KEY con il contenuto di quei file (con gli a-capo come \n, oppure usando la sintassi multi-riga nel .env). La chiave pubblica viene poi esposta su GET /.well-known/jwks.json, perché terze parti possano verificare i token.
Cifratura a riposo
| Variabile | Default | Descrizione |
|---|---|---|
DATA_ENCRYPTION_KEY | — | Chiave AES-GCM per i seed TOTP, le credenziali dei canali di notifica e le prove dei segreti trovati. Almeno 32 caratteri; senza materiale robusto l'API rifiuta l'avvio |
DATA_ENCRYPTION_KEY_PREVIOUS | (vuoto) | La chiave da cui si sta ruotando. Da impostare solo durante una rotazione — vedi Rotazione dei segreti; la decrittazione prova prima quella corrente e poi questa |
Osservabilità
| Variabile | Default | Descrizione |
|---|---|---|
LOG_LEVEL | INFO | Verbosità di API e worker. Ogni record porta l'identificativo di richiesta, che torna anche nell'header di risposta X-Request-Id |
GET /metrics espone le serie Prometheus — tasso di richieste, errori e latenza per template di rotta, più l'utilizzo del pool del database. È non autenticato e montato fuori da /api/v1, perché Prometheus lo interroga sulla rete di compose per nome di servizio; bloccalo al bordo se esponi l'API direttamente. Il prometheus.yml incluso lo interroga già.
GET /api/v1/health riporta la versione in esecuzione e il commit da cui l'immagine è stata costruita.
Ripristino Password (B05)
Il flusso per dimenticare/ripristinare la password richiede un URL pubblico da inserire nel link via email e un relay SMTP (o la dev outbox) per la consegna. In make dev e nella suite e2e, lasciare SMTP_HOST vuoto attiva la dev outbox in memoria — l'email viene loggata a livello INFO e catturata per GET /api/v1/auth/debug/last-email (montata solo quando ENVIRONMENT != "production"). La produzione con SMTP_HOST vuoto si rifiuta di consegnare l'email: la rotta converte l'errore RuntimeError in un errore 5xx piuttosto che ignorare silenziosamente l'invio.
| Variabile | Default | Descrizione |
|---|---|---|
PUBLIC_URL | http://localhost:8077 | URL di base a cui punta il link di ripristino. L'utente clicca su ${PUBLIC_URL}/reset-password?token=… |
RESET_TOKEN_TTL_MINUTES | 30 | Durata del token di ripristino. I token sono monouso; una volta consumati (quando used_at non è null) vengono rifiutati anche se non sono ancora scaduti |
SMTP_HOST | `` (dev outbox) | Hostname del relay SMTP. Lasciare vuoto in dev / e2e — l'email viene catturata in-process |
SMTP_PORT | 587 | Porta del relay SMTP |
SMTP_USER | `` | Username di autenticazione SMTP (omettere se il relay non richiede l'auth) |
SMTP_PASSWORD | `` | Password di autenticazione SMTP |
SMTP_FROM | noreply@nis2.local | Header From: sulle email in uscita |
SMTP_STARTTLS | true | Invia STARTTLS dopo l'EHLO (caso comune per le porte 25 / 587) |
SMTP_SSL | false | Avvolge l'intera connessione in TLS (stile porta 465). Mutualmente esclusivo con SMTP_STARTTLS |
Report
I report generati (PDF / HTML / Markdown / JSON / CSV / JUnit XML) vengono salvati in /tmp/nis2-reports/ sul worker Celery, e sono condivisi con il container API tramite il volume Docker denominato reports-data. Un task Celery beat giornaliero (cleanup-old-reports) pulisce questa directory dai file più vecchi del TTL impostato — senza questo meccanismo, il disco si riempirebbe in modo incontrollato man mano che gli utenti generano report.
| Variabile | Default | Descrizione |
|---|---|---|
REPORT_TTL_DAYS | 30 | Giorni di conservazione per i file di report prima che il task di pulizia giornaliera li elimini. Un tempo sufficiente per permettere a un team di compliance di scaricare il report della settimana precedente dopo le ferie, ma abbastanza breve da evitare che un'installazione con centinaia di scansioni al giorno riempia il disco in poche settimane. Il task di pulizia viene eseguito indipendentemente da questo valore, che si limita a stabilire l'età limite dei file da cancellare. |
Revoca dei certificati (CertMate)
La revoca di un certificato viene chiesta a un'istanza CertMate, invece di essere stabilita qui. Una risposta sulla revoca vale solo se è stata verificata — la risposta OCSP firmata dall'emittente o da un delegato autorizzato, riferita proprio a quel certificato e ancora valida nel tempo; oppure una CRL emessa e firmata da quell'emittente e non scaduta — e quel client ce l'ha già CertMate.
Senza questa configurazione la scansione funziona lo stesso e riporta la revoca come UNKNOWN, indicando il motivo nel report. Non deduce mai: un certificato che si limita a indicare un responder OCSP non è un certificato che è stato verificato.
| Variabile | Default | Descrizione |
|---|---|---|
CERTMATE_URL | (non impostata) | URL base dell'istanza CertMate, ad esempio https://certmate.example.com. Servono sia questa sia il token: il solo URL non è una configurazione. |
CERTMATE_TOKEN | (non impostata) | Una chiave API di quell'istanza. È sufficiente una chiave viewer limitata ai domini che questo scanner può esaminare, perché lo scanner si limita a leggere. |
CERTMATE_TIMEOUT | 15 | Secondi di attesa per una risposta prima di riportare UNKNOWN. |
Il client si installa con l'extra opzionale: pip install nis2scan[certmate].
Celery
| Variabile | Default | Descrizione |
|---|---|---|
CELERY_BROKER_URL | redis://redis:6379/1 | Message broker per Celery |
CELERY_RESULT_BACKEND | redis://redis:6379/2 | Backend per i risultati di Celery |
Frontend (Next.js)
| Variabile | Default | Descrizione |
|---|---|---|
NEXT_PUBLIC_API_URL | http://localhost:8000 | URL pubblico dell'API (lato client) |
NEXTAUTH_URL, NEXTAUTH_SECRET e API_URL erano documentate qui e non sono lette da nulla: next-auth non è una dipendenza di packages/web. Se il tuo .env le contiene ancora sono inerti.
Produzione (Caddy)
| Variabile | Default | Descrizione |
|---|---|---|
DOMAIN | nis2.tuodominio.com | Dominio per la configurazione automatica di HTTPS con Caddy. Da impostare nei deployment in produzione |
Default dello Scanner
Il comportamento dello scanner viene configurato per ogni scansione tramite l'API al momento della creazione della scansione o della pianificazione. Le impostazioni a livello di organizzazione stabiliscono i default ereditati dalle nuove scansioni. I principali parametri nell'endpoint di creazione della scansione includono:
- Timeout: 10 secondi per controllo (
scan_timeout) - Concorrenza: 20 task paralleli (
concurrency) - Host massimi: 0 (illimitato) -- limite configurabile per i target di ogni scansione (
max_hosts) - Funzionalità: Le singole categorie di controlli (
dns_checks,web_checks,port_scan,whois_checks) possono essere attivate/disattivate per ogni scansione. Le impostazioni dell'organizzazione salvano i default che ogni nuova scansione andrà ad ereditare.
Impostazioni dell'Organizzazione
Le impostazioni a livello organizzativo sono gestite dalla dashboard nella sezione Impostazioni:
- Nome dell'organizzazione e metadati
- Configurazione di default delle scansioni (funzionalità, concorrenza, timeout)
- Gestione dei membri del team (inviti, assegnazione ruoli)
- Gestione chiavi API
- Preferenze per i canali di notifica
Row-Level Security
| Variabile | Predefinito | Descrizione |
|---|---|---|
RLS_SUPERUSER_OK | — | Impostare a 1 per sopprimere l'errore di avvio quando il ruolo database è SUPERUSER o BYPASSRLS. Sconsigliato in produzione — provisionare un ruolo applicativo non-superuser |