SecureCheck/CLAUDE.md

CLAUDE.md

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

Commandes de développement

# 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/