ics-simlab-config-gen-claude/README.md

ICS-SimLab Configuration Generator (Claude)

Generatore di configurazioni e logica PLC/HIL per ICS-SimLab usando LLM.

🚀 Quick Start

1. Genera configurazione da testo (LLM)

source .venv/bin/activate
python3 main.py --input-file prompts/input_testuale.txt

2. Build scenario completo

python3 build_scenario.py --out outputs/scenario_run --overwrite

3. Valida fix PLC

python3 validate_fix.py

4. Esegui ICS-SimLab

./scripts/run_simlab.sh

📁 Struttura Progetto

ics-simlab-config-gen_claude/
├── main.py                    # Script principale (LLM -> configuration.json)
├── build_scenario.py          # Builder scenario (config -> IR -> logic)
├── validate_fix.py            # Validazione fix PLC startup race
├── README.md                  # Questo file
│
├── docs/                      # 📚 Documentazione completa
│   ├── README_FIX.md         # Main doc per fix PLC startup race
│   ├── QUICKSTART.txt        # Guida rapida
│   ├── RUNTIME_FIX.md        # Fix completo con troubleshooting
│   ├── CHANGES.md            # Dettaglio modifiche con diff
│   ├── DELIVERABLES.md       # Summary completo
│   └── ...
│
├── scripts/                   # 🔧 Script utility
│   ├── run_simlab.sh         # Avvia ICS-SimLab (path assoluti)
│   ├── test_simlab.sh        # Test interattivo
│   └── diagnose_runtime.sh   # Diagnostica
│
├── tools/                     # ⚙️ Generatori
│   ├── compile_ir.py         # IR -> logic/*.py (CON FIX!)
│   ├── make_ir_from_config.py # config.json -> IR
│   ├── generate_logic.py     # Generatore alternativo
│   ├── validate_logic.py     # Validatore
│   └── pipeline.py           # Pipeline end-to-end
│
├── services/                  # 🔄 Pipeline LLM
│   ├── pipeline.py           # Pipeline principale
│   ├── generation.py         # Chiamate LLM
│   ├── patches.py            # Patch automatiche config
│   └── validation/           # Validatori
│
├── models/                    # 📋 Schemi dati
│   ├── ics_simlab_config.py  # Config ICS-SimLab
│   ├── ir_v1.py              # IR (Intermediate Representation)
│   └── schemas/              # JSON Schema
│
├── templates/                 # 📝 Template codice
│   └── tank.py               # Template water tank
│
├── helpers/                   # 🛠️ Utility
│   └── helper.py
│
├── prompts/                   # 💬 Prompt LLM
│   ├── input_testuale.txt    # Input esempio
│   ├── prompt_json_generation.txt
│   └── prompt_repair.txt
│
├── examples/                  # 📦 Esempi riferimento
│   ├── water_tank/
│   ├── smart_grid/
│   └── ied/
│
├── spec/                      # 📖 Specifiche
│   └── ics_simlab_contract.json
│
└── outputs/                   # 🎯 Output generati
    ├── configuration.json    # Config base generata
    ├── ir/                   # IR intermedio
    │   └── ir_v1.json
    └── scenario_run/         # 🚀 SCENARIO FINALE PER ICS-SIMLAB
        ├── configuration.json
        └── logic/
            ├── plc1.py       # ✅ Con _safe_callback
            ├── plc2.py       # ✅ Con _safe_callback
            └── hil_1.py

🔧 Workflow Completo

Opzione A: Solo generazione logica (da config esistente)

# Da configuration.json esistente -> scenario completo
python3 build_scenario.py --config outputs/configuration.json --overwrite

Opzione B: Pipeline completa (da testo)

# 1. Testo -> configuration.json (LLM)
python3 main.py --input-file prompts/input_testuale.txt

# 2. Config -> scenario completo
python3 build_scenario.py --overwrite

# 3. Valida
python3 validate_fix.py

# 4. Esegui
./scripts/run_simlab.sh

Opzione C: Pipeline manuale step-by-step

# 1. Config -> IR
python3 -m tools.make_ir_from_config \
    --config outputs/configuration.json \
    --out outputs/ir/ir_v1.json \
    --overwrite

# 2. IR -> logic/*.py
python3 -m tools.compile_ir \
    --ir outputs/ir/ir_v1.json \
    --out-dir outputs/scenario_run/logic \
    --overwrite

# 3. Copia config
cp outputs/configuration.json outputs/scenario_run/

# 4. Valida
python3 -m tools.validate_logic \
    --config outputs/configuration.json \
    --logic-dir outputs/scenario_run/logic \
    --check-callbacks \
    --check-hil-init

🐛 Fix PLC Startup Race Condition

Il generatore include un fix per il crash di PLC2 all'avvio:

• Problema: PLC2 crashava quando scriveva a PLC1 prima che fosse pronto
• Soluzione: Retry wrapper _safe_callback() in tools/compile_ir.py
• Dettagli: Vedi docs/README_FIX.md

Verifica Fix

python3 validate_fix.py
# Output atteso: ✅ SUCCESS: All PLC files have the callback retry fix

🚀 Esecuzione ICS-SimLab

IMPORTANTE: Usa percorsi ASSOLUTI con sudo, non ~!

# ✅ CORRETTO
cd /home/stefano/projects/ICS-SimLab-main/curtin-ics-simlab
sudo ./start.sh /home/stefano/projects/ics-simlab-config-gen_claude/outputs/scenario_run

# ❌ SBAGLIATO (sudo non espande ~)
sudo ./start.sh ~/projects/ics-simlab-config-gen_claude/outputs/scenario_run

Oppure usa lo script (gestisce automaticamente i path):

./scripts/run_simlab.sh

Monitoraggio

# Log PLC2 (cercare: NO "Exception in thread" errors)
sudo docker logs $(sudo docker ps --format '{{.Names}}' | grep plc2) -f

# Stop
cd /home/stefano/projects/ICS-SimLab-main/curtin-ics-simlab
sudo ./stop.sh

📚 Documentazione

• Quick Start: docs/QUICKSTART.txt
• Fix Completo: docs/README_FIX.md
• Troubleshooting: docs/RUNTIME_FIX.md
• Modifiche: docs/CHANGES.md
• Comandi Corretti: docs/CORRECT_COMMANDS.txt

🔑 Setup Iniziale

# Crea venv
python3 -m venv .venv
source .venv/bin/activate

# Installa dipendenze (se necessario)
pip install openai python-dotenv pydantic

# Configura API key
echo "OPENAI_API_KEY=sk-..." > .env

🎯 File Chiave

• tools/compile_ir.py - Generatore PLC logic (CON FIX)
• build_scenario.py - Builder scenario deterministico
• validate_fix.py - Validatore fix
• outputs/scenario_run/ - Scenario finale per ICS-SimLab

⚠️ Note Importanti

1. Sempre usare .venv/bin/python3 per assicurare venv corretto
2. Percorsi assoluti con sudo (no ~)
3. Rebuild scenario dopo modifiche a config: python3 build_scenario.py --overwrite
4. Validare sempre dopo rebuild: python3 validate_fix.py

📝 TODO / Roadmap

• Supporto per più modelli (oltre "tank")
• Generazione automatica HMI
• Parametri retry configurabili
• Test automatizzati end-to-end

📄 Licenza

Tesi Stefano D'Orazio - OT Security

---

Status: ✅ Production Ready Last Update: 2026-01-27