diff --git a/.gitignore b/.gitignore index 5616def0..a6ac2603 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ var/log/cowrie/* cowrie.egg-info/ dl/ dist/ +docs/_build build/ log/ __pycache__/ diff --git a/.travis.yml b/.travis.yml index 37f8512a..6c11c3f4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -14,10 +14,11 @@ before_install: - sudo apt-get -qq update install: pip install -r requirements.txt before_script: - - pip install flake8 flake8-import-order + - pip install flake8 flake8-import-order Sphinx # stop the build if there are Python syntax errors or undefined names - flake8 --count --application-import-names cowrie --max-line-length=120 --statistics . - python setup.py build sdist bdist + - make -C docs html script: - PYTHONPATH=${TRAVIS_BUILD_DIR}/src trial cowrie notifications: diff --git a/CHANGELOG.md b/CHANGELOG.rst similarity index 99% rename from CHANGELOG.md rename to CHANGELOG.rst index f9adb6f4..125d9b86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.rst @@ -1,5 +1,6 @@ Release 1.5.2 +============= * 2018-11-19 Fix tftp exception and tftp test * 2018-11-14 Remove `dblog` mechanism and `splunk` legacy output plugin. @@ -9,6 +10,7 @@ Release 1.5.2 * 2018-10-16 Save VT results to JSON log Release 1.5.1 +============= * 2018-10-13 Fixes VT uploads, tab completion on Python3, Hassh support, setuptools functional. userdb migration * 2018-09-07 NOTE! data/userdb.txt has moved to etc/userdb.txt and a default config is no longer provided! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.rst similarity index 61% rename from CONTRIBUTING.md rename to CONTRIBUTING.rst index 68460b98..b60a4b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.rst @@ -1,16 +1,18 @@ -# Contributing Guidelines +Contributing Guidelines +####################### -Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional +Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community. -Please read through this document before submitting any issues or pull requests to ensure we have all the necessary +Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution. -## Reporting Bugs/Feature Requests +Reporting Bugs/Feature Requests +############################### We welcome you to use the GitHub issue tracker to report bugs or suggest features. -When filing an issue, please check [existing open](https://github.com/cowrie/cowrie), or [recently closed](https://github.com/cowrie/cowrie/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already +When filing an issue, please check `existing open `_, or `recently closed `_, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: * A reproducible test case or series of steps @@ -19,7 +21,8 @@ reported the issue. Please try to include as much information as you can. Detail * Anything unusual about your environment or deployment -## Contributing via Pull Requests +Contributing via Pull Requests +############################## Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: 1. You are working against the latest source on the *master* branch. @@ -35,14 +38,16 @@ To send us a pull request, please: 5. Send us a pull request, answering any default questions in the pull request interface. 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. -GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and -[creating a pull request](https://help.github.com/articles/creating-a-pull-request/). +GitHub provides additional document on `forking a repository `_ and +`creating a pull request `_. -## Finding contributions to work on -Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/cowrie/cowrie/labels/help%20wanted) issues is a great place to start. +Finding contributions to work on +################################ +Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any `help wanted' `_ issues is a great place to start. -## Licensing -See the [LICENSE](https://github.com/cowrie/cowrie/blob/master/LICENSE.md) file for our project's licensing. We will ask you confirm the licensing of your contribution. +Licensing +######### +See the `LICENSE `_ file for our project's licensing. We will ask you confirm the licensing of your contribution. diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index d26a2a6f..00000000 --- a/INSTALL.md +++ /dev/null @@ -1,246 +0,0 @@ - -# Installing Cowrie in seven steps. - -* [Step 1: Install dependencies](#step-1-install-dependencies) -* [Step 2: Create a user account](#step-2-create-a-user-account) -* [Step 3: Checkout the code](#step-3-checkout-the-code) -* [Step 4: Setup Virtual Environment](#step-4-setup-virtual-environment) -* [Step 5: Install configuration file](#step-5-install-configuration-file) -* [Step 6: Generate a DSA key (OPTIONAL)](#step-6-generate-a-dsa-key) -* [Step 7: Starting Cowrie](#step-7-turning-on-cowrie) -* [Step 8: Port redirection (OPTIONAL)](#step-8-port-redirection-optional) -* [Running within supervisord (OPTIONAL)](#running-using-supervisord) -* [Configure Additional Output Plugins (OPTIONAL)](#configure-additional-output-plugins-optional) -* [Troubleshooting](#troubleshooting) - -## 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): -For a Python3 based environment: -``` -$ sudo apt-get install git python-virtualenv libssl-dev libffi-dev build-essential libpython3-dev python3-minimal authbind -``` -Or for Python2: -``` -$ sudo apt-get install git python-virtualenv libssl-dev libffi-dev build-essential libpython-dev python2.7-minimal authbind -``` - -## Step 2: Create a user account - -It's strongly recommended to run with a dedicated non-root user id: - -``` -$ sudo adduser --disabled-password cowrie -Adding user `cowrie' ... -Adding new group `cowrie' (1002) ... -Adding new user `cowrie' (1002) with group `cowrie' ... -Changing the user information for cowrie -Enter the new value, or press ENTER for the default -Full Name []: -Room Number []: -Work Phone []: -Home Phone []: -Other []: -Is the information correct? [Y/n] - -$ sudo su - cowrie -``` - -## Step 3: Checkout the code - -``` -$ git clone http://github.com/cowrie/cowrie -Cloning into 'cowrie'... -remote: Counting objects: 2965, done. -remote: Compressing objects: 100% (1025/1025), done. -remote: Total 2965 (delta 1908), reused 2962 (delta 1905), pack-reused 0 -Receiving objects: 100% (2965/2965), 3.41 MiB | 2.57 MiB/s, done. -Resolving deltas: 100% (1908/1908), done. -Checking connectivity... done. - -$ cd cowrie -``` - -## Step 4: Setup Virtual Environment - -Next you need to create your virtual environment: - -``` -$ pwd -/home/cowrie/cowrie -$ virtualenv --python=python3 cowrie-env -New python executable in ./cowrie/cowrie-env/bin/python -Installing setuptools, pip, wheel...done. -``` - -Alternatively, create a Python2 virtual environment -``` -$ virtualenv --python=python2 cowrie-env -New python executable in ./cowrie/cowrie-env/bin/python -Installing setuptools, pip, wheel...done. -``` - -Activate the virtual environment and install packages - -``` -$ source cowrie-env/bin/activate - -(cowrie-env) $ pip install --upgrade pip - -(cowrie-env) $ pip install --upgrade -r requirements.txt -``` - -## 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 data -$ ssh-keygen -t dsa -b 1024 -f ssh_host_dsa_key -$ cd .. -``` - -## Step 7: 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" - -``` -$ bin/cowrie start -Activating virtualenv "cowrie-env" -Starting cowrie with extra arguments [] ... -``` - -## Step 8: Port redirection (OPTIONAL) - -All port redirection commands are system-wide and need to be executed as root. -A firewall redirect can make your existing SSH server unreachable, remember to move the existing -server to a different port number first. - -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 on Linux: - -``` -$ 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. - -On MacOS run: - -``` -$ echo "rdr pass inet proto tcp from any to any port 22 -> 127.0.0.1 port 2222" | sudo pfctl -ef - -``` - -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 -``` -* Edit bin/cowrie and modify the AUTHBIND_ENABLED setting -* Change listen_port to 22 in cowrie.cfg - -Or for telnet: -``` -$ sudo iptables -t nat -A PREROUTING -p tcp --dport 23 -j REDIRECT --to-port 2223 -``` -with authbind: -``` -$ 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 -``` - -## Running using Supervisord (OPTIONAL) - -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 (OPTIONAL) - -Cowrie automatically outputs event data to text and JSON log files -in `var/log/cowrie`. 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/docs/[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, and upgrade your Python dependencies. -``` -bin/cowrie stop -git pull -pip install --upgrade -r requirements.txt -``` - -If you use output plugins like SQL, Splunk, or ELK, remember to also upgrade your dependencies for these too. -``` -pip install --upgrade -r requirements-output.txt -``` - -And finally, start Cowrie back up after finishing all updates. -``` -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`. diff --git a/INSTALL.rst b/INSTALL.rst new file mode 100644 index 00000000..447be781 --- /dev/null +++ b/INSTALL.rst @@ -0,0 +1,226 @@ + +Installing Cowrie in seven steps. +################################# + +* [Step 1: Install dependencies](#step-1-install-dependencies) +* [Step 2: Create a user account](#step-2-create-a-user-account) +* [Step 3: Checkout the code](#step-3-checkout-the-code) +* [Step 4: Setup Virtual Environment](#step-4-setup-virtual-environment) +* [Step 5: Install configuration file](#step-5-install-configuration-file) +* [Step 6: Generate a DSA key (OPTIONAL)](#step-6-generate-a-dsa-key) +* [Step 7: Starting Cowrie](#step-7-turning-on-cowrie) +* [Step 8: Port redirection (OPTIONAL)](#step-8-port-redirection-optional) +* [Running within supervisord (OPTIONAL)](#running-using-supervisord) +* [Configure Additional Output Plugins (OPTIONAL)](#configure-additional-output-plugins-optional) +* [Troubleshooting](#troubleshooting) + +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): +For a Python3 based environment:: + + $ sudo apt-get install git python-virtualenv libssl-dev libffi-dev build-essential libpython3-dev python3-minimal authbind + +Or for Python2:: + + $ sudo apt-get install git python-virtualenv libssl-dev libffi-dev build-essential libpython-dev python2.7-minimal authbind + +Step 2: Create a user account +***************************** + +It's strongly recommended to run with a dedicated non-root user id:: + + $ sudo adduser --disabled-password cowrie + Adding user 'cowrie' ... + Adding new group 'cowrie' (1002) ... + Adding new user 'cowrie' (1002) with group 'cowrie' ... + Changing the user information for cowrie + Enter the new value, or press ENTER for the default + Full Name []: + Room Number []: + Work Phone []: + Home Phone []: + Other []: + Is the information correct? [Y/n] + + $ sudo su - cowrie + +Step 3: Checkout the code +***************************** + +Check out the code:: + + $ git clone http://github.com/cowrie/cowrie + Cloning into 'cowrie'... + remote: Counting objects: 2965, done. + remote: Compressing objects: 100% (1025/1025), done. + remote: Total 2965 (delta 1908), reused 2962 (delta 1905), pack-reused 0 + Receiving objects: 100% (2965/2965), 3.41 MiB | 2.57 MiB/s, done. + Resolving deltas: 100% (1908/1908), done. + Checking connectivity... done. + + $ cd cowrie + +## Step 4: Setup Virtual Environment +************************************ + +Next you need to create your virtual environment:: + + $ pwd + /home/cowrie/cowrie + $ virtualenv --python=python3 cowrie-env + New python executable in ./cowrie/cowrie-env/bin/python + Installing setuptools, pip, wheel...done. + +Alternatively, create a Python2 virtual environment:: + + $ virtualenv --python=python2 cowrie-env + New python executable in ./cowrie/cowrie-env/bin/python + Installing setuptools, pip, wheel...done. + +Activate the virtual environment and install packages:: + + + $ source cowrie-env/bin/activate + (cowrie-env) $ pip install --upgrade pip + (cowrie-env) $ pip install --upgrade -r requirements.txt + +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: 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":: + + + $ bin/cowrie start + Activating virtualenv "cowrie-env" + Starting cowrie with extra arguments [] ... + +Step 7: Port redirection (OPTIONAL) +*********************************** + +All port redirection commands are system-wide and need to be executed as root. +A firewall redirect can make your existing SSH server unreachable, remember to move the existing +server to a different port number first. + +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 on Linux:: + + $ 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. + +On MacOS run:: + + $ echo "rdr pass inet proto tcp from any to any port 22 -> 127.0.0.1 port 2222" | sudo pfctl -ef - + +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 + +* Edit bin/cowrie and modify the AUTHBIND_ENABLED setting +* Change listen_port to 22 in cowrie.cfg + +Or for telnet:: + + $ sudo iptables -t nat -A PREROUTING -p tcp --dport 23 -j REDIRECT --to-port 2223 + +with authbind:: + + $ 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 + +Running using Supervisord (OPTIONAL) +************************************ + +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 (OPTIONAL) +********************************************** + +Cowrie automatically outputs event data to text and JSON log files +in `var/log/cowrie`. 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/docs/[Output Plugin]/README.rst 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, and upgrade your Python dependencies:: + + bin/cowrie stop + git pull + pip install --upgrade -r requirements.txt + +If you use output plugins like SQL, Splunk, or ELK, remember to also upgrade your dependencies for these too:: + + pip install --upgrade -r requirements-output.txt + +And finally, start Cowrie back up after finishing all updates:: + + 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`. diff --git a/LICENSE.md b/LICENSE.rst similarity index 94% rename from LICENSE.md rename to LICENSE.rst index 2e9914e7..e67e184d 100644 --- a/LICENSE.md +++ b/LICENSE.rst @@ -1,3 +1,6 @@ +LICENSE +####### + Copyright (c) 2009 Upi Tamminen All rights reserved. @@ -13,7 +16,7 @@ are met: products derived from this software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR +THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, diff --git a/README.md b/README.rst similarity index 61% rename from README.md rename to README.rst index e5741639..7714784c 100644 --- a/README.md +++ b/README.rst @@ -1,50 +1,58 @@ Cowrie -====== +###### -![Travis CI Status](https://travis-ci.org/cowrie/cowrie.svg?branch=master "Travis CI Status") +|travis|_ +|codecov|_ -# Welcome to the Cowrie GitHub repository +Welcome to the Cowrie GitHub repository +***************************************** This is the official repository for the Cowrie SSH and Telnet Honeypot effort. -# What is Cowrie +What is Cowrie +***************************************** Cowrie is a medium interaction SSH and Telnet honeypot designed to log brute force attacks and the shell interaction performed by the attacker. -[Cowrie](http://github.com/cowrie/cowrie/) is developed by Michel Oosterhof. +`Cowrie `_ is developed by Michel Oosterhof. -## Slack +Slack +***************************************** -You can join the Cowrie community at the following [Slack workspace](http://bit.ly/cowrieslack) +You can join the Cowrie community at the following `Slack workspace `_. -## Features +Features +***************************************** Some interesting features: * Fake filesystem with the ability to add/remove files. A full fake filesystem resembling a Debian 5.0 installation is included * Possibility of adding fake file contents so the attacker can `cat` files such as `/etc/passwd`. Only minimal file contents are included -* Session logs are stored in an [UML Compatible](http://user-mode-linux.sourceforge.net/) format for easy replay with original timings with the `bin/playlog` utility. -* Cowrie saves files downloaded with wget/curl or uploaded with SFTP and scp for later inspection -log +* Session logs are stored in an `UML Compatible `_ format for easy replay with original timings with the `bin/playlog` utility. +* Cowrie saves files downloaded with wget/curl or uploaded with SFTP and scp for later inspection log + Additional functionality over standard kippo: * SFTP and SCP support for file upload * Support for SSH exec commands * Logging of direct-tcp connection attempts (ssh proxying) -* Forward SMTP connections to SMTP Honeypot (e.g. [mailoney](https://github.com/awhitehatter/mailoney)) +* Forward SMTP connections to SMTP Honeypot (e.g. `mailoney `_) * Logging in JSON format for easy processing in log management solutions * Many, many additional commands -## Docker +Docker +***************************************** Docker versions are available. -* Get the Dockerfile directly at https://github.com/cowrie/docker-cowrie -* Run from Docker Hub with: ```docker pull cowrie/cowrie``` -## Requirements +* Run from Docker Hub with: ``docker pull cowrie/cowrie`` +* Or get the Dockerfile directly at https://github.com/cowrie/docker-cowrie + +Requirements +***************************************** Software required: @@ -53,7 +61,8 @@ Software required: For Python dependencies, see requirements.txt -## Files of interest: +Files of interest: +***************************************** * `cowrie.cfg` - Cowrie's configuration file. Default values can be found in `etc/cowrie.cfg.dist` * `share/cowrie/fs.pickle` - fake filesystem @@ -69,15 +78,13 @@ For Python dependencies, see requirements.txt * `bin/createfs` - used to create the fake filesystem * `bin/playlog` - utility to replay session logs -## Is it secure? +I have some questions! +***************************************** -Maybe. See [FAQ](https://github.com/cowrie/cowrie/wiki/Frequently-Asked-Questions) +Please visit the `Slack workspace `_ and join the #questions channel. -## I have some questions! - -Please visit https://cowrie.slack.com/ and join the #questions channel - -## Contributors +Contributors +*************** Many people have contributed to Cowrie over the years. Special thanks to: @@ -88,3 +95,9 @@ Many people have contributed to Cowrie over the years. Special thanks to: * Florian Pelgrim (craneworks) for his work on code cleanup and Docker. * And many many others. + +.. |travis| image:: https://travis-ci.org/cowrie/cowrie.svg?branch=master +.. _travis: https://travis-ci.org/cowrie/cowrie + +.. |codecov| image:: https://codecov.io/gh/cowrie/cowrie/branch/master/graph/badge.svg +.. _codecov: https://codecov.io/gh/cowrie/cowrie diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..bd9489cf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,23 @@ +# Minimal makefile for Sphinx documentation +# + +# Expand PYTHONPATH so we can import Cowrie version +#export PYTHONPATH := $(PYTHONPATH):../src + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = PYTHONPATH="../src" sphinx-build +SOURCEDIR = . +BUILDDIR = _build + + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..baf70f85 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,191 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +# The Makefile sets PYTHONPATH so this module is available +from cowrie import version as cowrie_version_object + +# -- Project information ----------------------------------------------------- + +project = 'cowrie' +copyright = '2018, Michel Oosterhof' +author = 'Michel Oosterhof' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = "{major}.{minor}".format(major=cowrie_version_object.major, + minor=cowrie_version_object.minor) +# The full version, including alpha/beta/rc tags. +release = cowrie_version_object.short() + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.doctest', + 'sphinx.ext.githubpages', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'cowriedoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'cowrie.tex', 'cowrie Documentation', + 'Michel Oosterhof', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'cowrie', 'cowrie Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'cowrie', 'cowrie Documentation', + author, 'cowrie', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/elk/README.md b/docs/elk/README.md deleted file mode 100644 index e14d8a27..00000000 --- a/docs/elk/README.md +++ /dev/null @@ -1,167 +0,0 @@ -# How to process Cowrie output in an ELK stack - -(Note: work in progress, instructions are not verified) - - -## Prerequisites - -* Working Cowrie installation -* Cowrie JSON log file (enable database json in cowrie.cfg) -* Java 8 - -## Installation - - -We'll examine simple installation, when we install ELK stack on the same machine that used for cowrie. - -* Add Elastic's repository and key -``` -wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add - -echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list -apt-get update -``` - -* Install logstash, elasticsearch and kibana - -``` -sudo apt-get install elasticsearch logstash kibana -``` - -* Set them to autostart -``` -sudo update-rc.d elasticsearch defaults 95 10 -sudo update-rc.d kibana defaults 95 10 -``` - -## ElasticSearch Configuration - -TBD - -## Kibana Configuration - -* Make a folder for logs - -``` -sudo mkdir /var/log/kibana -sudo chown kibana:kibana /var/log/kibana -``` - -* Change the following parameters in `/etc/kibana/kibana.yml` to reflect your server setup: - -``` -"server.host" - set it to "localhost" if you use nginx for basic authentication or external interface if you use XPack (see below) -"server.name" - name of the server -"elasticsearch.url" - address of the elasticsearch -"elasticsearch.username", "elasticsearch.password" - needed only if you use XPack (see below) -"logging.dest" - set path to logs (/var/log/kibana/kibana.log) -``` - -* Make sure the file `/etc/kibana/kibana.yml` contains a line like - -``` -tilemap.url: https://tiles.elastic.co/v2/default/{z}/{x}/{y}.png?elastic_tile_service_tos=agree&my_app_name=kibana -``` -or your map visualizations won't have any background. When this file is created during the installation -of Kibana, it does _not_ contain such a line, not even in commented out form. - -## Logstash Configuration - -* Download GeoIP data - -``` -wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz -``` - -* Place these somewhere in your filesystem and make sure that "logstash" user can read it - -``` -sudo mkdir -p /var/opt/logstash/vendor/geoip/ -sudo mv GeoLite2-City.mmdb /var/opt/logstash/vendor/geoip -``` - -* Configure logstash - -``` -sudo cp logstash-cowrie.conf /etc/logstash/conf.d -``` - -* Make sure the configuration file is correct. Check the input section (path), filter (geoip databases) and output (elasticsearch hostname) - -``` -sudo service logstash restart -``` - -* By default the logstash is creating debug logs in /tmp. - -* To test whether logstash is working correctly, check the file in /tmp - -``` -tail /tmp/cowrie-logstash.log -``` - -* To test whether data is loaded into ElasticSearch, run the following query: - -``` -curl 'http://:9200/_search?q=cowrie&size=5' -``` - -(Replace `` with the name or IP address of the machine on which ElasticSearch is running, e.g., `localhost`.) - -* If this gives output, your data is correctly loaded into ElasticSearch - -* When you successfully configured logstash, remove "file" and "stdout" blocks from output section of logstash configuration. - -## Distributed setup of sensors or multiple sensors on the same host - - If you have multiple sensors, you will need to setup up FileBeat to feed logstash with logs from all sensors - - On the logstash server: - - * Change "input" section of the logstash to the following: - - ``` - input { - beats { - port => 5044 - } - } - ``` - - On the sensor servers: - - * Install filebeat - ``` - wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add - - echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list - sudo apt-get update - sudo apt-get install filebeat - ``` - - * Enable autorun for it - ``` - sudo update-rc.d filebeat defaults 95 10 - ``` - - * Configure filebeat - - ``` - sudo cp filebeat-cowrie.conf /etc/filebeat/filebeat.yml - ``` - - * Check the following parameters - ``` - paths - path to cowrie's json logs - logstash - check ip of the logstash host - ``` - - * Start filebeat - - ``` - sudo service filebeat start - ``` - -## Tuning ELK stack - -* Refer to elastic's documentation about proper configuration of the system for the best elasticsearch's performance - -* You may avoid installing nginx for restricting access to kibana by installing official elastic's plugin called "X-Pack" (https://www.elastic.co/products/x-pack) \ No newline at end of file diff --git a/docs/elk/README.rst b/docs/elk/README.rst new file mode 100644 index 00000000..94101993 --- /dev/null +++ b/docs/elk/README.rst @@ -0,0 +1,145 @@ +How to process Cowrie output in an ELK stack +############################################# + +(Note: work in progress, instructions are not verified) + + +Prerequisites +================ + +* Working Cowrie installation +* Cowrie JSON log file (enable database json in cowrie.cfg) +* Java 8 + +Installation +================ + + +We'll examine simple installation, when we install ELK stack on the same machine that used for cowrie. + +Add Elastic's repository and key:: + + wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add - + echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list + apt-get update + +Install logstash, elasticsearch and kibana:: + + sudo apt-get install elasticsearch logstash kibana + +Set them to autostart:: + + sudo update-rc.d elasticsearch defaults 95 10 + sudo update-rc.d kibana defaults 95 10 + +ElasticSearch Configuration +============================= + +TBD + +Kibana Configuration +============================= + +Make a folder for logs:: + + sudo mkdir /var/log/kibana + sudo chown kibana:kibana /var/log/kibana + +Change the following parameters in `/etc/kibana/kibana.yml` to reflect your server setup:: + + "server.host" - set it to "localhost" if you use nginx for basic authentication or external interface if you use XPack (see below) + "server.name" - name of the server + "elasticsearch.url" - address of the elasticsearch + "elasticsearch.username", "elasticsearch.password" - needed only if you use XPack (see below) + "logging.dest" - set path to logs (/var/log/kibana/kibana.log) + +Make sure the file `/etc/kibana/kibana.yml` contains a line like:: + + tilemap.url: https://tiles.elastic.co/v2/default/{z}/{x}/{y}.png?elastic_tile_service_tos=agree&my_app_name=kibana + +or your map visualizations won't have any background. When this file is created during the installation +of Kibana, it does _not_ contain such a line, not even in commented out form. + +Logstash Configuration +============================= + +Download GeoIP data:: + + wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz + +Place these somewhere in your filesystem and make sure that "logstash" user can read it:: + + sudo mkdir -p /var/opt/logstash/vendor/geoip/ + sudo mv GeoLite2-City.mmdb /var/opt/logstash/vendor/geoip + +Configure logstash:: + + sudo cp logstash-cowrie.conf /etc/logstash/conf.d + +Make sure the configuration file is correct. Check the input section (path), filter (geoip databases) and output (elasticsearch hostname):: + + sudo service logstash restart + +By default the logstash is creating debug logs in /tmp. + +To test whether logstash is working correctly, check the file in /tmp:: + + tail /tmp/cowrie-logstash.log + +To test whether data is loaded into ElasticSearch, run the following query:: + + curl 'http://:9200/_search?q=cowrie&size=5' + +(Replace `` with the name or IP address of the machine on which ElasticSearch is running, e.g., `localhost`.) + +If this gives output, your data is correctly loaded into ElasticSearch + +When you successfully configured logstash, remove "file" and "stdout" blocks from output section of logstash configuration. + +Distributed setup of sensors or multiple sensors on the same host +================================================================================ + +If you have multiple sensors, you will need to setup up FileBeat to feed logstash with logs from all sensors + +On the logstash server: + +Change "input" section of the logstash to the following:: + + input { + beats { + port => 5044 + } + } + +On the sensor servers: + +Install filebeat:: + + wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add - + echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list + sudo apt-get update + sudo apt-get install filebeat + +Enable autorun for it:: + + sudo update-rc.d filebeat defaults 95 10 + +Configure filebeat:: + + sudo cp filebeat-cowrie.conf /etc/filebeat/filebeat.yml + +Check the following parameters:: + + paths - path to cowrie's json logs + logstash - check ip of the logstash host + +Start filebeat:: + + sudo service filebeat start + +Tuning ELK stack +================== + +Refer to elastic's documentation about proper configuration of the system for the best elasticsearch's performance + +You may avoid installing nginx for restricting access to kibana by installing official elastic's plugin called "X-Pack" (https://www.elastic.co/products/stack) diff --git a/docs/graylog/README.md b/docs/graylog/README.md deleted file mode 100644 index 397f2f25..00000000 --- a/docs/graylog/README.md +++ /dev/null @@ -1,55 +0,0 @@ -# How to process Cowrie output into Graylog - - -## Prerequisites - -* Working Cowrie installation -* Working Graylog installation - -## Cowrie Configuration - - -* Open the Cowrie configuration file and uncomment these 3 lines. - -``` -[output_localsyslog] -facility = USER -format = text -``` - -* Restart Cowrie - -## Graylog Configuration - -* Open the Graylog web interface and click on the **System** drop-down in the top menu. From the drop-down menu select **Inputs**. Select **Syslog UDP** from the drop-down menu and click the **Launch new input** button. In the modal dialog enter the following information. - -**Title:** Cowrie -**Port:** 8514 -**Bind address:** 127.0.0.1 - -* Then click **Launch.** - -## Syslog Configuration - -* Create a rsyslog configuration file in /etc/rsyslog.d - -``` -$ sudo nano /etc/rsyslog.d/85-graylog.conf -``` - -* Add the following lines to the file - -``` -$template GRAYLOGRFC5424,"<%pri%>%protocol-version% %timestamp:::date-rfc3339% %HOSTNAME% %app-name% %procid% %msg%\n" -*.* @127.0.0.1:8514;GRAYLOGRFC5424 -``` - -* Save and quit. - -* Restart rsyslog - -``` -$ sudo service rsyslog restart -``` - - diff --git a/docs/graylog/README.rst b/docs/graylog/README.rst new file mode 100644 index 00000000..bbedd63b --- /dev/null +++ b/docs/graylog/README.rst @@ -0,0 +1,51 @@ +How to process Cowrie output into Graylog +############################################ + + +Prerequisites +====================== + +* Working Cowrie installation +* Working Graylog installation + +Cowrie Configuration +====================== + +Open the Cowrie configuration file and uncomment these 3 lines:: + + [output_localsyslog] + facility = USER + format = text + +Restart Cowrie + +Graylog Configuration +====================== + +Open the Graylog web interface and click on the **System** drop-down in the top menu. From the drop-down menu select **Inputs**. Select **Syslog UDP** from the drop-down menu and click the **Launch new input** button. In the modal dialog enter the following information:: + + **Title:** Cowrie + **Port:** 8514 + **Bind address:** 127.0.0.1 + +Then click **Launch.** + +Syslog Configuration +====================== + +Create a rsyslog configuration file in /etc/rsyslog.d:: + + $ sudo nano /etc/rsyslog.d/85-graylog.conf + +Add the following lines to the file:: + + $template GRAYLOGRFC5424,"<%pri%>%protocol-version% %timestamp:::date-rfc3339% %HOSTNAME% %app-name% %procid% %msg%\n" + *.* @127.0.0.1:8514;GRAYLOGRFC5424 + +Save and quit. + +Restart rsyslog:: + + $ sudo service rsyslog restart + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..b98f83de --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,26 @@ +.. cowrie documentation master file, created by + sphinx-quickstart on Sun Dec 30 18:27:51 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Cowrie's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + elk/README.rst + graylog/README.rst + kippo-graph/README.rst + splunk/README.rst + sql/README.rst + squid/README.rst + supervisor/README.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/kippo-graph/README.md b/docs/kippo-graph/README.md deleted file mode 100644 index 3a564728..00000000 --- a/docs/kippo-graph/README.md +++ /dev/null @@ -1,117 +0,0 @@ -# How to process Cowrie output in kippo-graph - -* (Note: work in progress, instructions are not verified) -* Tested on Debian 9. - - -## Prerequisites - -* Working Cowrie installation -* LAMP stack (Linux, Apache, MySQL, PHP) - -## Installation - -This covers a simple installation, with kippo-graph and Cowrie on the same server. -Please see here for installation: https://github.com/ikoniaris/kippo-graph - - -## mySQL configuration - -Configuring Cowrie requires setting up the SQL tables and then telling Cowrie to use them. - -To install the tables and create the Cowrie user account enter the following commands: -``` -mysql -u root -p -CREATE DATABASE cowrie; -GRANT ALL ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; -FLUSH PRIVILEGES; -exit -``` - -next create the database schema: -``` -cd /opt/cowrie/ -mysql -u cowrie -p -USE cowrie; -source ./docs/sql/mysql.sql; -exit -``` - -disable MySQL strict mode: -``` -vi /etc/mysql/conf.d/disable_strict_mode.cnf -``` - -``` -[mysqld] -sql_mode=IGNORE_SPACE,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION -``` - -## cowrie configuration - -``` -vi /opt/cowrie/cowrie.cfg -``` - - -* Activate output to mysql -``` -[output_mysql] -host = localhost -database = cowrie -username = cowrie -password = PASSWORD HERE -port = 3306 -debug = false -``` - -* set read access to tty-files for group www-data (group maybe differ on other distributions) -``` -sudo apt-get install acl -sudo setfacl -Rm g:www-data:rx /opt/cowrie/var/lib/cowrie/tty/ -``` - -## kippo-graph Configuration - -``` -vi /var/www/html/kippo-graph/config.php -``` - - -* Change db settings -``` -define('DB_HOST', 'localhost'); -define('DB_USER', 'cowrie'); -define('DB_PASS', 'PASSWORD HERE'); -define('DB_NAME', 'cowrie'); -define('DB_PORT', '3306'); -``` - -## Apache2 configuration (optional) - -* to secure the installation - -Create password database: -``` -cd /etc/apache2/ -htpasswd -c /etc/apache2/cowrie.passwd -htpasswd /etc/apache2/cowrie.passwd (second user) -``` - - -``` -vi /etc/apache2/sites-enabled/000-default.conf -``` -Between the tags, add: -``` - - AuthBasicAuthoritative On - AllowOverride AuthConfig - - AuthType Basic - AuthName "cowrie honeypot" - AuthUserFile /etc/apache2/cowrie.passwd - Require valid-user - -``` - diff --git a/docs/kippo-graph/README.rst b/docs/kippo-graph/README.rst new file mode 100644 index 00000000..7a29c67a --- /dev/null +++ b/docs/kippo-graph/README.rst @@ -0,0 +1,113 @@ +How to process Cowrie output in kippo-graph +############################################# + +(Note: work in progress, instructions are not verified) +Tested on Debian 9. + + +Prerequisites +**************** + +* Working Cowrie installation +* LAMP stack (Linux, Apache, MySQL, PHP) + +Installation +**************** + +This covers a simple installation, with kippo-graph and Cowrie on the same server. +Please see here for installation: https://github.com/ikoniaris/kippo-graph + + +MySQL configuration +*********************** + +Configuring Cowrie requires setting up the SQL tables and then telling Cowrie to use them. + +To install the tables and create the Cowrie user account enter the following commands:: + + mysql -u root -p + CREATE DATABASE cowrie; + GRANT ALL ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; + FLUSH PRIVILEGES; + exit + +Next create the database schema:: + + cd /opt/cowrie/ + mysql -u cowrie -p + USE cowrie; + source ./docs/sql/mysql.sql; + exit + +disable MySQL strict mode:: + + vi /etc/mysql/conf.d/disable_strict_mode.cnf + + [mysqld] + sql_mode=IGNORE_SPACE,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION + +Cowrie configuration +************************ + +Edit cowrie.cfg:: + + vi /opt/cowrie/cowrie.cfg + +Activate output to mysql:: + + [output_mysql] + host = localhost + database = cowrie + username = cowrie + password = PASSWORD HERE + port = 3306 + debug = false + +Set read access to tty-files for group www-data (group maybe differ on other distributions):: + + sudo apt-get install acl + sudo setfacl -Rm g:www-data:rx /opt/cowrie/var/lib/cowrie/tty/ + +kippo-graph Configuration +**************************** + + +Edit config file:: + + vi /var/www/html/kippo-graph/config.php + +Change db settings:: + + define('DB_HOST', 'localhost'); + define('DB_USER', 'cowrie'); + define('DB_PASS', 'PASSWORD HERE'); + define('DB_NAME', 'cowrie'); + define('DB_PORT', '3306'); + +Apache2 configuration (optional) +************************************ + +To secure the installation + +Create password database:: + + cd /etc/apache2/ + htpasswd -c /etc/apache2/cowrie.passwd + htpasswd /etc/apache2/cowrie.passwd (second user) + + + vi /etc/apache2/sites-enabled/000-default.conf + +Between the tags, add:: + + + AuthBasicAuthoritative On + AllowOverride AuthConfig + + AuthType Basic + AuthName "cowrie honeypot" + AuthUserFile /etc/apache2/cowrie.passwd + Require valid-user + + + diff --git a/docs/splunk/README.md b/docs/splunk/README.rst similarity index 72% rename from docs/splunk/README.md rename to docs/splunk/README.rst index 0c2fac00..da63eb68 100644 --- a/docs/splunk/README.md +++ b/docs/splunk/README.rst @@ -1,8 +1,8 @@ -# How to process Cowrie output with Splunk +How to process Cowrie output with Splunk +######################################## -## Sending data - -### Splunk Output Module +Splunk Output Module +==================== * In Splunk, enable the HTTP Event Collector (go to Settings->Add Data) * Do not enable `Indexer Acknowledgment` @@ -11,10 +11,12 @@ * Add URL to HTTP Event Collector and add the authorization token * Optionally enable sourcetype, source, host and index settings -### File Based +File Based +========== * Collect cowrie.json output file using Splunk -## Reporting +Reporting +========== Please see: https://github.com/aplura/Tango diff --git a/docs/sql/README.md b/docs/sql/README.md deleted file mode 100644 index 407841ee..00000000 --- a/docs/sql/README.md +++ /dev/null @@ -1,131 +0,0 @@ -# How to Send Cowrie Output to a MySQL Database - - -## Prerequisites - -* Working Cowrie installation -* MySQL Server installation - - -## Installation - -``` -$ sudo apt-get install mysql-server libmysqlclient-dev python-mysqldb -$ su - cowrie -$ source cowrie/cowrie-env/bin/activate -$ pip install mysqlclient - -``` - -Previously MySQL-python was used. Only if you run into isses with mysqlclient, try this instead: -``` -$ pip install MySQL-python -``` - -## MySQL Configuration - -First create an empty database named 'cowrie'. -``` -$ mysql -u root -p -CREATE DATABASE cowrie; -``` - -Create a cowrie user account for the database and grant access privileges: - -**All Privileges:** - -``` -GRANT ALL ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; - -``` - -**Restricted Privileges:** - -Alternatively you can grant the cowrie account with less privileges. The following command grants the account with the -bare minimum required for the output logging to function: - -``` -GRANT INSERT, SELECT, UPDATE ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; -``` - -Apply the privilege settings and exit mysql. -``` -FLUSH PRIVILEGES; -exit -``` - -Next, log into the MySQL database using the cowrie account to verify proper access privileges and load the database schema provided in the docs/sql/ directory: -``` -$ cd ~/cowrie/docs/sql/ -$ mysql -u cowrie -p -USE cowrie; -source mysql.sql; -exit -``` - - -## Cowrie Configuration - -Uncomment and update the following entries to ~/cowrie/cowrie.cfg under the Output Plugins section: - -``` -[output_mysql] -host = localhost -database = cowrie -username = cowrie -password = PASSWORD HERE -port = 3306 -debug = false -``` - - -## Restart Cowrie - -``` -$ cd ~/cowrie/bin/ -$ ./cowrie restart -``` - - -## Verify That the MySQL Output Engine Has Been Loaded - -Check the end of the ~/cowrie/log/cowrie.log to make sure that the MySQL output engine has loaded successfully. -``` -$ cd ~/cowrie/log/ -$ tail cowrie.log -``` - -Example expected output: -``` -2017-11-27T22:19:44-0600 [-] Loaded output engine: jsonlog -2017-11-27T22:19:44-0600 [-] Loaded output engine: mysql -... -2017-11-27T22:19:58-0600 [-] Ready to accept SSH connections - -``` - - -## Confirm That Events are Logged to the MySQL Database -Wait patiently for a new login attempt to occur. Use tail like before to quickly check if any activity has -been recorded in the cowrie.log file. - -Once a login event has occurred, log back into the MySQL database and verify that the event was recorded: - -``` -$ mysql -u cowrie -p -USE cowrie; -SELECT * FROM auth; -``` - -Example output: -``` -+----+--------------+---------+----------+-------------+---------------------+ -| id | session | success | username | password | timestamp | -+----+--------------+---------+----------+-------------+---------------------+ -| 1 | a551c0a74e06 | 0 | root | 12345 | 2017-11-27 23:15:56 | -| 2 | a551c0a74e06 | 0 | root | seiko2005 | 2017-11-27 23:15:58 | -| 3 | a551c0a74e06 | 0 | root | anko | 2017-11-27 23:15:59 | -| 4 | a551c0a74e06 | 0 | root | 123456 | 2017-11-27 23:16:00 | -| 5 | a551c0a74e06 | 0 | root | dreambox | 2017-11-27 23:16:01 | -... -``` diff --git a/docs/sql/README.rst b/docs/sql/README.rst new file mode 100644 index 00000000..b596da50 --- /dev/null +++ b/docs/sql/README.rst @@ -0,0 +1,112 @@ +How to Send Cowrie Output to a MySQL Database +################################################ + + +Prerequisites +============= + +* Working Cowrie installation +* MySQL Server installation + + +Installation +============ + +Run:: + + $ sudo apt-get install mysql-server libmysqlclient-dev python-mysqldb + $ su - cowrie + $ source cowrie/cowrie-env/bin/activate + $ pip install mysqlclient + +Previously MySQL-python was used. Only if you run into isses with mysqlclient, try this instead:: + + $ pip install MySQL-python + +MySQL Configuration +=================== + +First create an empty database named 'cowrie':: + + $ mysql -u root -p + CREATE DATABASE cowrie; + +Create a cowrie user account for the database and grant all access privileges:: + + GRANT ALL ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; + +**Restricted Privileges:** + +Alternatively you can grant the cowrie account with less privileges. The following command grants the account with the +bare minimum required for the output logging to function:: + + GRANT INSERT, SELECT, UPDATE ON cowrie.* TO 'cowrie'@'localhost' IDENTIFIED BY 'PASSWORD HERE'; + +Apply the privilege settings and exit mysql:: + + FLUSH PRIVILEGES; + exit + +Next, log into the MySQL database using the cowrie account to verify proper access privileges and load the database schema provided in the docs/sql/ directory:: + + $ cd ~/cowrie/docs/sql/ + $ mysql -u cowrie -p + USE cowrie; + source mysql.sql; + exit + +Cowrie Configuration +==================== + +Uncomment and update the following entries to ~/cowrie/cowrie.cfg under the Output Plugins section:: + + [output_mysql] + host = localhost + database = cowrie + username = cowrie + password = PASSWORD HERE + port = 3306 + debug = false + +Restart Cowrie:: + + $ cd ~/cowrie/bin/ + $ ./cowrie restart + +Verify That the MySQL Output Engine Has Been Loaded + +Check the end of the ~/cowrie/log/cowrie.log to make sure that the MySQL output engine has loaded successfully:: + + $ cd ~/cowrie/log/ + $ tail cowrie.log + +Example expected output:: + + 2017-11-27T22:19:44-0600 [-] Loaded output engine: jsonlog + 2017-11-27T22:19:44-0600 [-] Loaded output engine: mysql + ... + 2017-11-27T22:19:58-0600 [-] Ready to accept SSH connections + +## Confirm That Events are Logged to the MySQL Database +Wait for a new login attempt to occur. Use tail like before to quickly check if any activity has +been recorded in the cowrie.log file. + +Once a login event has occurred, log back into the MySQL database and verify that the event was recorded:: + + $ mysql -u cowrie -p + USE cowrie; + SELECT * FROM auth; + `` + +Example output:: + + +----+--------------+---------+----------+-------------+---------------------+ + | id | session | success | username | password | timestamp | + +----+--------------+---------+----------+-------------+---------------------+ + | 1 | a551c0a74e06 | 0 | root | 12345 | 2017-11-27 23:15:56 | + | 2 | a551c0a74e06 | 0 | root | seiko2005 | 2017-11-27 23:15:58 | + | 3 | a551c0a74e06 | 0 | root | anko | 2017-11-27 23:15:59 | + | 4 | a551c0a74e06 | 0 | root | 123456 | 2017-11-27 23:16:00 | + | 5 | a551c0a74e06 | 0 | root | dreambox | 2017-11-27 23:16:01 | + ... + diff --git a/docs/squid/README.md b/docs/squid/README.rst similarity index 68% rename from docs/squid/README.md rename to docs/squid/README.rst index 7bcfdd0d..5396ce89 100644 --- a/docs/squid/README.md +++ b/docs/squid/README.rst @@ -1,40 +1,45 @@ -# Using TCP tunneling with Squid +Using TCP tunneling with Squid +################################# -## Prerequisites +Prerequisites +============= * Working Cowrie installation * Working Squid installation with CONNECT allowed * (optional) Rate limit and black/white lists in Squid -## Installation +Installation +============ -``` +`` $ sudo apt-get install squid -``` +`` -## Squid Configuration +Squid Configuration +=================== See `squid.conf` for an example configuration. -## Cowrie Configuration +Cowrie Configuration +==================== Uncomment and update the following entries to ~/cowrie/cowrie.cfg under the SSH section: -``` +`` forward_tunnel = true forward_tunnel_80 = 127.0.0.1:3128 forward_tunnel_443 = 127.0.0.1:3128 -``` +`` ## Restart Cowrie -``` +`` $ cd ~/cowrie/bin/ $ ./cowrie restart -``` +`` diff --git a/docs/supervisor/README.md b/docs/supervisor/README.md deleted file mode 100644 index 5b2c6de5..00000000 --- a/docs/supervisor/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Automatically starting Cowrie with supervisord - -* Copy the file `cowrie.conf` to `/etc/supervisor/conf/` diff --git a/docs/supervisor/README.rst b/docs/supervisor/README.rst new file mode 100644 index 00000000..740ffb51 --- /dev/null +++ b/docs/supervisor/README.rst @@ -0,0 +1,4 @@ +Automatically starting Cowrie with supervisord +################################################# + +* Copy the file `cowrie.conf` to `/etc/supervisor/conf/` diff --git a/src/cowrie/__init__.py b/src/cowrie/__init__.py index 3a8d6d5c..206353ec 100644 --- a/src/cowrie/__init__.py +++ b/src/cowrie/__init__.py @@ -1 +1,3 @@ -from ._version import __version__ # noqa: F401 +# setup version +from twisted._version import __version__ as version +__version__ = version.short()