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>
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
/datao 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 standardread,write,delete,post/issue/finalize,reopen,export,print,override_*. - Definiti da ogni
IModulecomePermissionDefinition; ruoli predefiniti come modelli insys_roles_templates, copiati inroles/role_permissionsdi 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;ModuleNotLicensedExceptionnei 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 èICompanyRegistrytramiteICompanyContext. ICompanyContextè per circuito Blazor e per richiesta API. Per gli utenti aziendali l'azienda è quella dell'utente e non può essere cambiata dall'headerX-Company; per le chiavi API è quella della chiave: unX-Companydiverso 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.
3. Sessioni e cookie
| 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 insys_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);/apie/mcpper chiave API (mockup 086: 600/minuto).
- Oltre il limite:
429 Too Many RequestsconRetry-After. - Proposta: dietro reverse proxy usare
ForwardedHeadersfidandosi solo degli indirizzi del proxy configurato; altrimenti l'IP del client è falsificabile conX-Forwarded-Fore il limite per IP perde efficacia.
5. Verifica in due passaggi (TOTP)
TotpGeneratorscritto 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 daRandomNumberGenerator, 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
ApiKeyAuthenticationHandlersuAuthorization: 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_errorssolo 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 conETag/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()). SecretProtectorcifra 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_KEYcon HKDF-SHA256 (in-box,HKDF) ed etichetta di contestokhaemhat/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 esempiocompany:ACME:databaseper 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(conSecretKeyeSecretRotation), interfacciaISecretProtectorinKhaemhat.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>.jsoncon segreti, nessun file temporaneo). - Le varianti
_FILE(Docker secrets) valgono per tutte le variabili sensibili,KHAEMHAT_SECRET_KEYcompresa (ADR 0014); impostare sia la variabile sia la sua_FILEè un errore di avvio.
7.2 Rotazione (SecretRotationService, SecretRotation)
- L'operatore imposta
KHAEMHAT_SECRET_KEY_NEWaccanto alla chiave attuale e riavvia. - 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.
- L'operatore sostituisce
KHAEMHAT_SECRET_KEYcon la nuova e rimuoveKHAEMHAT_SECRET_KEY_NEW. - 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) tramiteDataProtectionDbXmlRepository: 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 conSecretProtector(scopodataprotection: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 inwwwroot/js, senzaevalné 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
MarkupStringsu 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>eSqlFragmentparametrizzati; mai concatenazione di input utente (SPEC §5.2). I nomi di colonna per ordinamenti e filtri arrivano da una lista bianca dellaEntityMap, mai dalla richiesta. - Processi: nessun
Process.Startfuori daInfrastructure/Backup(test di architettura).pg_dumpepg_restoresi 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 = ProhibiteXmlResolver = nullper 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. sha256calcolato all'upload e alla generazione;lockedper 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: attachmentper 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 daKHAEMHAT_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_KEYi 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 |
AuditTrailServicescrive nella stessa transazione dell'operazione (SPEC §19: servizi transazionali).- Immutabilità di
sys_security_audit(proposta): nessun metodo di update/delete nel repository; su PostgreSQL revocareUPDATE/DELETEsulla 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 asys_security_audit; la sua conservazione sarà definita con ADR. - Il diff dell'
audit_lognon contiene mai segreti (solo l'indicazione "modificato").
13. Licenze
- Licenza di istanza: JSON firmato ECDSA P-256 (file
.khl) conlicensee,instanceId,issuedAt,expiresAt,maxConcurrentUsers,maxCompanies,modules[],gracePeriodDays. Codici di attivazione per moduloKH<v>-<MODULO>-<AAAAMM>-<payload base32>-<firma>, verificati offline (LicenseVerifier,ModuleActivationCode). - Chiave pubblica incorporata nel binario; chiave privata solo nello strumento
tools/Khaemhat.LicenseTooldell'emittente, mai nel repository, mai nei segreti della CI, mai nell'immagine. Proposta:.gitignoreper*.pem,*.key,*.p8,*.pfxe un controllo inscripts/check-packages.sho 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 conKHAEMHAT_LICENSE_MODE=test; in produzione rifiutati conlicense_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_activationse insys_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, mailatest. - 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
CREATEDBma non superuser (come nel mockup 078). - Redis, se usato, con password e su rete Docker interna (
rediss://se esce dall'host). .envmai versionato;KHAEMHAT_LICENSE_MODEmaitestin produzione.
17. Segnalazione di vulnerabilità
Il repository BalboSoft/Khaemhat su Gitea è pubblico e Gitea non offre issue riservate. Per questo:
- Non aprire un'issue pubblica per una vulnerabilità non ancora corretta.
- Segnala in privato al titolare del progetto (organizzazione
BalboSoftsuhttps://gitea.encke-hake.ts.net/BalboSoft), usando il contatto indicato nel profilo dell'organizzazione, con: versione o commit, descrizione, passi per riprodurre, impatto stimato. - Il titolare conferma la ricezione, valuta e prepara la correzione su un ramo non pubblico o in locale.
- Dopo il rilascio della versione corretta si apre l'issue con etichetta
Kind/Security(eArea/Sicurezza e licenze), si aggiornaCHANGELOG.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
MarkupStringcon contenuti non fidati.
Segreti
- I nuovi segreti sono cifrati con
SecretProtectore coperti dalla rotazione. - Nessun segreto in log, errori, diagnostica,
audit_log, fixture o test. - Nessuna chiave privata o
.envnel commit (controllo del diff).
Audit e log
- Le nuove azioni di sicurezza o di istanza scrivono in
sys_security_audit; le modifiche ai dati inaudit_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.shverde: 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).