HoneyPotter 🍯
The Boy Who Logged
An experimental Python honeypot for Telnet, Redis, MQTT, and raw TCP. It powers the deployed collectors behind honeypotter.dev.
This is a work in progress, started for fun and learning. The protocol parsers and handler pipeline are implemented by hand to explore networking, state machines, and what happens when the internet knocks. The pipeline runs on Python's asyncio and takes inspiration from Java's Netty.
This repository contains the honeypot component. The website's backend and frontend live separately and are planned for a future release.
Try it
Run with uv:
Telnet with an emulated BusyBox shell:
uvx honeypotter -v telnet --port 2323
Redis:
uvx honeypotter -v redis --port 6379
MQTT:
uvx honeypotter -v mqtt --port 1883
Raw TCP, listening on multiple ports:
uvx honeypotter -v tcp --port 8080 --port 9090
Listeners bind to 127.0.0.1 by default. Add --host 0.0.0.0 to listen on all IPv4 interfaces. The -v flag enables debug logging; use uvx honeypotter <protocol> --help for available options.
Export observations
All four modes can export session records as JSON over HTTP when connections close:
uvx honeypotter telnet --port 2323 \
--export-url https://collector.example.com/events \
--export-header "Authorization: Bearer YOUR_TOKEN" \
--export-header "X-Honeypot-Name: curious-wizard"
From bytes to events
Each connection has a pipeline of handlers. Inbound events move forward; outbound commands travel back toward the transport. Handlers can forward, transform, or consume events.
For MQTT, for example, DataReceived events from the transport become MQTT-level events such as PublishReceived and SubscribeReceived:
sequenceDiagram
participant IO as Transport
participant IP as IpRateLimiterHandler
participant M as MqttHandler
participant R as MqttRecorder
IO->>IP: DataReceived
IP-->>IO: CloseConnection (optional)
IP->>M: DataReceived
M->>R: PublishReceived
M->>R: SubscribeReceived
M->>IP: WriteData
IP->>IO: WriteData
Other handlers are omitted for clarity. The dashed arrow shows a possible rejection on ConnectionOpened; the remaining arrows illustrate an accepted connection. MqttRecorder is enabled when exporting.
Development
From a checkout, run uv sync --locked, then make test or make lint.
License
MIT © 2026 Vlad Dmitrievich.
Metadata
Release files for honeypotter 0.1.50
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| honeypotter-0.1.50.tar.gz | 34.0 kB | With provenance | Details for honeypotter-0.1.50.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| honeypotter-0.1.50-py3-none-any.whl | Python 3 | none | any | Details for honeypotter-0.1.50-py3-none-any.whl |
Total release size: 80.7 kB
Release files / honeypotter-0.1.50.tar.gz
| Download URL | honeypotter-0.1.50.tar.gz |
|---|---|
| Size | 34.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e99eb86aaadb797338256925f2bdd3d9ce510727c2ef00a7bb8e21b3185bfba
|
|
BLAKE2b-256 checksum How to use checksums |
cce81c2960deb42a747f2cd8a7bd8f48b0123375d85948bd1991860de9b706a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / honeypotter-0.1.50-py3-none-any.whl
| Download URL | honeypotter-0.1.50-py3-none-any.whl |
|---|---|
| Size | 46.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
77fe505be0b77dd7b21564a587cb1d871537421ec9606f282dbaeee7eaeb0dc2
|
|
BLAKE2b-256 checksum How to use checksums |
e6ab0df2d3083700d2e33116fb8110098c1a5d5718c8b21317191ce675faec83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for honeypotter 0.1.50
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for honeypotter-0.1.50.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.