Guide: Users
Table of Contents
This guide is intended for end users of the replay management frontend and command line interface (CLI). This document assumes that a successful run of the Install Guide has been performed. To find more information on how to contribute to the project, see the Developers Guide.
The replay manager frontend lets you see information about your deployed honeypots.
The first thing you need to do is set up an account by following the new user process in the Install Guide.
Once you have accounts for Couchdb and the replay frontend, continue to the next step. Right now, the only way to change your account details is through administrative configuration on the database side of things. Proceed to the login page on port 8080.
After login, you will see a list of honeypots in your system and some graphs that show the logs' time distribution of the last active time period. You can change this time period with the avaliable selections. The way this works, is you define a time period (say 2 hours), this page will then show you the time distribution of logs, with your specified time range ending on the most recent recorded log. If the most recent log for a device is 2 days ago, then the graph will show the 2 hours preceeding the most recent log. This process is repeated for each device.
The next page of importance is the Alerts page. Here you can see alerts from your honeypots and dig into the details of those alerts with the JSON viewer.
To view the details of a specific honeypot, click any of the links under the "Dashboards" header in the navigation menu (left side of screen).
These details pages have the same layouts and options (with the exception of the
Aggregate page):
- the top section gives you basic info on the device
- the graph section allows you to drill down to specific timeframes to see the activity logged by the device
- the datatable section lets you scroll, paginate, and search the logs the device has recorded
Please note that the search function takes quite a long time if there are many logs for the device. A speedup needs to be researched more before implementation.
There has been some confusion surrounding the Specificity button, you use this button
to reduce the number of points on the graph and group them together.
To see an overview of recent logs, click the About link in the navbar. Here you can choose between specific honeypots and an amount of recent logs to analyze.
On this page, you can see overviews on the recent logs. By default, the page will only show the top 5 listings in each category. The Toggle All button will show you the rest.
At the bottom of the frontend’s navigation bar are some useful links to external APIs. The Management Database link leads to an interface for the log database, the PouchDB link leads to the API documentation for PouchDB API, and the Database API link leads to the documentation for CouchDB.
Note: PouchDB is the way the frontend talks to the main CouchDB.
The CLI allows users on the management system to deploy and configure honeypots. The CLI can be run in interactive mode with menus/submenus, or the CLI’s commands can be run directly outside of interactive mode. The majority of the commands in this guide will be run directly.
_For further details on each command, refer to the Final Progress Report. _
Menus
When the CLI is run in interactive mode, it will start in the main menu. The main menu will contain all of the submenus, and the submenus will contain all of the CLI’s commands. Below is the structure of the menus:
-
Main Menu
-
Manage Hosts (submenu)
- Add Host
- Remove Host
- Check Status
-
Install (submenu)
- Install Honeypot
- Uninstall Honeypot
- Reinstall Honeypot
-
Edit Honeypots (submenu)
- Start Honeypot
- Stop Honeypot
- Configure Honeypot
- Exit
-
Manage Hosts (submenu)
Return
From any point of the CLI, Ctrl+D will allow you to perform a return.
- If you are running in interactive mode:
- Commands will return to the main menu
- Submenus will return to the main menu
- Main menu will exit to the command line
- If you are running a command directly, you will exit to the command line
Exit
From any point of the CLI, Ctrl+C will allow you to perform a force exit back to the command line.
Note: Returning or force exiting in the middle of a command will cause all unsaved progress to be lost!
To run the CLI in interactive mode:
$ python3 replay\_cli.py startThis will allow you to run several commands consecutively until you exit. Refer to the navigation section of this guide for further details.
To add a host:
$ python3 replay\_cli.py addhostThis will prompt you for the following info:
- Hostname - the id of this host on the CLI
- Username - the username you use on the host machine
- IP Address - the IP address of the host machine
- Port - the port of the ssh server on the host machine
- SSH Key - the path to the ssh key created for this machine
To remove a host:
$ python3 replay\_cli.py removehostThis will prompt you to select one or more hosts to remove.
-or-
$ python3 replay\_cli.py removehost --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)To check the status of a host:
$ python3 replay\_cli.py checkstatusThis will prompt you to select one or more hosts to check on
-or-
$ python3 replay\_cli.py checkstatus --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)To install a honeypot on a host:
$ python3 replay\_cli.py installhoneypotThis will prompt you to select one or more hosts to install a honeypot on
-or-
$ python3 replay\_cli.py installhoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)You will then be prompted for the tar file of the honeypot repository (created in the Installation Guide).
To uninstall a honeypot on a host:
$ python3 replay\_cli.py uninstallhoneypotThis will prompt you to select one or more hosts to uninstall a honeypot on
-or-
$ python3 replay\_cli.py uninstallhoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)You will then be prompted for the password of the username saved for the selected host.
To reinstall a honeypot on a host:
$ python3 replay\_cli.py reinstallhoneypotThis will prompt you to select one or more hosts to reinstall a honeypot on
-or-
$ python3 replay\_cli.py reinstallhoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)You will then be prompted for the tar file of the honeypot repository and the password of the username saved for the selected host.
To start a honeypot on a host:
$ python3 replay\_cli.py starthoneypotThis will prompt you to select one or more hosts to start a honeypot on
-or-
$ python3 replay\_cli.py starthoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)The first time you run this command, you will be prompted for the url to the management database.
You will then be prompted for the password of the username saved for the selected host.
To stop a honeypot on a host:
$ python3 replay\_cli.py stophoneypotThis will prompt you to select one or more hosts to stop a honeypot on
-or-
$ python3 replay\_cli.py stophoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)You will then be prompted for the password of the username saved for the selected host.
To configure a honeypot on a host:
$ python3 replay\_cli.py configurehoneypotThis will prompt you to select one or more hosts to configure a honeypot on
-or-
$ python3 replay\_cli.py configurehoneypot --hosts \[host\] (--hosts \[host\_2\] --hosts \[host\_3\] ...)You will then be prompted to select between Edit Configuration Files and Reconfigure.
If you select edit configuration files, you will be ssh’d into the selected hosts.
From there, navigate to the honeypot’s configuration folder and use the editor of your choice to change the configuration files.
To exit the ssh session:
$ exitIf you select reconfigure, you will then be prompted again to select which portion(s) of the honeypot to restart.
Go here for details on general UNIX account management.
Depending on the configuration of your management system, you may need extra permissions to manage the docker engine instance. Talk to your sysadmin about getting added to the “docker” group on the system.