# 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 5060 for UDP traffic](#step-2-open-port-5060-for-udp-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: Testing the honeypot](#step-8-testing-the-honeypot)
  - [Step 9: Make the honeypot start at boot time](#step-9-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 5060 for UDP traffic

If UDP port 5060 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 'UDP-5060' -Profile @('Domain', 'Private') -Direction Inbound -Action Allow -Protocol UDP -LocalPort 5060
```

## 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:\siphoney-env
```

For the obsolete Python 2.7, use

```powershell
PS C:\> pip install "virtualenv==20.15.1"
PS C:\> virtualenv siphoney-env
```

Then activate the virtual environment with

```powershell
PS C:\> .\siphoney-env\Scripts\activate.ps1
```

and update `pip`

```powershell
(siphoney-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
(siphoney-env) PS C:\> pip install --prefer-binary siphoney[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
(siphoney-env) PS C:\> pip install build --upgrade
(siphoney-env) PS C:\> git clone https://gitlab.com/bontchev/siphoney.git
(siphoney-env) PS C:\> cd .\siphoney
(siphoney-env) PS C:\siphoney> python -m build
(siphoney-env) PS C:\siphoney> pip install --prefer-binary "$((Get-Item dist\siphoney-*-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
(siphoney-env) PS C:\> mkdir .\siphoney-workdir
(siphoney-env) PS C:\> cd .\siphoney-workdir
(siphoney-env) PS C:\siphoney-workdir> siphoney init
```

This creates the `data/`, `docs/`, `etc/`, and `log/` subdirectories. It
also copies the files `test.*` (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 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/siphoney.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
(siphoney-env) PS C:\> cd C:\siphoney-workdir
(siphoney-env) PS C:\siphoney-workdir> siphoney start
(siphoney-env) PS C:\siphoney-workdir> siphoney status
The honeypot is running (PID: 12345).
```

To run in the foreground (useful for debugging):

```powershell
(siphoney-env) PS C:\siphoney-workdir> siphoney run
```

Stop it by pressing Ctrl-C.

To stop the honeypot when it is running in the background, use

```powershell
(siphoney-env) PS C:\siphoney-workdir> siphoney stop
Stopping honeypot (PID 12345)... Stopped.
```

## Step 8: Testing the honeypot

Once the honeypot is set up and running at a particular IP address, you can
use the program `test.py` to test that it is working.

The general usage of the program is:

```bash
usage: test.py [-h] [-v] [-P PORT] [-H HOST] [-s SENDER] [-t TO] [-c CALLID] [-r REQUEST]

Test the SIPHoney honeypot

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -P PORT, --port PORT  Port to send data to (default: 5060)
  -H HOST, --host HOST  Host to communicate with (default: 127.0.0.1)
  -s SENDER, --sender SENDER
                        From address (default: "sipvicious"<sip:100@1.1.1.1>)
  -t TO, --to TO        To address (default: <sip:user_2@test.test>)
  -c CALLID, --callid CALLID
                        Call ID (default: 1@0.0.0.0)
  -r REQUEST, --request REQUEST
                        Call ID (default: OPTIONS)
```

To test the honeypot with all the requests it supports, use the script `test.ps1`
like this:

```powershell
PS C:\siphoney-workdir> .\test.ps1 >output
PS C:\siphoney-workdir> Compare-Object -ReferenceObject (Get-Content .\docs\baseline) -DifferenceObject (Get-Content .\output) | Select-String -Pattern 'Via:' -SimpleMatch -NotMatch
```

The contents of the created file `output` should be identical to the existing
file `docs\baseline` (except maybe the `Via` lines, which is why they're
excluded from the comparison).

If you are running the honeypot on `127.0.0.1`, make sure to change the
`blacklist=` option in `etc\honeypot.cfg` because by default the honeypot
ignores the requests coming from that IP address (or from the internal
network, `192.168.*.*`)

## Step 9: 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:\siphoney-env\Scripts\siphoney.exe" -Argument "start" -WorkingDirectory "C:\siphoney-workdir"
$Settings = New-ScheduledTaskSettingsSet -Hidden -Compatibility Win8
Register-ScheduledTask -Action $Action -TaskName "SIPHoney" -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 `siphoney init`):

```powershell
PS C:\> cd C:\siphoney-workdir
PS C:\siphoney-workdir> .\siphoney-env\scripts\activate.ps1
(siphoney-env) PS C:\siphoney-workdir> $version = siphoney --version
(siphoney-env) PS C:\siphoney-workdir> deactivate

# Build with all plugins (default)
PS C:\siphoney-workdir> docker build --build-arg VERSION=$version -t siphoney .

# Or build with specific plugins only (e.g., only mysql and kafka)
PS C:\siphoney-workdir> docker build --build-arg VERSION=$version --build-arg PLUGINS=mysql,kafka -t siphoney .

# Run, mounting your config and data directories
PS C:\siphoney-workdir> docker run -d -p 5060:5060/udp `
  -v ${PWD}\etc\honeypot.cfg:/siphoney/etc/honeypot.cfg `
  -v ${PWD}\data:/siphoney/data `
  siphoney
```

## 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 SIPHONEY_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 `SIPHONEY_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: 5060)
  -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:\siphoney-workdir
PS C:\siphoney-workdir> C:\siphoney-env\Scripts\activate.ps1
(siphoney-env) PS C:\siphoney-workdir> siphoney stop
(siphoney-env) PS C:\siphoney-workdir> pip install --prefer-binary --upgrade siphoney[plugin_list]
(siphoney-env) PS C:\siphoney-workdir> siphoney init
(siphoney-env) PS C:\siphoney-workdir> siphoney start
```

where `[plugin_list]` is as explained above.

Note that `siphoney 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.
