Ousret / hermes

Automates programmables à réaction aux échanges électroniques depuis une boîte IMAP4

Automates programmables IMAP4 pour les humains 👋

Hermès est une divinité issue de la mythologie grecque. Messager des dieux.

_{^{Les noms et logos iTop et Microsoft Exchange sont affichés à titre d'exemple uniquement. N'importe quel service IMAP fonctionne avec Hermes. De même qu'iTop est UN des services sur lequel vous pouvez émettre des requêtes. Hermes n'est pas affilié à Combodo (iTop) ni à Microsoft (Exchange).}}

Contributions

Merci d'offrir une ⭐ à ce projet s'il vous a été utile. Encore mieux, participez en :

• Signalant un problème
• Proposant un correctif via le système de pull request
• Proposant des fonctionnalités/idées utiles à tous

🍰 Quel besoin ?

Ce projet est né d'un besoin spécifique qui a laissé entrevoir la possibilité d'un cas bien plus ouvert et générique. Une entreprise peut-être confrontée à cette problématique :

Comment gérer une interopérabilité des services avec n-tiers en se basant uniquement sur les échanges électroniques ?

L'origine est qu'une entreprise utilisant le programme ITSM iTop et l'Incoming Mail (Scanner de boîte mail). La description officielle du module iTop est la suivante : This extension runs in the background to scan the defined mail inbox(es) and either create or update tickets based on the content of the incoming emails.

Avec l'ancienne solution (Incoming Mail):

1. Identification d'un message très limitée et restreinte
2. Obligation de créer des dossiers IMAP pour n opération(s)
3. Les actions du scanner sont limitées à des simples opérations

Ils se sont retrouvés extrêment limitée par l'Incoming Mail.

Hermes offre une solution complète à ce qu'iTop ne peux pas fournir.

✨ Installation

Le projet Hermes s'installe et s'execute très facilement de deux manières. À condition d'avoir :

• Un compte IMAP et SMTP utilisable
• Environnement Linux, Unix ou Windows au choix

Quelque soit votre méthode préférée, commencez par :

cd $HOME
git clone https://github.com/Ousret/hermes.git
cd ./hermes
cp configuration.dist.yml configuration.yml

Modifions d'abord la configuration à l'aide de votre éditeur préféré, nano, vim, etc..

nano configuration.yml

PRODUCTION: &production
  <<: *common
  SECRET_KEY: MerciDeMeChangerImmediatementAvantPremierLancement  # Remplacer par une longue chaîne de caractère aléatoire 
  # *-* configuration smtp *-* à utiliser pour envoyer les rapports d'erreurs
  EMAIL_HOST: 'hote-smtp'
  EMAIL_PORT: 587
  EMAIL_TIMEOUT: 10
  EMAIL_USE_TLS: True
  EMAIL_HOST_USER: 'smtp-utilisateur@hote-smtp'
  EMAIL_HOST_PASSWORD: 'secret_smtp'
  EMAIL_FROM: 'smtp-utilisateur@hote-smtp'
  INCIDENT_NOTIFIABLE: '[e-mail]' # Remplacer par l'adresse email à laquelle transmettre un rapport d'erreur

Méthode 1 : AVEC Docker

En ayant déjà installé docker et docker-compose sur votre machine, vous n'avez plus qu'à lancer :

docker-compose up

Méthode 2 : SANS Docker

Les pré-requis sont les suivants : python3, pip, nodejs, npm. Optionnellement mariadb-server et mariadb-client.

Il est possible que cette commande nécessite les droits super-utilisateur. (Installation de l'utilitaire yarn)

npm install yarn -g

pip install certifi pyopenssl --user

python setup.py install --user
cd ./hermes_ui
yarn install
yarn build
cd ..

La seconde méthode nécessite de mettre en oeuvre une base de données. Si vous êtes sous mariadb, connectez-vous et créez une base de données hermes.

CREATE DATABASE hermes;

Si vous n'avez pas mariadb, vous pouvez opter pour un système léger sqlite qui ne nécessite rien de plus.

Dans le fichier configuration.yml, modifiez le paramètre suivant :

PRODUCTION: &production
  <<: *common
  SQLALCHEMY_DATABASE_URI: 'mysql://utilisateur:mdp@127.0.0.1/hermes'

Si vous ne souhaitez pas mettre en place mariadb, remplacez par :

PRODUCTION: &production
  <<: *common
  SQLALCHEMY_DATABASE_URI: 'sqlite:///hermes.sqlite'

Pour finir lancer le programme wsgi.py.

python wsgi.py

APRÈS Méthode 1 OU 2

Ouvrir le navigateur à l'adresse suivante : http://127.0.0.1:5000 L'utilisateur par défaut est hermes@localhost et le mot de passe associé est admin. Il est bien entendu sage de le modifier rapidement après la 1ere connexion.

⚡ Comment ça marche ?

En bref,

Un message électronique est reçu, nous arrivons, grâce à une suite de critères (depuis un détecteur) à définir la nature du message tout en conservant les résultats de l'évaluation des critères. Ensuite une suite d'actions déterminées par le concepteur s'enchainera en arbre binaire, chaque action se solde par une réussite ou un échec et prend la branche correspondante pour exécuter l'action suivante.

👤 Documentations

Cette section vous propose de prendre en main rapidement Hermes.

• Comprendre le mécanisme des variables simplifiées sous Hermes
• Écrire et enregistrer vos variables partagées / globales
• Configurer votre/vos boîte(s) IMAP
• Détecter un message électronique
• Créer un automate en réaction à une détection de message électronique
• Mettre en oeuvre une suite d'action à appliquer après la détection
• Test et debug d'un automate

Pour aller encore plus loin :

• Les critères de détection
• Les actions
• GMail

🚧 Maintenance

Ce programme n'est qu'à ses balbutiements. Hermès est stable et disponible pour la production. Ce projet peut être amélioré, des idées d'évolutions significatives sont à l'étude.

Un projet Github est ouvert avec l'ensemble des idées / tâches à réaliser pour rendre ce projet incroyable.

Pour le moment, j'adresse la maintenance concernant les bugs et la sécurité et je relis et j'approuve les contributions soumises.

⬆️ Mise à niveau

Hermès peut être sujet à une mise à jour. Pour ce faire il est possible d'utiliser le script upgrade.sh.

./upgrade.sh

📝 Droits

L'exploitation commerciale est strictement interdite tandis que l'usage interne professionnel est autorisée.

Publication sous "Non-Profit Open Software License 3.0 (NPOSL-3.0)"

Contributeur(s) :

• Ahmed TAHRI @Ousret, Développeur et mainteneur
• Didier JEAN ROBERT @SadarSSI, Conception et expression de besoins
• Denis GUILLOTEAU @Dsniss, Aide à la conception, expression de besoins, testeur, valideur