76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# 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/`
|