Security Whitepaper

1. Introduzione

Hermes Console (di seguito "Hermes") è uno strumento di audit e remediation statici per repository software. Produce un documento strutturato (PDF + Markdown) con: descrizione funzionale del codice del cliente, vulnerabilità reali nelle dipendenze, rischi dedotti dal codice, proposte concrete di rimedio.

Questo whitepaper descrive:

• il modello di minaccia per la piattaforma Hermes;
• il ciclo di vita del codice del cliente dentro Hermes (ingresso, elaborazione, persistenza, output, cancellazione);
• i controlli tecnici e organizzativi implementati;
• la posizione rispetto a ISO/IEC 27001:2022 e alla Direttiva NIS2.

Pubblico target: procurement, DPO, security officer, compliance officer che valutano l'adozione di Hermes da parte di un soggetto regolato (NIS2-scope, GDPR personal data, settore finanziario o sanitario, PA).

2. Scope & architettura

Hermes è un'applicazione web (Next.js) servita su HTTPS pubblico, con un database PostgreSQL dedicato e un engine TypeScript puro (@oasi/hermes-core). Il deployment standard è in modalità SaaS su infrastruttura controllata da OASI S.r.l.

Sono disponibili due ulteriori modalità per clienti con requisiti di sovranità più stringenti:

• Upload mono-shot (.zip/.tar.gz, sandbox temporanea, cancellazione entro 1 ora dall'analisi);
• On-prem (Docker Compose installato dentro la DMZ del cliente, swap del provider LLM verso Bedrock/Vertex/Ollama on-prem).

Le modalità on-prem e Hermes Agent (binary desktop) sono in roadmap commerciale; questo whitepaper riguarda la modalità SaaS.

3. Threat model

3.1 Asset protetti

3.2 Attori e capacità

3.3 Vettori di minaccia considerati

1. Esposizione codice cliente verso terzi → cifratura at-rest + minimizzazione (LLM riceve solo i file selezionati); cancellazione clone in finally.
2. Compromissione credenziali servizio → cifratura AES-256-GCM con scrypt-derived key, mai in clear, mai loggate.
3. Privilege escalation tra tenant → guard canAccessTenant su ogni route ID-based, filtro tenantWhere su ogni query list, 404 (non 403) per evitare leak di esistenza.
4. Compromissione sessione operatore → WebAuthn passkey only (no password riusabili), JWT a 15 min, step-up per azioni sensibili, audit log indelebile.
5. Iniezione via input malformato → input validation Zod su ogni POST body; SQL via Prisma ORM o $queryRaw parametrizzato; HTML output via React (auto-escape).
6. Compromissione webhook billing → HMAC-SHA256 con timing-safe compare e tolleranza 5 min.
7. Cross-Site Request Forgery → cookie SameSite=strict, Secure, HttpOnly; refresh in cookie separato.

3.4 Out of scope (esplicito)

• DDoS layer-7 (mitigazione presso reverse proxy / CDN, non a layer applicativo).
• Attacchi fisici al data center (responsabilità provider hosting; vedi Subprocessor list).
• Vulnerabilità nei dispositivi degli operatori (responsabilità del cliente e delle policy MFA dei suoi laptop).
• Vulnerabilità nei nodi Anthropic (responsabilità contrattuale di Anthropic, DPA di riferimento).

4. Controlli tecnici implementati

4.1 Crittografia

4.2 Autenticazione e gestione sessione

• Solo passkey (WebAuthn). Nessuna password riutilizzabile in alcun flusso.
• Step-up richiesto per azioni elevate (Apply→PR, .patch, gestione PAT).
• Recovery codes consegnati una sola volta al primo login; conservati come hash bcrypt.
• Bruteforce protection: tabella HermesLoginAttempt traccia gli attempts; dopo soglia configurabile rate-limit per IP.
• Logout: revoca refresh in DB (HermesSession.revokedAt), invalida cookie.

4.3 Multi-tenancy e segregazione dati

• Schema relazionale: ogni risorsa client-derived (HermesRepo, HermesDiscovery, HermesAuditLog) ha FK tenantId NOT NULL → HermesTenant.
• Filtro a livello applicativo: helper tenantWhere(ctx) su ogni query findMany; canAccessTenant(ctx, id) su ogni route ID-based.
• Cross-tenant solo a operatori OASI con superAdmin: true. Toggle solo via UI /tenants con doppio guardrail (no self-demote, no rimozione ultimo superAdmin attivo).
• Audit cross-tenant: ogni evento di modifica plan tenant è loggato con action: tenant.update + diff from→to.

4.4 Audit logging

• Indelebile a livello applicativo: HermesAuditLog è append-only (nessuna route fornisce DELETE).
• Coverage: ogni mutating action passa per logAudit(...) con userId, tenantId, action, target, ip, userAgent, success, metadata. Vedi tassonomia in §6.
• Retention DB: nessuna policy automatica di purga → conservato per tutta la vita del database (configurabile su richiesta cliente per esigenze legacy).
• Esposizione: lettura via UI /audit (filtri action/success/target, scope per tenant).

4.5 Gestione segreti

• deploy/.env con permessi 600, gitignored.
• Iniezione via STDIN → file 600 → SSH-pipe al box, mai in chat / mai in echo log. Pattern documentato in deploy/STRIPE.md §5 e nel playbook interno.
• Mai persistenza in repo: nessun *.env.local committato; .gitignore esplicita.
• Rotazione: REPO_DEPLOY_KEY_SECRET ruotabile (la cifratura per-blob include il salt; ri-cifratura batch dei blob esistenti supportata, on-demand). JWT_ACCESS_SECRET ruotabile (invalida tutte le sessioni → richiesto re-login).
• Logs: scrubbing dei pattern oauth2:[^@]+@ nei messaggi d'errore Git per non leak-are PAT.

4.6 Input validation

• zod su ogni request body (POST/PATCH/DELETE).
• Path traversal: rifiuto esplicito di .. nei path locali di Discovery (if (repo.includes("..")) throw ...).
• Path UUID-ish: /^[0-9a-fA-F-]{36}$/ prima di cast Prisma (no SQL injection via raw cast).
• HTML output: React auto-escape; nessun dangerouslySetInnerHTML su input utente.
• Markdown legal: rendering server-side con react-markdown (no eval).

4.7 Subprocess sandboxing

• Hermes esegue tool esterni (git, osv-scanner, ssh-keygen) via ChildProcessRunner con:
  • timeout esplicito (default 60-180s per operazione);
  • maxBuffer: 16 MB per output;
  • working directory mkdtemp temporanea;
  • cleanup in finally (rm -rf).
• L'InstrumentationApplier ha forbidden_targets configurabile (default vuoto in modalità SaaS; in onboarding template = ["master","main"] per evitare PR direttamente in produzione).

5. Ciclo di vita del codice del cliente

5.1 Ingresso (clone)

Il codice entra in Hermes via uno di questi canali:

1. HTTPS clone con PAT (per Apply→PR su GitHub) — URL oauth2:<PAT>@host/owner/name.git, durata transitiva (clone in temp dir, deletion immediata dopo l'apply).
2. SSH clone con deploy key (per Discovery, .patch) — chiave materializzata su temp file 0600, scoped via GIT_SSH_COMMAND, eliminata dopo il clone.
3. Path locale assoluto (per Discovery su filesystem del box) — nessuna copia, lettura diretta.

In tutti i casi: temp dir creata con mkdtemp(join(tmpdir(), "hermes-...")), cancellata in finally indipendentemente dall'esito.

5.2 Elaborazione

5.3 Persistenza

• HermesDiscovery.report/vulnReport/comprehension/remediation sono artifact dell'analisi, NON il codice sorgente. Tuttavia possono contenere estratti di codice (es. snippet incriminato nelle proposte di rimedio).
• Retention default: vita del database. Cancellazione singola Discovery via API (in roadmap); cancellazione massiva su richiesta cliente o termine contratto.

5.4 Output e consegna

• PDF (carta intestata OASI) e Markdown restituiti via TLS all'operatore. Nessuna memoria temporanea persistente lato server (rendering on-demand).
• PR su GitHub: contenuti già accessibili al cliente (è il suo repo).
• .patch: download diretto, scaricato e poi gestito dal cliente in locale.

5.5 Cancellazione

• Clone temporaneo: rm -rf in finally di ogni endpoint (/api/hermes/discovery, apply, patch).
• Dati persisitti: cancellazione contestuale alla cancellazione del tenant (onDelete: Restrict previene cancellazioni accidentali; il superAdmin deve disabilitare prima).
• Backup DB: vedi Subprocessor list (provider hosting) e DPA.

6. Tassonomia degli eventi audit

Eventi tracciati con action standardizzata:

Ogni evento è correlato a userId + tenantId (NULL solo per azioni di sistema pre-login).

7. Disaster Recovery & Business Continuity

• Backup DB: snapshot giornaliero gestito dal provider hosting (frequenza e RPO/RTO definiti nel DPA con il cliente; RPO target ≤24h, RTO target ≤4h per modalità SaaS standard).
• Recovery test: procedura documentata internamente, eseguita ad ogni release maggiore.
• Monitoring esterno: status page pubblica a status.oasi.systems (Upptime, GitHub Actions cron 5 minuti). Uptime + response time + incident history pubblici. Indipendente dall'infrastruttura monitorata (se il box muore, il monitor se ne accorge). Notifiche automatiche a security@oasi.systems su downtime >5 min.
• Multi-region: non incluso nel piano base SaaS; disponibile su modalità Enterprise (DR-aware).
• Code & build: tutto il source code è in repository Git versionato; ogni release è ricostruibile dal commit Git corrispondente (vedi footer commit hash su /legal).

8. Incident response

• Detection: monitoraggio applicativo (logs, status codes, audit anomalies) + alerting infrastrutturale (provider hosting).
• Triage: classificazione interna (P0 = data exposure / P1 = service down / P2 = degraded).
• Comunicazione: security@oasi.systems per il cliente; obbligo di notifica entro 24-72h ai sensi del GDPR Art. 33 (se applicabile) e NIS2 Art. 23 (early warning).
• Post-mortem: documento pubblicato (anonimizzato) in caso di incidenti P0/P1.

9. Vulnerability disclosure

OASI accetta segnalazioni responsabili di vulnerabilità via security@oasi.systems, idealmente PGP-encrypted. Tempistica di gestione:

• ack entro 48h;
• assessment entro 5 giorni lavorativi;
• fix per vulnerabilità critiche entro 14 giorni;
• public disclosure coordinata con il segnalante.

10. Posizione rispetto a ISO/IEC 27001:2022

Hermes è aligned allo standard ISO/IEC 27001:2022. Il Statement of Applicability (vedi pagina dedicata /legal/iso27001-soa) mappa i 93 controlli dell'Annex A allo stato attuale (implementato / parzialmente / N/A con motivazione).

Hermes non è ancora certificato da ente accreditato. La certificazione formale è programmata in funzione del raggiungimento delle soglie commerciali (€100k+ ARR). Fino ad allora, la posizione è ISO27001-aligned, autocertificata: la documentazione (questo whitepaper + SoA + DFD + DPA + Subprocessor list) è prodotta secondo i requisiti dello standard ed è disponibile per audit indipendente su richiesta sotto NDA.

11. Posizione rispetto a NIS2 (Direttiva UE 2022/2555)

OASI non è un soggetto NIS2-scope per sé (le soglie dimensionali e settoriali della direttiva non si applicano a Hermes come prodotto).

Hermes facilita la conformità del cliente in-scope rispetto a vari punti dell'Art. 21(2) — vedi pagina dedicata /legal/nis2-mapping per il mapping puntuale (in particolare lettere d, e, f, h sulla supply-chain e gestione vulnerabilità).

12. Contatti

• Sicurezza: security@oasi.systems
• Privacy / DPO: privacy@oasi.systems
• Procurement / Sales: hermes@oasi.systems
• Vulnerability disclosure: security@oasi.systems (PGP su richiesta)

Versione 1.0 — pubblicata insieme al commit Git riportato nel footer. La cronologia delle modifiche è ricostruibile via git log apps/hermes-console/src/app/legal/whitepaper/. Aggiornamenti maggiori sono comunicati ai clienti attivi via email.