honeyfile 0.3.0__tar.gz

honeyfile-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

honeyfile-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thanut Jongteerathanachote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

honeyfile-0.3.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: honeyfile
+Version: 0.3.0
+Summary: Plant decoy files and get alerted the moment ransomware or an intruder touches them.
+Project-URL: Homepage, https://github.com/winxtxrgit/honeyfile
+Project-URL: Issues, https://github.com/winxtxrgit/honeyfile/issues
+Author: Thanut Jongteerathanachote
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blue-team,canary,decoy,detection,honeypot,incident-response,ransomware,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# honeyfile
+
+[![CI](https://github.com/winxtxrgit/honeyfile/actions/workflows/ci.yml/badge.svg)](https://github.com/winxtxrgit/honeyfile/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-0e75b6)
+![No dependencies](https://img.shields.io/badge/dependencies-none-2ea44f)
+[![MIT License](https://img.shields.io/badge/license-MIT-0e75b6)](https://github.com/winxtxrgit/honeyfile/blob/main/LICENSE)
+
+**Plant decoy files and get alerted the moment ransomware or an intruder touches them.**
+
+honeyfile drops tempting-looking bait — `Payroll_2026_Q4.csv`, `passwords.txt`, `.env`, `backup.sql` — into a directory and records exactly what each one looks like. Then it watches. The instant something encrypts, modifies or deletes a decoy, you get an alert with the file and what happened. It's a tripwire: a normal user never touches these files, so any change is a signal.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/winxtxrgit/honeyfile/main/docs/terminal.png" alt="honeyfile planting three office decoys, reporting them intact, then detecting two encrypted files, one deleted file and a dropped ransom note" width="820">
+</p>
+
+## Why
+
+Ransomware encrypts files fast, and by the time you notice, it's done. But it has to touch files to encrypt them, and a decoy that no human ever opens is the perfect early warning: one honeyfile changing means something is walking through your directory encrypting everything. The same tripwire catches an intruder browsing a file share for `passwords.txt`.
+
+This is a detection tool, the opposite of malware. It never encrypts anything; it watches for something else that does.
+
+## Try it in 30 seconds
+
+```bash
+pipx install git+https://github.com/winxtxrgit/honeyfile
+
+mkdir demo
+honeyfile plant demo --profile office
+honeyfile status demo                 # OK: all 3 decoys are intact
+
+echo "encrypted" > demo/passwords.txt # pretend to be ransomware
+honeyfile watch demo --once           # [modified] passwords.txt — contents changed
+```
+
+## Usage
+
+```bash
+honeyfile plant /srv/share --profile office   # plant decoys and record a baseline
+honeyfile plant ./repo --profile dev          # .env, id_rsa, deploy_keys.json
+honeyfile status /srv/share                   # one-shot check, exits 1 if anything changed
+
+honeyfile watch /srv/share                    # keep watching, alert on every change
+honeyfile watch /srv/share --json alerts.jsonl
+honeyfile watch /srv/share --webhook https://hooks.example.com/honeyfile
+honeyfile watch /srv/share --exec "/usr/local/bin/isolate-host.sh"
+honeyfile watch /srv/share --once             # for cron; exits 1 if anything changed
+
+honeyfile unplant /srv/share                  # remove the decoys and the baseline
+
+# Keep the baseline out of the watched directory (recommended for shares an
+# intruder can browse). Use the same --manifest path for plant, status and watch:
+honeyfile plant  /srv/share --manifest /var/lib/honeyfile/share.json
+honeyfile status /srv/share --manifest /var/lib/honeyfile/share.json
+```
+
+On Linux, `watch` uses **inotify** by default: it reacts the instant a decoy is touched and — unlike polling — catches a decoy merely being *opened or read*, before anything is changed. Elsewhere it falls back to polling. Force either with `--backend poll` or `--backend inotify`.
+
+**Profiles** decide which decoys get planted: `office` (payroll, passwords, a confidential doc), `dev` (`.env`, `id_rsa`, deploy keys), `db` (SQL dumps, a customer export). Every decoy contains only inert placeholder data — the one AWS-shaped key is AWS's own documented example — plus a unique `HONEYFILE-CANARY-…` token you can also search for in logs, email or outbound traffic.
+
+## What it detects
+
+| Event | Severity | Means |
+| :--- | :---: | :--- |
+| `modified` | high | A decoy's contents changed — ransomware encrypting, or someone editing it |
+| `deleted` | high | A decoy is gone — wiped or moved |
+| `manifest-error` | high | The baseline itself was altered or deleted — someone covering their tracks |
+| `opened` | high | A decoy was opened or read — someone browsing the bait (Linux inotify backend only) |
+| `new-file` | medium | A file that wasn't planted appeared next to the decoys — a ransom note, a dropped tool |
+| `touched` | low | A decoy's timestamp changed but its contents are intact — re-saved or restored |
+
+Each decoy is fingerprinted by **sha256 + size**, so a change that keeps the same byte count is still caught. The baseline lives in `.honeyfile.json`, which carries a checksum of its own contents: editing it to hide a change fails the check, and deleting it is reported too. Pass `--manifest PATH` to keep that baseline **outside** the watched directory, so an intruder among the decoys can't read it to learn which files are bait. Planted decoys also get **varied, backdated timestamps** so a directory of them doesn't betray itself by sharing one creation time.
+
+## Alerting
+
+`watch` prints every alert to stderr (coloured by severity on a terminal) and fans each one out to whatever you configure:
+
+- **`--json FILE`** — one JSON object per line: `{"time", "event", "severity", "path", "directory", "detail"}`. Feed it to your log pipeline.
+- **`--webhook URL`** — POST that JSON to Slack, Discord, or your SOAR. A dead endpoint is logged and never stops the watch.
+- **`--exec CMD`** — run a command on each alert, with the event passed as `HONEYFILE_EVENT`, `HONEYFILE_PATH`, `HONEYFILE_SEVERITY` and so on. Use it to isolate a host, kill a session, or page someone. No shell is involved, so a filename from disk is never interpreted.
+
+## Good places to plant decoys
+
+- **File shares** people rarely open — the first thing ransomware and intruders sweep.
+- **A user's Documents or Desktop** — many ransomware strains start there.
+- **Backup and database directories** — high-value targets.
+- **Web roots and repos** — where a `.env` or `id_rsa` is what an attacker is hunting for.
+
+Put decoys where a legitimate user has no reason to go, so every alert is real. honeyfile tells you *something touched the bait*; pair it with `--exec` or your EDR to respond.
+
+## Limits, honestly
+
+- **Read detection is Linux-only.** On Linux the inotify backend reports a decoy being opened or read (`opened`), the earliest possible signal. On macOS and Windows `watch` polls, which can only compare snapshots: a plain read changes nothing it can see, so there it detects **tampering**, not reads. For OS-level read-auditing everywhere, use `auditd` (Linux) or Windows file-access auditing; honeyfile is the lightweight, portable layer.
+- **Polling is near-real-time, not instant.** Where inotify isn't used, `watch` scans every few seconds, so fast ransomware may encrypt several files between scans — you'll still catch it, within one interval. The inotify backend reacts immediately.
+- Decoys protect themselves and signal an attack; they don't stop it. The response is yours, via `--exec` or your tooling.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+No dependencies outside the Python standard library. Tested on Python 3.10–3.13, Linux/macOS/Windows.
+
+## License
+
+[MIT](https://github.com/winxtxrgit/honeyfile/blob/main/LICENSE) © Thanut Jongteerathanachote

honeyfile-0.3.0/README.md

@@ -0,0 +1,109 @@
+# honeyfile
+
+[![CI](https://github.com/winxtxrgit/honeyfile/actions/workflows/ci.yml/badge.svg)](https://github.com/winxtxrgit/honeyfile/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-0e75b6)
+![No dependencies](https://img.shields.io/badge/dependencies-none-2ea44f)
+[![MIT License](https://img.shields.io/badge/license-MIT-0e75b6)](https://github.com/winxtxrgit/honeyfile/blob/main/LICENSE)
+
+**Plant decoy files and get alerted the moment ransomware or an intruder touches them.**
+
+honeyfile drops tempting-looking bait — `Payroll_2026_Q4.csv`, `passwords.txt`, `.env`, `backup.sql` — into a directory and records exactly what each one looks like. Then it watches. The instant something encrypts, modifies or deletes a decoy, you get an alert with the file and what happened. It's a tripwire: a normal user never touches these files, so any change is a signal.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/winxtxrgit/honeyfile/main/docs/terminal.png" alt="honeyfile planting three office decoys, reporting them intact, then detecting two encrypted files, one deleted file and a dropped ransom note" width="820">
+</p>
+
+## Why
+
+Ransomware encrypts files fast, and by the time you notice, it's done. But it has to touch files to encrypt them, and a decoy that no human ever opens is the perfect early warning: one honeyfile changing means something is walking through your directory encrypting everything. The same tripwire catches an intruder browsing a file share for `passwords.txt`.
+
+This is a detection tool, the opposite of malware. It never encrypts anything; it watches for something else that does.
+
+## Try it in 30 seconds
+
+```bash
+pipx install git+https://github.com/winxtxrgit/honeyfile
+
+mkdir demo
+honeyfile plant demo --profile office
+honeyfile status demo                 # OK: all 3 decoys are intact
+
+echo "encrypted" > demo/passwords.txt # pretend to be ransomware
+honeyfile watch demo --once           # [modified] passwords.txt — contents changed
+```
+
+## Usage
+
+```bash
+honeyfile plant /srv/share --profile office   # plant decoys and record a baseline
+honeyfile plant ./repo --profile dev          # .env, id_rsa, deploy_keys.json
+honeyfile status /srv/share                   # one-shot check, exits 1 if anything changed
+
+honeyfile watch /srv/share                    # keep watching, alert on every change
+honeyfile watch /srv/share --json alerts.jsonl
+honeyfile watch /srv/share --webhook https://hooks.example.com/honeyfile
+honeyfile watch /srv/share --exec "/usr/local/bin/isolate-host.sh"
+honeyfile watch /srv/share --once             # for cron; exits 1 if anything changed
+
+honeyfile unplant /srv/share                  # remove the decoys and the baseline
+
+# Keep the baseline out of the watched directory (recommended for shares an
+# intruder can browse). Use the same --manifest path for plant, status and watch:
+honeyfile plant  /srv/share --manifest /var/lib/honeyfile/share.json
+honeyfile status /srv/share --manifest /var/lib/honeyfile/share.json
+```
+
+On Linux, `watch` uses **inotify** by default: it reacts the instant a decoy is touched and — unlike polling — catches a decoy merely being *opened or read*, before anything is changed. Elsewhere it falls back to polling. Force either with `--backend poll` or `--backend inotify`.
+
+**Profiles** decide which decoys get planted: `office` (payroll, passwords, a confidential doc), `dev` (`.env`, `id_rsa`, deploy keys), `db` (SQL dumps, a customer export). Every decoy contains only inert placeholder data — the one AWS-shaped key is AWS's own documented example — plus a unique `HONEYFILE-CANARY-…` token you can also search for in logs, email or outbound traffic.
+
+## What it detects
+
+| Event | Severity | Means |
+| :--- | :---: | :--- |
+| `modified` | high | A decoy's contents changed — ransomware encrypting, or someone editing it |
+| `deleted` | high | A decoy is gone — wiped or moved |
+| `manifest-error` | high | The baseline itself was altered or deleted — someone covering their tracks |
+| `opened` | high | A decoy was opened or read — someone browsing the bait (Linux inotify backend only) |
+| `new-file` | medium | A file that wasn't planted appeared next to the decoys — a ransom note, a dropped tool |
+| `touched` | low | A decoy's timestamp changed but its contents are intact — re-saved or restored |
+
+Each decoy is fingerprinted by **sha256 + size**, so a change that keeps the same byte count is still caught. The baseline lives in `.honeyfile.json`, which carries a checksum of its own contents: editing it to hide a change fails the check, and deleting it is reported too. Pass `--manifest PATH` to keep that baseline **outside** the watched directory, so an intruder among the decoys can't read it to learn which files are bait. Planted decoys also get **varied, backdated timestamps** so a directory of them doesn't betray itself by sharing one creation time.
+
+## Alerting
+
+`watch` prints every alert to stderr (coloured by severity on a terminal) and fans each one out to whatever you configure:
+
+- **`--json FILE`** — one JSON object per line: `{"time", "event", "severity", "path", "directory", "detail"}`. Feed it to your log pipeline.
+- **`--webhook URL`** — POST that JSON to Slack, Discord, or your SOAR. A dead endpoint is logged and never stops the watch.
+- **`--exec CMD`** — run a command on each alert, with the event passed as `HONEYFILE_EVENT`, `HONEYFILE_PATH`, `HONEYFILE_SEVERITY` and so on. Use it to isolate a host, kill a session, or page someone. No shell is involved, so a filename from disk is never interpreted.
+
+## Good places to plant decoys
+
+- **File shares** people rarely open — the first thing ransomware and intruders sweep.
+- **A user's Documents or Desktop** — many ransomware strains start there.
+- **Backup and database directories** — high-value targets.
+- **Web roots and repos** — where a `.env` or `id_rsa` is what an attacker is hunting for.
+
+Put decoys where a legitimate user has no reason to go, so every alert is real. honeyfile tells you *something touched the bait*; pair it with `--exec` or your EDR to respond.
+
+## Limits, honestly
+
+- **Read detection is Linux-only.** On Linux the inotify backend reports a decoy being opened or read (`opened`), the earliest possible signal. On macOS and Windows `watch` polls, which can only compare snapshots: a plain read changes nothing it can see, so there it detects **tampering**, not reads. For OS-level read-auditing everywhere, use `auditd` (Linux) or Windows file-access auditing; honeyfile is the lightweight, portable layer.
+- **Polling is near-real-time, not instant.** Where inotify isn't used, `watch` scans every few seconds, so fast ransomware may encrypt several files between scans — you'll still catch it, within one interval. The inotify backend reacts immediately.
+- Decoys protect themselves and signal an attack; they don't stop it. The response is yours, via `--exec` or your tooling.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+No dependencies outside the Python standard library. Tested on Python 3.10–3.13, Linux/macOS/Windows.
+
+## License
+
+[MIT](https://github.com/winxtxrgit/honeyfile/blob/main/LICENSE) © Thanut Jongteerathanachote

honeyfile-0.3.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+# Cap hatchling below 1.28: 1.28+ emits Metadata-Version 2.5, which no released
+# twine yet understands, so `twine check --strict` in release.yml rejects the
+# build. 1.27 emits 2.4 (same PEP 639 License-Expression) and passes. Lift the
+# ceiling once twine supports metadata 2.5.
+requires = ["hatchling>=1.27,<1.28"]
+build-backend = "hatchling.build"
+
+[project]
+name = "honeyfile"
+dynamic = ["version"]
+description = "Plant decoy files and get alerted the moment ransomware or an intruder touches them."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Thanut Jongteerathanachote" }]
+keywords = ["security", "ransomware", "honeypot", "canary", "decoy", "blue-team", "detection", "incident-response"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+honeyfile = "honeyfile.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/winxtxrgit/honeyfile"
+Issues = "https://github.com/winxtxrgit/honeyfile/issues"
+
+[tool.hatch.version]
+path = "src/honeyfile/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

honeyfile-0.3.0/src/honeyfile/__init__.py

@@ -0,0 +1,3 @@
+"""Plant decoy files and get alerted when ransomware or an intruder touches them."""
+
+__version__ = "0.3.0"

honeyfile-0.3.0/src/honeyfile/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

honeyfile-0.3.0/src/honeyfile/alerts.py

@@ -0,0 +1,96 @@
+"""Where an alert goes once it fires: the terminal, a JSON-lines file, a webhook,
+or a command of your own.
+
+The webhook and command sinks reach outside the process, so both fail soft: a
+dead endpoint or a broken command must never stop the watch from reporting the
+next event.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .watch import Alert
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def to_record(alert: Alert, directory: str) -> dict:
+    return {
+        "time": _now(),
+        "event": alert.event,
+        "severity": alert.severity,
+        "path": alert.path,
+        "directory": directory,
+        "detail": alert.detail,
+    }
+
+
+_COLORS = {True: {90: "1;31", 95: "1;31", 50: "33", 40: "2"}, False: {}}
+
+
+def _use_color(stream) -> bool:
+    return stream.isatty() and "NO_COLOR" not in os.environ
+
+
+def format_terminal(alert: Alert, color: bool) -> str:
+    tag = f"[{alert.event}]"
+    line = f"{_now()}  {tag:<16} {alert.path}  —  {alert.detail}"
+    code = _COLORS[color].get(alert.severity) if color else None
+    return f"\033[{code}m{line}\033[0m" if code else line
+
+
+@dataclass
+class Sinks:
+    """Fan one alert out to every configured destination."""
+
+    directory: str
+    json_path: str | None = None
+    webhook: str | None = None
+    exec_cmd: list[str] | None = None
+    color: bool = False
+
+    def emit(self, alert: Alert) -> None:
+        print(format_terminal(alert, self.color), file=sys.stderr, flush=True)
+        record = to_record(alert, self.directory)
+        if self.json_path:
+            self._write_json(record)
+        if self.webhook:
+            self._post(record)
+        if self.exec_cmd:
+            self._run(record)
+
+    def _write_json(self, record: dict) -> None:
+        try:
+            with open(self.json_path, "a", encoding="utf-8") as handle:
+                handle.write(json.dumps(record) + "\n")
+        except OSError as error:
+            print(f"honeyfile: cannot write {self.json_path}: {error}", file=sys.stderr)
+
+    def _post(self, record: dict) -> None:
+        body = json.dumps(record).encode()
+        request = urllib.request.Request(
+            self.webhook, data=body, headers={"Content-Type": "application/json"}
+        )
+        try:
+            urllib.request.urlopen(request, timeout=10).close()
+        except (urllib.error.URLError, OSError) as error:
+            print(f"honeyfile: webhook failed: {error}", file=sys.stderr)
+
+    def _run(self, record: dict) -> None:
+        # The command gets the event as HONEYFILE_* env vars; no shell, so a path
+        # from the filesystem is never interpreted.
+        env = {**os.environ, **{f"HONEYFILE_{k.upper()}": str(v) for k, v in record.items()}}
+        try:
+            subprocess.run(self.exec_cmd, env=env, timeout=30, check=False)
+        except (OSError, subprocess.SubprocessError) as error:
+            print(f"honeyfile: --exec failed: {error}", file=sys.stderr)

honeyfile-0.3.0/src/honeyfile/cli.py

@@ -0,0 +1,221 @@
+"""Command line: ``honeyfile plant``, ``honeyfile watch``, ``honeyfile status``."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import sys
+from pathlib import Path
+
+from . import __version__, inotify
+from .alerts import Sinks, format_terminal
+from .decoys import PROFILES
+from .manifest import ManifestError, manifest_path, read
+from .plant import PlantError, plant, unplant
+from .watch import monitor, scan
+
+
+def _add_manifest_arg(p: argparse.ArgumentParser, *, writing: bool) -> None:
+    verb = "store" if writing else "read"
+    p.add_argument(
+        "--manifest",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help=f"{verb} the baseline at PATH instead of .honeyfile.json inside the "
+        "directory, so an intruder among the decoys cannot find it",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="honeyfile",
+        description="Plant decoy files and get alerted the moment something modifies, "
+        "encrypts or deletes them — an early warning for ransomware and intruders.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("plant", help="write decoy files and record their baseline")
+    p.add_argument("directory", type=Path, help="directory to plant decoys in")
+    p.add_argument(
+        "--profile",
+        choices=sorted(PROFILES),
+        default="office",
+        help="which set of decoys to plant (default: %(default)s)",
+    )
+    p.add_argument("--force", action="store_true", help="overwrite existing files of the same name")
+    _add_manifest_arg(p, writing=True)
+
+    w = sub.add_parser("watch", help="monitor planted decoys and alert on any change")
+    w.add_argument("directory", type=Path)
+    w.add_argument(
+        "--interval",
+        type=_positive,
+        default=5.0,
+        metavar="SECONDS",
+        help="seconds between scans (default: %(default)s)",
+    )
+    w.add_argument("--once", action="store_true", help="scan once and exit instead of looping")
+    w.add_argument(
+        "--backend",
+        choices=("auto", "poll", "inotify"),
+        default="auto",
+        help="auto (default) uses inotify on Linux for instant, read-level detection "
+        "and falls back to polling elsewhere; poll forces the portable scanner",
+    )
+    w.add_argument(
+        "--no-new-files",
+        action="store_true",
+        help="do not alert on unplanted files appearing in the directory",
+    )
+    w.add_argument("--json", metavar="FILE", help="append each alert to FILE as JSON lines")
+    w.add_argument("--webhook", metavar="URL", help="POST each alert as JSON to URL")
+    w.add_argument(
+        "--exec",
+        dest="exec_cmd",
+        metavar="CMD",
+        help="run CMD on each alert (shell-style quoting; event passed as HONEYFILE_* env)",
+    )
+    _add_manifest_arg(w, writing=False)
+
+    s = sub.add_parser("status", help="show the current state of the decoys and exit")
+    s.add_argument("directory", type=Path)
+    s.add_argument("--no-new-files", action="store_true")
+    _add_manifest_arg(s, writing=False)
+
+    u = sub.add_parser("unplant", help="remove the planted decoys and their baseline")
+    u.add_argument("directory", type=Path, help="directory the decoys were planted in")
+    _add_manifest_arg(u, writing=False)
+
+    return parser
+
+
+def _positive(text: str) -> float:
+    value = float(text)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("must be greater than 0")
+    return value
+
+
+def _cmd_plant(args) -> int:
+    try:
+        manifest = plant(args.directory, args.profile, args.force, manifest_path=args.manifest)
+    except (PlantError, ValueError, OSError) as error:
+        print(f"honeyfile: {error}", file=sys.stderr)
+        return 2
+    print(f"Planted {len(manifest.entries)} {args.profile} decoys in {args.directory}:")
+    for entry in manifest.entries:
+        print(f"  {entry.name}")
+    print(f"Baseline: {manifest_path(args.directory, args.manifest)}")
+    watch_cmd = f"honeyfile watch {args.directory}"
+    if args.manifest:
+        watch_cmd += f" --manifest {args.manifest}"
+    print(f"\nNow watch them:\n  {watch_cmd}")
+    return 0
+
+
+def _cmd_status(args) -> int:
+    try:
+        manifest = read(args.directory, args.manifest)
+    except ManifestError as error:
+        print(f"honeyfile: {error}", file=sys.stderr)
+        return 2
+    alerts = scan(args.directory, manifest, detect_new=not args.no_new_files)
+    color = sys.stdout.isatty()
+    if not alerts:
+        print(f"OK: all {len(manifest.entries)} decoys in {args.directory} are intact.")
+        return 0
+    print(f"{len(alerts)} alert(s) in {args.directory}:")
+    for alert in alerts:
+        print("  " + format_terminal(alert, color))
+    return 1
+
+
+def _cmd_watch(args) -> int:
+    sinks = Sinks(
+        directory=str(args.directory),
+        json_path=args.json,
+        webhook=args.webhook,
+        exec_cmd=shlex.split(args.exec_cmd) if args.exec_cmd else None,
+        color=sys.stderr.isatty(),
+    )
+    if args.once:
+        try:
+            manifest = read(args.directory, args.manifest)
+        except ManifestError as error:
+            print(f"honeyfile: {error}", file=sys.stderr)
+            return 2
+        alerts = scan(args.directory, manifest, detect_new=not args.no_new_files)
+        for alert in alerts:
+            sinks.emit(alert)
+        return 1 if alerts else 0
+
+    use_inotify = args.backend == "inotify" or (args.backend == "auto" and inotify.available())
+    if args.backend == "inotify" and not inotify.available():
+        print(
+            "honeyfile: the inotify backend needs Linux; use --backend poll here",
+            file=sys.stderr,
+        )
+        return 2
+
+    if use_inotify:
+        print(
+            f"Watching {args.directory} with inotify (real-time). Ctrl+C to stop.",
+            file=sys.stderr,
+        )
+        events = inotify.monitor(
+            args.directory,
+            detect_new=not args.no_new_files,
+            manifest_path=args.manifest,
+        )
+    else:
+        print(
+            f"Watching {args.directory} every {args.interval:g}s. Ctrl+C to stop.", file=sys.stderr
+        )
+        events = monitor(
+            args.directory,
+            args.interval,
+            detect_new=not args.no_new_files,
+            manifest_path=args.manifest,
+        )
+
+    try:
+        for event in events:
+            if isinstance(event, ManifestError):
+                print(f"honeyfile: baseline problem: {event}", file=sys.stderr, flush=True)
+            else:
+                sinks.emit(event)
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+def _cmd_unplant(args) -> int:
+    try:
+        removed = unplant(args.directory, args.manifest)
+    except (ManifestError, OSError) as error:
+        print(f"honeyfile: {error}", file=sys.stderr)
+        return 2
+    print(f"Removed {len(removed.deleted)} decoy(s) from {args.directory}:")
+    for name in removed.deleted:
+        print(f"  {name}")
+    for name in removed.missing:
+        print(f"  {name} (already gone)")
+    print(f"Removed baseline: {removed.manifest}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    handlers = {
+        "plant": _cmd_plant,
+        "watch": _cmd_watch,
+        "status": _cmd_status,
+        "unplant": _cmd_unplant,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())