tommydeeee / hermes

SMTP honeypot built on top of the Salmon mail server

Hermes

Hermes is an SMTP honeypot built on top of the Salmon mail server (https://pypi.org/project/salmon-mail/). It has all the features of Salmon, but our code has been added to create a honeypot so it is now only used as an SMTP server and it is not reasonable to use it like anything else.

Features

All hermes features can be set in the configuration/salmon.yaml configuration file, which is located in the hermes/configuration/ path after installation. If you decide to install honeypot using Ansible playbook, this file is created interactively.

• Honeypot supports Python 3.
• Periodic inspection that the honeypot is running.
• SMTP server listening on the required port and IP address.
• SMTP AUTH command support. Credentials can be set in the configuration file.
• You can configure exim 4 (port and IP address).
• You can turn off e-mail relaying completely. Or you can leave it on and the honeypot will decide which e-mail to relay.
• Possibility to save eml file and email attachment.
• Destroying of attachments, links, and reply-to field.
• Rule file where it is possible to specify the e-mail to be relayed.
• MQTT support.
• Intelligent spam relaying.
• Fast honeypot start, stop, restart using commands salmon-receiver <start|stop|restart> and salmon-relay <start|stop|restart>.

Installation

Shell script

Honeypot can be installed using a shell script in configuration/install.sh. The script must be run from the configuration directory as:

./install.sh -p <path>

The path is either a relative or absolute path to the directory where the honeypot is to be installed. The directory must already exist. The script is primarily intended for users who do not have Ansible installed. The script assumes that the honeypot doesn't exist before the script is run. You must also clone the source repository first. After installation, it's up to you if you want to have two cron jobs to delete old records from the maybe_test_emails table and to check that the honeypot is running. It is also highly recommended to use logrotate because hermes logs can be large after some time. By default, the debug level is set to DEBUG in hermes/salmon-relay/myproject/config/logging.conf after installation. I recommend changing the level to INFO or the salmon.log file will be very long very soon. Also add on line 12 helo_data = hermes.server.com to the file /etc/exim4/conf.d/transport/30_exim4-config_remote_smtp. The ansible playbook takes care of this itself.

Ansible

Honeypot can be installed using the Ansible playbook in ansible/honeypot.yml. You don't need to have the git repository cloned on your local host. You need files from the ansible directory and you need to have Ansible installed on your local host. You can find here how to install Ansible according to the Linux distribution. I recommend installation using pip3:

pip3 install ansible

Missing packages on your local host can be pip3, sshpass. Install as:

sudo apt install python3-pip
sudo apt install sshpass

If you have ansible installed, go to the ansible directory where the playbook is located. Change the IP address of the managed host in the inventory file. Make sure you're using the correct version of the ansible configuration file using the ansible command ansible --version, which must show you something like this:

ansible 2.9.9
  config file = /path/to/git_repository/ansible/ansible.cfg
  configured module search path = ['$HOME/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = $HOME.local/lib/python3.7/site-packages/ansible
  executable location = $HOME.local/bin/ansible
  python version = 3.7.3 (default, Dec 20 2019, 18:57:59) [GCC 8.3.0]

Run playbook as:

ansible-playbook honeypot.yml

You will be prompt to type the password for the remote host. At the end of the installation you will need to type some specifications for salmon.yaml. The playbook will add two cron jobs (see crontab -e) and it will add a logrotate setting to /etc/logrotate.d/hermes. If you want to log on to the remote host other than as root, you must change remote_user = root to remote_user = your_user and become_ask_pass = false to become_ask_pass = true in the ansible.cfg file. Please note that if the remote_user was changed, hermes was still installed in /root, otherwise it would not be possible to run the honeypot on port 25. You will need to run commands salmon-receiver <start|stop|restart> and salmon-relay <start|stop|restart> with sudo.

If you want to run a program that checks the run/queue directory for incoming e-mails, go to hermes/salmon-receiver/myproject/run/ after installation and run:

python3 new_email_inotify.py -r <your_email_address>

Upgrading With Ansible

If you want to upgrade a deployed instance of Hermes with the latest features in master branch, use upgrade.yaml file. In ansible directory, simply run following code with wanted honeypot instances in inventory file.

ansible-playbook upgrade.yml

Testing

In relay/new/tests there are tests written using pytest. Go to the test directory (after installation) and run the tests as:

./run_tests.sh

This runs the tests in test_models.py, test_mailparser.py, and test_conclude.py. Don't run the tests in any other way as they need to have the SALMON_SETTINGS_MODULE environmental variable set. These tests use their own configuration file testing_salmon.yaml and in memory database. Another test is in the test_permeability.py file. Run as:

python3 test_permeability.py -p "<absolute_path_to_directory_with_eml>"

or if you want to use an ssh connection (assuming that port 22 is open)

python3 test_permeability.py -p "<path_to_directory_with_eml>" --scp --password "<password_for_host>" --username "<username_for_host>" --hostname "<hostname|IP>"

or if you want to test only 10 e-mails in the directory

python3 test_permeability.py -p "<absolute_path_to_directory_with_eml>" -n 10

There is also a test test_honeypot_working.py located in the directory hermes/configuration/ after installation. This test will try to send an e-mail using hermes and then check your inbox to see if the e-mail has arrived. Run as:

python3 test_honeypot_working.py --listenhost "<IP_of_salmon_receiver>" --listenport <port_of_salmon_receiver> --recipient "<your_email_address>" --password "<your_password>"

By default it uses imap.seznam.cz imap server so if you want to use e-mail address from another account, you have to specify another imap server using --imap "<imap_server>".

Statistics

See honeypot statistics after installation in hermes/salmon-relay/myproject:

cd hermes/salmon-relay/myproject
./statistics.sh