HoneyMire Client Integrations

HoneyMire-compatible honeypots report attacks by speaking the HoneyMire Honeypot Protocol. Existing honeypot codebases do not need to build that payload by hand: this repository ships small first-party clients and examples.

Available Clients

All clients emit the canonical nested honeymire.attack/v1 payload and support attack.target.port, so non-standard listeners such as Telnet on TCP/2323 or SSH on TCP/2222 are reported as observed facts.

Python

Install from this repository:

python -m pip install -e clients/python

Minimal use:

from honeymire import HoneyMireClient

client = HoneyMireClient(
    hub_url="https://hub.example",
    token="hop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    honeypot={
        "device_id": "python-demo-1",
        "firmware_version": "example/0.1",
        "hardware": {"mcu": "esp32-s3", "board": "python-honeypot", "display": "none"},
    },
)

client.report_attack(
    attack_id=1,
    protocol="telnet",
    source_ip="203.0.113.7",
    source_port=54321,
    target_port=2323,
    username="root",
    password="12345",
    authenticated=True,
)

See clients/python/examples/ for payload-only and full-report examples.

Cowrie

Copy or symlink the output module into Cowrie:

cp clients/cowrie/honeymire.py /opt/cowrie/src/cowrie/output/honeymire.py
python -m pip install -e clients/python

Add to etc/cowrie.cfg:

[output_honeymire]
enabled = true
hub_url = https://hub.example
token = hop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
device_id = cowrie-prod-1
target_port = 2222
protocol = ssh

Set target_port to the public listener attackers connect to, especially when Cowrie is behind NAT, port forwarding, or a non-standard SSH/Telnet port.

Node

Use the local Node 20+ package:

npm install /path/to/HoneyMireHUB/clients/node

const { HoneyMireClient } = require('@honeymire/client-node');

const client = new HoneyMireClient({
  hubUrl: 'https://hub.example',
  token: process.env.HONEYMIRE_TOKEN,
});

await client.ingest({
  honeypot: {
    deviceId: 'node-demo-1',
    firmwareVersion: 'example/0.1',
    hardware: { mcu: 'esp32-s3', board: 'node-honeypot', display: 'none' },
  },
  attack: {
    id: 1,
    ts: new Date(),
    protocol: 'ssh',
    sourceIp: '203.0.113.7',
    sourcePort: 54321,
    targetPort: 2222,
    auth: { user: 'root', pass: '12345', authenticated: true },
  },
});

See clients/node/examples/.

C

The C client is a small C99 payload builder plus transport hook:

cc -std=c99 -Wall -Wextra -Iclients/c/include \
  clients/c/src/honeymire_client.c clients/c/examples/build_payload_only.c \
  -o /tmp/honeymire_build_payload_only

Use clients/c/include/honeymire_client.h and clients/c/src/honeymire_client.c directly in your project. The optional clients/c/examples/curl_ingest.c file shows one possible libcurl transport.

Verification

Run all client checks from the HoneyMireHUB repository root:

clients/scripts/verify.sh

The script runs the hub TypeScript build, Node tests, Python tests, Cowrie syntax checks, C payload tests, C examples, and git diff --check.