OpenCanary

OpenCanary is a lightweight, multi‑protocol network honeypot written in Python that emulates real services (FTP, SSH, HTTP, SMB, DNS, etc.) to lure attackers after a network breach. From a developer’s standpoint, the project exposes a clean, event‑driven architecture: each protocol is implemented as an independent module that listens on its own port, logs interactions, and triggers alerts through a pluggable notification system. The core daemon runs in the foreground or as a system service, making it trivial to integrate into existing monitoring stacks.

Technical Stack & Architecture

• Language: Python 3.7+ (Python 3.9 on ARM) – the entire codebase is pure Python, which simplifies cross‑platform builds and debugging.
• Frameworks: No heavy frameworks; the project uses asyncio for concurrency and a small internal event bus to wire modules together.
• Data Persistence: Optional SQLite or plain JSON logs for audit trails; the default is in‑memory event handling with optional file rotation.
• Alerting: Built‑in support for email, Slack webhook, Syslog, and a custom REST endpoint. Developers can add new sinks by implementing the AlertHandler interface.
• Configuration: YAML‑based configuration (opencanary.yaml) allows enabling/disabling modules, setting port numbers, and specifying alert destinations. The configuration loader validates schema on startup, providing clear error messages.

Core Capabilities & APIs

• Protocol Modules: Each service is a self‑contained module exposing a start() and stop() method. Adding a new protocol is as simple as inheriting from the base module class and registering it in opencanary.conf.
• Event Bus: Events such as “connection opened”, “command executed”, or “file transferred” are published to a central bus. Consumers can subscribe via callbacks, enabling real‑time dashboards or custom analytics.
• REST API: A lightweight HTTP interface (optional) exposes current status, active connections, and a trigger endpoint to programmatically start or stop the honeypot. The API is documented with OpenAPI specs available in the repo.
• Webhooks & Extensions: Developers can hook into events with external scripts or services. For example, a webhook could trigger an incident response playbook in an SOAR platform.

Deployment & Infrastructure

• Self‑Hosting: Runs on any Linux or macOS host; ARM support (e.g., Raspberry Pi) is fully functional. The daemon requires only Python and optional OS‑specific dependencies (iptables for portscan, Samba for SMB emulation).
• Containerization: Official Docker images are available via GitHub Actions. The image is a minimal Alpine/Python base, keeping the attack surface small and allowing easy orchestration with docker‑compose or Kubernetes via a custom Helm chart.
• Scalability: While designed for low‑resource environments, multiple instances can be deployed behind a reverse proxy or load balancer to cover larger subnet ranges. Each instance is isolated, and shared alerting endpoints can aggregate events centrally.

Integration & Extensibility

• Plugin System: The module loader dynamically imports Python packages from a plugins/ directory. This allows third‑party developers to ship new protocols or alert handlers without modifying core code.
• Webhooks & Callbacks: OpenCanary can push events to any HTTP endpoint. Combined with tools like Zapier or custom microservices, developers can enrich alerts with threat intel feeds or trigger automated playbooks.
• Custom Scripts: The optional “custom module” feature lets you write arbitrary Python code that runs on each connection, enabling sophisticated simulation of vulnerable services or data exfiltration patterns.

Developer Experience

• Configuration: YAML with clear defaults; the CLI (opencanaryctl) provides subcommands for status, config validation, and log rotation.
• Documentation: The README covers installation on Ubuntu/macOS, Docker usage, and advanced configuration. API docs are generated with Sphinx and hosted in the docs/ folder.
• Community & Support: The project is actively maintained on GitHub with CI workflows, issue templates for bugs and feature requests, and a Code of Conduct. Contributions are welcomed via pull requests; the core team reviews them quickly.

Use Cases

• Internal Red‑Team Exercises: Deploy a low‑footprint honeypot on an internal subnet to surface lateral movement attempts.
• Threat Hunting: Integrate OpenCanary alerts with SIEM tools (Splunk, ELK) to correlate attack patterns across the network.
• Incident Response Automation: Use webhooks to trigger playbooks in SOAR platforms whenever a honeypot interaction is detected.
• Compliance Audits: Demonstrate continuous monitoring of critical services by running OpenCanary on production servers.

Advantages Over Alternatives

OpenCanary’s lightweight, Python‑based design gives developers the freedom to prototype custom protocols, embed it in existing observability stacks