RiskKey

Automatisation de la mécanique d'une analyse de risques EBIOS RM.

In English. ebiosrm is a small open source command-line tool that automates the tedious mechanics of an EBIOS Risk Manager analysis (the risk management method published by ANSSI, the French national cybersecurity agency). The analysis is written in a YAML file following the five workshops; the tool validates it (schema, cross-references, scales), computes stakeholder threat levels and risk levels, and generates a single-file HTML report with initial and residual risk matrices and the treatment plan. An optional local web interface lets consultants fill in the workshops through forms instead of editing YAML. An optional, disabled-by-default AI command suggests operational scenarios into a separate file flagged "to be validated": the analyst stays in charge of every decision.

À quoi sert l'outil

Une analyse EBIOS RM, ce sont des décisions d'experts (quels événements redoutés, quelle gravité, quels scénarios, quelles mesures) et beaucoup de mécanique autour : tenir les identifiants cohérents d'un atelier à l'autre, calculer le niveau de menace de chaque partie prenante, reporter les risques sur les matrices, remettre le rapport à jour à chaque changement.

ebiosrm automatise cette mécanique et laisse les décisions à l'analyste :

• une seule source de vérité : l'analyse est un fichier YAML lisible, versionnable et comparable d'une révision à l'autre ;
• validation : schéma, échelles et références croisées, avec des messages d'erreur clairs en français, toutes les erreurs listées en une seule passe ;
• calculs : niveau de menace des parties prenantes selon la formule du guide ANSSI, classement en zones, niveaux de risque initiaux et résiduels ;
• rapport : un fichier HTML autonome (CSS intégré, aucune dépendance externe), imprimable et partageable tel quel ;
• interface web locale (en option) : saisie par formulaires, atelier par atelier, avec calculs et rapport mis à jour en direct ;
• option IA (désactivée par défaut) : propositions de scénarios opérationnels écrites dans un fichier séparé, marquées « à valider », jamais intégrées d'office.

Démo en 2 minutes

Prérequis : Python 3.11 ou plus.

git clone https://github.com/Ayzen1003/RiskKey.git
cd RiskKey

Puis :

python -m venv .venv
source .venv/bin/activate        # Windows PowerShell : .venv\Scripts\Activate.ps1
pip install -e .
ebiosrm rapport exemples/atelier_lumen.yaml -o rapport.html

Si la commande ebiosrm n'est pas trouvée (environnement non activé, dossier des scripts absent du PATH), python -m ebiosrm fonctionne partout à l'identique : python -m ebiosrm rapport exemples/atelier_lumen.yaml -o rapport.html.

Ouvrez ensuite rapport.html dans un navigateur. L'exemple « Atelier Lumen » décrit une PME entièrement fictive de vente en ligne de luminaires.

Autres commandes utiles :

ebiosrm valider exemples/atelier_lumen.yaml            # contrôle complet, points d'attention
ebiosrm valider exemples/atelier_lumen.yaml --strict   # échoue aussi sur les points d'attention
ebiosrm suggerer exemples/atelier_lumen.yaml --apercu  # option IA : montre ce qui serait envoyé
ebiosrm --help

Interface web de saisie

Pour saisir une analyse sans éditer de YAML :

pip install -e ".[web]"
ebiosrm interface                                # nouvelle analyse vierge
ebiosrm interface exemples/atelier_lumen.yaml    # ou ouvrir une analyse existante

Le navigateur s'ouvre sur http://localhost:8501 (option --sans-navigateur pour ne pas l'ouvrir, --port pour changer de port ; arrêt par Ctrl+C dans le terminal).

• Critères : seuils de menace et matrice d'acceptation, modifiables.
• Un onglet par atelier : tableaux éditables (ajout et suppression de lignes), listes déroulantes alimentées par les identifiants déjà saisis, échelles de 1 à 4 rappelées dans les en-têtes. Le niveau de menace des parties prenantes est recalculé en direct.
• Résultats et rapport : erreurs en français tant que l'analyse est incomplète, puis indicateurs, rapport intégré et téléchargements (rapport HTML, analyse YAML).
• Enregistrer (barre latérale) : écrit le fichier YAML, par défaut dans analyses/.

L'interface ne contient aucune règle EBIOS RM : elle produit le même fichier YAML que la saisie manuelle, et c'est le moteur qui valide et calcule. Le serveur n'écoute que sur localhost : l'interface n'est pas accessible depuis le réseau. Le dossier analyses/ est exclu de Git, pour qu'aucune analyse réelle ne soit publiée par erreur.

Aperçu du rapport

Le rapport contient, dans l'ordre :

1. la synthèse du cadrage : périmètre, participants, valeurs métier, biens supports, événements redoutés et socle de sécurité (atelier 1) ;
2. les couples source de risque / objectif visé retenus, et ceux qui ont été écartés (atelier 2) ;
3. les parties prenantes avec leur niveau de menace et leur zone, puis les scénarios stratégiques et leur chemin d'attaque (atelier 3) ;
4. les scénarios opérationnels et leur séquence d'attaque (atelier 4) ;
5. les matrices des risques initiaux et résiduels côte à côte ;
6. le plan de traitement : mesures, responsable, échéance, statut, risques couverts (atelier 5).

Format du fichier YAML

Le fichier exemples/atelier_lumen.yaml est commenté et sert de modèle. Les clés et les codes sont en ASCII (reduire, tolerable) ; le rapport affiche les libellés accentués. Chaque élément porte un identifiant unique dans toute l'analyse (lettres, chiffres, _, - et .), que les autres ateliers référencent.

Échelles du guide ANSSI, utilisées partout où une note est attendue :

Note	Gravité	Vraisemblance
1	Mineure	Peu vraisemblable
2	Significative	Vraisemblable
3	Grave	Très vraisemblable
4	Critique	Quasi certain

Paramètres (facultatif)

parametres:
  seuils_menace:
    danger: 3.0     # menace >= 3 : zone de danger
    controle: 1.0   # menace >= 1 : zone de contrôle ; en dessous : zone de veille
  matrice_acceptation:   # une ligne par gravité, une zone par vraisemblance de 1 à 4
    4: [tolerable, inacceptable, inacceptable, inacceptable]
    3: [acceptable, tolerable, inacceptable, inacceptable]
    2: [acceptable, acceptable, tolerable, tolerable]
    1: [acceptable, acceptable, acceptable, tolerable]

Ce sont aussi les valeurs par défaut quand le bloc est absent. Elles sont propres à l'outil, pas à l'ANSSI : le guide laisse à chaque organisation le soin de fixer ses seuils et ses critères d'acceptation. Les seuils sont inclusifs (une menace égale à 3,0 est en zone de danger).

Atelier 1 : cadrage et socle de sécurité

Bloc	Champs
cadrage	organisation, perimetre, description, date, participants (liste de role)
valeurs_metier	id, nom, nature (processus ou information), description, responsable
biens_supports	id, nom, type (materiel, logiciel, reseau, personne, local, prestataire), description, valeurs_metier (identifiants)
evenements_redoutes	id, valeur_metier, description, impacts (liste), gravite (1 à 4)
socle	nom, type (interne, externe, reglementaire), application (complete, partielle, non_appliquee), ecarts (liste de description et justification)

Atelier 2 : sources de risque et objectifs visés

Bloc	Champs
sources_risque	id, nom, description
objectifs_vises	id, libelle
couples	id, source, objectif, motivation, ressources, activite (1 à 4), pertinence (faible, moyenne, elevee), retenu (true ou false), justification

La pertinence est appréciée par l'analyste : le guide ne donne pas de formule, l'outil n'en invente pas.

Atelier 3 : écosystème et scénarios stratégiques

Bloc	Champs
parties_prenantes	id, nom, categorie, dependance, penetration, maturite, confiance (1 à 4)
scenarios_strategiques	id, nom, couple (couple retenu), evenement_redoute, chemin_attaque (liste d'étapes : description, partie_prenante facultative)

Niveau de menace de chaque partie prenante, selon le guide ANSSI :

menace = (dépendance × pénétration) / (maturité cyber × confiance)

Atelier 4 : scénarios opérationnels

Bloc	Champs
scenarios_operationnels	id, scenario_strategique, biens_supports (identifiants), sequence (connaitre, rentrer, trouver, exploiter : listes d'actions), vraisemblance (1 à 4)

Atelier 5 : traitement du risque

Bloc	Champs
risques	id, scenario_operationnel, strategie (reduire, transferer, eviter, accepter), justification, residuel (gravite, vraisemblance)
mesures	id, libelle, categorie (gouvernance, protection, defense, resilience), responsable, echeance (AAAA-MM-JJ), statut (a_lancer, en_cours, terminee), risques_couverts

Pour chaque risque, la gravité initiale est héritée de l'événement redouté visé par le scénario stratégique et la vraisemblance initiale est portée par le scénario opérationnel. Le niveau du risque est la zone lue dans la matrice d'acceptation : l'outil ne calcule pas de score « gravité × vraisemblance », que le guide ne définit pas. Le résiduel est estimé par l'analyste ; l'outil vérifie seulement qu'il ne dépasse pas l'initial.

Contrôles effectués

• Bloquants : champ manquant ou inconnu (faute de frappe), note hors échelle, valeur non reconnue, identifiant en double, référence vers un élément inexistant, scénario stratégique fondé sur un couple non retenu, scénario opérationnel porté par deux risques, résiduel supérieur à l'initial, seuils ou matrice incohérents.
• Points d'attention : valeur métier sans événement redouté, couple retenu sans scénario, scénario opérationnel sans risque, risque à réduire sans mesure, risque résiduel encore inacceptable.

Exemple de message :

Analyse invalide : 1 erreur dans analyse.yaml
  - Scénario stratégique SS2 : l'événement redouté « ER9 » n'existe pas (connus : ER1, ER2, ER3, ER4).

Option IA

pip install -e ".[ia]"
export ANTHROPIC_API_KEY="sk-ant-..."        # PowerShell : $env:ANTHROPIC_API_KEY = "sk-ant-..."
ebiosrm suggerer exemples/atelier_lumen.yaml --apercu              # ce qui serait envoyé
ebiosrm suggerer exemples/atelier_lumen.yaml -o suggestions.yaml   # demande confirmation

• Minimisation : seuls les biens supports et les scénarios stratégiques sont transmis. Le nom de l'organisation, les valeurs métier, le socle et les mesures ne le sont pas. --apercu affiche exactement le texte envoyé, sans rien envoyer.
• Consentement : la commande récapitule l'envoi et demande confirmation (--oui pour l'automatiser).
• Contrôle : la réponse est structurée, puis revalidée localement (échelles, identifiants existants) ; les propositions invalides sont écartées et signalées.
• Décision humaine : les propositions vont dans un fichier séparé, chacune marquée statut: à valider. L'analyse n'est jamais modifiée.
• Sans clé ni SDK, la commande explique comment activer l'option et s'arrête proprement.

La clé est lue par le SDK Anthropic dans la variable d'environnement ANTHROPIC_API_KEY ; elle ne doit jamais être écrite dans le code ni dans le dépôt. Le modèle est modifiable avec --modele.

Architecture

src/ebiosrm/
├── echelles.py      échelles et vocabulaires EBIOS RM (codes et libellés)
├── modele.py        modèle pydantic des 5 ateliers : structure et échelles
├── references.py    cohérence entre ateliers : identifiants, règles de la méthode
├── chargement.py    lecture YAML et traduction des erreurs en français
├── calculs.py       menace, zones, niveaux de risque (fonctions pures)
├── rapport.py       contexte et rendu Jinja2
├── templates/       gabarit HTML autonome
├── ia/              interface Suggesteur, contrôle des propositions, client Claude
├── web/             formulaire.py (conversion pure tableaux <-> analyse), app.py (page Streamlit)
└── cli.py           commandes Typer : valider, rapport, suggerer, interface

Choix principaux :

• Séparation saisie / calcul / présentation : le modèle ne contient que ce que saisit l'analyste, les calculs sont des fonctions pures testées isolément, le gabarit ne fait qu'afficher.
• Validation en deux temps : pydantic pour la structure, un vérificateur dédié pour les références croisées, afin de produire des messages métier précis.
• Rapport sans dépendance : HTML et CSS dans un seul fichier, matrices en tableaux colorés, lisible hors ligne et à l'impression.
• IA derrière une interface : le SDK n'est importé qu'à l'appel ; les tests utilisent un faux suggesteur et ne font aucun appel réseau.
• Interface mince : la page Streamlit ne fait qu'afficher et collecter ; la conversion entre tableaux et analyse est un module pur, testé sans Streamlit.

Développement

pip install -e ".[dev,web]"
pytest            # tests unitaires, page web et génération du rapport d'exemple
ruff check .      # lint
ruff format .     # mise en forme

Les tests de la page web utilisent l'outil de test de Streamlit et ne lancent aucun navigateur : un garde-fou fait échouer tout test qui tenterait d'en ouvrir un. Sous Windows, chaque navigateur Chromium (Edge, Chrome) lancé avec un profil neuf vérifie si le compte a un mot de passe vide, ce qui journalise un échec d'authentification (événement 4625) ; une série de tests automatisés peut ainsi verrouiller le compte. Si des tests dans un navigateur deviennent nécessaires, utilisez un profil persistant, réutilisé d'un lancement à l'autre.

La CI GitHub Actions exécute le lint, les tests sur Python 3.11, 3.12 et 3.13, puis la démo complète sur l'exemple, à chaque push.

Limites et avertissement

• Outil pédagogique, non affilié à l'ANSSI ni approuvé par elle. EBIOS est une marque de l'ANSSI ; seule la documentation officielle de l'ANSSI fait référence.
• Il ne remplace pas l'animation des ateliers avec les parties prenantes : il structure et calcule, il ne décide pas. La qualité de l'analyse dépend des échanges et des cotations faites en atelier.
• Périmètre volontairement réduit : pas de menace résiduelle des parties prenantes, un seul événement redouté par scénario stratégique, pas de cotation de la vraisemblance par actions élémentaires, pas d'export PDF (l'impression du rapport depuis le navigateur en tient lieu).
• L'interface web est prévue pour un usage local par une personne à la fois : pas de comptes ni de travail à plusieurs. Les commentaires d'un fichier YAML ne sont pas conservés quand il est enregistré depuis l'interface.
• Les suggestions IA peuvent être inexactes ou incomplètes et doivent toujours être relues par l'analyste.
• Aucune donnée sensible ne doit être envoyée à un service d'IA sans validation préalable de l'organisation (RSSI, DPO, politique d'usage de l'IA). Utilisez --apercu pour vérifier ce qui serait transmis.
• L'exemple Atelier Lumen est entièrement fictif ; toute ressemblance avec une entreprise existante serait fortuite.

Licence

MIT