Package: pogo
==================================================================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 Elasticsearchdatabase. It NOT does set up the Elasticsearch server for you -- it's assumed you've already done thator 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 yourHonSSH instances generate, but only puts the information into Elasticsearch.When Pogo runs, it checks the directories specified in its configuration file (see below) fordata files. It ignores any that are from the current day - any older ones are processed. Oncethey're processed, they're collected into archive files (tarred and bzipped by default) and thenthe originals are deleted. You should remove older archive files from time to time to avoid fillingup your disk.The normal way to use Pogo is to run it from a cron job, although you can run it manually if desired. Inits 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. (Seebelow for installation information.)Installation------------As of now (early March 2015), Pogo's status is Beta. This means that pip won't install itunless you add "--pre" to the command to tell it that a pre-release version is OK. So, toinstall Pogo with pip, do (as root):# pip install --pre pogoYou may also use easy_install if desired, but this isn't recommended. I've found that installingPogo with easy_install doesn't install the configuration file, so if you do this you'll haveto create the configuration file manually. I don't know if this is due to my package not beingset up properly, or is inherent in the way easy_install works, but in any case, for now justuse 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 packageIf 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 adda call to Pogo at the intervals you desire. For example, if you want to run it everymorning at 3:05, you would do (as root):# crontab -eThis will open your crontab file in the default text editor. Add the following line atthe end of the file:5 3 * * * /usr/local/bin/pogoSave the file and exit from the editor.To run the file manually, execute (as root):# pogoThere are no command line arguments -- everything that can be changed is changed byediting 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 thedefault configuration file to that location. Before running pogo for the first time, please lookat /etc/pogo.cfg and change any settings to match your environment. In particular, you will probably needto specify the hostname or IP address of your Elasticsearch server. Also, the first time or two thatyou run the program, you may want to set the logging level to INFO to display more information. (Afteryou're satisfied that pogo is running properly, you'll probably want to set it back to WARNING to savedisk 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 fromIf 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 fulldetails, 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 beloware the defaults.[main]debug=0honssh_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/honsshlog_dir=%(top_dir)s/logsattempt_dir=%(top_dir)s/logssession_dir=%(top_dir)s/sessionsarchive_dir = %(top_dir)s/archivesThe [locations] section specifies where the program should look for the various typesof 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 associatedwith 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=sqlitesqlite_dir=/usr/local/share/pogo/dbname=%(sqlite_dir)s/pogo.dbhost=''port=''user=''password=''The [db_connection] section tells pogo how to connect to the database. NOTE: The databasereferred to here is NOT your Elasticsearch database, but another one used for temporarystorage during processing of the HonSSH-generated files.As of now, the only database type supported is sqlite3, and no host, port, user, orpassword settings are needed for that; only the directory and data file name. Whenpogo 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 somethingother than /usr/local/share/pogo/db/pogo.db, specify it here.[elasticsearch]es_host=localhostes_port=9200es_index=hon_sshes_timeout=30Change 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 thedefault settings have been changed in Elasticsearch's configuration. By the way, the timeoutparameter is in seconds.[logging]level=WARNINGfilename=/var/log/pogo.logThe 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.