← tools

decoygrid

in progress Go repo not yet public

A honeypot status tracker — polls deployed decoys, records connection attempts, and surfaces grid state over a local JSON API.

What it does

decoygrid sits alongside your deployed honeypots and tracks them in one place. It doesn’t generate decoys or emulate services itself — it tracks the ones you’ve already deployed:

  • Polls each registered decoy on a configurable interval (concurrent checks via goroutines, so polling twenty decoys takes as long as the slowest single check, not the sum of all of them)
  • Records connection attempts to disk (SQLite — one file, no server, no setup beyond the binary)
  • Exposes a /api/status JSON endpoint so the web interface (and anything else) can read current state
  • Provides a status board web interface served by the binary itself — no separate frontend build step

The binary is a single static Go executable. Drop it on any Linux box, point it at a config file, done. Caddy reverse-proxies to its HTTP port.

Installation

Not yet available — tool is in active development. Follow progress in the dev log writeups.

The repo is currently private. It will move to public when the HTTP status endpoint and persistent state layer are both stable.

Usage

Configuration will be YAML-based — one entry per honeypot, with address, port, expected protocol, and a label. Full usage docs will be written when the API surface stabilises.

# decoygrid.yaml (preview — may change)
interval: 30s
honeypots:
  - name: "fake-ssh-01"
    address: "10.0.0.10"
    port: 22
    protocol: tcp
  - name: "decoy-http"
    address: "10.0.0.11"
    port: 80
    protocol: http

Design notes

Everything is one binary by design. The instinct to split this into a separate frontend build is wrong for this use case — Go’s html/template package produces clean HTML from the same binary that runs the polling loop, without a Node.js install or build step on the target host. The tradeoff (less interactive UI) is acceptable for a status board that updates every 30 seconds.

SQLite over a full database for the same reason: one .db file in the working directory, backed up with cp, no auth, no connection pooling, no service to manage. At this scale it’s the right tool.