Files
Alby96andClaude Opus 5.5 032c602b49
CI / Build and test (SQLite) (pull_request) Successful in 55s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Failing after 2m4s
feat: system and security - start-up, accounts, sign-in, licences, log, jobs, companies (M2)
The instance now starts on its own from KHAEMHAT_* variables: it migrates the system
and company databases, creates the super user and the first company, and only then
reports ready. Users sign in with password and TOTP through revocable database
sessions, and licences decide which modules and how many companies are available.

- Configuration: every wrong variable reported at once (exit code 2), _FILE variants
- Accounts, password policy and lockout, TOTP with recovery codes, session states
  with token rotation, security audit with a hash chain
- Sign-in pages (mockups 001-003), authorization attributes, security headers and a
  CSP without inline scripts, login rate limit
- Signed licences, activation codes, test mode, licence tool
- DataProtection keys in the system database, encrypted with the instance key
- Memory or Redis cache (in-house RESP client) that falls back to memory
- Database log by section with trace id; cron scheduler with locks and system jobs;
  record history (audit_log)
- Company creation, states, company context and X-Company, 503 in maintenance
- In-memory SQLite databases stay alive for the process (tests, demo)
- Tests for all of the above, ADR 0019, wiki, SECURITY, CHANGELOG, STATUS, DATA-MODEL

Refs #15 #16 #17 #18 #19 #20 #21 #22 #23 #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:29:24 +01:00

31 KiB

Sicurezza di Khaemhat

Stato: bozza · Revisione 2026-11-10 · Fonte: SPEC §1, §2, §5.4, §6, §7, §8, §9.4, §9.5, §12, §13, §15, §18, §21; emendamenti E1-E2

Documento tecnico per chi sviluppa e rivede Khaemhat. Descrive il modello di minaccia, i meccanismi di sicurezza previsti dalla specifica e le regole di implementazione. Dove la specifica non fissa un dettaglio, il documento indica una proposta (marcata come tale) da confermare con un ADR quando il componente viene sviluppato.

La guida per gli utenti è nella wiki: Utenti e permessi, Impostazioni, API e MCP, Licenze e moduli.


1. Modello di minaccia (sintesi)

1.1 Beni da proteggere

Bene Dove sta Perché conta
Dati contabili e fiscali (documenti, registrazioni, liquidazioni) DB aziendali integrità con valore legale; registrazioni definitive immutabili
Dati personali (clienti, fornitori, contatti, utenti) DB aziendali riservatezza (GDPR)
Credenziali di accesso (hash password, segreti TOTP, chiavi API) sys_users, users, sys_api_keys, api_keys presa di controllo degli account
Segreti di integrazione (connection string, SMTP/PEC, S3/WebDAV, intermediari SDI, canali) DB di sistema/aziendale, cifrati accesso a sistemi terzi, invio di fatture a nome dell'azienda
KHAEMHAT_SECRET_KEY solo variabile d'ambiente decifra tutti i segreti e i backup
Chiavi DataProtection sys_data_protection_keys falsificazione dei cookie di sessione
Backup /data/backups, S3, WebDAV copia completa dei dati
Chiave privata di firma licenze solo fuori dal repository emissione di licenze false

1.2 Attori

  • Attaccante esterno che raggiunge l'applicazione attraverso il reverse proxy (Internet o LAN).
  • Utente autenticato che tenta di superare i propri permessi, di vedere un'altra azienda o costi e margini.
  • Integrazione compromessa: chiave API esposta, sistema esterno ostile, assistente AI che riceve istruzioni malevole nei dati (prompt injection) e prova a usare gli strumenti MCP.
  • Amministratore che tenta azioni riservate al super utente.
  • Chi ottiene un backup o l'accesso al volume /data o al bucket remoto.
  • File malevoli caricati come allegati o importati (CSV/XLSX/XML/P7M).

1.3 Confini di fiducia

Browser ──HTTPS──> Reverse proxy (TLS, HSTS) ──HTTP──> Khaemhat (Kestrel, 8080) ──> PostgreSQL / SQLite
                                                        │                        ──> Redis (opzionale)
Sistemi esterni ──HTTPS (API key)──> /api/v1, /mcp      ├──> SMTP, IMAP/PEC, SDI, VIES, BCE
                                                        ├──> S3 / WebDAV (backup cifrati)
                                                        └──> registro pacchetti Gitea (sola lettura)

Tutto ciò che arriva dal browser, dalle API, dai file caricati, dalle caselle PEC, dagli intermediari e dalle risposte HTTP esterne è non fidato e va validato sul server.

1.4 Minacce principali e contromisure

Minaccia Contromisura Sezione
Indovinare o riusare password PBKDF2 600.000 iterazioni, policy, storico, lockout, rate limit, TOTP §3, §4, §5
Furto della sessione cookie HttpOnly; Secure; SameSite=Lax, id 256 bit, revoca, verifica a ogni riconnessione del circuito §3
Escalation di privilegi autorizzazione sempre lato server, livelli, permessi, licenza, ruoli mai superiori ai propri §2
Accesso ai dati di un'altra azienda un database per azienda, ICompanyContext vincolato all'utente/chiave §2.4
SQL injection QueryBuilder e SqlFragment parametrizzati, mai concatenazione di input §9
XSS e clickjacking rendering Blazor con escaping, CSP con nonce, X-Frame-Options: DENY §8
Esecuzione di comandi nessun Process.Start fuori da Infrastructure/Backup; script solo da catalogo §9
Furto di backup o di segreti a riposo AES-256-GCM con chiave da KHAEMHAT_SECRET_KEY, SHA-256 per l'integrità §6, §11
Chiave API esposta hash SHA-256, prefisso visibile, scadenza, IP consentiti, permessi minimi, revoca §5
File caricati malevoli streaming, limite dimensione, percorso generato, hook antivirus, anteprima sicura §10
Licenze contraffatte firma ECDSA P-256, chiave privata fuori dal repository, codici test solo in modalità test §13
Ripudio di azioni critiche audit_log per azienda, sys_security_audit immutabile §12

2. Livelli e autorizzazione

2.1 Livelli

UserLevel (SPEC §7.1, §22):

Livello Tabella Note di sicurezza
SuperUser sys_users uno solo, creato al bootstrap da KHAEMHAT_SUPERUSER*; non eliminabile né degradabile; TOTP obbligatorio
Administrator sys_users creato solo dal super utente; TOTP obbligatorio; non crea amministratori, non attiva licenze, non elimina database; il ripristino richiede la conferma del super utente
Standard users (DB aziendale) `Kind = Human

Azioni riservate al super utente: creazione/eliminazione amministratori, attivazione moduli e licenze, creazione/eliminazione/clonazione database aziendali, impostazioni critiche (SMTP, chiavi, cloud backup), conferma del ripristino (notifica + TOTP), modalità manutenzione, rimozione dati demo, rotazione segreti.

2.2 Permessi

  • Codici modulo.entità.azione (es. sales.invoice.issue, ledger.entry.finalize, company.users.manage), azioni standard read, write, delete, post/issue/finalize, reopen, export, print, override_*.
  • Definiti da ogni IModule come PermissionDefinition; ruoli predefiniti come modelli in sys_roles_templates, copiati in roles/role_permissions di ogni azienda; non modificabili, clonabili.
  • Permessi effettivi = unione dei ruoli (user_roles) + override (user_permission_overrides); i divieti espliciti prevalgono (mockup 081).
  • Flag per utente con effetto di sicurezza: vede solo i propri clienti, vede costi e margini, può esportare, può usare le API. Vanno applicati nelle query (filtro dei clienti dell'agente, esclusione delle colonne di costo dai DTO), non solo nascondendo colonne nell'interfaccia.
  • Un amministratore non può creare o assegnare ruoli con permessi superiori ai propri: il controllo sta in RoleService, non nell'interfaccia.

2.3 Applicazione lato server

Regola: l'interfaccia nasconde, il server decide. Ogni pagina, endpoint API, tool MCP, procedura e attività programmata passa da un controllo esplicito.

Componente Uso
[RequirePermission("sales.invoice.issue")] (RequirePermissionAttribute) pagine Blazor ed endpoint che richiedono un permesso
[RequireLevel(UserLevel.Administrator)] (RequireLevelAttribute) pagine e endpoint di amministrazione; SuperUser per le azioni riservate
[RequireModule(ModuleCode.Acct)] (RequireModuleAttribute) funzioni dietro licenza
PermissionAuthorizationHandler valuta permessi, livello e licenza a partire da ICurrentUser
LicenseGate / ModuleRegistry filtrano menu, endpoint, tool MCP e procedure per licenza attiva
  • Modulo non licenziato = permesso negato: risposta con codice module_not_licensed (problem details RFC 9457 per le API; ModuleNotLicensedException nei servizi). Gli endpoint dei moduli non licenziati non sono nemmeno registrati.
  • I controlli vanno ripetuti nei servizi applicativi per le operazioni invocabili da più ingressi (UI, API, MCP, regole, attività programmate): non basta l'attributo sulla pagina.
  • Le attività programmate e le procedure girano con l'identità indicata in Esegui come e ne rispettano i permessi.
  • Test obbligatori (SPEC §18): permessi per livello, multi-azienda con due database.

2.4 Isolamento fra aziende

  • Ogni azienda ha il proprio database; le tabelle operative non hanno company_id. Una query non può "sbagliare filtro" verso un'altra azienda, ma può aprire la connessione sbagliata: l'unico punto di risoluzione è ICompanyRegistry tramite ICompanyContext.
  • ICompanyContext è per circuito Blazor e per richiesta API. Per gli utenti aziendali l'azienda è quella dell'utente e non può essere cambiata dall'header X-Company; per le chiavi API è quella della chiave: un X-Company diverso produce 403. Solo gli account di istanza scelgono l'azienda.
  • Le chiavi di cache sono kh:{azienda}:{area}:{key}: mai una chiave senza azienda per dati aziendali (permessi e menu compresi).
  • I file stanno in /data/files/<azienda>/…: il percorso deriva dal contesto, mai da un parametro della richiesta.

Aspetto Regola
Autenticazione schema KhaemhatSession scritto in casa (SessionAuthenticationHandler, ADR 0019); nessun ASP.NET Identity/EF
Attributi del cookie khaemhat_session, HttpOnly; SameSite=Lax; Secure quando la richiesta è HTTPS o KHAEMHAT_PUBLIC_URL è https
Identificatore 256 bit casuali da SecureTokenGenerator (RandomNumberGenerator)
Stato riga di sessione in sys_sessions (account di istanza) o user_sessions (utenti aziendali): dispositivo, IP, creazione, ultimo uso, revoca
Scadenza scorrevole, con timeout di inattività da impostazioni (mockup 086: 480 minuti)
Revoca dall'utente (Il mio profilo) e dall'amministratore; effetto immediato
Blazor Server il circuito riverifica la sessione a ogni riconnessione; una sessione revocata chiude il circuito
Nuovi dispositivi avviso all'utente al primo accesso da un dispositivo non visto
Limiti sessioni per utente (impostazione); utenti concorrenti da licenza contati sulle sessioni attive di tutte le aziende
Antiforgery sui form statici (login, cambio password, recupero)
Cookie ammessi sessione e tema prima del login (SPEC §1.5); nessun cookie di profilazione

Implementato in M2. La riga di sessione contiene solo l'hash SHA-256 dell'identificatore: una lettura del database non consente di impersonare le sessioni attive. L'identificatore viene rigenerato a ogni passaggio di stato (password verificata, TOTP verificato, password cambiata), contro la session fixation. Una sessione che non è ancora attiva (manca il TOTP o il cambio password) apre solo le pagine del suo passo. Il circuito Blazor ricontrolla la sessione ogni minuto e si chiude se è stata revocata; mettere un'azienda in manutenzione o disattivarla revoca le sessioni dei suoi utenti.


4. Password, lockout e rate limiting

4.1 Hash delle password

  • PasswordHasher: PBKDF2-HMAC-SHA256, 600.000 iterazioni, salt casuale di 16 byte (Rfc2898DeriveBytes.Pbkdf2).
  • Confronto in tempo costante (CryptographicOperations.FixedTimeEquals).
  • Proposta di formato memorizzato, versionato per consentire di aumentare le iterazioni in futuro con rehash al login: pbkdf2-sha256$600000$<salt base64>$<hash base64> con hash di 32 byte.
  • La password del super utente arriva da KHAEMHAT_SUPERUSER_PASSWORD (o _FILE) solo al primo avvio; nel database finisce solo l'hash; il cambio è obbligatorio al primo accesso (mockup 003).

4.2 Policy (PasswordPolicy)

Regola Predefinito
Lunghezza minima 10
Classi di caratteri 3
Storico 5 (hash precedenti, stesso algoritmo)
Scadenza opzionale
Password provvisorie monouso, cambio obbligatorio al primo uso
Recupero via e-mail con token monouso a scadenza breve (proposta: hash del token in DB, validità 30 minuti)

4.3 Lockout

  • 5 tentativi falliti → blocco di 15 minuti per account (valori configurabili).
  • I tentativi sono registrati (LoginAttempt) e finiscono nella sezione Autenticazione del log e in sys_security_audit.
  • Messaggi d'errore uniformi: non rivelare se l'utente esiste o se il blocco è attivo per un utente specifico (proposta).

4.4 Rate limiting

  • Middleware di rate limiting di ASP.NET Core (in-box), LoginRateLimiter:
    • /login (e passaggio TOTP) per indirizzo IP (mockup 086: 10/minuto);
    • /api e /mcp per chiave API (mockup 086: 600/minuto).
  • Oltre il limite: 429 Too Many Requests con Retry-After.
  • Proposta: dietro reverse proxy usare ForwardedHeaders fidandosi solo degli indirizzi del proxy configurato; altrimenti l'IP del client è falsificabile con X-Forwarded-For e il limite per IP perde efficacia.

5. Verifica in due passaggi (TOTP)

  • TotpGenerator scritto in casa secondo RFC 6238 (su HOTP, RFC 4226), compatibile con le comuni app di autenticazione (parametri standard: HMAC-SHA1, 6 cifre, passo di 30 secondi; proposta).
  • Obbligatorio per super utente e amministratori; per gli utenti aziendali per impostazione globale o per singolo utente.
  • Il segreto TOTP è un segreto: va cifrato con SecretProtector (proposta) e mai mostrato dopo l'attivazione.
  • Proposta: tolleranza di ±1 passo per la deriva dell'orologio; rifiutare il riuso dello stesso codice (memorizzare l'ultimo passo accettato); applicare lockout e rate limit anche al passaggio TOTP.
  • Il TOTP è richiesto anche come conferma di azioni critiche: conferma del ripristino da parte del super utente (SPEC §13).
  • Il reset della 2FA di un utente da parte di un amministratore è un evento di sys_security_audit.

6. Chiavi API e MCP

  • Formato kh_<valore casuale>; proposta: almeno 256 bit da RandomNumberGenerator, codificati base32/base64url.
  • Memorizzazione: hash SHA-256 (ApiKeyHasher) + prefisso visibile (es. kh_7f3a) per riconoscerla. Un hash veloce è adeguato perché la chiave ha alta entropia (non è una password); il confronto avviene in tempo costante.
  • La chiave in chiaro è mostrata una sola volta alla creazione.
  • Ogni chiave è legata a: utente tecnico (users.kind = Technical), azienda, permessi propri (sottoinsieme di quelli dell'utente), scadenza, IP consentiti (CIDR). Tabelle: api_keys (azienda), sys_api_keys (istanza).
  • Autenticazione con ApiKeyAuthenticationHandler su Authorization: Bearer kh_…; le API accettano anche il cookie di sessione (SPEC §15) — per le richieste con cookie che modificano dati vale la protezione antiforgery / SameSite (proposta: richiedere un header personalizzato o un token antiforgery per le chiamate API con cookie).
  • Rate limiting per chiave; ogni uso aggiorna ultimo uso e scrive nella sezione API / MCP del log.
  • MCP (/mcp, JSON-RPC 2.0): strumenti in lettura filtrati per permessi e licenza; strumenti in scrittura opzionali per chiave (create_sale_order, create_party, create_crm_activity) e disattivati per impostazione predefinita (proposta); get_log_errors solo per chiavi di amministratori. Gli strumenti in scrittura creano solo bozze, mai documenti emessi, perché un assistente AI può essere manipolato dai dati che legge.
  • Idempotenza con Idempotency-Key, concorrenza con ETag/If-Match.

7. Segreti, chiave di istanza e DataProtection

7.1 KHAEMHAT_SECRET_KEY e SecretProtector

  • Variabile obbligatoria, base64 di almeno 32 byte; senza chiave l'applicazione non parte (KhaemhatOptions.Validate()).
  • SecretProtector cifra con AES-256-GCM (System.Security.Cryptography.AesGcm) i segreti salvati: connection string delle aziende (sys_companies), password SMTP/PEC/S3/WebDAV, token degli intermediari SDI, credenziali dei canali e-commerce.
  • La chiave AES è derivata da KHAEMHAT_SECRET_KEY con HKDF-SHA256 (in-box, HKDF) ed etichetta di contesto khaemhat/secrets/aes-256-gcm/v1; altri usi (backup, TOTP) avranno etichette proprie, così una chiave non viene riusata fra domini. L'identificativo della chiave è una seconda derivazione HKDF di 4 byte (8 cifre esadecimali): identifica la chiave senza rivelarla.
  • Formato del testo cifrato (M1): khs1.<id-chiave>.<base64url(nonce 12 byte | tag 16 byte | ciphertext)>. Il nonce è casuale e non si riusa mai con la stessa chiave. Il dato associato (AAD) è lo scopo del segreto (per esempio company:ACME:database per la connessione di un'azienda): un valore copiato in un'altra riga o usato per un altro scopo non si decifra. Un valore cifrato con un'altra chiave è rifiutato con un messaggio che indica i due identificativi (SecretProtectionException), senza mai ripetere il segreto.
  • Implementazione: Khaemhat.Infrastructure.Security.SecretProtector (con SecretKey e SecretRotation), interfaccia ISecretProtector in Khaemhat.Core.
  • La chiave e i segreti in chiaro non vanno mai in log, messaggi d'errore, diagnostica, risposte API o file su disco (SPEC §1.5: nessun appsettings.<Env>.json con segreti, nessun file temporaneo).
  • Le varianti _FILE (Docker secrets) valgono per tutte le variabili sensibili, KHAEMHAT_SECRET_KEY compresa (ADR 0014); impostare sia la variabile sia la sua _FILE è un errore di avvio.

7.2 Rotazione (SecretRotationService, SecretRotation)

  1. L'operatore imposta KHAEMHAT_SECRET_KEY_NEW accanto alla chiave attuale e riavvia.
  2. Il super utente avvia la rotazione guidata (Impostazioni): ogni segreto viene decifrato con la vecchia chiave e ri-cifrato con la nuova, in transazione per database; l'operazione è idempotente e riprendibile.
  3. L'operatore sostituisce KHAEMHAT_SECRET_KEY con la nuova e rimuove KHAEMHAT_SECRET_KEY_NEW.
  4. Evento in sys_security_audit.

In M1 esiste il mattone SecretRotation (NeedsRotation legge l'identificativo della chiave, Rotate decifra e ri-cifra); la procedura che percorre tutte le colonne cifrate arriva in M12.

Da decidere con ADR: trattamento dei backup già cifrati con la vecchia chiave (ri-cifratura o conservazione della vecchia chiave come chiave di sola decifratura identificata dalla versione nel formato).

7.3 DataProtection

  • Le chiavi DataProtection di ASP.NET Core (cookie, antiforgery) sono nel database di sistema (sys_data_protection_keys) tramite DataProtectionDbXmlRepository: nessun file su disco, cookie validi dopo un riavvio o un nuovo container.
  • Implementato in M2 (DataProtectionKeyStore, SecretKeyXmlEncryptor): l'XML delle chiavi è cifrato a riposo con SecretProtector (scopo dataprotection:keys), così la sola lettura del database di sistema non consente di falsificare cookie o token antiforgery. Il database di sistema è migrato prima che DataProtection legga le chiavi.

8. Header di sicurezza e CSP

SecurityHeadersMiddleware imposta su tutte le risposte:

Header Valore
Content-Security-Policy default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'
X-Frame-Options DENY
Referrer-Policy same-origin
X-Content-Type-Options nosniff
Permissions-Policy camera=(), microphone=(), geolocation=(), payment=()
Cross-Origin-Opener-Policy same-origin
Strict-Transport-Security impostato dal reverse proxy, che termina TLS
  • Nessuna risorsa da CDN, nessun font scaricato, nessuno script di terze parti (SPEC §1.2): la CSP può restare rigorosa. In M2 non serve nemmeno il nonce: nessuna pagina ha script inline (la <ImportMap /> di Blazor, che ne scriverebbe uno, non è usata). style-src 'unsafe-inline' resta perché Blazor applica stili agli elementi durante la riconnessione. JavaScript solo in wwwroot/js, senza eval né gestori inline.
  • L'impostazione CSP rigorosa (nonce) (mockup 086) esiste per la diagnosi; disattivarla è un evento di audit.
  • Blazor esegue l'escaping dell'output: vietato MarkupString su contenuti provenienti da utenti o da file (eccezione: l'anteprima XML formattata, che va resa come testo).

9. Input, query ed esecuzione di processi

  • SQL: solo QueryBuilder<T> e SqlFragment parametrizzati; mai concatenazione di input utente (SPEC §5.2). I nomi di colonna per ordinamenti e filtri arrivano da una lista bianca della EntityMap, mai dalla richiesta.
  • Processi: nessun Process.Start fuori da Infrastructure/Backup (test di architettura). pg_dump e pg_restore si invocano con argomenti passati come lista (ProcessStartInfo.ArgumentList), mai attraverso una shell; la password del database passa per variabile d'ambiente del processo figlio, non sulla riga di comando (proposta).
  • Script di manutenzione: solo dal catalogo interno, mai shell libera (SPEC §12.5).
  • XML (FatturaPA, notifiche SDI, P7M, WebDAV, S3): proposta DtdProcessing = Prohibit e XmlResolver = null per evitare XXE ed espansione di entità.
  • Import CSV/XLSX: limite di dimensione e di righe, decompressione XLSX con limite sulla dimensione espansa (zip bomb) (proposta).
  • Export CSV/XLSX: neutralizzare le celle che iniziano con =, +, -, @ (formula injection) (proposta).
  • Validazione in Core/Application (SPEC §19): l'interfaccia mostra, non decide.

10. Upload e allegati

  • Upload in streaming, limite configurabile (predefinito 25 MB), quota per azienda (IFileStore).
  • Percorso su disco generato: /data/files/<azienda>/<yyyy>/<guid>; il nome originale resta solo nei metadati (attachments), quindi nessun path traversal.
  • sha256 calcolato all'upload e alla generazione; locked per i file che non devono cambiare (es. XML inviato).
  • Ogni allegato appartiene a un solo documento: l'autorizzazione a leggerlo/scaricarlo deriva dal permesso sul documento; l'eliminazione richiede attachments.delete; il documento cancellato porta gli allegati nel cestino per 30 giorni.
  • Antivirus non incluso: hook predisposto nel flusso di upload (punto di estensione in AttachmentStore).
  • Anteprima: PDF e immagini serviti con il tipo MIME verificato; proposta: download con Content-Disposition: attachment per tutti i tipi non in anteprima, SVG mai reso inline, nosniff.
  • Nessun file temporaneo fuori da /data; le stampe massive sono ZIP in streaming.

11. Backup cifrati

  • pg_dump -Fc / VACUUM INTO / backup logico JSON Lines → /data/backups/<db>/…, con SHA-256 e cifratura AES-256-GCM con chiave derivata da KHAEMHAT_SECRET_KEY (BackupEncryptor); cifratura in streaming a blocchi (proposta: segmenti con nonce derivato dall'indice, per non tenere il file in memoria).
  • Copie remote su S3 compatibile (S3Client, firma SigV4 in casa, HTTPS) e WebDAV (HTTPS): i file escono già cifrati (cifratura lato client); verifica dopo l'upload (ETag/SHA-256).
  • Verifica con pg_restore --list; prova di ripristino su database temporaneo.
  • Ripristino: avviato da un amministratore, confermato dal super utente con notifica + TOTP; backup di sicurezza dello stato corrente prima dello scambio; evento in sys_security_audit.
  • Il database di sistema si ripristina solo da CLI (scripts/restore-system.sh) a istanza ferma.
  • Senza KHAEMHAT_SECRET_KEY i backup cifrati non sono ripristinabili: la chiave va custodita fuori dal server (password manager o cassaforte), separata dai backup.
  • Eliminazione di un'azienda: backup preventivo automatico, conferma digitando il nome, file nel cestino 30 giorni.

12. Audit

Registro Dove Contenuto Proprietà
audit_log DB aziendale ogni insert/update/delete su anagrafiche, documenti, registrazioni, impostazioni: entity, entity_id, action, user, at, diff JSON visibile dal record (Storico)
sys_security_audit DB di sistema login (riusciti e falliti), 2FA, permessi e ruoli, licenze, backup, ripristini, operazioni sui database, manutenzione, impostazioni critiche, rotazione segreti immutabile
  • AuditTrailService scrive nella stessa transazione dell'operazione (SPEC §19: servizi transazionali).
  • Immutabilità di sys_security_audit (proposta): nessun metodo di update/delete nel repository; su PostgreSQL revocare UPDATE/DELETE sulla tabella al ruolo applicativo o usare un trigger che li rifiuta; catena di hash (hash = SHA-256(riga ‖ hash precedente)) per rendere evidenti le manomissioni.
  • La retention del log applicativo (sys_log) non si applica a sys_security_audit; la sua conservazione sarà definita con ADR.
  • Il diff dell'audit_log non contiene mai segreti (solo l'indicazione "modificato").

13. Licenze

  • Licenza di istanza: JSON firmato ECDSA P-256 (file .khl) con licensee, instanceId, issuedAt, expiresAt, maxConcurrentUsers, maxCompanies, modules[], gracePeriodDays. Codici di attivazione per modulo KH<v>-<MODULO>-<AAAAMM>-<payload base32>-<firma>, verificati offline (LicenseVerifier, ModuleActivationCode).
  • Chiave pubblica incorporata nel binario; chiave privata solo nello strumento tools/Khaemhat.LicenseTool dell'emittente, mai nel repository, mai nei segreti della CI, mai nell'immagine. Proposta: .gitignore per *.pem, *.key, *.p8, *.pfx e un controllo in scripts/check-packages.sh o in un hook che rifiuti file di chiave privata.
  • Proposta: la firma copre una forma canonica del JSON (ordine dei campi e serializzazione fissati) da definire con ADR, per evitare ambiguità di verifica.
  • Verifica all'avvio, al login e ogni ora (LicenseMonitor); oltre scadenza + grazia l'istanza va in sola lettura con banner.
  • Codici fittizi di SPEC §8.3 (TestLicenseCatalog) accettati solo con KHAEMHAT_LICENSE_MODE=test; in produzione rifiutati con license_test_only. La modalità test è visibile (banner, Stato sistema) e va segnalata come anomalia se attiva su un'istanza con dati reali.
  • Attivazioni solo dal super utente; storico in sys_license_activations e in sys_security_audit.

14. Comunicazioni in uscita

Destinazione Protezione
SMTP / PEC STARTTLS o SSL; IMAP su TLS; credenziali cifrate
S3, WebDAV HTTPS; contenuto già cifrato lato client
Intermediari SDI, SdICoop HTTPS; certificato client per SdICoop (scadenza monitorata in Stato sistema)
VIES, BCE HTTPS, sola lettura
Registro pacchetti Gitea (GiteaPackagesClient) sola lettura, token KHAEMHAT_UPDATE_TOKEN opzionale con permessi minimi; nessun aggiornamento automatico
Webhook (OutboundWebhookClient) firma HMAC del corpo con segreto per webhook; retry

Proposte per i webhook: HMAC-SHA256 su timestamp + "." + corpo, header con firma e timestamp, tolleranza di pochi minuti contro il replay; il segreto è cifrato con SecretProtector. Proposta contro SSRF: gli URL di webhook, S3 e WebDAV sono configurabili solo da amministratori; rifiutare schemi diversi da https (salvo eccezione esplicita per la LAN) e indirizzi link-local.


15. Errori, log e diagnostica

  • Errori API in formato RFC 9457 con trace_id; nessuno stack trace verso i client. L'utente vede il Codice errore (= trace_id) per ritrovare l'evento nel log.
  • Log su stdout JSON e sys_log (SPEC §9.5): mai password, token, chiavi API, segreti TOTP, connection string con credenziali; i dati personali solo dove servono alla diagnosi.
  • La diagnostica scaricabile (Stato sistema) contiene configurazione senza segreti.
  • Regole di avviso consigliate: errori in Autenticazione, picchi di tentativi falliti, uso di chiavi revocate o scadute.

16. Deploy sicuro (sintesi)

  • Unico artefatto: immagine gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> (emendamenti E1, E2); in produzione tag esplicito, mai latest.
  • Container con utente non root (PUID/PGID), scritture solo in /data, porta interna 8080 in HTTP, TLS sul reverse proxy (che imposta anche HSTS); la porta 8080 non va esposta direttamente su Internet.
  • Ruolo PostgreSQL applicativo con CREATEDB ma non superuser (come nel mockup 078).
  • Redis, se usato, con password e su rete Docker interna (rediss:// se esce dall'host).
  • .env mai versionato; KHAEMHAT_LICENSE_MODE mai test in produzione.

17. Segnalazione di vulnerabilità

Il repository BalboSoft/Khaemhat su Gitea è pubblico e Gitea non offre issue riservate. Per questo:

  1. Non aprire un'issue pubblica per una vulnerabilità non ancora corretta.
  2. Segnala in privato al titolare del progetto (organizzazione BalboSoft su https://gitea.encke-hake.ts.net/BalboSoft), usando il contatto indicato nel profilo dell'organizzazione, con: versione o commit, descrizione, passi per riprodurre, impatto stimato.
  3. Il titolare conferma la ricezione, valuta e prepara la correzione su un ramo non pubblico o in locale.
  4. Dopo il rilascio della versione corretta si apre l'issue con etichetta Kind/Security (e Area/Sicurezza e licenze), si aggiorna CHANGELOG.md (sezione Security) e, se serve, si avvisano gli utenti nelle note di rilascio.

Non usare dati reali di clienti nelle segnalazioni: riproduci sui dati demo.


18. Checklist di revisione di sicurezza per milestone

Da spuntare nell'issue Chiusura milestone (oltre alla Definition of Done, SPEC §20), per le parti toccate dalla milestone.

Autorizzazione

  • Ogni nuova pagina, endpoint API, tool MCP e procedura ha [RequirePermission]/[RequireLevel]/[RequireModule] o un controllo equivalente nel servizio.
  • I nuovi permessi sono definiti nel modulo e assegnati ai ruoli predefiniti corretti.
  • I flag solo propri clienti e costi e margini sono applicati nelle query e nei DTO.
  • Test: utente senza permesso → 403; modulo non licenziato → module_not_licensed; altra azienda → 403.

Dati e input

  • Nessuna concatenazione di input in SQL; ordinamenti/filtri da lista bianca.
  • Parsing XML senza DTD; limiti su file importati.
  • Nessun MarkupString con contenuti non fidati.

Segreti

  • I nuovi segreti sono cifrati con SecretProtector e coperti dalla rotazione.
  • Nessun segreto in log, errori, diagnostica, audit_log, fixture o test.
  • Nessuna chiave privata o .env nel commit (controllo del diff).

Audit e log

  • Le nuove azioni di sicurezza o di istanza scrivono in sys_security_audit; le modifiche ai dati in audit_log.
  • Il modulo logga nella propria sezione con trace_id.

Superficie esterna

  • Header di sicurezza e CSP verificati sulle nuove pagine (nessuna violazione CSP in console).
  • Rate limiting attivo sui nuovi endpoint pubblici.
  • Nuove chiamate in uscita su HTTPS, con URL configurabili solo da amministratori.
  • check-packages.sh verde: nessuna dipendenza fuori allowlist.

File e backup (se toccati)

  • Upload in streaming, limite di dimensione, percorso generato, sha256.
  • Backup cifrati e verificati; prova di ripristino eseguita.

Licenze (M2 e successive)

  • Codici test rifiutati in produzione; nessuna chiave privata nel repository.

19. Riferimenti

  • SPEC: §1 (vincoli), §5.4 (DB di sistema e segreti), §6 (variabili), §7 (utenti, permessi, sicurezza), §8 (licenze), §9.4 (allegati), §9.5 (log), §12 (amministrazione), §13 (backup), §15 (API/MCP), §18 (test), §21 (classi).
  • Emendamenti E1 (Gitea) ed E2 (solo Docker) in CLAUDE.md; ADR 0009, 0010.
  • Standard: RFC 6238 (TOTP), RFC 4226 (HOTP), RFC 9457 (problem details), NIST SP 800-38D (GCM), RFC 5869 (HKDF).