thinkst/opencanary
GitHub: thinkst/opencanary
Stars: 2785 | Forks: 396
# Thinkst Canary 的 OpenCanary
OpenCanary 是一个多协议网络蜜罐。它的主要用例是在黑客入侵非公开网络后捕获他们。它的资源需求极低，并且可以进行调整、修改和扩展。
[](https://github.com/thinkst/opencanary/actions/workflows/opencanary_tests.yml)
[](https://github.com/thinkst/opencanary/actions/workflows/docker-build.yml)
[](https://github.com/thinkst/opencanary/actions/workflows/publish.yml)
## 概述
OpenCanary 作为守护进程运行，并实现了多种常见的网络协议。当攻击者入侵网络并与蜜罐交互时，OpenCanary 将通过多种机制向您发送警报。
OpenCanary 是用 Python 实现的，因此核心蜜罐是跨平台的；但是，某些功能需要特定的操作系统。在 Linux 上运行将为您提供最多的选择。它的资源需求极低；例如，它可以愉快地部署在 Raspberry Pi 或资源极少的虚拟机上。
本 README 描述了如何在 Ubuntu Linux 和 MacOS 上安装和配置 OpenCanary。
OpenCanary 是我们商业 [Thinkst Canary](https://canary.tools) 蜜罐的开源版本。
## 目录
- **[Prerequisites](#prerequisites)**
- **[Features](#features)**
- **[Installation](#installation)**
- [Installation on Ubuntu](#installation-on-ubuntu)
- [Installation on macOS](#installation-on-macos)
- [Installation via Git](#installation-via-git)
- [Installation for Docker](#installation-for-docker)
- **[Configuring OpenCanary](#configuring-opencanary)**
- [Creating the initial configuration](#creating-the-initial-configuration)
- [Enabling protocol modules and alerting](#enabling-protocol-modules-and-alerting)
- [Optional modules](#optional-modules)
- [SNMP](#snmp)
- [Portscan](#portscan)
- [Samba Setup](#samba-setup)
- **[Running OpenCanary](#running-opencanary)**
- [Directly on Linux or macOS](#directly-on-linux-or-macos)
- [With docker compose](#with-docker-compose)
- [With Docker](#with-docker)
- **[Documentation](#documentation)**
- **[Project Participation](#project-participation)**
- [Contributing](#contributing)
- [Security Vulnerability Reports](#security-vulnerability-reports)
- [Bug reports](#bug-reports)
- [Feature Requests](#feature-requests)
- [Code of Conduct](#code-of-conduct)
## 前置条件
* AMD64：Python 3.7（推荐 Python 3.7+）
* ARM64：Python 3.9+
* *可选* SNMP 需要 Python 库 Scapy
* *可选* Samba 模块需要正常安装的 Samba
* *可选* 端口扫描使用 iptables（而非 nftables），且仅在基于 Linux 的操作系统上受支持
## 功能
* 模拟一系列可供攻击者交互的网络可访问服务。
* 一旦检测到潜在威胁，立即接收各种警报，突出显示威胁源 IP 地址以及可能发生违规的位置。
## 安装
OpenCanary 的安装本质上涉及确保 Python 环境准备就绪，然后安装 OpenCanary Python 包（以及可选的额外组件）。
### 在 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
```
可选的额外组件（如果您希望使用 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
```
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/openssl@1.1/lib" CFLAGS="-I/opt/homebrew/opt/openssl@1.1/include" pip install cryptography
```
（上面的编译步骤是必要的，因为可能存在多个 OpenSSL 版本，这会使 Python 库混淆。）
现在可以照常运行安装：
```
$ pip install opencanary
$ 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-.tar.gz
```
### 通过 pkgx 使用
OpenCanary 通过 [pkgx](https://pkgx.sh/) 打包，因此如果安装了 pkgx，则无需安装，只需在 `opencanaryd` 命令前加上 `pkgx`。由于现代 `sudo` 实现中的环境变量保护，整个命令必须以 root 身份运行，或通过 `sudo -E` 运行。
```
$ pkgx opencanaryd --version
```
### Docker 安装
OpenCanary Docker 镜像托管在 Docker Hub 上。这些仅在 Linux Docker 主机上有用，因为准确的网络信息需要 `host` 网络引擎。
## 配置 OpenCanary
### 创建初始配置
当 OpenCanary 启动时，它会在以下位置查找配置文件，并在找到第一个配置时停止：
1. `./opencanary.conf`（即 OpenCanary 安装的目录）
2. `~/.opencanary.conf`（即用户的主目录，通常这将是 `root`，所以是 `/root/.opencanary.conf`）
3. `/etc/opencanaryd/opencanary.conf`
要创建初始配置，请以 `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`。您现在必须编辑配置文件，以确定要启用哪些服务和日志记录选项。
### 启用协议模块和警报
配置通过 JSON 配置文件执行。编辑文件，满意后保存并退出。
### 可选模块
#### 简单网络管理协议
`snmp` 模块仅在存在 Scapy 时可用。请参阅上面有关 SNMP 的安装步骤。
#### 端口扫描
`portscan` 模块仅在 Linux 主机上可用，因为它会修改 `iptables` 规则。
请注意，对于端口扫描服务，我们添加了一个 `portscan.ignore_localhost` 设置，这意味着 OpenCanary `portscan` 服务将忽略（不警报）源自本地主机 IP（`127.0.0.1`）的端口扫描。此设置默认为 false。
#### Samba 设置
Windows 文件共享模块（`smb`）需要安装 Samba。请参阅 [the Wiki](https://github.com/thinkst/opencanary/wiki/Opencanary-and-Samba) 上的分步指南。
## 运行 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](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/)。
1. 编辑 `data/.opencanary.conf` 文件，以启用、禁用或自定义将运行的服务。
2. 编辑 `docker-compose.yml` 文件的 `ports` 部分，根据您在配置文件中启用的服务启用/禁用所需的端口。
3. 运行容器。
docker compose up latest
要查看日志，请运行 `docker compose logs latest`。
要停止容器，请运行 `docker compose down`。
要使用 `docker compose` 构建您自己的 Docker OpenCanary，请前往我们的 [wiki](https://github.com/thinkst/opencanary/wiki/Using-Dockerised-OpenCanary#building-and-running-your-own-docker-opencanary-image-with-docker-compose)
### 使用 Docker
请前往我们专门的 Docker [wiki](https://github.com/thinkst/opencanary/wiki/Using-Dockerised-OpenCanary#building-and-running-your-own-docker-opencanary-image-with-docker) 了解所有 Docker 化的 OpenCanary 内容### 使用 Ansible
请前往我们的分叉仓库，通过 [here](https://github.com/thinkst/ansible-role-opencanary) 获取 Ansible OpenCanary 角色。
## 文档
* [Wiki](https://github.com/thinkst/opencanary/wiki) 包含我们的常见问题解答。
* 我们的 [main site](https://opencanary.org) 上提供了其他文档。
## 项目参与
### 贡献
我们欢迎对此项目提交 PR。在提交拉取请求之前，请阅读我们的 [Code of Conduct](https://github.com/thinkst/.github/blob/master/CODE_OF_CONDUCT.md) 和 [Contributing](https://github.com/thinkst/.github/blob/master/CONTRIBUTING.md) 文档。
至少，您应该在提交 PR 之前运行 `pre-commit`。将其安装并运行在安装了 OpenCanary 的同一 Python 环境中：
```
$ pip install pre-commit
# 工作
$ git add file
$ pre-commit
$ git add file # only run this if pre-commit auto-fixed the file
$ git commit
```
### 安全漏洞报告
有关如何报告安全漏洞的详细信息，请参阅我们的 [Security Policy](https://github.com/thinkst/opencanary/security/policy)。
### 错误报告
请使用我们提供的模板在 [Github](https://github.com/thinkst/opencanary/issues) 上提交错误报告。
### 功能请求
功能请求在 [here](https://github.com/thinkst/opencanary/discussions/categories/feature-requests) 处跟踪。
### 行为准则
本项目及其参与的每个人都受
[Code of Conduct](https://github.com/thinkst/.github/blob/master/CODE_OF_CONDUCT.md) 管辖。
通过参与，您应遵守此准则。请将不可接受的行为报告给
github@thinkst.com。
OpenCanary 是一个多协议网络蜜罐。它的主要用例是在黑客入侵非公开网络后捕获他们。它的资源需求极低，并且可以进行调整、修改和扩展。
[](https://github.com/thinkst/opencanary/actions/workflows/opencanary_tests.yml)
[](https://github.com/thinkst/opencanary/actions/workflows/docker-build.yml)
[](https://github.com/thinkst/opencanary/actions/workflows/publish.yml)
## 概述
OpenCanary 作为守护进程运行，并实现了多种常见的网络协议。当攻击者入侵网络并与蜜罐交互时，OpenCanary 将通过多种机制向您发送警报。
OpenCanary 是用 Python 实现的，因此核心蜜罐是跨平台的；但是，某些功能需要特定的操作系统。在 Linux 上运行将为您提供最多的选择。它的资源需求极低；例如，它可以愉快地部署在 Raspberry Pi 或资源极少的虚拟机上。
本 README 描述了如何在 Ubuntu Linux 和 MacOS 上安装和配置 OpenCanary。
OpenCanary 是我们商业 [Thinkst Canary](https://canary.tools) 蜜罐的开源版本。
## 目录
- **[Prerequisites](#prerequisites)**
- **[Features](#features)**
- **[Installation](#installation)**
- [Installation on Ubuntu](#installation-on-ubuntu)
- [Installation on macOS](#installation-on-macos)
- [Installation via Git](#installation-via-git)
- [Installation for Docker](#installation-for-docker)
- **[Configuring OpenCanary](#configuring-opencanary)**
- [Creating the initial configuration](#creating-the-initial-configuration)
- [Enabling protocol modules and alerting](#enabling-protocol-modules-and-alerting)
- [Optional modules](#optional-modules)
- [SNMP](#snmp)
- [Portscan](#portscan)
- [Samba Setup](#samba-setup)
- **[Running OpenCanary](#running-opencanary)**
- [Directly on Linux or macOS](#directly-on-linux-or-macos)
- [With docker compose](#with-docker-compose)
- [With Docker](#with-docker)
- **[Documentation](#documentation)**
- **[Project Participation](#project-participation)**
- [Contributing](#contributing)
- [Security Vulnerability Reports](#security-vulnerability-reports)
- [Bug reports](#bug-reports)
- [Feature Requests](#feature-requests)
- [Code of Conduct](#code-of-conduct)
## 前置条件
* AMD64：Python 3.7（推荐 Python 3.7+）
* ARM64：Python 3.9+
* *可选* SNMP 需要 Python 库 Scapy
* *可选* Samba 模块需要正常安装的 Samba
* *可选* 端口扫描使用 iptables（而非 nftables），且仅在基于 Linux 的操作系统上受支持
## 功能
* 模拟一系列可供攻击者交互的网络可访问服务。
* 一旦检测到潜在威胁，立即接收各种警报，突出显示威胁源 IP 地址以及可能发生违规的位置。
## 安装
OpenCanary 的安装本质上涉及确保 Python 环境准备就绪，然后安装 OpenCanary Python 包（以及可选的额外组件）。
### 在 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
```
可选的额外组件（如果您希望使用 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
```
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/openssl@1.1/lib" CFLAGS="-I/opt/homebrew/opt/openssl@1.1/include" pip install cryptography
```
（上面的编译步骤是必要的，因为可能存在多个 OpenSSL 版本，这会使 Python 库混淆。）
现在可以照常运行安装：
```
$ pip install opencanary
$ 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-标签：Beacon Object File, BOF, Docker, GUI应用, LangChain, Linux, OpenCanary, PE 加载器, Python, Raspberry Pi, Web界面, 二进制文件分析, 入侵检测, 内存执行, 内网安全, 函数图谱, 域名收集, 多协议支持, 威胁情报, 安全防御, 安全防御评估, 密码管理, 带宽管理, 开发者工具, 开源安全工具, 插件系统, 攻击预警, 无后门, 服务器监控, 欺骗防御, 网络安全, 网络欺骗, 蜜罐, 证书利用, 跨平台, 轻量级, 逆向工程平台, 隐私保护, 黑客追踪