{"id":13468875,"url":"https://github.com/thinkst/opencanary","last_synced_at":"2025-05-14T01:06:34.959Z","repository":{"id":35960686,"uuid":"40250792","full_name":"thinkst/opencanary","owner":"thinkst","description":"Modular and decentralised honeypot","archived":false,"fork":false,"pushed_at":"2025-03-24T18:25:10.000Z","size":3274,"stargazers_count":2432,"open_issues_count":6,"forks_count":370,"subscribers_count":76,"default_branch":"master","last_synced_at":"2025-04-03T17:38:03.912Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://opencanary.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thinkst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-05T14:44:09.000Z","updated_at":"2025-04-02T21:02:29.000Z","dependencies_parsed_at":"2023-02-18T19:15:36.027Z","dependency_job_id":"93ab0f98-e3ac-4a0e-9d4a-711d6f36aac9","html_url":"https://github.com/thinkst/opencanary","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinkst%2Fopencanary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinkst%2Fopencanary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinkst%2Fopencanary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinkst%2Fopencanary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thinkst","download_url":"https://codeload.github.com/thinkst/opencanary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248294202,"owners_count":21079802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:01:20.964Z","updated_at":"2025-04-10T20:44:00.183Z","avatar_url":"https://github.com/thinkst.png","language":"Python","readme":"# OpenCanary by Thinkst Canary\n\n\u003cimg src=\"docs/logo.png\" width=\"50\" style=\"float: left\"\u003e OpenCanary is a multi-protocol network honeypot. It's primary use-case is to catch hackers after they've breached non-public networks. It has extremely low resource requirements and can be tweaked, modified, and extended.\n\n[![OpenCanary Tests](https://github.com/thinkst/opencanary/actions/workflows/opencanary_tests.yml/badge.svg)](https://github.com/thinkst/opencanary/actions/workflows/opencanary_tests.yml)\n[![Docker build](https://github.com/thinkst/opencanary/actions/workflows/docker-build.yml/badge.svg)](https://github.com/thinkst/opencanary/actions/workflows/docker-build.yml)\n[![Publish to PyPI](https://github.com/thinkst/opencanary/actions/workflows/publish.yml/badge.svg)](https://github.com/thinkst/opencanary/actions/workflows/publish.yml)\n\n## Overview\n\nOpenCanary runs as a daemon and implements multiple common network protocols. When attackers breach networks and interact with the honeypot, OpenCanary will send you alerts via a variety of mechanisms.\n\nOpenCanary is implemented in Python, so the core honeypot is cross-platform; however, certain features require specific OSes. Running on Linux will give you the most options. It has extremely low resource requirements; for example, it can be deployed happily on a Raspberry Pi or a VM with minimal resources.\n\nThis README describes how to install and configure OpenCanary on Ubuntu Linux and MacOS.\n\nOpenCanary is the Open Source version of our commercial [Thinkst Canary](https://canary.tools) honeypot.\n\n## Table of Contents\n- **[Prerequisites](#prerequisites)**\n- **[Features](#features)**\n- **[Installation](#installation)**\n  - [Installation on Ubuntu](#installation-on-ubuntu)\n  - [Installation on macOS](#installation-on-macos)\n  - [Installation via Git](#installation-via-git)\n  - [Installation for Docker](#installation-for-docker)\n- **[Configuring OpenCanary](#configuring-opencanary)**\n  - [Creating the initial configuration](#creating-the-initial-configuration)\n  - [Enabling protocol modules and alerting](#enabling-protocol-modules-and-alerting)\n  - [Optional modules](#optional-modules)\n     - [SNMP](#snmp)\n     - [Portscan](#portscan)\n     - [Samba Setup](#samba-setup)\n- **[Running OpenCanary](#running-opencanary)**\n  - [Directly on Linux or macOS](#directly-on-linux-or-macos)\n  - [With docker-compose](#with-docker-compose)\n  - [With Docker](#with-docker)\n- **[Documentation](#documentation)**\n- **[Project Participation](#project-participation)**\n  - [Contributing](#contributing)\n  - [Security Vulnerability Reports](#security-vulnerability-reports)\n  - [Bug reports](bug-reports)\n  - [Feature Requests](#feature-requests)\n  - [Code of Conduct](#code-of-conduct)\n\n## Prerequisites\n\n* AMD64: Python 3.7 (Recommended Python 3.7+)\n* ARM64: Python 3.9+\n* _Optional_ SNMP requires the Python library Scapy\n* _Optional_ Samba module needs a working installation of Samba\n* _Optional_ Portscan uses iptables (not nftables) and is only supported on Linux-based operating systems\n\n## Features\n\n* Mimic an array of network-accessible services for attackers to interact with.\n* Receive various alerts as soon as potential threats are detected, highlighting the threat source IP address and where the breach may have occurred.\n\n## Installation\n\nThe OpenCanary installation essentially involves ensuring the Python environment is ready, then installing the OpenCanary Python package (plus optional extras).\n\n### Installation on Ubuntu\n\nInstallation on Ubuntu 22.04 LTS or 24.04 LTS:\n```\n$ sudo apt-get install python3-dev python3-pip python3-virtualenv python3-venv python3-scapy libssl-dev libpcap-dev\n$ virtualenv env/\n$ . env/bin/activate\n$ pip install opencanary\n```\n\nOptional extras (if you wish to use the Windows File Share module, and the SNMP module):\n```\n$ sudo apt install samba # if you plan to use the Windows File Share module\n$ pip install scapy pcapy-ng # if you plan to use the SNMP module\n```\n\n### Installation on macOS\n\nFirst, create and activate a new Python virtual environment:\n```\n$ virtualenv env/\n$ . env/bin/activate\n```\n\nMacports users should then run:\n```\n$ sudo port install openssl\n$ env ARCHFLAGS=\"-arch x86_64\" LDFLAGS=\"-L/opt/local/lib\" CFLAGS=\"-I/opt/local/include\" pip install cryptography\n```\n\nAlternatively, Homebrew x86 users run:\n````\n$ brew install openssl\n$ env ARCHFLAGS=\"-arch x86_64\" LDFLAGS=\"-L/usr/local/opt/openssl/lib\" CFLAGS=\"-I/usr/local/opt/openssl/include\" pip install cryptography\n````\n\nHomebrew M1 users run:\n```\n$ brew install openssl\n$ env ARCHFLAGS=\"-arch arm64\" LDFLAGS=\"-L/opt/homebrew/opt/openssl@1.1/lib\" CFLAGS=\"-I/opt/homebrew/opt/openssl@1.1/include\" pip install cryptography\n```\n\n(The compilation step above is necessary as multiple OpenSSL versions may exist, which can confound the Python libraries.)\n\nNow the installation can run as usual:\n```\n$ pip install opencanary\n$ pip install scapy pcapy-ng # optional\n```\n\nThe Windows File Share (smb) module is not available on macOS.\n\n### Installation via Git\n\nTo install from source, instead of running pip do the following:\n\n```\n$ git clone https://github.com/thinkst/opencanary\n$ cd opencanary\n$ python setup.py sdist\n$ cd dist\n$ pip install opencanary-\u003cversion\u003e.tar.gz\n```\n\n### Use via pkgx\n\nOpenCanary is packaged via [pkgx](https://pkgx.sh/), so no installation is needed if pkgx is installed, simply preface the `opencanaryd` command with\n`pkgx`. Due to environment variable protections in modern `sudo` implementations, the entire command must be run as root, or via `sudo -E`.\n\n```\n$ pkgx opencanaryd --version\n```\n\n### Installation for Docker\n\nOpenCanary Docker images are hosted on Docker Hub. These are only useful on Linux Docker hosts, as the `host` network engine is required for accurate network information.\n\n## Configuring OpenCanary\n\n### Creating the initial configuration\n\nWhen OpenCanary starts it looks for config files in the following locations and will stop when the first configuration is found:\n\n1. `./opencanary.conf` (i.e. the directory where OpenCanary is installed)\n2. `~/.opencanary.conf` (i.e. the home directory of the user, usually this will be `root` so `/root/.opencanary.conf`)\n3. `/etc/opencanaryd/opencanary.conf`\n\nTo create an initial configuration, run as `root` (you may be prompted for a `sudo` password):\n```\n$ opencanaryd --copyconfig\n[*] A sample config file is ready /etc/opencanaryd/opencanary.conf\n\n[*] Edit your configuration, then launch with \"opencanaryd --start --uid=nobody --gid=nogroup\"\n```\n\nThis creates the path and file `/etc/opencanaryd/opencanary.conf`. You must now edit the config file to determine which services and logging options you want to enable.\n\n### Enabling protocol modules and alerting\n\nConfiguration is performed via the JSON config file. Edit the file, and when happy save and exit.\n\n### Optional modules\n\n#### SNMP\n\nThe `snmp` module is only available when Scapy is present. See the installation steps for SNMP above.\n\n#### Portscan\n\nThe `portscan` module is only available on Linux hosts, as it modifies `iptables` rules.\n\nPlease note that for the Portscan service, we have added a `portscan.ignore_localhost` setting, which means the OpenCanary `portscan` service will ignore (not alert on) port scans originating for the localhost IP (`127.0.0.1`). This setting is false by default.\n\n#### Samba Setup\n\nThe Windows File Share module (`smb`) requires a Samba installation. See a step-by-step guide on [the Wiki](https://github.com/thinkst/opencanary/wiki/Opencanary-and-Samba).\n\n## Running OpenCanary\n\nOpenCanary is either run directly on a Linux or macOS host, or via a Docker container.\n\n### Directly on Linux or macOS\n\nStart OpenCanary by running:\n\n```\n$ . env/bin/activate\n$ opencanaryd --start --uid=nobody --gid=nogroup\n```\n\nWith the `uid` and `gid` flags, OpenCanary drops root privileges after binding to its ports. This can be changed to other low-privileged user/group or omitted to keep running with root privileges.\n\n### With pkgx\n\nStart OpenCanary by running:\n\n```\n$ sudo -E pkgx opencanaryd --start --uid=nobody --gid=nogroup\n```\n\nWith the `uid` and `gid` flags, OpenCanary drops root privileges after binding to its ports. This can be changed to other low-privileged user/group or omitted to keep running with root privileges.\n\n\n### With docker-compose\n\nThe route requires [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) to be installed.\n\n\u003e **Note**\n\u003e The portscan module is automatically disabled for Dockerised OpenCanary.\n\n1. Edit the `data/.opencanary.conf` file to enable, disable or customize the services that will run.\n1. Edit the `ports` section of the `docker-compose.yml` file to enable/disable the desired ports based on the services you have enabled in the config file.\n1. Run the container.\n    ```bash\n    docker-compose up latest\n    ```\n\nTo view the logs run `docker-compose logs latest`.\n\nTo stop the container run `docker-compose down`.\n\nTo build your own Docker OpenCanary using `docker compose`, head over to our [wiki](https://github.com/thinkst/opencanary/wiki/Using-Dockerised-OpenCanary#building-and-running-your-own-docker-opencanary-image-with-docker-compose)\n\n### With Docker\n\nPlease head over our dedicated Docker [wiki](https://github.com/thinkst/opencanary/wiki/Using-Dockerised-OpenCanary#building-and-running-your-own-docker-opencanary-image-with-docker) for everything Dockerised OpenCanary.\n\n### With Ansible\n\nPlease head over to our forked repository for an Ansible OpenCanary role over [here](https://github.com/thinkst/ansible-role-opencanary).\n## Documentation\n\n* The [Wiki](https://github.com/thinkst/opencanary/wiki) contains our FAQ.\n* Additional documentation is available on our [main site](https://opencanary.org).\n\n## Project Participation\n\n### Contributing\n\nWe welcome PRs to this project. Please read our [Code of Conduct](https://github.com/thinkst/.github/blob/master/CODE_OF_CONDUCT.md) and [Contributing](https://github.com/thinkst/.github/blob/master/CONTRIBUTING.md) documents before submitting a pull request.\n\nAt a minimum you should run `pre-commit` before submitting the PR. Install and run it in the same Python environment that OpenCanary is installed into:\n```\n$ pip install pre-commit\n# Do work\n$ git add file\n$ pre-commit\n$ git add file # only run this if pre-commit auto-fixed the file\n$ git commit\n```\n\n### Security Vulnerability Reports\n\nSee our [Security Policy](https://github.com/thinkst/opencanary/security/policy) for details on how to report security vulnerabilities.\n\n### Bug reports\n\nPlease file bug reports on [Github](https://github.com/thinkst/opencanary/issues) using the template we provide.\n\n### Feature Requests\n\nFeature requests are tracked [here](https://github.com/thinkst/opencanary/discussions/categories/feature-requests).\n\n### Code of Conduct\n\nThis project and everyone participating in it is governed by the\n[Code of Conduct](https://github.com/thinkst/.github/blob/master/CODE_OF_CONDUCT.md).\nBy participating, you are expected to uphold this code. Please report unacceptable behavior\nto github@thinkst.com.\n","funding_links":[],"categories":["Python","Honeypots","\u003ca id=\"a2df15c7819a024c2f5c4a7489285597\"\u003e\u003c/a\u003e密罐\u0026\u0026Honeypot","\u003ca name=\"honeypots\"\u003e\u003c/a\u003e Honeypots","\u003ca id=\"a53d22b9c5d09dc894413453f4755658\"\u003e\u003c/a\u003e未分类","Other Lists"],"sub_categories":["\u003ca id=\"d20acdc34ca7c084eb52ca1c14f71957\"\u003e\u003c/a\u003e密罐","LAB","🧪 LAB"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinkst%2Fopencanary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthinkst%2Fopencanary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinkst%2Fopencanary/lists"}