nis2-agile/CLAUDE.md

NIS2 Agile - Documentazione Progetto

PRIMA DI INIZIARE

• Leggi sempre questo file prima di iniziare qualsiasi lavoro
• File specializzati per area di lavoro:
  • Assessment/Gap Analysis: docs/prompts/PROMPT_ASSESSMENT.md
  • Risk Management: docs/prompts/PROMPT_RISK.md
  • Incident Management: docs/prompts/PROMPT_INCIDENTS.md

Panoramica

NIS2 Agile è 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 e suggerimenti.

Target: PMI, Enterprise, Consulenti/CISO.

Stack Tecnologico

• Backend: PHP 8.4 vanilla (no framework)
• Database: MySQL 8.x (nis2_agile_db)
• Frontend: HTML5/CSS3/JavaScript vanilla
• Auth: JWT HS256 (2h access + 7d refresh)
• AI: Anthropic Claude API (Sonnet 4.5)
• Server: Hetzner CPX31 (135.181.149.254)
• VCS: Gitea (git.certisource.it)
• Routing: Front Controller pattern (public/index.php)

Regola Fondamentale

Il progetto NIS2 Agile è 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 - documentazione progetto
├── application/
│   ├── config/
│   │   ├── config.php                 # Costanti app, CORS, JWT, password policy
│   │   ├── database.php               # Classe Database (PDO singleton)
│   │   └── env.php                    # Caricamento variabili ambiente da .env
│   ├── controllers/
│   │   ├── BaseController.php         # Classe base: auth JWT, multi-tenancy, JSON responses
│   │   ├── AdminController.php        # Gestione piattaforma (super_admin)
│   │   ├── AssessmentController.php   # Gap analysis e questionari NIS2
│   │   ├── AssetController.php        # Inventario asset e dipendenze
│   │   ├── AuditController.php        # Controlli compliance, evidenze, report
│   │   ├── AuthController.php         # Login, register, JWT, refresh token
│   │   ├── DashboardController.php    # Overview, score, deadlines, heatmap
│   │   ├── IncidentController.php     # Gestione incidenti (24h/72h/30d)
│   │   ├── OrganizationController.php # CRUD organizzazioni, membri, classificazione
│   │   ├── PolicyController.php       # Gestione policy, approvazione, AI generation
│   │   ├── RiskController.php         # Risk register, trattamenti, matrice rischi
│   │   ├── SupplyChainController.php  # Fornitori, valutazione, risk overview
│   │   └── TrainingController.php     # Corsi, assegnazioni, compliance formativa
│   ├── services/
│   │   └── AIService.php              # Integrazione Anthropic Claude API
│   ├── models/                        # (riservato per modelli futuri)
│   └── data/
│       ├── nis2_questionnaire.json    # Domande questionario gap analysis
│       └── policy_templates/          # Template policy NIS2
├── public/
│   ├── index.php                      # Front Controller / Router
│   ├── api-status.php                 # Health check endpoint
│   ├── css/                           # Fogli di stile
│   ├── js/
│   │   └── api.js                     # Client API JavaScript
│   └── admin/                         # Pannello admin frontend
├── docker/
│   ├── Dockerfile                     # Build PHP-FPM
│   ├── docker-compose.yml             # Orchestrazione servizi
│   ├── nginx.conf                     # Configurazione Nginx
│   └── php.ini                        # Configurazione PHP custom
├── docs/
│   ├── sql/
│   │   └── 001_initial_schema.sql     # Schema database completo
│   ├── context/
│   │   └── CONTEXT_SCHEMA_DB.md       # Schema documentato
│   ├── prompts/                       # Prompt specializzati per AI
│   └── credentials/
│       ├── credentials.md             # Note credenziali
│       └── hetzner_key                # Chiave SSH Hetzner
├── .env                               # Variabili ambiente (NON committare)
└── .gitignore

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

API Endpoints

Tutti gli endpoint seguono il pattern: /nis2/api/{controller}/{action}/{id?}

AuthController (/api/auth/)

Metodo	Endpoint	Azione	Descrizione
POST	/api/auth/register	register	Registrazione nuovo utente
POST	/api/auth/login	login	Login con email/password
POST	/api/auth/logout	logout	Logout e invalidazione token
POST	/api/auth/refresh	refresh	Refresh JWT token
GET	/api/auth/me	me	Profilo utente corrente
PUT	/api/auth/profile	updateProfile	Aggiorna profilo
POST	/api/auth/change-password	changePassword	Cambio password

OrganizationController (/api/organizations/)

Metodo	Endpoint	Azione	Descrizione
POST	/api/organizations/create	create	Crea organizzazione
GET	/api/organizations/current	getCurrent	Org corrente dell'utente
GET	/api/organizations/list	list	Lista organizzazioni accessibili
PUT	/api/organizations/{id}	update	Aggiorna organizzazione
GET	/api/organizations/{id}/members	listMembers	Lista membri organizzazione
POST	/api/organizations/{id}/invite	inviteMember	Invita membro
DELETE	/api/organizations/{id}/members/{sid}	removeMember	Rimuovi membro
POST	/api/organizations/classify	classifyEntity	Classifica entità NIS2

AssessmentController (/api/assessments/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/assessments/list	list	Lista assessment
POST	/api/assessments/create	create	Crea nuovo assessment
GET	/api/assessments/{id}	get	Dettaglio assessment
PUT	/api/assessments/{id}	update	Aggiorna assessment
GET	/api/assessments/{id}/questions	getQuestions	Domande questionario
POST	/api/assessments/{id}/respond	saveResponse	Salva risposta
POST	/api/assessments/{id}/complete	complete	Completa assessment
GET	/api/assessments/{id}/report	getReport	Report assessment
POST	/api/assessments/{id}/ai-analyze	aiAnalyze	Analisi AI del gap

DashboardController (/api/dashboard/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/dashboard/overview	overview	Overview compliance
GET	/api/dashboard/compliance-score	complianceScore	Score compliance
GET	/api/dashboard/upcoming-deadlines	deadlines	Scadenze imminenti
GET	/api/dashboard/recent-activity	recentActivity	Attività recenti
GET	/api/dashboard/risk-heatmap	riskHeatmap	Heatmap rischi

RiskController (/api/risks/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/risks/list	list	Lista rischi
POST	/api/risks/create	create	Crea rischio
GET	/api/risks/{id}	get	Dettaglio rischio
PUT	/api/risks/{id}	update	Aggiorna rischio
DELETE	/api/risks/{id}	delete	Elimina rischio
POST	/api/risks/{id}/treatments	addTreatment	Aggiungi trattamento
PUT	/api/risks/treatments/{sid}	updateTreatment	Aggiorna trattamento
GET	/api/risks/matrix	getRiskMatrix	Matrice dei rischi
POST	/api/risks/ai-suggest	aiSuggestRisks	Suggerimenti AI rischi

IncidentController (/api/incidents/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/incidents/list	list	Lista incidenti
POST	/api/incidents/create	create	Crea incidente
GET	/api/incidents/{id}	get	Dettaglio incidente
PUT	/api/incidents/{id}	update	Aggiorna incidente
POST	/api/incidents/{id}/timeline	addTimelineEvent	Aggiungi evento timeline
POST	/api/incidents/{id}/early-warning	sendEarlyWarning	Early warning (24h)
POST	/api/incidents/{id}/notification	sendNotification	Notifica (72h)
POST	/api/incidents/{id}/final-report	sendFinalReport	Report finale (30d)
POST	/api/incidents/{id}/ai-classify	aiClassify	Classificazione AI incidente

PolicyController (/api/policies/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/policies/list	list	Lista policy
POST	/api/policies/create	create	Crea policy
GET	/api/policies/{id}	get	Dettaglio policy
PUT	/api/policies/{id}	update	Aggiorna policy
DELETE	/api/policies/{id}	delete	Elimina policy
POST	/api/policies/{id}/approve	approve	Approva policy
POST	/api/policies/ai-generate	aiGeneratePolicy	Genera policy con AI
GET	/api/policies/templates	getTemplates	Lista template policy

SupplyChainController (/api/supply-chain/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/supply-chain/list	list	Lista fornitori
POST	/api/supply-chain/create	create	Aggiungi fornitore
GET	/api/supply-chain/{id}	get	Dettaglio fornitore
PUT	/api/supply-chain/{id}	update	Aggiorna fornitore
DELETE	/api/supply-chain/{id}	delete	Elimina fornitore
POST	/api/supply-chain/{id}/assess	assessSupplier	Valuta fornitore
GET	/api/supply-chain/risk-overview	riskOverview	Overview rischio supply chain

TrainingController (/api/training/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/training/courses	listCourses	Lista corsi
POST	/api/training/courses	createCourse	Crea corso
GET	/api/training/assignments	myAssignments	Le mie assegnazioni
POST	/api/training/assign	assignCourse	Assegna corso
PUT	/api/training/assignments/{sid}	updateAssignment	Aggiorna assegnazione
GET	/api/training/compliance-status	complianceStatus	Status compliance formativa

AssetController (/api/assets/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/assets/list	list	Lista asset
POST	/api/assets/create	create	Crea asset
GET	/api/assets/{id}	get	Dettaglio asset
PUT	/api/assets/{id}	update	Aggiorna asset
DELETE	/api/assets/{id}	delete	Elimina asset
GET	/api/assets/dependency-map	dependencyMap	Mappa dipendenze

AuditController (/api/audit/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/audit/controls	listControls	Lista controlli compliance
PUT	/api/audit/controls/{sid}	updateControl	Aggiorna controllo
POST	/api/audit/evidence/upload	uploadEvidence	Carica evidenza
GET	/api/audit/evidence/list	listEvidence	Lista evidenze
GET	/api/audit/report	generateReport	Genera report audit
GET	/api/audit/logs	getAuditLogs	Log audit
GET	/api/audit/iso27001-mapping	getIsoMapping	Mapping ISO 27001

AdminController (/api/admin/)

Metodo	Endpoint	Azione	Descrizione
GET	/api/admin/organizations	listOrganizations	Lista tutte le organizzazioni
GET	/api/admin/users	listUsers	Lista tutti gli utenti
GET	/api/admin/stats	platformStats	Statistiche piattaforma

Database Schema

• 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, rate_limits
• Schema completo: docs/sql/001_initial_schema.sql
• Schema documentato: docs/context/CONTEXT_SCHEMA_DB.md

AI Integration

• Servizio: application/services/AIService.php
• Funzionalità: gap analysis, risk suggestions, policy generation, incident classification
• Modello: claude-sonnet-4-5-20250929
• API Key: da .env (ANTHROPIC_API_KEY)
• Rate limiting: tabella rate_limits, controllo per utente/organizzazione
• Logging: tabella ai_interactions per tracciare tutte le chiamate AI

Moduli NIS2 (Art. 21)

1. Gap Analysis & Assessment (Art. 21) - Questionario strutturato con analisi AI
2. Risk Management (Art. 21.2.a) - Risk register, matrice, trattamenti
3. Incident Management (Art. 23) - Timeline 24h/72h/30d, early warning, notifiche
4. Policy Management (Art. 21) - CRUD policy, approvazione, generazione AI
5. Supply Chain Security (Art. 21.2.d) - Valutazione fornitori, risk overview
6. Training & Awareness (Art. 20) - Corsi, assegnazioni, compliance formativa
7. Asset Management (Art. 21.2.i) - Inventario, classificazione, mappa dipendenze
8. Audit & Compliance (Art. 21.2.f) - Controlli, evidenze, report, mapping ISO 27001

Deploy

• SSH: ssh -i docs/credentials/hetzner_key root@135.181.149.254
• Path server: /var/www/nis2-agile/
• Deploy: scp via SSH (manuale)
• Docker: docker-compose up -d

Git

• Repository: https://git.certisource.it/AdminGit2026/nis2-agile
• Branch: main
• Commit format: [AREA] Descrizione
• Aree: [CORE], [AUTH], [ASSESSMENT], [RISK], [INCIDENT], [POLICY], [SUPPLY], [TRAINING], [ASSET], [AUDIT], [FRONTEND], [AI], [DOCS], [DOCKER]

Comandi Utili

# Sviluppo locale
php -S localhost:8080 -t public/

# Applicare schema database
mysql -u nis2_user -p nis2_agile_db < docs/sql/001_initial_schema.sql

# Docker
cd docker && docker-compose up -d

# SSH al server
ssh -i docs/credentials/hetzner_key root@135.181.149.254

# Deploy manuale
scp -i docs/credentials/hetzner_key -r application/ root@135.181.149.254:/var/www/nis2-agile/
scp -i docs/credentials/hetzner_key -r public/ root@135.181.149.254:/var/www/nis2-agile/

Ultimo aggiornamento: 2026-02-17