# 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 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

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 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, use:

```bash
sudo ufw allow 5060/udp
```

## Step 3: Create a user account

It is strongly recommended to run the honeypot as a dedicated non-root user
(named `siphoney` in our example), who cannot `sudo`:

```bash
$ sudo adduser --disabled-password siphoney
Adding user `siphoney' ...
Adding new group `siphoney' (1019) ...
Adding new user `siphoney' (1019) with group `siphoney' ...
Creating home directory `/home/siphoney' ...
Copying files from `/etc/skel' ...
Changing the user information for siphoney
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 - siphoney
```

## Step 4: Install the honeypot

Create a virtual environment. For modern versions of Python (i.e., 3.x), use
just

```bash
python -m venv siphoney-env
```

For the obsolete Python 2.7, use

```bash
pip install "virtualenv==20.15.1"
virtualenv siphoney-env
```

Then activate the virtual environment with

```bash
source siphoney-env/bin/activate
```

and update `pip`

```bash
(siphoney-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
(siphoney-env) $ 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:

```bash
(siphoney-env) $ pip install build --upgrade
(siphoney-env) $ git clone https://gitlab.com/bontchev/siphoney.git
(siphoney-env) $ cd siphoney
(siphoney-env) $ python -m build
(siphoney-env) $ pip install --prefer-binary "dist/siphoney-*-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
(siphoney-env) $ mkdir ~/siphoney-workdir
(siphoney-env) $ cd ~/siphoney-workdir
(siphoney-env) $ 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 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/siphoney.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
(siphoney-env) $ cd ~/siphoney-workdir
(siphoney-env) $ siphoney start
```

To check that the honeypot is running, use

```bash
(siphoney-env) $ siphoney status
The honeypot is running (PID: 12345).
```

To run in the foreground (useful for debugging):

```bash
(siphoney-env) $ siphoney run
```

Stop it by pressing Ctrl-C.

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

```bash
(siphoney-env) $ siphoney stop
Stopping the 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.sh`
like this:

```bash
cd ~/siphoney-workdir
./test.sh >output
diff -y --suppress-common-lines --strip-trailing-cr output docs/baseline | grep -Fv "Via:"
```

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. The `--strip-trailing-cr` option is used in case
one of the compared files has Windows end-of-line separators.

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

Edit the `crontab` jobs with your favourite editor:

```bash
crontab -e
```

and add the line:

```bash
@reboot cd ${HOME}/siphoney-workdir && ${HOME}/siphoney-env/bin/siphoney 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 `siphoney`
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 `siphoney` 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 siphoney
```

Then switch to the `siphoney` user and build the image from the working
directory (the `Dockerfile` was placed there by `siphoney init`):

```bash
sudo su - siphoney
cd ~/siphoney-workdir
source ~/siphoney-env/bin/activate
VERSION=$(siphoney --version)
deactivate

# Build with all plugins (default)
docker build --build-arg VERSION=$VERSION -t siphoney .

# Or build with specific plugins only, e.g., mysql and kafka:
docker build --build-arg VERSION=$VERSION --build-arg PLUGINS=mysql,kafka -t siphoney .

# Run, mounting your config and data directories
docker run -d -p 5060:5060/udp \
  -v ${HOME}/siphoney-workdir/etc/honeypot.cfg:/siphoney/etc/honeypot.cfg \
  -v ${HOME}/siphoney-workdir/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:

```bash
$ cd ~/siphoney-workdir
$ source ~/siphoney-env/bin/activate
(siphoney-env) $ siphoney stop
(siphoney-env) $ pip install --prefer-binary --upgrade siphoney[plugin_list]
(siphoney-env) $ siphoney init
(siphoney-env) $ 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.
