OpenCanary（Thinkst Canary 开发）

OpenCanary 是一个多协议网络蜜罐。它的主要用途是捕捉那些已经突破非公开网络的黑客。它的资源要求极低，并且可以调整、修改和扩展。

概述

OpenCanary 以守护进程（daemon）方式运行，并实现了多种常见网络协议。当攻击者突破网络并与蜜罐交互时，OpenCanary 会通过多种机制向你发送告警。

OpenCanary 使用 Python 实现，因此核心蜜罐是跨平台的；不过，某些功能需要特定的操作系统。在 Linux 上运行会提供最多的选项。它的资源要求极低；例如，可以轻松部署在树莓派或资源极少的虚拟机上。

本 README 介绍如何在 Ubuntu Linux 和 macOS 上安装和配置 OpenCanary。

OpenCanary 是我们商业蜜罐 Thinkst Canary 的开源版本。

目录

• 前提条件
• 功能特性
• 安装
  • 在 Ubuntu 上安装
  • 在 macOS 上安装
  • 通过 Git 安装
  • Docker 安装
• 配置 OpenCanary
  • 创建初始配置
  • 启用协议模块与告警
  • 可选模块
    • SNMP
    • Portscan
    • Samba 设置
• 运行 OpenCanary
  • 直接在 Linux 或 macOS 上运行
  • 使用 docker compose
  • 使用 Docker
• 文档
• 项目参与
  • 贡献
  • 安全漏洞报告
  • 错误报告
  • 功能请求
  • 行为准则

前提条件

• AMD64：Python 3.10+
• ARM64：Python 3.10+
• 可选 SNMP 需要 Python 库 Scapy
• 可选 Samba 模块需要可正常工作的 Samba 安装
• 可选 Portscan 使用 iptables（而非 nftables），并且仅在基于 Linux 的操作系统上受支持

功能特性

• 模拟一系列可供攻击者交互的网络服务。
• 在检测到潜在威胁时立即接收多种告警，并突出显示威胁来源 IP 地址以及可能发生失陷的位置。

安装

OpenCanary 的安装基本上包括确保 Python 环境就绪，然后安装 OpenCanary Python 包（以及可选的附加组件）。

如果已安装 uv，可以使用它来创建虚拟环境和安装包。如果未安装，下面标准的 python/pip 流程仍然有效。

在 Ubuntu 上安装

在 Ubuntu 22.04 LTS 或 24.04 LTS 上安装：

$ sudo apt-get install python3-dev python3-pip python3-virtualenv python3-venv python3-scapy libssl-dev libpcap-dev
$ virtualenv env/
$ . env/bin/activate
$ pip install opencanary

可选的 uv 等效命令：

$ uv venv env
$ . env/bin/activate
$ uv pip install opencanary

可选附加组件（如果你希望使用 Windows 文件共享模块和 SNMP 模块）：

$ sudo apt install samba # if you plan to use the Windows File Share module
$ pip install scapy pcapy-ng # if you plan to use the SNMP module

在 macOS 上安装

首先，创建并激活一个新的 Python 虚拟环境：

$ virtualenv env/
$ . env/bin/activate

可选的 uv 等效命令：

$ uv venv env
$ . env/bin/activate

Macports 用户接下来应运行：

$ sudo port install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography

或者，Homebrew x86 用户运行：

$ brew install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography

Homebrew M1 用户运行：

$ brew install openssl
$ env ARCHFLAGS="-arch arm64" LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib" CFLAGS="-I/opt/homebrew/opt/[email protected]/include" pip install cryptography

（上述编译步骤是必要的，因为系统中可能存在多个 OpenSSL 版本，这可能会干扰 Python 库。）

现在可以照常进行安装了：

$ pip install opencanary
$ pip install scapy pcapy-ng # optional

安装 uv 后，等效命令为：

$ uv pip install opencanary
$ uv pip install scapy pcapy-ng # optional

Windows 文件共享（smb）模块在 macOS 上不可用。

通过 Git 安装

要从源码安装，请运行以下命令，而不是执行 pip：

$ git clone https://github.com/thinkst/opencanary
$ cd opencanary
$ python setup.py sdist
$ cd dist
$ pip install opencanary-<version>.tar.gz

安装 uv 后，可以将最终安装步骤替换为：

$ uv pip install opencanary-<version>.tar.gz

通过 pkgx 使用

OpenCanary 已通过 pkgx 打包，因此如果安装了 pkgx，则无需安装，只需在 opencanaryd 命令前加上 pkgx 即可。由于现代 sudo 实现中的环境变量保护机制，整个命令必须以 root 身份运行，或通过 sudo -E 运行。

$ pkgx opencanaryd --version

Docker 安装

OpenCanary Docker 镜像托管在 Docker Hub 上。这些镜像仅在 Linux Docker 主机上有用，因为需要 host 网络引擎才能获得准确的网络信息。

配置 OpenCanary

创建初始配置

当 OpenCanary 启动时，它会按以下位置查找配置文件，并在找到第一个配置后停止查找：

1. /etc/opencanaryd/opencanary.conf
2. ~/.opencanary.conf（即用户的主目录，通常为 root，因此是 /root/.opencanary.conf）
3. ./opencanary.conf（即 OpenCanary 的安装目录）

要创建初始配置，请以 root 身份运行（系统可能会提示你输入 sudo 密码）：

$ opencanaryd --copyconfig
[*] A sample config file is ready /etc/opencanaryd/opencanary.conf

[*] Edit your configuration, then launch with "opencanaryd --start --uid=nobody --gid=nogroup"

这会创建路径和文件 /etc/opencanaryd/opencanary.conf。现在你必须编辑配置文件，以决定要启用哪些服务和日志记录选项。

[!WARNING] 配置文件包含复杂的数据，包括用于日志记录配置的 Python 对象。配置文件是在进程以 root 权限运行时被读取的。我们建议将该文件设置为 root 所有，并且仅 root 可写。如果普通用户可以写入该文件，则可能将权限提升至 root。

启用协议模块与告警

配置通过 JSON 配置文件进行。编辑该文件，满意后保存并退出。

可选模块

SNMP

只有在安装了 Scapy 时，snmp 模块才可用。请参阅上面有关 SNMP 的安装步骤。

Portscan

portscan 模块仅在 Linux 主机上可用，因为它会修改 iptables 规则。

请注意，对于 Portscan 服务，我们添加了一个 portscan.ignore_localhost 设置，这意味着 OpenCanary portscan 服务将忽略（不针对）来自本机 IP（127.0.0.1）的端口扫描发出告警。该设置默认为 false。

Samba 设置

Windows 文件共享模块（smb）需要安装 Samba。请参阅 Wiki 上的分步指南。

运行 OpenCanary

OpenCanary 可以直接在 Linux 或 macOS 主机上运行，也可以通过 Docker 容器运行。

直接在 Linux 或 macOS 上运行

运行以下命令启动 OpenCanary：

$ . env/bin/activate
$ opencanaryd --start --uid=nobody --gid=nogroup

使用 uid 和 gid 标志后，OpenCanary 在绑定端口后即放弃 root 权限。你可以将其改为其他低权限用户/组，或省略以继续以 root 权限运行。

使用 pkgx

运行以下命令启动 OpenCanary：

$ sudo -E pkgx opencanaryd --start --uid=nobody --gid=nogroup

使用 uid 和 gid 标志后，OpenCanary 在绑定端口后即放弃 root 权限。你可以将其改为其他低权限用户/组，或省略以继续以 root 权限运行。

使用 docker compose

这种方式需要安装 Docker 和 Docker Compose。

注意 对于 Docker 化的 OpenCanary，portscan 模块会自动禁用。

1. 编辑 data/.opencanary.conf 文件，以启用、禁用或自定义将要运行的服务。
2. 根据配置文件中启用的服务，编辑 docker-compose.yml 文件的 ports 部分，以启用/禁用所需的端口。
3. 运行容器。
   root@kitploit:~

   docker compose up latest
   

要查看日志，请运行 docker compose logs latest。

要停止容器，请运行 docker compose down。

要使用 docker compose 构建自己的 Docker OpenCanary，请前往我们的 wiki。

使用 Docker

有关 Docker 化 OpenCanary 的一切，请前往我们专门的 Docker wiki。

使用 Ansible

请前往我们 fork 的仓库获取 Ansible OpenCanary 角色：此处。

文档

• Wiki 包含我们的常见问题解答（FAQ）。
• 更多文档可在我们的 主站 上获取。

项目参与

贡献

我们欢迎为本项目提交 PR。请先阅读我们的行为准则和贡献指南文档，然后再提交拉取请求。

在提交 PR 之前，你至少应运行 pre-commit。请在与 OpenCanary 相同的 Python 环境中安装并运行它：

$ pip install pre-commit
$ pre-commit install
# Do work
$ git add file
$ git commit
# If pre-commit generated errors, then run "git add ... && git commit" again

安全漏洞报告

有关如何报告安全漏洞的详细信息，请参阅我们的安全策略。

错误报告

请使用我们提供的模板在 Github 上提交错误报告。

功能请求

功能请求在此处跟踪。

行为准则

本项目及所有参与者均受 行为准则的约束。 参与即表示你同意遵守该准则。如有不可接受的行为， 请向 [email protected] 举报。