thinkst/opencanaryЛегковесный honeypot, эмулирующий распространённые сетевые сервисы для обнаружения активности злоумышленника после взлома, с расширяемыми модулями протоколов и настраиваемыми оповещениями.
OpenCanary — это многопротокольный сетевой хонейпот. Его основное применение — ловить хакеров после того, как они проникли в непубличные сети. Он предъявляет крайне низкие требования к ресурсам и может быть настроен, модифицирован и расширен.
OpenCanary работает как демон и реализует множество распространённых сетевых протоколов. Когда злоумышленники проникают в сети и взаимодействуют с хонейпотом, OpenCanary будет отправлять вам оповещения через различные механизмы.
OpenCanary реализован на Python, поэтому ядро хонейпота кроссплатформенно; однако некоторые функции требуют определённых ОС. Запуск на Linux даст вам больше всего возможностей. Он предъявляет крайне низкие требования к ресурсам; например, его можно без проблем развернуть на Raspberry Pi или на виртуальной машине с минимальными ресурсами.
В этом README описано, как установить и настроить OpenCanary на Ubuntu Linux и macOS.
OpenCanary — это версия с открытым исходным кодом нашего коммерческого хонейпота Thinkst Canary.
Установка OpenCanary по сути сводится к подготовке окружения Python, а затем к установке Python-пакета OpenCanary (плюс необязательные дополнительные компоненты).
Если установлен uv, вы можете использовать его для создания виртуального окружения и установки пакетов. Если он не установлен, стандартный процесс с python/pip, описанный ниже, продолжит работать.
Установка на 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 File Share и модуль 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
Сначала создайте и активируйте новое виртуальное окружение 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 File Share (smb) недоступен на macOS.
Чтобы установить из исходного кода, вместо запуска 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
OpenCanary распространяется через pkgx, поэтому установка не требуется, если pkgx установлен: просто добавьте pkgx перед командой opencanaryd. Из-за защиты переменных окружения в современных реализациях sudo всю команду необходимо запускать от имени root или через sudo -E.
$ pkgx opencanaryd --version
Образы OpenCanary для Docker размещаются на Docker Hub. Они полезны только на Linux-хостах с Docker, поскольку для точной сетевой информации требуется сетевой движок host.
При запуске OpenCanary ищет файлы конфигурации в следующих местах и остановится, когда найдёт первую конфигурацию:
/etc/opencanaryd/opencanary.conf~/.opencanary.conf (т.е. домашний каталог пользователя, обычно это root, поэтому /root/.opencanary.conf)./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 смотрите выше.
Модуль portscan доступен только на Linux-хостах, поскольку он изменяет правила iptables.
Обратите внимание: для сервиса Portscan мы добавили параметр portscan.ignore_localhost. Это означает, что сервис portscan в OpenCanary будет игнорировать (не оповещать о) сканирования портов, исходящие с IP-адреса localhost (127.0.0.1). По умолчанию этот параметр имеет значение false.
Модуль Windows File Share (smb) требует установки Samba. Пошаговое руководство смотрите в Вики.
OpenCanary можно запускать либо напрямую на хосте Linux или macOS, либо через Docker-контейнер.
Запустите OpenCanary следующей командой:
$ . env/bin/activate
$ opencanaryd --start --uid=nobody --gid=nogroup
С флагами uid и gid OpenCanary сбрасывает привилегии root после привязки к своим портам. Эти флаги можно изменить на другого непривилегированного пользователя/группу или опустить, чтобы продолжить работу с привилегиями root.
Запустите OpenCanary следующей командой:
$ sudo -E pkgx opencanaryd --start --uid=nobody --gid=nogroup
С флагами uid и gid OpenCanary сбрасывает привилегии root после привязки к своим портам. Эти флаги можно изменить на другого непривилегированного пользователя/группу или опустить, чтобы продолжить работу с привилегиями root.
Этот способ требует установки Docker и Docker Compose.
Примечание Модуль portscan автоматически отключается для OpenCanary в Docker.
data/.opencanary.conf, чтобы включить, отключить или настроить сервисы, которые будут запущены.ports файла docker-compose.yml, чтобы включить/отключить нужные порты в зависимости от сервисов, включённых вами в файле конфигурации.docker compose up latest
Чтобы просмотреть журналы, выполните docker compose logs latest.
Чтобы остановить контейнер, выполните docker compose down.
Чтобы собрать собственный Docker-образ OpenCanary с помощью docker compose, перейдите в нашу вики
За всей информацией об OpenCanary в Docker обращайтесь в нашу специализированную вики по Docker.
За ролью Ansible для OpenCanary обращайтесь в наш форкнутый репозиторий здесь.
Мы приветствуем PR в этот проект. Пожалуйста, прочитайте наши документы Кодекс поведения и Внесение вклада перед отправкой pull request.
Как минимум перед отправкой PR вы должны запустить pre-commit. Установите и запустите его в том же окружении Python, в которое установлен OpenCanary:
$ 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].