# Installation guide (on Ubuntu/Debian)

(For installation on Windows, see the corresponding [installation document](INSTALLWIN.md))

- [Installation guide (on Ubuntu/Debian)](#installation-guide-on-ubuntudebian)
  - [Step 1: Install the dependencies](#step-1-install-the-dependencies)
  - [Step 2: Open port 5555 for TCP traffic](#step-2-open-port-5555-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: 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 5555 for TCP traffic

If TCP port 5555 is not already opened for incoming connections on your
firewall and router, you must open it now:

```bash
sudo ufw allow 5555/tcp
```

If your honeypot machine is behind a NAT router, you must also forward port
5555 to it. Consult your router's instruction manual.

## Step 3: Create a user account

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

```bash
sudo adduser --disabled-password adbhoneypot
sudo su - adbhoneypot
```

## Step 4: Install the honeypot

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

```bash
python -m venv adbhoneypot-env
```

For the obsolete Python 2.7 use

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

Then activate the virtual environment with

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

and update `pip`

```bash
(adbhoneypot-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
(adbhoneypot-env) $ pip install --prefer-binary adbhoneypot[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
(adbhoneypot-env) $ pip install build --upgrade
(adbhoneypot-env) $ git clone https://gitlab.com/bontchev/adbhoneypot.git
(adbhoneypot-env) $ cd adbhoneypot
(adbhoneypot-env) $ python -m build
(adbhoneypot-env) $ pip install --prefer-binary "dist/adbhoneypot-*-py2.py3-none-any.whl[plugin_list]"
```

where `plugin_list` is as described in the previous section.

## Step 5: Initialize the working directory

```bash
(adbhoneypot-env) $ mkdir ~/adbhoneypot-workdir
(adbhoneypot-env) $ cd ~/adbhoneypot-workdir
(adbhoneypot-env) $ adbhoneypot init
```

This creates the `data/`, `dl/`, `docs/`, `etc/`, and `log/` subdirectories
and populates them with the default configuration file and documentation.
It also copies `test.py` (for verifying the honeypot works) 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 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, to enable JSON logging and save captured files in `dl/`:

```ini
[honeypot]
download_path = dl

[output_jsonlog]
enabled = true
logfile = log/adbhoneypot.json
epoch_timestamp = true
```

## Step 7: Start the honeypot

```bash
(adbhoneypot-env) $ cd ~/adbhoneypot-workdir
(adbhoneypot-env) $ adbhoneypot start
```

To check the status:

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

To run in the foreground (useful for debugging):

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

Press Ctrl-C to stop.

To stop the background honeypot:

```bash
(adbhoneypot-env) $ adbhoneypot stop
```

## Step 8: Testing the honeypot

To verify the honeypot is working, run the test script:

```bash
python test.py
```

(The test script connects to `127.0.0.1`. If you have configured a blacklist
that includes `127.0.0.1`, you may need to clear it temporarily, or connect
from to your external IP.)

If the honeypot is working correctly, the testing script should generate
something like this:

```test.py
ADBHoneypot Test Client v1.0.1
Connecting to 127.0.0.1:5555...
Connected.

[TEST] CNXN handshake...
  PASS: CNXN OK: device_id='device::ro.product.name=hlteuc;ro.product.model=SAMSUNG-SM-N900A;ro.product.device=hlteatt;features=cmd,stat_v2,shell_v2'
[TEST] Shell: echo hello...
  PASS: Shell response: 'hello'
[TEST] Shell: busybox echo hello...
  PASS: Shell response: 'hello'
[TEST] Shell: id...
  PASS: Shell response: '#'
[TEST] Shell: wget...
  PASS: Download OK: data-76b40bbe3be56852....raw
[TEST] Shell: curl...
  PASS: Download OK: data-76b40bbe3be56852....raw
[TEST] Shell: busybox wget...
  PASS: Download OK: data-76b40bbe3be56852....raw
[TEST] File push...
  PASS: File push OK: /sdcard/test.txt (11 bytes)

8 passed, 0 failed.
```

In general, the script supports the following command-line options:

```test.py
usage: test.py [-h] [-v] [-H HOST] [-P PORT] [-d DLDIR] [-V]

Test connection to an ADB honeypot

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -H HOST, --host HOST  Host to connect to (default: 127.0.0.1)
  -P PORT, --port PORT  Port to connect to (default: 5555)
  -d DLDIR, --dldir DLDIR
                        Honeypot download directory (default: dl)
  -V, --verbose         Show raw packet details
```

## 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}/adbhoneypot-workdir && ${HOME}/adbhoneypot-env/bin/adbhoneypot 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 a log file
if configured). Additional output plugins can be configured to record the data
in other ways. Supported output plugins:

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 `adbhoneypot`
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 `adbhoneypot` 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 adbhoneypot
```

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

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

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

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

# Run, mounting your config and data directories
docker run -d -p 5555:5555 \
  -v ${HOME}/adbhoneypot-workdir/etc/honeypot.cfg:/adbhoneypot/etc/honeypot.cfg \
  -v ${HOME}/adbhoneypot-workdir/data:/adbhoneypot/data \
  adbhoneypot
```

## 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 ADBHONEYPOT_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 the honeypot in the background
    status              Show running status
```

All subcommands accept `-w / --workdir DIR` to specify the working directory
explicitly, overriding the `ADBHONEYPOT_WORKDIR` environment variable and the
current directory.

The `run`, `start`, and `restart` subcommands also accept the options

```bash
  -a ADDR, --addr ADDR        Address to bind to (default: 0.0.0.0)
  -p PORT, --port PORT        Port to listen on (default: 5555)
  -d DLFOLDER, --dlfolder DIR Directory for uploaded samples (default: dl)
  -l LOGFILE, --logfile FILE  Log file (default: stdout)
  -s SENSOR, --sensor NAME    Sensor name (default: hostname)
  -b, --debug                 Produce verbose output
```

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

where `[plugin_list]` is as explained above.

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