Local-first honeypot toolkit for security-conscious individuals
Important
ZHoneyPot is in public beta (v0.1.0). Core features are stable and actively used, but the database schema may change between releases. Back up ~/.local/share/zhoneypot/ before upgrading.
ZHoneyPot places convincing decoy files across your filesystem — AWS credentials, SSH keys, .env files, kubeconfigs, Docker auth tokens — and alerts you the instant anything touches them.
No legitimate software reads your AWS credentials unprompted. Any access means something is wrong: malware, an intruder, or a runaway script. ZHoneyPot catches them the moment they look.
Unlike SaaS honeypot services:
| ZHoneyPot | SaaS (e.g. Canarytokens) | |
|---|---|---|
| Runs entirely on your machine | ✓ | — |
| Zero telemetry | ✓ | — |
| No account required | ✓ | — |
| Works fully offline | ✓ | — |
| GUI-driven desktop app | ✓ | — |
| Free & open source | ✓ | Partial |
| Forensic process capture | ✓ | — |
| Tamper-evident alert log | ✓ | — |
| Token type | What it mimics | Default placement |
|---|---|---|
aws_credentials |
AWS access key ID + secret key | ~/.aws/credentials |
ssh_keypair |
SSH private key (ed25519 / RSA) | ~/.ssh/id_rsa_backup |
dotenv |
.env with DB URL, JWT secret, Stripe key |
~/projects/.env |
git_repo |
Fake git repo with credential leak in history | ~/projects/internal |
kube_config |
Kubernetes cluster config | ~/.kube/config |
docker_config |
Docker registry auth token | ~/.docker/config.json |
npmrc |
npm auth token | ~/.npmrc |
pypirc |
PyPI upload credentials | ~/.pypirc |
passwords_txt |
Plaintext password list | ~/passwords.txt |
generic_file |
Any custom bait file | Any path you choose |
All tokens are format-accurate — they match the exact structure of real credentials (correct prefixes, lengths, character sets) so attackers cannot identify them as fakes by inspection.
- Sub-second detection via Linux
inotify— read, write, rename, delete, and attribute changes all fire alerts - Forensic capture at trigger time — PID, parent process chain back to PID 1, UID/GID, cmdline, executable path + SHA-256 hash, working directory, open file descriptors, and a live
/proc/net/tcpnetwork snapshot - BLAKE3 tamper-evident hash chain — every alert is cryptographically chained; any post-hoc modification to the database is detected and flagged in the UI
- False-positive labelling — known file indexers (GNOME Tracker, Baloo, Nautilus, Dolphin, Thunar) are automatically identified and labelled so you don't chase your own OS
- Desktop notifications (native)
- System tray badge with unread count
- Webhook — raw JSON for generic endpoints, Discord rich embeds (auto-detected), Slack messages (auto-detected)
- Append-only
.jsonlalert mirror at~/.local/share/zhoneypot/alerts.jsonl
- Smart scanner — scans your home directory for existing credential paths and suggests matching honeypot placements with confidence scores
- Auto-response rules — automatically lock files, kill processes, or run custom scripts when a trigger matches configured conditions (token filter + severity threshold)
- Self-heal — recreates deleted or tampered tokens after a configurable delay so your tripwires never go dark
- Anomaly detection — per-token 24-hour and 7-day access-time baseline; flags accesses at unusual hours
- System tray — close the window, watchers keep running
- Autostart on login — XDG autostart / systemd user, no manual setup
- Start minimized — launches silently in tray-only mode
- Single-instance enforcement — second launch focuses the existing window
- inotify watch-limit detection — warns when
/proc/sys/fs/inotify/max_user_watchesis too low and shows the fix
- Self-test suite — 10 end-to-end test groups: DB connectivity, all 10 token generators, disk I/O, file watcher, alert pipeline, hash chain integrity, anomaly detection, auto-response CRUD, and self-heal queue
- Three deployment templates — deploy a sensible set of tokens in one click:
- Developer Workstation — AWS creds + SSH keypair +
.env+ fake git repo - Server Simulation — root AWS creds + cron script + DB dump
- Minimal — 3 highest-signal tokens for a quick start
- Developer Workstation — AWS creds + SSH keypair +
- Linux x86_64
- Standard kernel with
inotifysupport (any kernel ≥ 2.6.36)
Note
Prebuilt .deb and .rpm packages are hosted on the project website, not on GitHub Releases.
# Debian / Ubuntu / Mint
sudo dpkg -i zhoneypot_0.1.0_amd64.deb
sudo apt-get install -f # resolve any deps
# Fedora / openSUSE / RHEL
sudo rpm -i zhoneypot-0.1.0-1.x86_64.rpm
# or:
sudo dnf install ./zhoneypot-0.1.0-1.x86_64.rpmSHA-256 checksums (verify before installing):
584cf0f142ae33b84040beac68e51aad9e9d9cde6e670873f927e85aafcaaab5 zhoneypot_0.1.0_amd64.deb
8644ccd7f64ca9019c3bb33e550613400c7ac2b1ba0b054efe3b5359a0740466 zhoneypot-0.1.0-1.x86_64.rpm
Prerequisites: Rust (stable), Node.js ≥ 20, pnpm
git clone https://github.com/TheHolyOneZ/ZHoneyPot
cd ZHoneyPot
pnpm install
pnpm tauri buildRelease bundles land in src-tauri/target/release/bundle/.
For development with hot-reload:
pnpm tauri devNote
The linux-forensics Cargo feature (enabled automatically on Linux) enables /proc-based forensic capture. It has no effect on non-Linux builds.
- Launch ZHoneyPot → New Token
- Choose AWS Credentials — accept the suggested path
~/.aws/credentials - Click Deploy
- Open a terminal:
cat ~/.aws/credentials - An alert fires in under a second — check the Alerts tab
Or use a template: Dashboard → Deploy template → Developer Workstation deploys 5 high-signal tokens in one click and you're covered.
Important
ZHoneyPot makes zero outbound network requests with default settings.
The only traffic it ever sends is to your own configured webhook URL or callback server. Both are logged in the built-in network audit log under Settings → Privacy. There is no telemetry, no auto-update probe, and no crash reporting.
This is verifiable: run sudo tcpdump -i any with default settings and observe zero outbound connections.
| Path | Contents |
|---|---|
~/.local/share/zhoneypot/zhoneypot.db |
SQLite (WAL mode) — tokens, alerts, chain, settings |
~/.local/share/zhoneypot/alerts.jsonl |
Append-only alert mirror |
~/.config/zhoneypot/ |
Config directory |
~/.local/state/zhoneypot/logs/ |
Structured rolling logs |
Backend — Rust
| Crate | Purpose |
|---|---|
tauri v2 |
Desktop shell — no Electron, native OS WebView |
tokio |
Async runtime |
notify + notify-debouncer-full |
inotify file watching with 300 ms debounce |
sqlx + SQLite |
Async compile-time-checked queries, WAL mode |
blake3 |
BLAKE3 cryptographic hash chain |
procfs |
Linux /proc forensic snapshots |
ed25519-dalek + rsa + ssh-key |
Real SSH keypair generation |
git2 |
Fake git repository construction |
reqwest (rustls) |
Webhook HTTP delivery — no OpenSSL |
uuid v7 |
Sortable unique IDs |
tracing + tracing-appender |
Structured rolling-file logging |
Frontend — TypeScript + React
| Library | Purpose |
|---|---|
| React 18 + TypeScript 5 | UI |
| Vite 7 | Build tooling with instant HMR |
| TanStack Router | Type-safe client-side routing |
| TanStack Query | Server-state caching and automatic invalidation |
| Tailwind CSS v4 | Utility-first styling with CSS variable dark mode |
| shadcn/ui + Radix UI | Accessible component primitives |
| Zustand | Lightweight client state |
| Lucide React | Icons |
Note
These are planned for post-beta milestones — not promised dates.
- Stable
.deb/.rpmrelease pipeline (currently hand-built and hosted on zsync.eu) - Windows support (file watcher + forensics layer)
- macOS support
- Network canary tokens (DNS / HTTP callback server companion)
- Plugin API (declarative TOML plugins in
~/.config/zhoneypot/plugins/) - Decoy density heatmap on Dashboard
ZHoneyPot is free software under the GNU General Public License v3.0.
You can use, modify, and distribute it freely. Any derivative work must also be released under GPL v3 — this prevents closed-source forks of a tool you're trusting to protect your machine.
For a security tool, open source is not optional. You should be able to read exactly what it does.
→ LICENSE
TheHolyOneZ
Security tooling · Systems programming · Open source
ZHoneyPot v0.1.0-beta · GPL-3.0 · Linux · Built with Tauri v2 + Rust + React
Your threat intelligence stays yours.