pgsqlpot 2.0.0__py2.py3-none-any.whl

pgsqlpot/data/docs/INSTALL.md

@@ -0,0 +1,400 @@
+# Installation guide (on Ubuntu)
+
+(For installation on Windows, see the corresponding [installation document](INSTALLWIN.md))
+
+- [Installation guide (on Ubuntu)](#installation-guide-on-ubuntu)
+  - [Step 1: Install the dependencies](#step-1-install-the-dependencies)
+  - [Step 2: Open port 5432 for TCP traffic](#step-2-open-port-5432-for-tcp-traffic)
+  - [Step 3: Create a user account](#step-3-create-a-user-account)
+  - [Step 4: Install the honeypot](#step-4-install-the-honeypot)
+    - [Installing from PyPI (recommended)](#installing-from-pypi-recommended)
+    - [Installing from the repo](#installing-from-the-repo)
+  - [Step 5: Initialize the working directory](#step-5-initialize-the-working-directory)
+  - [Step 6: Create a configuration file](#step-6-create-a-configuration-file)
+  - [Step 7: Start the honeypot](#step-7-start-the-honeypot)
+  - [Step 8: Make the honeypot start at boot time](#step-8-make-the-honeypot-start-at-boot-time)
+  - [Configure additional output plugins (OPTIONAL)](#configure-additional-output-plugins-optional)
+  - [Docker usage (OPTIONAL)](#docker-usage-optional)
+  - [Command-line options](#command-line-options)
+  - [Upgrading the honeypot](#upgrading-the-honeypot)
+
+## Step 1: Install the dependencies
+
+Install system-wide support for Python and pip:
+
+```bash
+sudo apt-get update
+sudo apt-get install python3 python3-pip
+```
+
+If you plan to use the MySQL output plugin, also install the MySQL client
+development library:
+
+```bash
+sudo apt-get install libmysqlclient-dev
+```
+
+## Step 2: Open port 5432 for TCP traffic
+
+If TCP port 5432 is not already opened for incoming connections on your
+firewall and router, you must open it now. How exactly to do this from a NAT
+router depends on the router model; please consult the instruction manual of
+the router.
+
+To open the port on the firewall, use:
+
+```bash
+sudo ufw allow 5432/tcp
+```
+
+## Step 3: Create a user account
+
+It is strongly recommended to run the honeypot as a dedicated non-root user
+(named `pgsqlpot` in our example), who cannot `sudo`:
+
+```bash
+$ sudo adduser --disabled-password pgsqlpot
+Adding user `pgsqlpot' ...
+Adding new group `pgsqlpot' (1019) ...
+Adding new user `pgsqlpot' (1019) with group `pgsqlpot' ...
+Creating home directory `/home/pgsqlpot' ...
+Copying files from `/etc/skel' ...
+Changing the user information for pgsqlpot
+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]
+```
+
+Switch to that user's account:
+
+```bash
+sudo su - pgsqlpot
+```
+
+## Step 4: Install the honeypot
+
+Create a virtual environment. For modern versions of Python (i.e., 3.x), use
+just
+
+```bash
+python -m venv pgsqlpot-env
+```
+
+For the obsolete Python 2.7, use
+
+```bash
+pip install "virtualenv==20.15.1"
+virtualenv pgsqlpot-env
+```
+
+Then activate the virtual environment with
+
+```bash
+source pgsqlpot-env/bin/activate
+```
+
+and update `pip`
+
+```bash
+(pgsqlpot-env) $ python -m pip install pip --upgrade
+```
+
+How you should proceed further depends on whether you want to install the
+honeypot from the repo (usually done for testing purposes) or from PyPI
+(the recommended approach).
+
+### Installing from PyPI (recommended)
+
+Installing from PyPI is very simple. Just use
+
+```bash
+(pgsqlpot-env) $ pip install --prefer-binary pgsqlpot[plugin_list]
+```
+
+Here, `plugin_list` is a comma-separated list of output plugin names whose
+dependencies you want to install. You do not need to install the dependencies
+for all existing plugins. For instance, if you plan to use only the `mysql`
+and `redisdb` plugins, use `[mysql,redisdb]`. If you want to install the
+dependencies for all plugins, use `[all]`.
+
+The output plugins `discord`, `jsonlog`, `localsyslog`, `socketlog`, `sqlite`,
+`telegram`, and `textlog` have no dependencies of their own. If you plan to use
+only one or more of those, omit the `[plugin_list]` part entirely. It won't hurt
+to specify such a plugin (e.g., `[mysql,jsonlog]`) but this is essentially
+equivalent to omitting it.
+
+If, after installation, you decide that you're going to use yet another plugin,
+simply run the installation command again with the new plugin included in the
+`plugin_list`
+
+### Installing from the repo
+
+Ensure that the `build` module is installed, clone the repo, build the
+distribution wheel, and install from it:
+
+```bash
+(pgsqlpot-env) $ pip install build --upgrade
+(pgsqlpot-env) $ git clone https://gitlab.com/bontchev/pgsqlpot.git
+(pgsqlpot-env) $ cd pgsqlpot
+(pgsqlpot-env) $ python -m build
+(pgsqlpot-env) $ pip install --prefer-binary "dist/pgsqlpot-*-py2.py3-none-any.whl[plugin_list]"
+```
+
+where `plugin_list` is as described in the previous section.
+
+## Step 5: Initialize the working directory
+
+Create a directory where the honeypot will store its configuration, data,
+documentation, and logs, then initialize it:
+
+```bash
+(pgsqlpot-env) $ mkdir ~/pgsqlpot-workdir
+(pgsqlpot-env) $ cd ~/pgsqlpot-workdir
+(pgsqlpot-env) $ pgsqlpot init
+```
+
+This creates the `data/`, `docs/`, `etc/`, and `log/` subdirectories. It
+also copies the files `test.py` (for verifying the honeypot is working)
+and `Dockerfile` into the working directory.
+
+## Step 6: Create a configuration file
+
+The configuration for the honeypot is stored in `etc/honeypot.cfg.base` and
+`etc/honeypot.cfg`. Both files are read on startup but entries from
+`etc/honeypot.cfg` take precedence. The `.base` file contains the default
+settings and should not be edited — it may be overwritten by upgrades. All
+your customisations should go into `etc/honeypot.cfg`.
+
+To run with a standard configuration there is no need to change anything.
+
+For instance, in order to enable JSON logging, create `etc/honeypot.cfg` and
+put in it only the following:
+
+```ini
+[output_jsonlog]
+enabled = true
+logfile = log/pgsqlpot.json
+epoch_timestamp = true
+```
+
+For more information about how to configure additional output plugins, please
+consult the appropriate `README.md` file in the subdirectory corresponding to
+the plugin inside the `docs/` directory.
+
+**Note on testing:** The default blacklist excludes connections from
+`127.0.0.1` and `192.168.0.0/16`. If you run `test.py` from the same machine
+as the honeypot, you will not see any log output because the connection will
+not be logged. Either run `test.py` with `-H <your-external-IP>`, or
+temporarily clear the blacklist in `etc/honeypot.cfg`:
+
+```ini
+[honeypot]
+blacklist =
+```
+
+## Step 7: Start the honeypot
+
+From the working directory, with the virtual environment active:
+
+```bash
+(pgsqlpot-env) $ cd ~/pgsqlpot-workdir
+(pgsqlpot-env) $ pgsqlpot start
+```
+
+To check that the honeypot is running, use
+
+```bash
+(pgsqlpot-env) $ pgsqlpot status
+The honeypot is running (PID: 12345).
+```
+
+To run in the foreground (useful for debugging):
+
+```bash
+(pgsqlpot-env) $ pgsqlpot run
+```
+
+Stop it by pressing Ctrl-C.
+
+To stop the honeypot when it is running in the background, use
+
+```bash
+(pgsqlpot-env) $ pgsqlpot stop
+Stopping the honeypot (PID 12345)... Stopped.
+```
+
+To verify that the honeypot is working correctly, run the test script (see
+the note about the blacklist above):
+
+```bash
+(pgsqlpot-env) $ python test.py -u Foo -p Bar -H $(curl -s "http://api.ipify.org")
+```
+
+It should print a message like this:
+
+```test.py
+Error: connection to server at "123.123.123.123", port 5432 failed: FATAL:  password authentication failed for user "Foo"
+```
+
+where instead of `123.123.123.123` you'll see your external IP address.
+
+## Step 8: Make the honeypot start at boot time
+
+Edit the `crontab` jobs with your favourite editor:
+
+```bash
+crontab -e
+```
+
+and add the line:
+
+```bash
+@reboot cd ${HOME}/pgsqlpot-workdir && ${HOME}/pgsqlpot-env/bin/pgsqlpot start >/dev/null 2>&1
+```
+
+This starts the honeypot automatically whenever the computer boots.
+
+## Configure additional output plugins (OPTIONAL)
+
+The honeypot automatically outputs event data as text to stdout (or to a log
+file, if configured). Additional output plugins can be configured to record
+the data in other ways. Supported output plugins currently include:
+
+Destination|Plugin Name
+---|---
+CouchDB|couch
+[Datadog](datadog/README.md)|datadog
+[Discord](discord/README.md)|discord
+Elasticsearch|elastic
+HPFeeds|hpfeed
+InfluxDB 2.0|influx2
+JSON|jsonlog
+Kafka|kafka
+MongoDB|mongodb
+[MySQL](mysql/README.md)|mysql
+NLCV API|nlcvapi
+[PostgreSQL](postgres/README.md)|postgres
+Redis|redisdb
+RethinkDB|rethinkdblog
+[Slack](slack/README.md)|slack
+Socket|socketlog
+[SQLite3](sqlite3/README.md)|sqlite
+Syslog|localsyslog
+[Telegram](telegram/README.md)|telegram
+Text|textlog
+XMPP|xmpp
+
+More plugins are likely to be added in the future.
+
+See `docs\[plugin]\README.md` for details on each plugin or click on the
+names in the above table that are clickable.
+
+**Note:** The `influx2` plugin requires Python 3.x and cannot be used with
+Python 2.7. The `localsyslog` plugin works only on Linux.
+
+## Docker usage (OPTIONAL)
+
+**WARNING!** A user who belongs to the `docker` group has effective root
+privileges on the host, which negates the advantages of creating the `pgsqlpot`
+user as a restricted user in the first place. Since this significantly increases
+the [attack surface](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface),
+we strongly advise against using the honeypot with Docker. One alternative is
+to use [Podman](https://podman.io/), which does not require privileged user
+access in order to operate.
+
+If you nevertheless wish to use Docker, first make sure it is installed and
+that the user `pgsqlpot` is a member of the `docker` group (from a user who
+can `sudo`):
+
+```bash
+sudo apt-get install docker.io
+sudo usermod -a -G docker pgsqlpot
+```
+
+Then switch to the `pgsqlpot` user and build the image from the working
+directory (the `Dockerfile` was placed there by `pgsqlpot init`):
+
+```bash
+sudo su - pgsqlpot
+cd ~/pgsqlpot-workdir
+source ~/pgsqlpot-env/bin/activate
+VERSION=$(pgsqlpot --version)
+deactivate
+
+# Build with all plugins (default)
+docker build --build-arg VERSION=$VERSION -t pgsqlpot .
+
+# Or build with specific plugins only, e.g., mysql and kafka:
+docker build --build-arg VERSION=$VERSION --build-arg PLUGINS=mysql,kafka -t pgsqlpot .
+
+# Run, mounting your config and data directories
+docker run -d -p 5432:5432 \
+  -v ${HOME}/pgsqlpot-workdir/etc/honeypot.cfg:/pgsqlpot/etc/honeypot.cfg \
+  -v ${HOME}/pgsqlpot-workdir/data:/pgsqlpot/data \
+  pgsqlpot
+```
+
+## Command-line options
+
+The honeypot supports the following command-line options:
+
+```bash
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -w WORKDIR, --workdir WORKDIR
+                        Working directory (overrides PGSLQPOT_WORKDIR and cwd)
+```
+
+It also supports the following subcommands:
+
+```bash
+    init                Scaffold a working directory
+    run                 Start the honeypot in the foreground
+    start               Start the honeypot in the background
+    stop                Stop the backgrounded honeypot
+    restart             Restart (stop and start) the honeypot in the background
+    status              Show running status
+```
+
+All subcommands accept `-w / --workdir DIR` to specify the working directory
+explicitly, overriding the `PGSLQPOT_WORKDIR` environment variable and the
+current directory.
+
+The `run`, `start`, and `restart` subcommands also accept the options
+
+```bash
+  -h, --help            show this help message and exit
+  -p PORT, --port PORT  Port to listen on (default: 5432)
+  -l LOGFILE, --logfile LOGFILE
+                        Log file (default: stdout)
+  -s SENSOR, --sensor SENSOR
+                        Sensor name (default: hostname)
+```
+
+Settings specified via command-line options take precedence over the
+corresponding settings in the configuration files.
+
+## Upgrading the honeypot
+
+Stop the honeypot, upgrade the package, re-initialize (to pick up any new
+default config or response files), and restart:
+
+```bash
+$ cd ~/pgsqlpot-workdir
+$ source ~/pgsqlpot-env/bin/activate
+(pgsqlpot-env) $ pgsqlpot stop
+(pgsqlpot-env) $ pip install --prefer-binary --upgrade pgsqlpot[plugin_list]
+(pgsqlpot-env) $ pgsqlpot init
+(pgsqlpot-env) $ pgsqlpot start
+```
+
+where `[plugin_list]` is as explained above.
+
+Note that `pgsqlpot init` is safe to re-run — it never overwrites files that
+you have already edited or created (such as `etc/honeypot.cfg`). It only
+copies files that are missing, so any new defaults added by an upgrade are
+picked up automatically.