AdminGit2026/nis2-agile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
73e78ea6b4
nis2-agile/CLAUDE.md
Cristiano Benassati ae78a2f7f4 [CORE] Initial project scaffold - NIS2 Agile Compliance Platform 
Complete MVP implementation including:
- PHP 8.4 backend with Front Controller pattern (80+ API endpoints)
- Multi-tenant architecture with organization_id isolation
- JWT authentication (HS256, 2h access + 7d refresh tokens)
- 14 controllers: Auth, Organization, Assessment, Dashboard, Risk,
  Incident, Policy, SupplyChain, Training, Asset, Audit, Admin
- AI Service integration (Anthropic Claude API) for gap analysis,
  risk suggestions, policy generation, incident classification
- NIS2 gap analysis questionnaire (~80 questions, 10 categories)
- MySQL schema (20 tables) with NIS2 Art. 21 compliance controls
- NIS2 Art. 23 incident reporting workflow (24h/72h/30d)
- Frontend: login, register, dashboard, assessment wizard, org setup
- Docker configuration (PHP-FPM + Nginx + MySQL)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 17:50:18 +01:00

280 lines
18 KiB
Markdown
Raw Blame History

# 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
```bash
# 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*
Reference in New Issue View Git Blame Copy Permalink