pogo 0.9.5.1

Pogo is a utility for putting data generated by a HonSSH honeypot into an Elasticsearch database.

==================================================================
pogo: Pogo is a utility for putting data generated by a HonSSH honeypot into an Elasticsearch database.
==================================================================

WHAT IT DOES
------------
Pogo parses the data files generated by HonSSH and inserts the information into an Elasticsearch
database. It NOT does set up the Elasticsearch server for you -- it's assumed you've already done that
or are about to do so; otherwise, this tool isn't much good to you.

Pogo is strictly a "back-end" tool; it doesn't help you at all with displaying the information your
HonSSH instances generate, but only puts the information into Elasticsearch.

When Pogo runs, it checks the directories specified in its configuration file (see below) for
data files. It ignores any that are from the current day - any older ones are processed. Once
they're processed, they're collected into archive files (tarred and bzipped by default) and then
the originals are deleted. You should remove older archive files from time to time to avoid filling
up your disk.

The normal way to use Pogo is to run it from a cron job, although you can run it manually if desired. In
its default configuration, it does need root privileges, since it's writing to directories it doesn't own.

You must install Pogo separately on each HonSSH host for which you want the data processed. (See
below for installation information.)


Installation
------------

As of now (early March 2015), Pogo's status is Beta. This means that pip won't install it
unless you add "--pre" to the command to tell it that a pre-release version is OK. So, to
install Pogo with pip, do (as root):

# pip install --pre pogo

You may also use easy_install if desired, but this isn't recommended. I've found that installing
Pogo with easy_install doesn't install the configuration file, so if you do this you'll have
to create the configuration file manually. I don't know if this is due to my package not being
set up properly, or is inherent in the way easy_install works, but in any case, for now just
use pip.

The default installation installs:
* /usr/local/bin/pogo - the executable
* /etc/pogo.cfg - the default configuration file
* /etc/logrotate.d/pogo - the default logrotate configuration
* /usr/local/lib/python-2.7/dist-packages/pogo - the Python libraries
* /usr/local/lib/python-2.7/dist-packages/pogo-<VERSION>.egg-info - metadata about the package

If you want to install to different locations, see the help pages for pip or easy_install.

After running the pip installation command:

* Make changes to pogo.cfg as needed or desired.

* If needed or desired, move pogo.cfg to another directory. If the directory is not in the list given in the COnfiguration File section of this document, edit util/config.py as appropriate.

* Make changes to the logrotate configuration file if needed or desired.


Usage
-----

As stated earlier, Pogo normally runs via a cron job. As root, edit your crontab to add
a call to Pogo at the intervals you desire. For example, if you want to run it every
morning at 3:05, you would do (as root):
# crontab -e

This will open your crontab file in the default text editor. Add the following line at
the end of the file:
5 3 * * * /usr/local/bin/pogo

Save the file and exit from the editor.

To run the file manually, execute (as root):
# pogo

There are no command line arguments -- everything that can be changed is changed by
editing the configuration file (see below).

Configuration File
------------------

When pogo runs, it looks for a file called "pogo.cfg;" if it's found, pogo reads its configuration from there,
otherwise it uses default settings.

The default location for pogo.cfg is in the /etc directory, and the installation should copy the
default configuration file to that location. Before running pogo for the first time, please look
at /etc/pogo.cfg and change any settings to match your environment. In particular, you will probably need
to specify the hostname or IP address of your Elasticsearch server. Also, the first time or two that
you run the program, you may want to set the logging level to INFO to display more information. (After
you're satisfied that pogo is running properly, you'll probably want to set it back to WARNING to save
disk space.)

If the program can't find pogo.cfg in /etc, it will then look in the following locations, in this order:
* /etc/default
* /etc/pogo
* /usr/local/share/pogo
* ~/.config/pogo/ ("~" means the home directory of the user [probably root] running Pogo.)
* The directory the program was started from

If you move pogo.cfg from /etc, please move it to one of these locations, or edit the file util/config.py,
one of the library files installed as part of Pogo.

The format of the configuration file is that used by the Python ConfigParser module -- for full
details, see the official Python documentation here: https://docs.python.org/2/library/configparser.html.

Here is an explanation of the configuration file contents; the settings below
are the defaults.

[main]

debug=0

honssh_type = 'SINGLE'

debug can be 0 or 1; however, this setting isn't used at present.

Pogo can work with development versions of HonSSH that handle multiple honeypots. If you are using such a version, change the honssh_type from 'SINGLE' to 'MULTI.'

[locations]

top_dir=/opt/honssh

log_dir=%(top_dir)s/logs

attempt_dir=%(top_dir)s/logs

session_dir=%(top_dir)s/sessions

archive_dir = %(top_dir)s/archives

The [locations] section specifies where the program should look for the various types
of data files generated by HonSSH, and also where the archived files should be stored.
By the way, "attempt" refers to the user name, password, and other information associated
with an intruder trying to log in.

The locations by default are relative to "top_dir," which is the root of the HonSSH installation.


[db_connection]

type=sqlite

sqlite_dir=/usr/local/share/pogo/db

name=%(sqlite_dir)s/pogo.db

host=''

port=''

user=''

password=''

The [db_connection] section tells pogo how to connect to the database. NOTE: The database
referred to here is NOT your Elasticsearch database, but another one used for temporary
storage during processing of the HonSSH-generated files.

As of now, the only database type supported is sqlite3, and no host, port, user, or
password settings are needed for that; only the directory and data file name. When
pogo runs, it checks to see if the database file named in this configuration exists,
and creates and initializes it if not. If you want your sqlite3 file to be something
other than /usr/local/share/pogo/db/pogo.db, specify it here.


[elasticsearch]

es_host=localhost

es_port=9200

es_index=hon_ssh

es_timeout=30

Change the information in this section to the values for your Elasticsearch database.
These values should work as is for a server on the same host as Pogo, unless the
default settings have been changed in Elasticsearch's configuration. By the way, the timeout
parameter is in seconds.

[logging]

level=WARNING

filename=/var/log/pogo.log

The default logging level will generate very little output as long as things are going right.
For more detailed logging, change this to INFO, DEBUG for even more verbose output.