Deployment of the T-Pot Security Platform represents a strategic shift from passive defense to active deception within high-availability environments. In complex technical stacks such as energy grids, water treatment facilities, or distributed cloud architectures, visibility into lateral movement and zero-day exploitation attempts is often obscured by high noise-to-signal ratios. The T-Pot Security Platform solves this visibility gap by consolidating multiple honeypot daemons into a single, Docker-encapsulated ecosystem. This approach permits infrastructure auditors to capture, analyze, and visualize adversarial maneuvers in real time. By mimicking vulnerable services across diverse protocols, T-Pot provides an early warning system that identifies malicious payloads before they reach production assets. The platform functions as a sophisticated sensor network; it converts raw network traffic into structured intelligence via an integrated ELK stack. This manual provides the technical specifications and execution protocols necessary to deploy T-Pot as a hardened security appliance within a professional infrastructure.
Technical Specifications
| Requirement | Default Port/Operating Range | Protocol/Standard | Impact Level (1-10) | Recommended Resources |
| :— | :— | :— | :— | :— |
| Management Access | 64297 | SSH / TCP | 10 | 8+ CPU Cores (Physical) |
| Web Interface (Kibana) | 64295 | HTTPS / TLS 1.3 | 9 | 16GB – 128GB RAM (ECC) |
| Honeypot Services | 1-64294 | Multiple (TCP/UDP) | 8 | 256GB NVMe SSD |
| Log Transformation | Internal | JSON / Syslog | 7 | 10Gbps NIC |
| Data Persistence | N/A | Docker Volume | 8 | RAID 1 or RAID 10 |
The Configuration Protocol
Environment Prerequisites:
Successful implementation requires a clean installation of Debian 11 or 12 (Bullseye or Bookworm). The underlying hardware or virtual machine must support virtualization extensions (VT-x or AMD-V) to manage containerized overhead and maintain low latency during high-concurrency attacks. A minimum of 16GB of RAM is mandatory to support the simultaneous execution of the ELK stack and nineteen separate honeypot containers. Network configuration must allow for two distinct zones: a management zone for administrative access and a “dirty” zone for enticing adversarial traffic. All users must have sudo privileges or root access to modify kernel-level network parameters.
Section A: Implementation Logic:
The engineering design of the T-Pot Security Platform relies on the principle of isolation through containerization. By utilizing Docker, the platform maintains an idempotent state; if a honeypot service is compromised or crashed by a complex exploit payload, the container can be instantly reset without affecting the host operating system. The platform employs a specialized NAT (Network Address Translation) logic to redirect incoming traffic from standard ports (e.g., 22, 80, 445) into specific honeypot containers while moving the actual management services to high-numbered ports. This prevents the “observer effect” where an attacker might detect the presence of a monitoring system based on non-standard management signatures.
Step-By-Step Execution
Step 1: System Baseline and Repository Synchronization
The first requirement is to synchronize the local package index with the upstream repositories to ensure all security patches are current.
Execute: sudo apt update && sudo apt upgrade -y
System Note: This command updates the Debian kernel and core libraries. Consistency in the kernel version is vital for Docker hardware abstraction and cgroup management. Failure to update may lead to signal-attenuation in the data pipeline if the Docker daemon encounters legacy kernel bugs.
Step 2: Resource Acquisition and Installer Initialization
Clone the official T-Pot repository from the Telekom Security GitHub infrastructure.
Execute: git clone https://github.com/telekom-security/tpotce && cd tpotce/iso/installer/
System Note: This action downloads the installation scripts. Use chmod +x install.sh to ensure the script has execution permissions. This script is the primary logic controller for the deployment; it validates system resources and hardware compatibility.
Step 3: Execution of the Deployment Script
Initiate the interactive installer to configure the platform type and administrative credentials.
Execute: sudo ./install.sh –type=user
System Note: The installer modifies the /etc/ssh/sshd_config file to change the default SSH port to 64297. It also installs the Docker engine and pulls the necessary images for Cowrie, Dionaea, Honeytrap, and other daemons. This process modifies the system’s iptables to handle complex packet routing between the physical NIC and the virtual Docker bridge.
Step 4: Verification of Service Concurrency
After the mandatory reboot, verify that all honeypot containers are operational and communicating with the centralized logging service.
Execute: sudo /opt/tpot/bin/dps.sh
System Note: This diagnostic tool queries the Docker daemon to check the status of each container. It ensures that the throughput of the ELK stack is sufficient to handle incoming JSON payloads. If a container shows a status other than “Up”, the system architect must investigate local log files for port conflicts.
Step 5: Firewall and Network Encapsulation
Configure the host-based firewall to restrict management access to trusted IP ranges while remaining open for “dirty” traffic.
Execute: sudo ufw allow from [Admin_IP] to any port 64295,64297 proto tcp
System Note: Precise firewalling prevents the T-Pot management interface from being indexed by automated scanners. It enforces strict access control at the network layer while leaving the lower-range ports exposed to the public internet for data collection.
Section B: Dependency Fault-Lines:
Installation failures typically occur due to occupied ports or insufficient memory. If a service like Apache or Nginx is already running on the host, the T-Pot installer will fail during the container binding phase. Always ensure that the command netstat -tulpn shows no listeners on ports 22, 80, or 443 before starting the installation. Another common bottleneck is the thermal-inertia of high-density SSDs during massive logging events: if the I/O wait time exceeds 10%, the Logstash service may drop packets, leading to incomplete forensic data.
THE TROUBLESHOOTING MATRIX
Section C: Logs & Debugging:
When the platform fails to visualize data, the architect must trace the log flow from the individual honeypot to the Elasticsearch index. Use the following hierarchy for debugging:
1. Honeypot Logs: Located at /data/[honeypot]/log/. Check these for raw capture errors or payload exceptions.
2. Docker Logs: Execute docker logs [container_name] to view standard output and error streams. This is critical for identifying container crashes caused by malformed packets.
3. Logstash Pipeline: Verify the health of the transformation engine at /var/log/tpot/logstash.log. This log often reveals mapping errors or JSON parsing failures.
4. Elasticsearch Health: Monitor the cluster status with curl -X GET “localhost:9200/_cluster/health?pretty”. A status of “red” indicates missing shards or disk space exhaustion.
If the Kibana dashboard at https://[IP]:64295 is unreachable, verify the status of the tpot service using systemctl status tpot. If the service is active but the web interface is down, check for port 64295 conflicts or TLS certificate expiration.
OPTIMIZATION & HARDENING
– Performance Tuning: To minimize latency and maximize throughput, adjust the vm.max_map_count kernel parameter. Execute sysctl -w vm.max_map_count=262144 to allow Elasticsearch to handle large numbers of memory-resident indices. Additionally, enable “Discard” on SSDs to maintain high write speeds over time.
– Security Hardening: Implement a “Jump Box” architecture where management ports are only accessible via a VPN. Disable all non-essential kernel modules and utilize the sysctl hardening features to prevent IP spoofing and ICMP redirects. Ensure that the /data directory is mounted on a separate partition with the noexec and nosuid flags to prevent attackers from executing local exploits if they break out of a container.
– Scaling Logic: As traffic volume increases, the centralized T-Pot node may become a bottleneck. Scale the deployment by using a “Sensor” installation type for remote sites and a “Collector” type for the central ELK stack. This distributed model reduces signal-attenuation and allows for localized data capture while maintaining a unified view of the threat landscape.
THE ADMIN DESK
How do I reset the platform to a clean state?
Execute the command sudo /opt/tpot/bin/dps.sh to stop services, then use docker system prune -a to remove all images and volumes. Rerun the install.sh script to restore the idempotent configuration from the repository sources.
Why is the Kibana dashboard showing 0 results?
This usually indicates a time-sync error between the sensor and the browser. Verify the system time using timedatectl. If the hardware clock has drifted, the ELK stack cannot index events correctly, resulting in chronological data gaps.
Can I run T-Pot on a Raspberry Pi?
T-Pot requires significant resources for the ELK stack. While a “Sensor” mode can run on a Pi 4 with 8GB RAM, the full platform requires an x86_64 architecture with high disk I/O to avoid persistent packet-loss.
How do I capture custom malware payloads?
Navigate to /data/cowrie/downloads/ or /data/dionaea/binaries/. These directories contain the raw hex-encoded or binary artifacts captured during automated exploitation attempts. Use sha256sum to generate unique file signatures for further threat intelligence reporting.
Is it safe to run T-Pot on my home network?
Only if it is isolated via a VLAN. T-Pot intentionally presents vulnerabilities; without proper network encapsulation, a sophisticated attacker could use the honeypot as a pivot point to attack other assets on the local network.
