In my last post, Introduction to HoneyPy & HoneyDB, I covered the basics of honeypots and provided a brief introduction to HoneyPy. In this post, I’ll walk through getting up and running with HoneyPy.

Why Run A Honeypot?

As a reminder, I would like to quickly touch on why you should even think about running a honeypot in the first place. Because I think you ought to be running honeypots if you are a researcher, “blue team” practitioner monitoring and defending a network, or a cyber security hobbyist.

As a researcher, the more data you have on malicious activity happening in the wild the more informed you will be, and you may discover something new.

As a defender, making your network as bumpy as possible increases your chances of tripping up malicious actors attempting to traverse your network. This increases the risk and costs for attackers, which in turn may cause them to think about spending their resources elsewhere, e.g. someone else’s network.

As a hobbyist, it’s just interesting and fun! It can be compared to someone on the beach going around with a metal detector, you just never know what you’re going to find.

Whichever of these scenarios you fit into, HoneyPy is a good way to get started.

Installing HoneyPy

Ok, let’s get into it. The first thing you will need is a running instance of Linux. I test and run HoneyPy on Debian Linux, but since HoneyPy is written in Python there is no reason why you can’t run HoneyPy on another Linux distributions as well. Also, I recommend creating a dedicated user account for HoneyPy just to keep things neat. One Important note, do not run HoneyPy as the root user!

Download the latest release from https://github.com/foospidy/HoneyPy/releases/latest. As of this blog post the latest release is v0.4.8, so the command to download HoneyPy is:

wget https://github.com/foospidy/HoneyPy/archive/0.4.8.tar.gz

Unzip the file with the command tar -xzf 0.4.8.tar.gz, this will create the folder HoneyPy-0.4.8. The directory can be renamed and moved to wherever you like. If you created a dedicated user account for HoneyPy, that user’s $HOME directory will work just fine.

Next, you need to address Python dependencies. Obviously, you need Python installed, and you will need pip as well. To ensure you have both, on Debian run the following commands as root (or using sudo):

apt-get install -y python-requests python-twisted python-pip
pip install twitter dnslib

For more information on HoneyPy dependencies see the ReadMe file.

That’s it, HoneyPy is installed!

Running HoneyPy

Running HoneyPy is simple, however getting everything configured properly involves a few steps but bear with me.

First, run HoneyPy with its “out-of-the-box” configuration:

python Honey.py

You will now see the HoneyPy console:

Next, at the HoneyPy console prompt type start and hit enter, and you are now running a HoneyPy honeypot!

Note: When running HoneyPy in console mode it is possible you could lose your terminal session. When the terminal session terminates so will HoneyPy. There are two options for running HonePy to prevent this from happening. The first is to use the terminal utility screen. To install screen on Debian run apt-get install screen. Alternatively, you can run HoneyPy in daemon mode using:

python Honey.py -d

The default setup is limited so there is some configuration that needs configuring :-). But before we dive into HoneyPy configuration we need to deal with running HoneyPy services on low ports. Notice the initial output above the HoneyPy banner.

Your service configuration suggests that you want to run on at least one low port!
To enable port redirection run the following ipt-kit (https://github.com/foospidy/ipt-kit) commands as root:

./ipt_set_tcp 7 10007
./ipt_set_udp 7 10007
./ipt_set_tcp 8 10008
./ipt_set_udp 8 10008
./ipt_set_tcp 23 10009
./ipt_set_tcp 24 1001

This is telling us that we have HoneyPy configured to listen on low ports (ports below 1024). A process needs root user privilege to open and listen on low ports, however, HoneyPy should be run as a non-root user. Since there are many low port services you might like to run, e.g. telnet, ftp, ssh, etc., we need a way for HoneyPy to receive connections on these ports. This can be done using iptables to enable port forwarding on a low port to a high port that HoneyPy can use.

Iptables can be complex to work with so I’ve actually published a utility called ipt-kit to help make things easier. In fact, the output noted above are the ipt-kit commands needed to configure iptables for the current HoneyPy configuration.

Below are the steps on how to use ipt-kit to configure iptables for HoneyPy. Note, modifying iptables does require root user privilege so you will need to run the ipt-kit commands as root.

1. Instead of copy/pasting the ipt-kit commands from the output noted above, HoneyPy can generate a script file for us. If you are still in the HonePy console type quit to exit. Next run:

   python Honey.py -ipt 

2. This will generate the file /tmp/honeypy-ipt.sh

   Download ipt-kit from https://github.com/foospidy/ipt-kit/archive/v1.1.tar.gz.

3. Extract ipt-kit to a directory of your choosing, tar -xzf v1.1.tar.gz.
4. Change directory to ipt-kit-v1.1 and copy honeypy-ipt.sh to the current directory cp /tmp/honeypy-ipt.sh.
5. Run the script ./honey-ipt.sh (this needs to be run wirth root privilege, so either run this as the root user or use sudo)
   Now that we’ve updated iptables we want to make sure the changes persist even if the system is rebooted, run: ./ipt-survive-reboot.sh

Configuring HoneyPy

Configuration for HoneyPy itself is very simple and straight forward. The configuration file is in <your HoneyPy directory>/etc/honeypy.cfg You can actually run HoneyPy without changing this file, but by default, events are only logged to the default log file. The default log file is not the nicest file to read, which is why HoneyPy has more useful “loggers” that can be enabled. The current set of loggers as of this blog post are:

• Twitter — Tweet events on Twitter
• HoneyDB — Post events to HoneyDB (future blog post on HoneyDB to come).
• Slack — Post events to a Slack channel.
• Log stash — Post events to log stash.
• Elastic search — Post events directly to Elasticsearch

Configuring these loggers is very easy. By reviewing the honeypy.cfg file you will find it is self-explanatory so I won’t cover it in detail here. For the loggers you want to enable you’ll need the required configuration information specified for each one. Then simply change the enabled configuration option to Yes and restart HoneyPy.

If you have ideas for additional loggers I’d love to hear about them. Also, in a later blog post I’ll describe how to create your own! And I‘m always glad to accept pull requests on Github.

Configuring HoneyPy Services

HoneyPy’s services configuration file may be more interesting to you. The file is located at <your HoneyPy directory>/etc/services.cfg, and this is the file that tells HoneyPy what services to run, and what ports to run them on. In the services.cfg file you’ll see several entries that look like the example below. Each entry represents a service that HoneyPy will launch when started.

[Echo]plugin = Echo
low_port = tcp:7
port = tcp:10007
description = Echo back data received via tcp.
enabled = Yes

The first line of this entry is [Echo], this specifies the name of the service. The name can be anything you want and will be what is displayed in downstream loggers, e.g. Twitter, HoneyDB, Elasticsearch, etc. Note, the service name must not contain spaces.

The second line, plugin, tells HoneyPy which plugin to load and use for service emulation. All available plugins live in the plugins directory and they are what emulates a service, e.g. Telnet, FTP, SSH, etc.

The third line, low_port, if the service is going to listen on a low port specify that port number here. Otherwise, the value should be the same as the next line, port. Note this also specifies the protocol for the service, tcp or udp. The format to use is <protocol>:<port number>.

The fourth line, port, this is the port HoneyPy will actually listen on. Note, this also specifies the protocol for the service, tcp or udp. The format to use is <protocol>:<port number>.

The fifth line, description is a short description of what this service does. This is more for your own reference and is currently not used anywhere else.

The final line, enabled, can have the value Yes or No, and this tells HoneyPy whether this service should be enabled or disabled at startup.

As an example, if we wanted to configure HoneyPy to listen for DNS queries we would add an entry that looks like this:

[MyDNS]plugin = Echo
low_port = udp:53
port = udp:10053
description = A very simple fake DNS listener that echoes back data from DNS queries.
enabled = Yes

If we wanted a more interactive DNS service, there is a DnsUdp plugin in the plugins folder. The configuration entry would look like this:

[MyBetterDNS]plugin = DnsUdp
low_port = udp:53
port = udp:10053
description = A low interaction DNS listener that responds to DNS queries.
enabled = Yes

I hope this gives you a good idea of how HoneyPy can be configured to start services of different types. With this configurability you can create a honeypot that listens on any number of service ports that you want. For each service, you can decide what plugin is behind it. For more information on the plugins visit the HoneyPy wiki page on Github.

Conclusion

We covered a lot of ground in this post. There is more to cover in subsequent posts, but for now, you should have the foundational understanding of how startup a HoneyPy honeypot. Keep an eye out for the next post as I’ll cover more on services and service profiles.

In the next post, I’ll cover more on services and service profiles.
Guide To HoneyPy: Part 2
Guide To HoneyPy: Part 3

 

---

Thanks for Reading

At Signal Sciences we provide a modern approach to application security and web application firewalls. We also have a resource we provide for those doing security in the modern era of DevOps.