# Installation guide (on Windows)

(For installation on Ubuntu/Debian, 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 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

Log in as a user with Administrator privileges and install:

- **Python**. The latest Python 3.x is preferred, though Python 2.7 is
  supported. Download from [python.org](https://www.python.org/downloads/windows/).
  Install for all users and tick the option to add Python to the `PATH`.

- **Database server** (optional). If you want to send data to a local database
  server (e.g., MySQL), install it for all users.

- The latest **VS C++ redistributable** (required by some database output
  plugins). Download from
  [Microsoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist).

## Step 2: Open port 5555 for TCP traffic

Open a PowerShell window as Administrator and run:

```powershell
New-NetFirewallRule -DisplayName 'TCP-5555' -Profile @('Domain', 'Private') -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5555
```

## 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 "Honeypot Account"
Add-LocalGroupMember -Group "Users" -Member "HoneyPotter"
```

Replace `"PASSWORD"` with a strong password. Log in as that user to proceed.

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

For the obsolete Python 2.7, use

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

Then activate the virtual environment with

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

and update `pip`

```powershell
(adbhoneypot-env) PS C:\> python -m pip install pip --upgrade
```

### Installing from PyPI (recommended)

Installing from PyPI is very simple. Just use

```powershell
(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:

```powershell
(adbhoneypot-env) PS C:\> pip install build --upgrade
(adbhoneypot-env) PS C:\> git clone https://gitlab.com/bontchev/adbhoneypot.git
(adbhoneypot-env) PS C:\> cd .\adbhoneypot
(adbhoneypot-env) PS C:\adbhoneypot> python -m build
(adbhoneypot-env) PS C:\adbhoneypot> pip install --prefer-binary "$((Get-Item dist\adbhoneypot-*-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
(adbhoneypot-env) PS C:\> mkdir .\adbhoneypot-workdir
(adbhoneypot-env) PS C:\> cd .\adbhoneypot-workdir
(adbhoneypot-env) PS C:\adbhoneypot-workdir> 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 is working), `Dockerfile`, and
`geoipupdtask.ps1` (for scheduling automatic GeoIP database updates) into the
working directory.

## Step 6: Create a configuration file

Create `etc\honeypot.cfg` in the working directory. For example, to enable
JSON logging:

```ini
[honeypot]
download_path = dl

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

## Step 7: Start the honeypot

```cmd
(adbhoneypot-env) cd %USERPROFILE%\adbhoneypot-workdir
(adbhoneypot-env) adbhoneypot start
```

To check status:

```cmd
(adbhoneypot-env) adbhoneypot status
The honeypot is running (PID: 1234).
```

To run in the foreground for debugging:

```cmd
(adbhoneypot-env) adbhoneypot run
```

Press Ctrl-C to stop.

To stop the background honeypot:

```cmd
(adbhoneypot-env) adbhoneypot stop
```

## Step 8: Testing the honeypot

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

```powershell
PS C:\adbhoneypot-workdir> 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

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:\adbhoneypot-env\Scripts\adbhoneypot.exe" -Argument "start" -WorkingDirectory "C:\adbhoneypot-workdir"
$Settings = New-ScheduledTaskSettingsSet -Hidden -Compatibility Win8
Register-ScheduledTask -Action $Action -TaskName "ADBHoneyPot" -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 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/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)

**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:

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

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

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

```adbhoneypot
(adbhoneypot-env) PS C:\> cd C:\adbhoneypot-workdir
(adbhoneypot-env) PS C:\adbhoneypot-workdir> adbhoneypot stop
(adbhoneypot-env) PS C:\adbhoneypot-workdir> pip install --prefer-binary --upgrade adbhoneypot[plugin_list]
(adbhoneypot-env) PS C:\adbhoneypot-workdir> adbhoneypot init
(adbhoneypot-env) PS C:\adbhoneypot-workdir> 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.
