cowrie/INSTALL.md

Installing Cowrie in seven steps.

• Install with systemd support
  • Step 1: Install dependencies
  • Step 2: Create a user account
  • Step 3: Checkout the code
  • Step 4: Setup Virtual Environment
  • Step 5: Create folders and fix permissions
  • Step 6: Install systemd, rsyslog and logrotate configurations
  • Step 7: Install cowrie configuration file
  • Step 8: Starting Cowrie
  • Step 9: Capture traffic
• Install without systemd support
  • Step 1: Install dependencies
  • Step 2: Create a user account
  • Step 3: Checkout the code
  • Step 4: Setup Virtual Environment
  • Step 5: Install configuration file
  • Step 6: Generate a DSA key (OPTIONAL)
  • Step 7: Fixing permissions
  • Step 8: Starting Cowrie
  • Step 9: Port redirection
• Optional settings
  • Running within supervisord (OPTIONAL)
  • Configure Additional Output Plugins (OPTIONAL)
• Troubleshooting

Install with systemd support

This chapter explains how to install Cowrie to your system when you can and should use systemd.

Supported systems are:

• Debian 9 alias Stretch and higher
• Ubuntu 18.04 alias Bionic Beaver and higher

Note: All commands are run as root.

Step 1: Install dependencies

First install system-wide support for Python virtual environments and other dependencies. Actual Python packages are installed later.

On Debian based systems:

$ apt install git python-virtualenv libssl-dev libffi-dev build-essential libpython-dev python2.7-minimal

Step 2: Create a user account

It's strongly recommended to run with a dedicated non-root user id:

$ useradd -r -s /bin/false -U -M cowrie

Step 3: Checkout the code

$ git clone http://github.com/micheloosterhof/cowrie /opt/cowrie

Step 4: Setup Virtual Environment

Next create your virtual environment:

$ virtualenv /opt/cowrie-env

Alternatively, create a Python3 virtual environment (under development)

$ virtualenv --python=python3 /opt/cowrie-env

Activate the virtual environment and install packages

$ source /opt/cowrie-env/bin/activate
(cowrie-env) $ pip install --upgrade pip
(cowrie-env) $ pip install --upgrade -r /opt/cowrie/requirements.txt
(cowrie-env) $ deactivate

Step 5: Create folders and fix permissions

Nothing should be written into /opt/cowrie. However some parts still do this or don't have a proper setup routine to be created when the service is started the first time. So we need to fix this by hand.

$ chown root:cowrie /opt/cowrie/data
$ chmod 0775 /opt/cowrie/data
$ mkdir -p /var/lib/cowrie/{downloads,tty}
$ chmod -R cowrie:cowrie /var/lib/cowrie

Step 6: Install systemd, rsyslog and logrotate configurations

This will prepare your system to run cowrie with systemd, collect all logs to /var/log/cowrie and having logrotate taking care of it.

$ cp /opt/cowrie/doc/systemd/etc/logrotate.d/cowrie /etc/logrotate.d
$ cp /opt/cowrie/doc/systemd/etc/rsyslog.d/cowrie.conf /etc/rsyslog.d
$ cp /opt/cowrie/doc/systemd/etc/systemd/system/* /etc/systemd/system

Step 7: Install cowrie configurations file

The configuration for Cowrie is stored in cowrie.cfg.dist and cowrie.cfg. Both files are read on startup, where entries from cowrie.cfg take precedence. The .dist file can be overwritten by upgrades, cowrie.cfg will not be touched. To run with a standard configuration, there is no need to change anything. The version below is prepared to run with systemd:

$ cp /opt/cowrie/doc/systemd/cowrie.cfg /opt/cowrie

To enable Telnet modify /opt/cowrie/cowrie.cfg

[telnet]
enabled = true

And enable the socket in /etc/systemd/system/cowrie.socket

ListenStream=2223

Step 8: Starting Cowrie

First we need to reload some other services. This is only needed when something in the config files changed.

$ systemctl enable cowrie.socket
$ systemctl enable cowrie.service
$ systemctl daemon-reload
$ systemctl restart rsyslog.service
$ systemctl restart logrotate.service

And now we can start cowrie

$ systemctl start cowrie.service

Step 9: Capture traffic

To capture now traffic we have two options:

1. running cowrie on port 22 (recommended)
2. redirecting traffic with iptables

Running on port 22

First you need to mofiy your sshd to listen on another port then 22. Modify /etc/ssh/sshd_config and set the Port variable to a port you like. Then modify /etc/systemd/system/cowrie.socket and set

ListenStream=22

Note: It's very important that this is the first ListenStream. Otherwise you might end up mixing SSH and Telnet traffic

Now let's activate our changes. After reloading the ssh daemon you might be disconnected from your machine which is okay since we changed the port. Just reconnect with the new port and go on.

$ systemctl daemon-reload
$ systemctl restart ssh.service
$ systemctl restart cowrie.service

Redirecting traffic

All port redirection commands are system-wide and need to be executed as root.

Cowrie runs by default on port 2222. This can be modified in the configuration file. The following firewall rule will forward incoming traffic on port 22 to port 2222.

Note: Before setting this rule you will need to reconfigure your ssh daemon to listen on another port or to allow in iptables that your IP can bypass this rule. If not you will not be able to login into your machine without rebooting it!

$ sudo iptables -t nat -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 2222

Install without systemd support

This chapter explains how to install cowrie on systems where you don't have systemd support.

Note: All commands are run with root

Step 1: Install dependencies

First we install system-wide support for Python virtual environments and other dependencies. Actual Python packages are installed later.

On Debian based systems (last verified on Debian 9, 2017-07-25):

$ apt-get install git python-virtualenv libssl-dev libffi-dev build-essential libpython-dev python2.7-minimal

Step 2: Create a user account

It's strongly recommended to run with a dedicated non-root user id:

$ useradd -r -s /bin/bash -U -M cowrie

Step 3: Checkout the code

$ git clone http://github.com/micheloosterhof/cowrie /opt/cowrie

Step 4: Setup Virtual Environment

Next you need to create your virtual environment:

$ virtualenv /opt/cowrie/cowrie-env

Alternatively, create a Python3 virtual environment (under development)

$ virtualenv --python=python3 /opt/cowrie-env

Activate the virtual environment and install packages

$ source /opt/cowrie/cowrie-env/bin/activate
(cowrie-env) $ pip install --upgrade pip
(cowrie-env) $ pip install --upgrade -r /opt/cowrie/requirements.txt
(cowrie-env) $ deactivate

Step 5: Install configuration file

The configuration for Cowrie is stored in cowrie.cfg.dist and cowrie.cfg. Both files are read on startup, where entries from cowrie.cfg take precedence. The .dist file can be overwritten by upgrades, cowrie.cfg will not be touched. To run with a standard configuration, there is no need to change anything. To enable telnet, for example, create cowrie.cfg and input only the following:

[telnet]
enabled = true

Step 6: Generate a DSA key (OPTIONAL)

This step should not be necessary, however some versions of Twisted are not compatible. To avoid problems in advance, run:

$ cd /opt/cowrie/data
$ ssh-keygen -t dsa -b 1024 -f ssh_host_dsa_key

7 Fixing permissions

Cowrie runs with its own system user but we still need to be able to read/write into some directories

$ chown -R cowrie:cowrie /opt/cowrie/var
$ chown -R cowrie:cowrie /opt/cowrie/log
$ chown cowrie:cowrie /opt/cowrie/dl
$ chown root:cowrie /opt/cowrie/data
$ chmod 775 /opt/cowrie/data

Note: You will need to fix this permissions after you upgraded your cowrie from git.

Step 8: Starting Cowrie

Start Cowrie with the cowrie command. You can add the cowrie/bin directory to your path if desired. An existing virtual environment is preserved if activated, otherwise Cowrie will attempt to load the environment called "cowrie-env"

$ su cowrie -c '/opt/cowrie/bin/cowrie start'

Step 9: Port redirection

All port redirection commands are system-wide and need to be executed as root.

Cowrie runs by default on port 2222. This can be modified in the configuration file. The following firewall rule will forward incoming traffic on port 22 to port 2222.

Note: Before setting this rule you will need to reconfigure your ssh daemon to listen on another port or to allow in iptables that your IP can bypass this rule. If not you will not be able to login into your machine without rebooting it!

$ sudo iptables -t nat -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 2222

Note that you should test this rule only from another host; it doesn't apply to loopback connections. Alternatively you can run authbind to listen as non-root on port 22 directly:

$ sudo apt-get install authbind
$ sudo touch /etc/authbind/byport/22
$ sudo chown cowrie:cowrie /etc/authbind/byport/22
$ sudo chmod 770 /etc/authbind/byport/22

Or for telnet:

$ apt-get install authbind
$ sudo touch /etc/authbind/byport/23
$ sudo chown cowrie:cowrie /etc/authbind/byport/23
$ sudo chmod 770 /etc/authbind/byport/23

Edit bin/cowrie and modify the AUTHBIND_ENABLED setting Change listen_port to 22 in cowrie.cfg

Optional settings

Running using Supervisord

Note: This is not needed for systems with systemd.

On Debian, put the below in /etc/supervisor/conf.d/cowrie.conf

[program:cowrie]
command=/home/cowrie/cowrie/bin/cowrie start
directory=/home/cowrie/cowrie/
user=cowrie
autorestart=true
redirect_stderr=true

Update the bin/cowrie script, change:

DAEMONIZE=""

to:

DAEMONIZE="-n"

Configure Additional Output Plugins

Cowrie automatically outputs event data to text and JSON log files in ~/cowrie/log. Additional output plugins can be configured to record the data other ways. Supported output plugins include:

• Cuckoo
• ELK (Elastic) Stack
• Graylog
• Kippo-Graph
• Splunk
• SQL (MySQL, SQLite3, RethinkDB)

See ~/cowrie/doc/[Output Plugin]/README.md for details.

Troubleshooting

• If you see twistd: Unknown command: cowrie there are two possibilities. If there's a python stack trace, it probably means there's a missing or broken dependency. If there's no stack trace, double check that your PYTHONPATH is set to the source code directory.
• Default file permissions

To make Cowrie logfiles public readable, change the --umask 0077 option in start.sh into --umask 0022

Updating Cowrie

Updating is an easy process. First stop your honeypot. Then fetch updates from GitHub, as a next step upgrade your Python dependencies.

bin/cowrie stop
git pull
pip install --upgrade -r requirements.txt
bin/cowrie start

Modifying Cowrie

The pre-login banner can be set by creating the file honeyfs/etc/issue.net. The post-login banner can be customized by editing honeyfs/etc/motd.