We are proud to announce the release of T-Pot 24.04! T-Pot 24.04 marks probably the largest change in the history of the project. While most of the changes have been made to the underlying platform some changes will be standing out in particular - a T-Pot ISO image will no longer be provided with the benefit that T-Pot will now run on multiple Linux distributions (Alma Linux, Debian, Fedora, OpenSuse, Raspbian, Rocky Linux, Ubuntu), Raspberry Pi (optimized) and macOS / Windows (limited).

1. Meet the system requirements. The T-Pot installation needs at least 8-16 GB RAM, 128 GB free disk space as well as a working (outgoing non-filtered) internet connection.
2. Download or use a running, supported distribution.
3. Install the ISO with as minimal packages / services as possible (ssh required)
4. Install curl: $ sudo [apt, dnf, zypper] install curl if not installed already
5. Run installer as non-root from $HOME:

   env bash -c "$(curl -sL https://github.com/telekom-security/tpotce/raw/master/install.sh)"
   

   • Follow instructions, read messages, check for possible port conflicts and reboot

• T-Pot - The All In One Multi Honeypot Platform
• TL;DR
• Table of Contents
• Disclaimer
• Technical Concept
  • Technical Architecture
  • Services
  • User Types
• System Requirements
  • Running in a VM
  • Running on Hardware
  • Running in a Cloud
  • Required Ports
• System Placement
• Installation
  • Choose your distro
  • Raspberry Pi 4 (8GB) Support
  • Get and install T-Pot
  • macOS & Windows
  • Installation Types
    • Standard / HIVE
    • Distributed
  • Uninstall T-Pot
• First Start
  • Standalone First Start
  • Distributed Deployment
  • Community Data Submission
  • Opt-In HPFEEDS Data Submission
• Remote Access and Tools
  • SSH
  • T-Pot Landing Page
  • Kibana Dashboard
  • Attack Map
  • Cyberchef
  • Elasticvue
  • Spiderfoot
• Configuration
  • T-Pot Config File
  • Customize T-Pot Honeypots and Services
• Maintenance
  • General Updates
  • Update Script
  • Known Issues
    • Docker Images Fail to Download
  • Start T-Pot
  • Stop T-Pot
  • T-Pot Data Folder
  • Log Persistence
  • Factory Reset
  • Show Containers
  • Blackhole
  • Add Users to Nginx (T-Pot WebUI)
  • Import and Export Kibana Objects
    • Export
    • Import
• Troubleshooting
  • Logs
  • RAM and Storage
• Contact
  • Issues
  • Discussions
• Licenses
• Credits
  • The developers and development communities of
• Testimonials

• You install and run T-Pot within your responsibility. Choose your deployment wisely as a system compromise can never be ruled out.
• For fast help research the Issues and Discussions.
• The software is designed and offered with best effort in mind. As a community and open source project it uses lots of other open source software and may contain bugs and issues. Report responsibly.
• Honeypots - by design - should not host any sensitive data. Make sure you don’t add any.
• By default, your data is submitted to Sicherheitstacho. You can disable this in the config (~/tpotce/docker-compose.yml) by removing the ewsposter section. But in this case sharing really is caring!

T-Pot offers docker images for the following honeypots …

• adbhoney,
• ciscoasa,
• citrixhoneypot,
• conpot,
• cowrie,
• ddospot,
• dicompot,
• dionaea,
• elasticpot,
• endlessh,
• glutton,
• hellpot,
• heralding,
• honeypots,
• honeytrap,
• ipphoney,
• log4pot,
• mailoney,
• medpot,
• redishoneypot,
• sentrypeer,
• snare,
• tanner,
• wordpot

… alongside the following tools …

• Autoheal a tool to automatically restart containers with failed healthchecks.
• Cyberchef a web app for encryption, encoding, compression and data analysis.
• Elastic Stack to beautifully visualize all the events captured by T-Pot.
• Elasticvue a web front end for browsing and interacting with an Elasticsearch cluster.
• Fatt a pyshark based script for extracting network metadata and fingerprints from pcap files and live network traffic.
• T-Pot-Attack-Map a beautifully animated attack map for T-Pot.
• P0f is a tool for purely passive traffic fingerprinting.
• Spiderfoot an open source intelligence automation tool.
• Suricata a Network Security Monitoring engine.

Technical Architecture

The source code and configuration files are fully stored in the T-Pot GitHub repository. The docker images are built and preconfigured for the T-Pot environment.

Services

T-Pot offers a number of services which are basically divided into five groups:

1. System services provided by the OS
   • SSH for secure remote access.
2. Elastic Stack
   • Elasticsearch for storing events.
   • Logstash for ingesting, receiving and sending events to Elasticsearch.
   • Kibana for displaying events on beautifully rendered dashboards.
3. Tools
   • NGINX provides secure remote access (reverse proxy) to Kibana, CyberChef, Elasticvue, GeoIP AttackMap, Spiderfoot and allows for T-Pot sensors to securely transmit event data to the T-Pot hive.
   • CyberChef a web app for encryption, encoding, compression and data analysis.
   • Elasticvue a web front end for browsing and interacting with an Elasticsearch cluster.
   • T-Pot Attack Map a beautifully animated attack map for T-Pot.
   • Spiderfoot an open source intelligence automation tool.
4. Honeypots
   • A selection of the 23 available honeypots based on the selected docker-compose.yml.
5. Network Security Monitoring (NSM)
   • Fatt a pyshark based script for extracting network metadata and fingerprints from pcap files and live network traffic.
   • P0f is a tool for purely passive traffic fingerprinting.
   • Suricata a Network Security Monitoring engine.

User Types

During the installation and during the usage of T-Pot there are two different types of accounts you will be working with. Make sure you know the differences of the different account types, since it is by far the most common reason for authentication errors.

T-Pot does require …

• an IPv4 address via DHCP or statically assigned
• a working, non-proxied, internet connection … for a successful installation and operation.

  If you need proxy support or otherwise non-standard features, you should check the docs of the supported Linux distro images and / or the Docker documentation.

Running in a VM

All of the supported Linux distro images will run in a VM which means T-Pot will just run fine. The following were tested / reported to work:

• UTM (Intel & Apple Silicon)
• VirtualBox
• VMWare Fusion and VMWare Workstation
• KVM is reported to work as well.

Some configuration / setup hints:

• While Intel versions run stable, Apple Silicon (arm64) support has known issues which in UTM may require switching Display to Console Only during initial installation of the OS and afterwards back to Full Graphics.
• During configuration you may need to enable promiscuous mode for the network interface in order for fatt, suricata and p0f to work properly.
• If you want to use a wifi card as a primary NIC for T-Pot, please be aware that not all network interface drivers support all wireless cards. In VirtualBox e.g. you have to choose the “MT SERVER” model of the NIC.

Running on Hardware

Running in a Cloud

T-Pot is tested on and known to run on …

• Telekom OTC using the post install method … others may work, but remain untested.

Required Ports

Besides the ports generally needed by the OS, i.e. obtaining a DHCP lease, DNS, etc. T-Pot will require the following ports for incoming / outgoing connections. Review the T-Pot Architecture for a visual representation. Also some ports will show up as duplicates, which is fine since used in different editions.

Ports and availability of SaaS services may vary based on your geographical location.

For some honeypots to reach full functionality (i.e. Cowrie or Log4Pot) outgoing connections are necessary as well, in order for them to download the attacker’s malware. Please see the individual honeypot’s documentation to learn more by following the links to their repositories.

Choose your distro

Choose a supported distro of your choice. It is recommended to use the minimum / netiso installers linked below and only install a minimalistic set of packages. SSH is mandatory or you will not be able to connect to the machine remotely.

Raspberry Pi 4 (8GB) Support

| Distribution Name | arm64 | |:—————————————————————–|:—————————————————————————————————————————————————-| | Raspberry Pi OS (64Bit, Lite) | download |

Get and install T-Pot

1. Clone the GitHub repository: $ git clone https://github.com/telekom-security/tpotce or follow the TL;DR and skip this section.
2. Change into the tpotce/ folder: $ cd tpotce
3. Run the installer as non-root: $ ./install.sh:
   • ⚠️ Depending on your Linux distribution of choice the installer will:
     • Change the SSH port to tcp/64295
     • Disable the DNS Stub Listener to avoid port conflicts with honeypots
     • Set SELinux to Monitor Mode
     • Set the firewall target for the public zone to ACCEPT
     • Add Docker’s repository and install Docker
     • Install recommended packages
     • Remove packages known to cause issues
     • Add the current user to the docker group (allow docker interaction without sudo)
     • Add dps and dpsw aliases (grc docker ps -a, watch -c "grc --colour=on docker ps -a)
     • Add la, ll and ls aliases (for exa, a improved ls command)
     • Add mi (for micro, a great alternative to vi and / or nano)
     • Display open ports on the host (compare with T-Pot required ports)
     • Add and enable tpot.service to /etc/systemd/system so T-Pot can automatically start and stop
4. Follow the installer instructions, you will have to enter your user (sudo or root) password at least once
5. Check the installer messages for errors and open ports that might cause port conflicts
6. Reboot: $ sudo reboot

macOS & Windows

Sometimes it is just nice if you can spin up a T-Pot instance on macOS or Windows, i.e. for development, testing or just the fun of it. As Docker Desktop is rather limited not all honeypot types or T-Pot features are supported. Also remember, by default the macOS and Windows firewall are blocking access from remote, so testing is limited to the host. For production it is recommended to run T-Pot on Linux.
To get things up and running just follow these steps:

1. Install Docker Desktop for macOS or Windows.
2. Clone the GitHub repository: git clone https://github.com/telekom-security/tpotce
3. Go to: cd ~/tpotce
4. Copy cp compose/mac_win.yml ./docker-compose.yml
5. Create a WEB_USER by running ~/tpotce/genuser.sh
6. Adjust the .env file by changing TPOT_OSTYPE=linux to either mac or win:

   # OSType (linux, mac, win)
   #  Most docker features are available on linux
   TPOT_OSTYPE=mac
   

7. You have to ensure on your own there are no port conflicts keeping T-Pot from starting up.
8. Start T-Pot: docker compose up or docker compose up -d if you want T-Pot to run in the background.
9. Stop T-Pot: CTRL-C (it if was running in the foreground) and / or docker compose down -v to stop T-Pot entirely.

Installation Types

Standard / HIVE

Distributed

The distributed version of T-Pot requires at least two hosts

• the T-Pot HIVE, the standard installation of T-Pot (install this first!),
• and a T-Pot SENSOR, which will host only the honeypots, some tools and transmit log data to the HIVE.
• The SENSOR will not start before finalizing the SENSOR installation as described in Distributed Deployment.

Uninstall T-Pot

Once the T-Pot Installer successfully finishes, the system needs to be rebooted (sudo reboot). Once rebooted you can log into the system using the user you setup during the installation of the system. Logins are according to the User Types:

• user: [<OS_USERNAME>]
• pass: [password]

You can login via SSH to access the command line: ssh -l <OS_USERNAME> -p 64295 <your.ip>:

• user: [<OS_USERNAME>]
• pass: [password, ssh key recommended]

You can also login from your browser and access the T-Pot WebUI and tools: https://<your.ip>:64297

• user: [<WEB_USER>]
• pass: [password]

Standalone First Start

Distributed Deployment

Once you have rebooted the SENSOR as instructed by the installer you can continue with the distributed deployment by logging into HIVE and go to cd ~/tpotce folder.

If you have not done already generate a SSH key to securely login to the SENSOR and to allow Ansible to run a playbook on the sensor:

1. Run ssh-keygen, follow the instructions and leave the passphrase empty:

   Generating public/private rsa key pair.
   Enter file in which to save the key (/home/<your_user>/.ssh/id_rsa):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/<your_user>/.ssh/id_rsa
   Your public key has been saved in /home/<your_user>/.ssh/id_rsa.pub
   

2. Deploy the key to the SENSOR by running ssh-copy-id -p 64295 <SENSOR_SSH_USER>@<SENSOR_IP>):

   /usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/<your_user>/.ssh/id_rsa.pub"
   The authenticity of host '[<SENSOR_IP>]:64295 ([<SENSOR_IP>]:64295)' can't be stablished.
   ED25519 key fingerprint is SHA256:naIDxFiw/skPJadTcgmWZQtgt+CdfRbUCoZn5RmkOnQ.
   This key is not known by any other names.
   Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
   /usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
   /usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
   <your_user>@172.20.254.124's password:
     
   Number of key(s) added: 1
     
   Now try logging into the machine, with:   "ssh -p '64295' '<your_user>@<SENSOR_IP>'"
   and check to make sure that only the key(s) you wanted were added.
   

3. As suggested follow the instructions to test the connection ssh -p '64295' '<your_user>@<SENSOR_IP>'.
4. Once the key is successfully deployed run ./deploy.sh and follow the instructions.

T-Pot is provided in order to make it accessible to everyone interested in honeypots. By default, the captured data is submitted to a community backend. This community backend uses the data to feed Sicherheitstacho. You may opt out of the submission by removing the # Ewsposter service from ~/tpotce/docker-compose.yml by following these steps:

1. Stop T-Pot services: systemctl stop tpot
2. Open ~/tpotce/docker-compose.yml: micro ~/tpotce/docker-compose.yml
3. Remove the following lines, save and exit micro (CTRL+Q): ```

   ewsposter: container_name: ewsposter restart: always depends_on: tpotinit: condition: service_healthy networks:

   • ewsposter_local environment:
   • EWS_HPFEEDS_ENABLE=false
   • EWS_HPFEEDS_HOST=host
   • EWS_HPFEEDS_PORT=port
   • EWS_HPFEEDS_CHANNELS=channels
   • EWS_HPFEEDS_IDENT=user
   • EWS_HPFEEDS_SECRET=secret
   • EWS_HPFEEDS_TLSCERT=false
   • EWS_HPFEEDS_FORMAT=json image: ${TPOT_REPO}/ewsposter:${TPOT_VERSION} pull_policy: ${TPOT_PULL_POLICY} volumes:
   • ${TPOT_DATA_PATH}:/data
   • ${TPOT_DATA_PATH}/ews/conf/ews.ip:/opt/ewsposter/ews.ip ```
4. Start T-Pot services: systemctl start tpot

Opt-In HPFEEDS Data Submission

As an Opt-In it is possible to share T-Pot data with 3rd party HPFEEDS brokers.

1. Follow the instructions here to stop the T-Pot services and open ~/tpotce/docker-compose.yml.
2. Scroll down to the ewsposter section and adjust the HPFEEDS settings to your needs.
3. If you need to add a CA certificate add it to ~/tpotce/data/ews/conf and set EWS_HPFEEDS_TLSCERT=/data/ews/conf/<your_ca.crt>.
4. Start T-Pot services: systemctl start tpot.

SSH

According to the User Types you can login via SSH to access the command line: ssh -l <OS_USERNAME> -p 64295 <your.ip>:

• user: [<OS_USERNAME>]
• pass: [password]

T-Pot Landing Page

According to the User Types you can open the T-Pot Landing Page from your browser via https://<your.ip>:64297:

• user: [<WEB_USER>]
• pass: [password]

Kibana Dashboard

On the T-Pot Landing Page just click on Kibana and you will be forwarded to Kibana. You can select from a large variety of dashboards and visualizations all tailored to the T-Pot supported honeypots.

Attack Map

On the T-Pot Landing Page just click on Attack Map and you will be forwarded to the Attack Map. Since the Attack Map utilizes web sockets you may need to re-enter the <WEB_USER> credentials.

Cyberchef

On the T-Pot Landing Page just click on Cyberchef and you will be forwarded to Cyberchef.

Elasticvue

On the T-Pot Landing Page just click on Elastivue and you will be forwarded to Elastivue.

On the T-Pot Landing Page just click on Spiderfoot and you will be forwarded to Spiderfoot.

T-Pot Config File

T-Pot offers a configuration file providing variables not only for the docker services (i.e. honeypots and tools) but also for the docker compose environment. The configuration file is hidden in ~/tpoce/.env. There is also an example file (env.example) which holds the default configuration.
Before the first start run ~/tpotce/genuser.sh or setup the WEB_USER manually as described here.

Customize T-Pot Honeypots and Services

In ~/tpotce/compose you will find everything you need to adjust the T-Pot Standard / HIVE installation:

customizer.py
mac_win.yml
mini.yml
mobile.yml
raspberry_showcase.yml
sensor.yml
standard.yml
tpot_services.yml

1. Stop T-Pot with systemctl stop tpot.
2. Copy the docker compose file cp ~/tpotce/compose/<dockercompose.yml> ~/tpotce/docker-compose.yml.
3. Start T-Pot with systemctl start tpot.

To create your customized docker compose file:

1. Go to cd ~/tpotce/compose.
2. Run python3 customizer.py.
3. The script will guide you through the process of creating your own docker-compose.yml. As some honeypots and services occupy the same ports it will check if any port conflicts are present and notify regarding the conflicting services. You then can resolve them manually by adjusting docker-compose-custom.yml or re-run the script.
4. Stop T-Pot with systemctl stop tpot.
5. Copy the custom docker compose file: cp docker-compose-custom.yml ~/tpotce and cd ~/tpotce.
6. Check if everything works by running docker-compose -f docker-compose-custom.yml up. In case of errors follow the Docker Compose Specification for mitigation. Most likely it is just a port conflict you can adjust by editing the docker compose file.
7. If everything works just fine press CTRL-C to stop the containers and run docker-compose -f docker-compose-custom.yml down -v.
8. Replace docker compose file with the new and successfully tested customized docker compose file mv ~/tpotce/docker-compose-custom.yml ~/tpotce/docker-compose.yml.
9. Start T-Pot with systemctl start tpot.

General Updates

Update Script

T-Pot releases are offered through GitHub and can be pulled using ~/tpotce/update.sh.
If you made any relevant changes to the T-Pot config files make sure to create a backup first!
Updates may have unforeseen consequences. Create a backup of the machine or the files most valuable to your work!

The update script will …

• mercilessly overwrite local changes to be in sync with the T-Pot master branch
• create a full backup of the ~/tpotce folder
• update all files in ~/tpotce to be in sync with the T-Pot master branch
• restore your custom ews.cfg from ~/tpotce/data/ews/conf and the T-Pot configuration (~/tpotce/.env).

Known Issues

Docker Images Fail to Download

Some time ago Docker introduced download rate limits. If you are frequently downloading Docker images via a single or shared IP, the IP address might have exhausted the Docker download rate limit. Login to your Docker account to extend the rate limit.

T-Pot Networking Fails

T-Pot is designed to only run on machines with a single NIC. T-Pot will try to grab the interface with the default route, however it is not guaranteed that this will always succeed. At best use T-Pot on machines with only a single NIC.

Start T-Pot

Stop T-Pot

T-Pot Data Folder

Log Persistence

Factory Reset

All log data stored in the T-Pot Data Folder (except for Elasticsearch indices, of course) can be erased by running clean.sh. Sometimes things might break beyond repair and it has never been easier to reset a T-Pot to factory defaults (make sure to enter cd ~/tpotce).

1. Stop T-Pot using systemctl stop tpot.
2. Move / Backup the ~/tpotce/data folder to a safe place (this is optional, just in case).
3. Delete the ~/tpotce/data folder using sudo rm -rf ~/tpotce/data.
4. Reset T-Pot to the last fetched commit:

   cd ~/tpotce/
   git reset --hard
   

5. Now you can run ~/tpotce/install.sh.

Show Containers

Blackhole

Add Users to Nginx (T-Pot WebUI)

Import and Export Kibana Objects

Some T-Pot updates will require you to update the Kibana objects. Either to support new honeypots or to improve existing dashboards or visualizations. Make sure to export first so you do not loose any of your adjustments.

Export

1. Go to Kibana
2. Click on “Stack Management”
3. Click on “Saved Objects”
4. Click on “Export objects"
5. Click on “Export all” This will export a NDJSON file with all your objects. Always run a full export to make sure all references are included.

Import

1. Download the NDJSON file and unzip it.
2. Go to Kibana
3. Click on “Stack Management”
4. Click on “Saved Objects”
5. Click on “Import” and leave the defaults (check for existing objects and automatically overwrite conflicts) if you did not make personal changes to the Kibana objects.
6. Browse for NDJSON file When asked: “If any of the objects already exist, do you want to automatically overwrite them?” you answer with “Yes, overwrite all”.

Logs

• Check if your containers are running correctly: dps
• Check if your system resources are not exhausted: htop, docker stats
• Check if there is a port conflict:

  systemctl stop tpot
  grc netstat -tulpen
  mi ~/tpotce/docker-compose.yml
  docker-compose -f ~/tpotce/docker-compose.yml up
  CTRL+C
  docker-compose -f ~/tpotce/docker-compose.yml down -v
  

• Check individual container logs: docker logs -f <container_name>
• Check tpotinit log: cat ~/tpotce/data/tpotinit.log

RAM and Storage

The Elastic Stack is hungry for RAM, specifically logstash and elasticsearch. If the Elastic Stack is unavailable, does not receive any logs or simply keeps crashing it is most likely a RAM or storage issue.
While T-Pot keeps trying to restart the services / containers run docker logs -f <container_name> (either logstash or elasticsearch) and check if there are any warnings or failures involving RAM.

T-Pot is provided as is open source without any commitment regarding support (see the disclaimer).

Issues

Please report issues (errors) on our GitHub Issues, but troubleshoot first. Issues not providing information to address the error will be closed or converted into discussions.

Discussions

General questions, ideas, show & tell, etc. can be addressed on our GitHub Discussions.

Without open source and the development community we are proud to be a part of, T-Pot would not have been possible! Our thanks are extended but not limited to the following people and organizations:

The developers and development communities of

• adbhoney
• ciscoasa
• citrixhoneypot
• conpot
• cowrie
• ddospot
• dicompot
• dionaea
• docker
• elasticpot
• elasticsearch
• elasticvue
• endlessh
• ewsposter
• fatt
• glutton
• hellpot
• heralding
• honeypots
• honeytrap
• ipphoney
• kibana
• logstash
• log4pot
• mailoney
• maltrail
• medpot
• p0f
• redishoneypot
• sentrypeer
• spiderfoot
• snare
• tanner
• suricata
• wordpot

The following companies and organizations

• docker
• elastic.io
• honeynet project

Thank you for playing 💖