# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commandes de développement

```bash
# Lancer l'application (mode interactif, demande sudo automatiquement)
python3 -m securecheck

# Lancer sans sudo (pour tester sans élévation)
SECURECHECK_SKIP_SUDO=1 python3 -m securecheck

# Mode non interactif
python3 -m securecheck --dry-run --tasks system_update,lynis_audit
python3 -m securecheck --scenario baseline_workstation --run
python3 -m securecheck --list-scenarios

# Avec sudo (recommandé pour les tâches système réelles)
sudo -E python3 -m securecheck

# Installation locale
pip install .

# Build du binaire autonome (nécessite .venv avec pyinstaller)
python3 -m venv .venv
.venv/bin/pip install pyinstaller
./build_executable.sh
# Résultat dans dist/securecheck
```

## Architecture

### Flux d'exécution principal

`__main__.py:main()` orchestre tout :
1. `ensure_root()` — ré-exécute automatiquement avec `sudo -E` si non root (sauf `SECURECHECK_SKIP_SUDO=1`)
2. `detect_system()` — détecte distro, gestionnaire de paquets, user invocant
3. `task_catalog()` + `builtin_scenarios()` — charge tâches et scénarios
4. En mode interactif : `SecureCheckTUI` → sélection → `execute_tasks()` → `RunSummaryTUI`
5. En mode non interactif : résolution des tâches via `--tasks`/`--scenario` → `execute_tasks()` → affichage terminal

### Modules clés

- **`models.py`** — dataclasses centrales : `TaskDefinition`, `TaskResult`, `Scenario`
- **`catalog.py`** — registre de toutes les tâches (`task_catalog()`) et scénarios builtin (`builtin_scenarios()`). Utilise `bind()` pour attacher les handlers.
- **`tasks.py`** — implémentation de chaque tâche (une fonction par tâche). Chaque fonction reçoit `(context: ExecutionContext, task: TaskDefinition)` et retourne `TaskResult`.
- **`executor.py`** — `ExecutionContext` (contexte partagé par toutes les tâches) et `CommandRunner` (abstraction pour toutes les opérations système : paquets, fichiers, services, shell). `execute_tasks()` itère sur les tâches et capture les exceptions.
- **`app.py`** — TUI curses : `SecureCheckTUI` (menu principal) et `RunSummaryTUI` (résumé post-exécution)
- **`config.py`** — `AppPaths` et `build_paths()` : résolution XDG des chemins (config, state, logs). Logs dans `/var/log/securecheck` si root, sinon `~/.local/state/securecheck/logs`.
- **`storage.py`** — `ScenarioStore` : lecture/écriture des scénarios utilisateur dans `~/.config/securecheck/scenarios.json`
- **`system_info.py`** — `SystemInfo` + `detect_system()` : détecte OS, package manager, user réel (via `SUDO_USER`), home, uid/gid
- **`status.py`** — `collect_status()` : sonde les services/composants pour le tableau d'état LED
- **`assets.py`** — accès aux fichiers embarqués dans `securecheck/assets/` (banner.txt, p10k.zsh, icônes)

### Ajouter une nouvelle tâche

1. Écrire la fonction dans `tasks.py` avec la signature `(context: ExecutionContext, task: TaskDefinition) -> TaskResult`
2. Enregistrer dans `catalog.py` : ajouter un `TaskDefinition` dans `task_catalog()` et mapper son handler dans `handlers`
3. L'ajouter optionnellement à un `builtin_scenarios()` existant

### Conventions importantes

- `CommandRunner` est le seul point d'entrée pour les opérations système (jamais `subprocess` directement dans `tasks.py`)
- `context.runner.write_text_file()` est idempotent : ne réécrit pas si le contenu est identique
- `context.runner.update_package_index()` est appelé une seule fois par exécution (flag `_package_index_updated`)
- Le `target_user` dans `SystemInfo` est l'utilisateur réel ayant lancé `sudo`, pas root
- `--dry-run` : toutes les opérations système sont simulées, les commandes sont loggées sans être exécutées

### Emplacements runtime

- Scénarios : `~/.config/securecheck/scenarios.json`
- Logs : `/var/log/securecheck/` (root) ou `~/.local/state/securecheck/logs/`
- Rapports par exécution : `<log_dir>/run-YYYYMMDD-HHMMSS.log`
- Rapports tâches (lynis, rootkits) : `<log_dir>/reports/`