https://github.com/ousret/hermes
Automates programmables à réaction aux échanges électroniques depuis une boîte IMAP4
https://github.com/ousret/hermes
automation hermes imap mail mail-automation python web-ui
Last synced: 9 months ago
JSON representation
Automates programmables à réaction aux échanges électroniques depuis une boîte IMAP4
- Host: GitHub
- URL: https://github.com/ousret/hermes
- Owner: Ousret
- License: other
- Archived: true
- Created: 2019-11-19T13:18:28.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-05-13T04:33:48.000Z (about 2 years ago)
- Last Synced: 2025-10-06T15:58:01.624Z (9 months ago)
- Topics: automation, hermes, imap, mail, mail-automation, python, web-ui
- Language: Python
- Homepage:
- Size: 890 KB
- Stars: 16
- Watchers: 1
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README-en.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Programmable IMAP4 controllers for humans 👋 
> Hermès is a pagan god in Greek mythology - messenger of the gods.
The names and logos of `iTop` and `Microsoft Exchange` are displayed only as samples.
Any IMAP provider or service works with Hermes, just as `iTop` is only one of the services you can use to send HTTP requests. Hermes is not affiliated with Combodo (iTop) or Microsoft (Exchange).
## Contributions
Please ⭐ this project if you found it useful. Even better, contribute by :
- Reporting issues and problems
- Submitting a fix with a pull request
- Requesting features to benefit everyone
## 🍰 Why Hermes ?
This project was created with a specific use case in mind, which brought up the possibilities of a more open and generic use case.
A company may face this problem :
**How do we manage the interoperability of services with n-tiers, based only on electronic exchanges?**
A company was currently using the ITSM iTop program and the Incoming Mail (Mailbox Scanner) functionalities.
The official description of iTop is the following : `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.`
With the old solution (Incoming Mail):
1) Limited and restricted message identification
2) Forced to create IMAP files for *n* operations
3) Scanner actions are limited to basic operations
They found themselves extremely limited by Incoming Mail's functionalities.
Hermes offers a complete solution, building on what iTop cannot provide.
## ✨ Installation
Hermes is easily installed and executed in two ways. Requirements:
- A usable IMAP / SMTP account
- Your choice of a Linux / Unix / Windows environment
Whatever your preferred method, start by running :
```shell
cd $HOME
git clone https://github.com/Ousret/hermes.git
cd ./hermes
cp configuration.dist.yml configuration.yml
```
First, modify the configuration with your preferred text editor: `nano`, `vim`, etc..
```shell
nano configuration.yml
```
```yaml
PRODUCTION: &production
<<: *common
SECRET_KEY: PleaseChangeThisStringBeforeDeployment # Replace with a long randomly generated string
# *-* smtp configuration *-* used to send error reports
EMAIL_HOST: 'smtp-host'
EMAIL_PORT: 587
EMAIL_TIMEOUT: 10
EMAIL_USE_TLS: True
EMAIL_HOST_USER: 'smtp-user@smtp-host'
EMAIL_HOST_PASSWORD: 'secret_smtp'
EMAIL_FROM: 'smtp-user@smtp-host'
INCIDENT_NOTIFIABLE: 'destination@gmail.com' # Replace with the email to send error reports to
```
### Method 1 : WITH Docker
If you've already installed `docker` and `docker-compose` on your machine, you can simply run :
```shell
docker-compose up
```
### Method 2 : WITHOUT Docker
Requirements : `python3`, `pip`, `nodejs`, `npm`. Optional : `mariadb-server` and `mariadb-client`.
These commands may require superuser privileges. (Installing the `yarn` utility)
```bash
npm install yarn -g
```
```shell
pip install certifi pyopenssl --user
python setup.py install --user
cd ./hermes_ui
yarn install
yarn build
cd ..
```
The second method requires a database implementation. If you're using `mariadb`, connect and create a `hermes` database.
```sql
CREATE DATABASE hermes;
```
If you don't have `mariadb` installed, you can opt for a lightweight `sqlite` implementation.
In the `configuration.yml` file, change the following parameter :
```yaml
PRODUCTION: &production
<<: *common
SQLALCHEMY_DATABASE_URI: 'mysql://user:mdp@127.0.0.1/hermes'
```
If you don't want to use `mariadb`, replace it with :
```yaml
PRODUCTION: &production
<<: *common
SQLALCHEMY_DATABASE_URI: 'sqlite:///hermes.sqlite'
```
Finally, launch `wsgi.py`.
```shell
python wsgi.py
```
### AFTER Method 1 or 2
Navigate to the following address : [http://127.0.0.1:5000](http://127.0.0.1:5000)
The default user is `hermes@localhost` and the password is `admin`.
It's a good idea to change these after the first connection.
## ⚡ How does it work ?
Essentially,
An electronic **message** is received -> we use a **series of criteria** from a **detector** to find the nature of the message while preserving evaluation results -> **A series of actions** defined by the designer will be linked in a binary tree -> each action results in a **success** or a **failure** and takes the appropriate following action.
## 👤 Documentation
This section is a guide to getting started with Hermes quickly.
- [ ] [Understanding simplified variables with Hermes](docs/CHAPITRE-1.md)
- [ ] [Write / save global variables](docs/CHAPITRE-2.md)
- [ ] [Configure your IMAP box(es)](docs/CHAPITRE-3.md)
- [ ] [Detecting an email message](docs/CHAPITRE-4.md)
- [ ] [Creating a controller in response to a message detection](docs/CHAPITRE-5.md)
- [ ] [Implement an action sequence](docs/CHAPITRE-6.md)
- [ ] [Test and debug the controller](docs/CHAPITRE-7.md)
Going further :
- [ ] [Detection criteria](docs/CRITERES.md)
- [ ] [The actions](docs/ACTIONS.md)
- [ ] [Gmail](docs/GMAIL.md)
## 🚧 Maintenance
This program is still in its development stages.
Hermes is stable and available for production and deployment. This project can be improved - ideas for significant refactors are being considered.
A GitHub Project is open with all the tasks to be carried out to make Hermes even more incredible!
For now, I'm focusing on bugs and security maintenance, and I re-read and approve all contributions.
## ⬆️ Upgrade
Hermes may require updates. To do so, run the `upgrade.sh` script.
```shell
./upgrade.sh
```
## 📝 License
**Commercial exploitation is strictly prohibited, however, internal use is authorized.**
Released under "Non-Profit Open Software License 3.0 (NPOSL-3.0)"
## Contributor(s) :
- Ahmed TAHRI @Ousret, Developer and maintainer
- Didier JEAN ROBERT @SadarSSI, Initial conception and feature brainstormer
- Denis GUILLOTEAU @Dsniss, Initial conception, tester, validator.