This project was supported and funded by Google Summer of Code 2023. For more information about Honeyscanner in GSoC2023 click here.

This project was presented at BlackHat Europe 2023 in London. For more information about Honeyscanner in BlackHat Europe click here.

Honeyscanner - A vulnerability analyzer for Honeypots

Honeyscanner is a vulnerability analyzer for honeypots designed to automatically attack a given honeypot, in order to determine if the honeypot is vulnerable to specific types of cyber attacks. It uses a variety of attacks, ranging from exploiting vulnerable software libraries to DoS, and fuzzing attacks. The analyzer then provides an evaluation report to the honeypot administrator, offering advice on how to enhance the security of the honeypot. Targeted toward security enthusiasts, open-source communities, and companies, Honeyscanner provides a much needed safety check for various honeypots.

Video showcasing Honeyscanner against Cowrie v2.5.0

Architecture

References

Inspiration for Honeyscanner were the following research papers.

[1] Alexander Vetterl, Richard Clayton: "Bitter Harvest: Systematically Fingerprinting Low- and Medium-interaction Honeypots at Internet Scale"

[2] Shreyas Srinivasa, Jens Myrup Pedersen, Emmanouil Vasilomanolakis: "Gotta catch 'em all: a Multistage Framework for honeypot fingerprinting"

[3] Shreyas Srinivasa, Dimitrios Georgoulias, Jens Myrup Pedersen, Emmanouil Vasilomanolakis: "A Bad IDEa: Weaponizing uncontrolled online-IDEs in availability attacks"

Installation

The following instructions will guide you through the process of setting up Honeyscanner on your local machine.

Requirements

Python v3.10.12 - Required to run the project
Pipenv v2023.12.1 - Required to install Python dependencies
Git - Used to download the source code

Download the Honeyscanner source code from GitHub. Open a tarminal and introduce the following command.
```
git clone https://github.com/honeynet/honeyscanner.git
```
Navigate to the Honeyscanner's folder, install the required Python packages and activate the virtual environment.
```
cd Honeyscanner/honeyscanner
pipenv install
pipenv shell
```

NOTE FOR PIPENV: To exit the virtual environment, you just need to enter the command "exit" in the terminal.

Configuration

Before you run Honeyscanner, you need to control or own a Honeypot instance. For testing purposes, this guide assumes that the targeted Honeypot runs on a Docker container on the local machine, where Honeyscanner runs.
To test Honeyscanner against the latest Cowrie version, you can use the official Docker Image here, pull it locally and run a Docker container with it.
If you prefer to test Honeyscanner against Kippo, you can use the following Docker Image in DockerHub here.
For testing Honeyscanner against Dionaea, use the following Docker Image in DockerHub here.
For testing Honeyscanner against Conpot, use the following Docker Image in DockerHub here.
After running a Honeypot using Docker containers locally, you will be able to specify the target ip parameter with --target-ip 127.0.0.1 when running the Honeyscanner.

NOTE: NEVER RUN Honeyscanner AGAINST HONEYPOTS YOU DO NOT OWN, OR YOU DO NOT HAVE EXPLICIT PERMISSION TO TEST.

NOTE: Currently Honeyscanner can actively attack the Dionaea and the Conpot honeypots only by using the DoS attack module. The way it works is that initially Honeyscanner uses nmap to find the open ports on the targeted honeypot, then tries to DoS all ports simultaneously. In order to run the nmap scanner, run Honeyscanner with root privileges for scanning Dionaea and Conpot. This provides nmap with deeper view of the services that run behind each port on the honeypot.

NOTE: For Dionaea only version 0.11.0 is supported at this stage of Honeyscanner. For Conpot, all versions up to 0.6.0 are supported.

Usage

Use the following examples as a reference for how to run Honeyscanner:

python3 main.py --target-ip 127.0.0.1

python3 main.py --target-ip 127.0.0.1 --username root --password 1234

Contributors

For information on Contributors and How to contribute see our Contributors file.

Versioning

The SemVer is used for versioning. For the latest available version of Honeyscanner, see page releases.

Release History

Honeyscanner does not have any release yet.

Contact

Please use Github issues to report any issues or for questions.

FAQ

In case of troubles with running python on a specific version we suggest that you install the latest version of anaconda from here and use Python3.10. If you still face problems with pipenv install, try emptying your virtualenvs folder and trying again.

License

Distributed under the MIT license. See LICENSE for more information.

honeynet/honeyscanner