pgsqlpot 2.0.0__py2.py3-none-any.whl

pgsqlpot/data/docs/INSTALLWIN.md

@@ -0,0 +1,411 @@
+# Installation guide (on Windows)
+
+(For installation on Ubuntu, see the corresponding [installation document](INSTALL.md))
+
+- [Installation guide (on Windows)](#installation-guide-on-windows)
+  - [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
+
+Log in as a user with Administrator privileges and install the following
+programs (if they are not already present):
+
+- **Python**. The latest version of Python 3.x is preferred, although the
+  honeypot is compatible with Python 2.7. You can download it from
+  [python.org](https://www.python.org/downloads/windows/). Download the
+  installer for your platform (64-bit or 32-bit). Make sure to install it
+  for all users and not just for the current one, and tick the option to
+  add Python to the `PATH` variable of the environment.
+
+- **Database server** (optional). If you want the honeypot to send the data
+  it collects to a local database server (e.g., MySQL), make sure to install
+  it — again, for all users and not just for the current one.
+
+- The latest version of the **VS C++ redistributable** (required by some of
+  the database output plugins, e.g., for MySQL). Version 14 or higher should
+  be fine. You can download it from
+  [there](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170).
+
+## 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, open a PowerShell window as Administrator
+and use:
+
+```powershell
+New-NetFirewallRule -DisplayName 'TCP-5432' -Profile @('Domain', 'Private') -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5432
+```
+
+## Step 3: Create a user account
+
+It is strongly recommended to run the honeypot as a dedicated user with no
+administrative privileges (named `HoneyPotter` in our example):
+
+```powershell
+Import-Module Microsoft.Powershell.LocalAccounts -SkipEditionCheck
+$password = ConvertTo-SecureString "PASSWORD" -AsPlainText -Force
+New-LocalUser -Name "HoneyPotter" -Password $password -FullName "HoneyPotter" -Description "Honeypots Account"
+Add-LocalGroupMember -Group "Users" -Member "HoneyPotter"
+```
+
+Make sure to specify a proper password for that user instead of "PASSWORD".
+
+If you *really* need to be able to log in as this user over RDP, execute the
+following line:
+
+```powershell
+Add-LocalGroupMember -Group "Remote Desktop Users" -Member "HoneyPotter"
+```
+
+However, this is *strongly* discouraged. RDP is a serious attack surface - if
+you expose it to the Internet, you will be attacked immediately. Make sure the
+user has a very strong and hard-to-guess password, and preferably put some
+restriction on who can connect via RDP to this machine - e.g., by putting it
+behind a VPN, a Secure Gateway (if the machine is on an Active Directory
+network; something which is itself discouraged), or use a firewall rule to
+specify which particular IP addresses are allowed to connect to this machine via
+RDP - something along the lines of
+
+```powershell
+# List on the next line the IP addreses permitted to connect to this machine
+$AllowedIPs = @("IP address 1","IP address 2",...)
+Get-NetFirewallRule -DisplayGroup "Remote Desktop" | Disable-NetFirewallRule
+Get-NetFirewallRule -DisplayName "Restricted RDP" -ErrorAction SilentlyContinue | Remove-NetFirewallRule
+New-NetFirewallRule -DisplayName "Restricted RDP" -Direction Inbound -Protocol TCP -LocalPort 3389 -Action Allow -RemoteAddress $AllowedIPs -Profile Any
+```
+
+Log out of the Administrator account and log into the account of the newly
+created user HoneyPotter.
+
+## Step 4: Install the honeypot
+
+Open a PowerShell window and create a virtual environment. For modern versions
+of Python (i.e., 3.6+), use just
+
+```powershell
+PS C:\> python -m venv C:\pgsqlpot-env
+```
+
+For the obsolete Python 2.7, use
+
+```powershell
+PS C:\> pip install "virtualenv==20.15.1"
+PS C:\> virtualenv pgsqlpot-env
+```
+
+Then activate the virtual environment with
+
+```powershell
+PS C:\> .\pgsqlpot-env\Scripts\activate.ps1
+```
+
+and update `pip`
+
+```powershell
+(pgsqlpot-env) PS C:\> 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
+
+```powershell
+(pgsqlpot-env) PS C:\> 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:
+
+```powershell
+(pgsqlpot-env) PS C:\> pip install build --upgrade
+(pgsqlpot-env) PS C:\> git clone https://gitlab.com/bontchev/pgsqlpot.git
+(pgsqlpot-env) PS C:\> cd .\pgsqlpot
+(pgsqlpot-env) PS C:\pgsqlpot> python -m build
+(pgsqlpot-env) PS C:\pgsqlpot> pip install --prefer-binary "$((Get-Item dist\pgsqlpot-*-py2.py3-none-any.whl).FullName)[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:
+
+```powershell
+(pgsqlpot-env) PS C:\> mkdir .\pgsqlpot-workdir
+(pgsqlpot-env) PS C:\> cd .\pgsqlpot-workdir
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot init
+```
+
+This creates the `data/`, `docs/`, `etc/`, and `log/` subdirectories. It also
+copies the files `test.py` (for verifying the honeypot is working), `Dockerfile`,
+and `geoipupdtask.ps1` (for scheduling automatic GeoIP database updates) 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 the `*.cfg.base` and the `*.cfg` files are read on
+startup but entries from the `*.cfg` files take precedence. The `*.base` files
+contain the default settings and should not be edited — they may be overwritten
+by future updates. All your customisations should go into the `*.cfg` files.
+
+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` file
+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 `READMEWIN.md` file in the subdirectory corresponding
+to the plugin inside the `docs\` directory.
+
+**Note on testing:** The default blacklist excludes the logging of connections
+from `127.0.0.1` and `192.168.0.0/16`. If you run just `test.py` (with no
+arguments) 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 the
+option `-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:
+
+```powershell
+(pgsqlpot-env) PS C:\> cd C:\pgsqlpot-workdir
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot start
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot status
+The honeypot is running (PID: 12345).
+```
+
+To run in the foreground (useful for debugging):
+
+```powershell
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot run
+```
+
+Stop it by pressing Ctrl-C.
+
+To stop the honeypot when it is running in the background, use
+
+```powershell
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot stop
+Stopping honeypot (PID 12345)... Stopped.
+```
+
+To verify that the honeypot is working correctly, run the test script (see
+the note about the blacklist above):
+
+```powershell
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> python test.py -u Foo -p Bar -H $(Invoke-RestMethod -Uri "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
+
+To create a task that starts the honeypot at boot time, open a PowerShell
+window as `Administrator` and enter:
+
+```powershell
+$Trigger = New-ScheduledTaskTrigger -AtStartup
+$Action = New-ScheduledTaskAction -Execute "C:\pgsqlpot-env\Scripts\pgsqlpot.exe" -Argument "start" -WorkingDirectory "C:\pgsqlpot-workdir"
+$Settings = New-ScheduledTaskSettingsSet -Hidden -Compatibility Win8
+Register-ScheduledTask -Action $Action -TaskName "PGSQLPpot" -Trigger $Trigger -Settings $Settings -User "HoneyPotter" -Password "PASSWORD"
+```
+
+Make sure to supply the password for the user `HoneyPotter` instead of
+"PASSWORD", and adjust the paths if you used different locations.
+
+In order for the user `HoneyPotter` to be able to run tasks at startup, though,
+he must have the `SeBatchLogonRight` right - which, by default, he does not.
+Unfortunately, there is no way to give him this right via pure PowerShell, so
+you'll have to do it from the GUI.
+
+Log in as Administrator, if not already logged in as such, open the `Start` menu
+and in the search field enter `secpol.msc` and press Enter. This will start the
+Local Security Policy editor. Find
+`Local Policies -> User Rights Assignment -> Log on as a batch job` and
+double-click it. Press `Add User or Group` enter the user name `HoneyPotter`
+and press the two `OK` buttons to close the dialogs.
+
+## 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/READMEWIN.md)|mysql
+NLCV API|nlcvapi
+[PostgreSQL](postgres/READMEWIN.md)|postgres
+Redis|redisdb
+RethinkDB|rethinkdblog
+[Slack](slack/README.md)|slack
+Socket|socketlog
+[SQLite3](sqlite3/READMEWIN.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]\READMEWIN.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)
+
+Log in as the user `HoneyPotter`, open a PowerShell window, activate the
+virtual environment, get the honeypot version number, deactivate the virtual
+environment, and build the Docker image from the working directory (the
+`Dockerfile` was placed there by `pgsqlpot init`):
+
+```powershell
+PS C:\> cd C:\pgsqlpot-workdir
+PS C:\pgsqlpot-workdir> .\pgsqlpot-env\scripts\activate.ps1
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> $version = pgsqlpot --version
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> deactivate
+
+# Build with all plugins (default)
+PS C:\pgsqlpot-workdir> docker build --build-arg VERSION=$version -t pgsqlpot .
+
+# Or build with specific plugins only (e.g., only mysql and kafka)
+PS C:\pgsqlpot-workdir> docker build --build-arg VERSION=$version --build-arg PLUGINS=mysql,kafka -t pgsqlpot .
+
+# Run, mounting your config and data directories
+PS C:\pgsqlpot-workdir> docker run -d -p 5432:5432/tcp `
+  -v ${PWD}\etc\honeypot.cfg:/pgsqlpot/etc/honeypot.cfg `
+  -v ${PWD}\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:
+
+```powershell
+PS C:\> cd C:\pgsqlpot-workdir
+PS C:\pgsqlpot-workdir> C:\pgsqlpot-env\Scripts\activate.ps1
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot stop
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pip install --prefer-binary --upgrade pgsqlpot[plugin_list]
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> pgsqlpot init
+(pgsqlpot-env) PS C:\pgsqlpot-workdir> 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.

pgsqlpot/data/docs/PLUGINS.md

@@ -0,0 +1,21 @@
+# Creating output plugins for the honeypot
+
+To create additional output plugins, place Python modules in this directory.
+
+The plugins need to subclass the class `core.output.Output` and to define at
+least the methods `start`, `stop` and `write`:
+
+```python
+from core import output
+
+class Output(output.Output):
+
+    def start(self):
+        pass
+
+    def stop(self):
+        pass
+
+    def write(self, event):
+        pass
+```

pgsqlpot/data/docs/TODO.md

@@ -0,0 +1,8 @@
+# Planned Future Improvements
+
+* Additional output plugins for:
+  * DShield
+  * Graylog
+  * InfluxDB
+  * Oracle Cloud
+  * Splunk

pgsqlpot/data/docs/datadog/README.md

@@ -0,0 +1,32 @@
+# Sending the Output of the Honeypot to a Datadog Log Management Account
+
+This guide describes how to configure and send cowrie outputs to Datadog Log Management.
+
+- [Sending the Output of the Honeypot to a Datadog Log Management Account](#sending-the-output-of-the-honeypot-to-a-datadog-log-management-account)
+  - [Prerequisites](#prerequisites)
+  - [Configuration of the Datadog output module](#configuration-of-the-datadog-output-module)
+  - [Datadog Configuration](#datadog-configuration)
+
+## Prerequisites
+
+- Working honeypot installation
+- Existing Datadog account.
+
+## Configuration of the Datadog output module
+
+- Modify the file `etc/honeypot.cfg` and uncomment the `[output_datadog]` section.
+- Set the `url` variable to `https://http-intake.logs.datadoghq.eu/api/v2/logs`, if
+you're in the EU - or to `https://http-intake.logs.datadoghq.com/api/v2/logs`, if
+you reside elsewhere.
+- Add an API Key. You may generate one for your organisation
+[from here](https://app.datadoghq.eu/organization-settings/api-keys), if you're
+in the EU, or [from here](https://app.datadoghq.eu/organization-settings/api-keys),
+if you reside elsewhere.
+- Optionally customize the variables `ddsource`, `ddtags`, `service` and `hostname`.
+Otherwise, the defaults are respectively `pgsqlpot`, `env:prod`, `honeypot` and the
+hostname of the machine, running the honeypot.
+- Set the variable `enabled` to `true`.
+
+## Datadog Configuration
+
+JSON logs are handled without further configuration in Datadog.

pgsqlpot/data/docs/discord/README.md

@@ -0,0 +1,58 @@
+# Sending the output of the honeypot to a Discord channel
+
+This guide describes how to send the reports from the honeypot to a Discord
+channel.
+
+- [Sending the output of the honeypot to a Discord channel](#sending-the-output-of-the-honeypot-to-a-discord-channel)
+  - [Prerequisites](#prerequisites)
+  - [Select your Discord server](#select-your-discord-server)
+  - [Create a channel for the honeypot's reports](#create-a-channel-for-the-honeypots-reports)
+  - [Configure the honeypot](#configure-the-honeypot)
+
+## Prerequisites
+
+- Working honeypot installation
+- A Discord account
+
+## Select your Discord server
+
+- Log into your Discord account
+- If you don't have your own server yet, create one by cling the "+" icon on
+the bar on the left. The newly created server will appear on that bar.
+- Select your server by clicking its icon on the bar on the left.
+
+## Create a channel for the honeypot's reports
+
+- On the leftmost column of the page (to the right of the bar where the
+server's icon is), select the "+" sign in the "Text Channels" section.
+- Give the channel a name suggesting that the honeypot's reports will
+appear there - e.g., `pgsqlpot`. The channel will appear in the "Text
+Channels" section.
+- Click the channel's name and select the gear icon to open the "Edit
+Channel" dialog.
+- Click "Integrations" on the left, in order to switch to the channel's
+integrations page.
+- Click on the "Webhooks" button and then on "New Webhook". By default, the
+new webhook will be named "Captain Hook".
+- Click the newly created webhook to change is properties. You can change
+its name to something more meaningful, like `PGSQLPot` - it will be the name
+of the "user" posting to the channel.
+- While the webhook's properties are still open, click on the "Copy Webhook
+URL" button. This will copy the URL that you need to put in the honeypot's
+configuration section for Discord.
+- Press Esc to close the editor of the channel's properties. You can leave
+Discord now.
+
+## Configure the honeypot
+
+- Stop the honeypot, if it is running.
+- Open the file `etc/honeypot.cfg` and uncomment the `[output_discord]`
+section in it.
+- Set the variable `url` webhook URL that you have obtained in the previous
+section.
+- Optionally, set the variable `delay` to something different than the default
+value of `2.0`. This is the delay, in seconds, between any two messages sent
+to the bot. Note that if this number is smaller than `1.0`, DIscord's rate
+limiting will cause it to return `429 Too many requests` errors.
+- Set the variable `enabled` to `true`.
+- Launch the honeypot.