Cristiano Benassati
d3eac7ce38
Password DB e token Gitea rimossi dal file tracciato, creato DB_ACCESS.md dedicato. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
268 lines
14 KiB
Markdown
268 lines
14 KiB
Markdown
# NIS2 Agile - Documentazione Progetto
|
|
|
|
## PRIMA DI INIZIARE
|
|
- Leggi sempre questo file prima di iniziare qualsiasi lavoro
|
|
- Il progetto e' al **100% di completamento** (24.000+ righe di codice, 50+ file sorgente)
|
|
- 7 commit su main, tutto deployato e testato su Hetzner
|
|
- E2E test completati, bug fixing, Docker verificato, UI polished
|
|
|
|
## Panoramica
|
|
NIS2 Agile e' una piattaforma SaaS multi-tenant per supportare le aziende nella compliance alla Direttiva NIS2 (EU 2022/2555) e al D.Lgs. 138/2024 italiano. Include AI integration (Claude API) per gap analysis, generazione policy, classificazione incidenti e suggerimenti rischi.
|
|
|
|
Target: PMI, Enterprise, Consulenti/CISO.
|
|
|
|
## Stack Tecnologico
|
|
- Backend: PHP 8.4 vanilla (no framework, Front Controller pattern)
|
|
- Database: MySQL 8.x (nis2_agile_db)
|
|
- Frontend: HTML5/CSS3/JavaScript vanilla
|
|
- Auth: JWT HS256 (2h access + 7d refresh)
|
|
- AI: Anthropic Claude API (claude-sonnet-4-5-20250929)
|
|
- Server: Hetzner CPX31 (135.181.149.254)
|
|
- VCS: Gitea (git.certisource.it)
|
|
- URL Produzione: https://certisource.it/nis2/
|
|
|
|
|
|
## Visibilita Cross-Project
|
|
|
|
### agile-services (Read/Write BIDIREZIONALE)
|
|
|
|
**IMPORTANTE**: Questo progetto utilizza i microservizi condivisi di **agile-services** con accesso **Read/Write bidirezionale**.
|
|
|
|
#### Regole di integrazione
|
|
1. **Leggere SEMPRE** `agile-services-istructio.md` nella root del progetto per capire come interagire con i servizi
|
|
2. **Puoi leggere E modificare** i file in agile-services (path locale: `c:\Projects\agile-services`, path container: `/projects/agile-services`)
|
|
3. I servizi disponibili includono: vault, document, payment, certificate, subscription, billing, practice, company, supplier, investigation, whatsapp
|
|
4. Le credenziali di accesso ai servizi sono documentate in `agile-services-istructio.md`
|
|
5. Ogni nuovo servizio creato per NIS2 deve essere registrato anche in agile-services per essere riutilizzabile
|
|
6. **agile-services puo' leggere e modificare file di NIS2** — la visibilita e' bidirezionale
|
|
|
|
#### Accesso
|
|
- Path locale: `c:\Projects\agile-services`
|
|
- Path container: `/projects/agile-services` (read-write)
|
|
- File istruzioni: `./agile-services-istructio.md` (nella root del progetto)
|
|
|
|
### trpg.agile (Read-Only)
|
|
|
|
NIS2 puo' **leggere** il codice di TRPG Agile per riferimento e pattern, ma **NON deve modificare** nessun file.
|
|
|
|
- Path locale: `c:\Projects\trpg.agile`
|
|
- **Permessi**: SOLO LETTURA
|
|
- **Scopo**: Consultare pattern UI/UX, architettura frontend, convenzioni codice
|
|
- **DIVIETO**: NON modificare, NON creare, NON cancellare file in trpg.agile
|
|
|
|
### lg231.agile (Read-Only)
|
|
|
|
NIS2 puo' **leggere** il codice di 231 Agile per riferimento e pattern, ma **NON deve modificare** nessun file.
|
|
|
|
- Path locale: `c:\Projects\lg231.agile`
|
|
- **Permessi**: SOLO LETTURA
|
|
- **Scopo**: Consultare architettura microservizi PHP/Slim 4, pattern multi-tenancy, struttura database
|
|
- **DIVIETO**: NON modificare, NON creare, NON cancellare file in lg231.agile
|
|
|
|
### sustainai.agile (Read-Only)
|
|
|
|
NIS2 puo' **leggere** il codice di SustainAI Agile per riferimento e pattern, ma **NON deve modificare** nessun file.
|
|
|
|
- Path locale: `c:\Projects\sustainai.agile`
|
|
- **Permessi**: SOLO LETTURA
|
|
- **Scopo**: Consultare pattern UI/UX (identico a NIS2), struttura frontend, convenzioni CSS/JS
|
|
- **DIVIETO**: NON modificare, NON creare, NON cancellare file in sustainai.agile
|
|
|
|
### Riepilogo Visibilita
|
|
|
|
| Progetto | Permesso | Direzione |
|
|
|----------|----------|-----------|
|
|
| **agile-services** | Read/Write | Bidirezionale (NIS2 <-> agile-services) |
|
|
| **trpg.agile** | Read-Only | NIS2 -> trpg (solo lettura) |
|
|
| **lg231.agile** | Read-Only | NIS2 -> lg231 (solo lettura) |
|
|
| **sustainai.agile** | Read-Only | NIS2 -> sustainai (solo lettura) |
|
|
|
|
> **REGOLA**: Non accedere MAI a progetti non elencati in questa tabella. Nel dubbio, chiedere all'utente.
|
|
|
|
## Regola Fondamentale
|
|
Il progetto NIS2 Agile e' COMPLETAMENTE ISOLATO dagli altri applicativi (CertiSource, AGILE_DFM). Database dedicato, utente dedicato, path dedicati. Non condividere MAI credenziali tra applicativi.
|
|
|
|
## Struttura Progetto
|
|
```
|
|
nis2.agile/
|
|
├── CLAUDE.md # Questo file
|
|
├── .env # Variabili ambiente (NON committare)
|
|
├── .gitignore
|
|
├── application/
|
|
│ ├── config/
|
|
│ │ ├── config.php # Costanti app, CORS, JWT, AI, rate limiting
|
|
│ │ ├── database.php # Classe Database (PDO singleton)
|
|
│ │ └── env.php # Caricamento .env
|
|
│ ├── controllers/ # 15 controller (tutti implementati 100%)
|
|
│ │ ├── BaseController.php # Auth JWT, multi-tenancy, JSON responses (576 righe)
|
|
│ │ ├── AdminController.php # Gestione piattaforma (super_admin)
|
|
│ │ ├── AssessmentController.php # Gap analysis e questionari NIS2 (80 domande)
|
|
│ │ ├── AssetController.php # Inventario asset e dipendenze
|
|
│ │ ├── AuditController.php # Controlli, evidenze, report, export CSV
|
|
│ │ ├── AuthController.php # Login, register, JWT, rate limiting
|
|
│ │ ├── DashboardController.php # Overview, score, deadlines, heatmap
|
|
│ │ ├── IncidentController.php # Incidenti Art.23 (24h/72h/30d) + email
|
|
│ │ ├── OnboardingController.php # Wizard onboarding con visura/CertiSource
|
|
│ │ ├── OrganizationController.php # CRUD org, membri, classificazione NIS2
|
|
│ │ ├── PolicyController.php # Policy, approvazione, AI generation
|
|
│ │ ├── RiskController.php # Risk register, trattamenti, matrice, AI suggest
|
|
│ │ ├── SupplyChainController.php # Fornitori, valutazione, risk overview
|
|
│ │ └── TrainingController.php # Corsi, assegnazioni, compliance formativa
|
|
│ ├── services/ # 5 servizi
|
|
│ │ ├── AIService.php # Anthropic Claude API (gap, risk, policy, incident)
|
|
│ │ ├── EmailService.php # Email CSIRT, training, welcome, invite
|
|
│ │ ├── RateLimitService.php # Rate limiting file-based
|
|
│ │ ├── ReportService.php # Report esecutivo HTML, export CSV
|
|
│ │ └── VisuraService.php # AI extraction PDF visura + CertiSource API
|
|
│ ├── models/ # (vuoto - logica nei controller)
|
|
│ └── data/
|
|
│ └── nis2_questionnaire.json # 80 domande gap analysis (10 categorie Art.21)
|
|
├── public/
|
|
│ ├── index.php # Front Controller / Router
|
|
│ ├── .htaccess # Rewrite rules + Authorization header
|
|
│ ├── api-status.php # Health check
|
|
│ ├── index.html # Landing page
|
|
│ ├── login.html # Login
|
|
│ ├── register.html # Registrazione
|
|
│ ├── onboarding.html # Wizard 5-step (visura/CertiSource/manuale)
|
|
│ ├── setup-org.html # Setup org (legacy, ora usa onboarding.html)
|
|
│ ├── dashboard.html # Dashboard principale
|
|
│ ├── assessment.html # Gap analysis wizard
|
|
│ ├── risks.html # Risk management + matrice 5x5
|
|
│ ├── incidents.html # Gestione incidenti Art.23
|
|
│ ├── policies.html # Policy management + AI generate
|
|
│ ├── supply-chain.html # Fornitori + assessment sicurezza
|
|
│ ├── training.html # Formazione + assegnazioni
|
|
│ ├── assets.html # Inventario asset
|
|
│ ├── reports.html # Report compliance + audit log
|
|
│ ├── settings.html # Impostazioni org/profilo/membri
|
|
│ ├── admin/
|
|
│ │ ├── index.html # Admin dashboard
|
|
│ │ ├── organizations.html # Gestione organizzazioni
|
|
│ │ └── users.html # Gestione utenti
|
|
│ ├── css/
|
|
│ │ └── style.css # CSS principale (~1600 righe)
|
|
│ ├── js/
|
|
│ │ ├── api.js # Client API (270 righe, tutti gli endpoint)
|
|
│ │ └── common.js # Utility condivise (sidebar, notifiche, etc.)
|
|
│ └── uploads/ # Upload directory (gitignored)
|
|
│ └── visure/ # PDF visure camerali
|
|
├── docker/
|
|
│ ├── Dockerfile
|
|
│ ├── docker-compose.yml
|
|
│ ├── nginx.conf
|
|
│ └── php.ini
|
|
└── docs/
|
|
├── sql/
|
|
│ ├── 001_initial_schema.sql # Schema DB completo (20 tabelle)
|
|
│ └── 002_email_log.sql # Tabella email_log
|
|
├── context/
|
|
│ └── CONTEXT_SCHEMA_DB.md
|
|
├── prompts/
|
|
└── credentials/
|
|
├── credentials.md
|
|
└── hetzner_key # SSH key per Hetzner
|
|
```
|
|
|
|
## Multi-Tenancy
|
|
- Ogni tabella dati ha `organization_id`
|
|
- Header `X-Organization-Id` per selezionare org attiva
|
|
- Ruoli: `super_admin`, `org_admin`, `compliance_manager`, `board_member`, `auditor`, `employee`, `consultant`
|
|
- `requireOrgAccess()` in BaseController verifica membership
|
|
- Super admin bypassa tutti i controlli di membership
|
|
|
|
## Flusso Utente
|
|
1. **Registrazione** → redirect a `onboarding.html`
|
|
2. **Onboarding** (5 step): Scelta metodo → Visura/CertiSource/Manuale → Dati aziendali → Profilo → Classificazione NIS2
|
|
3. **Login** → se ha org → `dashboard.html`, altrimenti → `onboarding.html`
|
|
4. **Dashboard** → navigazione sidebar a tutti i moduli
|
|
|
|
## Database (21 tabelle)
|
|
organizations, users, user_organizations, refresh_tokens, assessments, assessment_responses, risks, risk_treatments, incidents, incident_timeline, policies, suppliers, training_courses, training_assignments, assets, compliance_controls, evidence_files, audit_logs, ai_interactions, email_log
|
|
|
|
Schema: `docs/sql/001_initial_schema.sql` + `docs/sql/002_email_log.sql`
|
|
|
|
## Servizi
|
|
|
|
### AIService.php
|
|
- `analyzeGapAssessment()` - Analisi assessment con raccomandazioni
|
|
- `suggestRisks()` - Suggerimenti rischi per settore/asset
|
|
- `generatePolicy()` - Generazione bozze policy NIS2
|
|
- `classifyIncident()` - Classificazione e severity incidenti
|
|
- Modello: claude-sonnet-4-5-20250929, API: https://api.anthropic.com/v1/messages
|
|
|
|
### EmailService.php
|
|
- Notifiche CSIRT: early warning 24h, notification 72h, final report 30d
|
|
- Training assignment e reminder
|
|
- Welcome email, member invite
|
|
- Template HTML professionale con branding NIS2 Agile
|
|
|
|
### RateLimitService.php
|
|
- File-based (/tmp/nis2_ratelimit/)
|
|
- Login: 5/min, 20/h | Register: 3/10min | AI: 10/min, 100/h
|
|
|
|
### ReportService.php
|
|
- Report esecutivo HTML (stampabile come PDF)
|
|
- Export CSV: rischi, incidenti, controlli, asset (separatore ;, BOM UTF-8)
|
|
|
|
### VisuraService.php
|
|
- Estrazione AI da PDF visura camerale (Claude con document type)
|
|
- Fetch dati da CertiSource API (GET /api/company/enrich?vat=)
|
|
- Mapping ATECO → settore NIS2
|
|
|
|
## Deploy
|
|
- **SSH**: `ssh -i docs/credentials/hetzner_key root@135.181.149.254`
|
|
- **Path server**: `/var/www/nis2-agile/`
|
|
- **Apache config**: `/etc/apache2/conf-available/nis2-agile.conf` (Alias /nis2)
|
|
- **Deploy**: `cd /var/www/nis2-agile && git pull origin main`
|
|
- **DB**: Vedi `docs/DB_ACCESS.md` per credenziali (password in `.env`)
|
|
|
|
## Git
|
|
- **Repository**: https://git.certisource.it/AdminGit2026/nis2-agile
|
|
- **Token Gitea**: Configurato in git credential manager (non documentare qui)
|
|
- **Branch**: main (7 commit)
|
|
- **Commit format**: `[AREA] Descrizione`
|
|
|
|
### Cronologia Commit
|
|
```
|
|
bcc5a2b [FIX] E2E testing - fix router, EmailService, frontend data mapping
|
|
6f4b457 [FEAT] Add EmailService, RateLimitService, ReportService + integrations
|
|
9aa2788 [FEAT] Add onboarding wizard with visura camerale and CertiSource integration
|
|
73e78ea [FEAT] Add all frontend pages - complete UI for NIS2 platform
|
|
c03d22e [FIX] Deploy fixes - Auth header passthrough, dashboard query, landing page
|
|
ae78a2f [CORE] Initial project scaffold - NIS2 Agile Compliance Platform
|
|
```
|
|
|
|
## API Endpoints Completi
|
|
|
|
Base: `/nis2/api/{controller}/{action}/{id?}`
|
|
|
|
### Auth: POST register, login, logout, refresh, change-password | GET me | PUT profile
|
|
### Organizations: POST create, classify | GET current, list, {id}/members | PUT {id} | POST {id}/invite | DELETE {id}/members/{sid}
|
|
### Assessments: GET list, {id}, {id}/questions, {id}/report | POST create, {id}/respond, {id}/complete, {id}/ai-analyze | PUT {id}
|
|
### Dashboard: GET overview, compliance-score, upcoming-deadlines, recent-activity, risk-heatmap
|
|
### Risks: GET list, {id}, matrix | POST create, {id}/treatments, ai-suggest | PUT {id}, treatments/{sid} | DELETE {id}
|
|
### Incidents: GET list, {id} | POST create, {id}/timeline, {id}/early-warning, {id}/notification, {id}/final-report, {id}/ai-classify | PUT {id}
|
|
### Policies: GET list, {id}, templates | POST create, {id}/approve, ai-generate | PUT {id} | DELETE {id}
|
|
### Supply Chain: GET list, {id}, risk-overview | POST create, {id}/assess | PUT {id} | DELETE {id}
|
|
### Training: GET courses, assignments, compliance-status | POST courses, assign | PUT assignments/{sid}
|
|
### Assets: GET list, {id}, dependency-map | POST create | PUT {id} | DELETE {id}
|
|
### Audit: GET controls, evidence/list, report, logs, iso27001-mapping, executive-report, export | PUT controls/{sid} | POST evidence/upload
|
|
### Onboarding: POST upload-visura, fetch-company, complete
|
|
### Admin: GET organizations, users, stats
|
|
|
|
## Stato Completamento
|
|
Tutti i moduli sono implementati e testati:
|
|
- [x] Test end-to-end: tutti gli endpoint API verificati
|
|
- [x] Bug fixing: router rewrite, EmailService parse fix, frontend data mapping
|
|
- [x] Docker setup: Dockerfile, docker-compose.yml, nginx.conf, php.ini verificati
|
|
- [x] UI polish: animazioni, skeleton loaders, mobile backdrop, print styles, a11y
|
|
|
|
### Bug Risolti (E2E Testing)
|
|
1. **Router /{id}/subAction** - Pattern matching riscritto completamente per gestire GET /assessments/1/questions, GET /organizations/2/members, etc.
|
|
2. **EmailService parse error** - PHP non supporta `??` dentro `{$var}` string interpolation, estratto a variabile
|
|
3. **Frontend data mapping** - Dashboard, Assessment, Onboarding avevano nomi campo diversi dal backend
|
|
4. **Field name mismatches** - annual_turnover→annual_turnover_eur, question_id→question_code, compliance_level→response_value
|
|
|
|
*Ultimo aggiornamento: 2026-02-17*
|