Справочник CuckooMX

Краткий справочник по файлам, параметрам Postfix и отличиям конфигурации от upstream xme/cuckoomx.

Пути и файлы по умолчанию (пример развёртывания)

Компонент Типичный путь

Скрипт фильтра

/data/cuckoo/cuckoomx.pl

Конфигурация XML

/data/cuckoo/conf/cuckoomx.conf

Конфигурация Postfix (сервисы)

/etc/postfix/master.cf

Основные параметры Postfix

/etc/postfix/main.cf

Журнал почты (Debian/Ubuntu)

/var/log/mail.log

Sendmail совместимый бинарь Postfix

/usr/sbin/sendmail (значение в XML может переопределяться)

Postfix: фрагмент master.cf

Строка приёма SMTP с фильтром (одна строка с smtpd и опцией через пробел):

smtp      inet  n       -       y       -       -       smtpd
  -o content_filter=cuckoomx

Сервис pipe (имя cuckoomx должно совпадать с content_filter; пользователь и путь — ваши):

cuckoomx  unix  -       n       n       -       -       pipe
  flags=Rq user=cuckoomx null_sender=
  argv=/data/cuckoo/cuckoomx.pl -f ${sender} ${recipient}

Точное форматирование колонок должно соответствовать стилю вашего master.cf; проще всего скопировать соседний pipe-сервис и заменить имя и argv.

Коды выхода скрипта (upstream)

В cuckoomx.pl используются константы Postfix для pipe:

  • 75 (EX_TEMPFAIL) — временная ошибка, Postfix отложит доставку.

  • 69 (EX_UNAVAILABLE) — постоянная ошибка, отказ.

Смысл: при сбоях скрипт не должен «ронять» Postfix через die() без кода — важна согласованность с документацией Postfix. Ошибки ответа REST API Cuckoo в модифицированной версии обрабатываются отдельно: они журналируются и не завершают процесс с этими кодами, чтобы письмо всё равно было доставлено.

REST API: пути и проверка

Базовый URL задаётся в cuckoomx.conf в элементе api-url без завершающего слэша (как в примере из поставки).

Скрипт обращается к следующим относительным путям:

Операция HTTP Путь

Постановка файла

POST

/tasks/create/file

Постановка URL (если включено process-url)

POST

/tasks/create/url

Проверка доступности API с узла Postfix (подставьте свой api-url):

curl "http://127.0.0.1:8090/cuckoo/status"

Если в ответ приходит код 401, включена проверка токена; тогда:

curl -H "Authorization: Bearer ВАШ_ТОКЕН" "http://127.0.0.1:8090/cuckoo/status"

Токен задаётся в файле conf/cuckoo.conf на узле Cuckoo Sandbox: параметр api_token в секции [cuckoo]; то же значение копируют в api-token в cuckoomx.conf на Postfix (см. README в каталоге поставки CuckooMX).

Зависимости Perl

В модифицированном скрипте используются модули (имена пакетов в Debian/Ubuntu могут отличаться):

  • LWP::UserAgent, HTTP::Request::Common — HTTP-клиент и POST;

  • MIME::Parser, File::LibMagic, Archive::Extract, URI::Find, XML::XPath, Digest::MD5, File::Temp, Sys::Syslog.

Если api-url использует схему https://, установите для Perl поддержку HTTPS (например пакет liblwp-protocol-https-perl в Debian/Ubuntu).

Конфигурация XML (cuckoomx.conf)

В upstream ветка /cuckoomx/cuckoo содержала basedir, db, guest для записи в SQLite.

В модифицированной поставке ветка /cuckoomx/cuckoo содержит:

  • api-url — базовый URL API Cuckoo Sandbox;

  • api-token — токен для заголовка Authorization: Bearer (можно оставить пустым, если на стороне Cuckoo аутентификация отключена);

  • guest — имя машины (ВМ) в конфигурации Cuckoo, передаётся в поле machine при создании задачи.

Узлы /cuckoomx/core (outputdir, process-zip, process-rar, process-url), /cuckoomx/logging и списки /cuckoomx/ignore-mime, /cuckoomx/ignore-url сохраняют назначение upstream; в примере конфигурации из поставки приведены комментарии и типовые значения.

Полный пример см. в файле cuckoomx.conf рядом со скриптом в репозитории решения.

Порядок запуска компонентов Cuckoo Sandbox

Чтобы API принимал задачи от CuckooMX, на стороне песочницы (см. README в поставке) обычно требуется:

  1. при использовании ВМ — маршрутизатор Cuckoo (cuckoo rooter);

  2. основной демон анализа (cuckoo -d);

  3. процесс REST API (cuckoo api --host … --port …), а не только веб-интерфейс.

Проверка прослушивания порта API: ss -tlnp или netstat на выбранном порту (часто 8090).

Связанные разделы

Следующая страница: Поиск и устранение неисправностей CuckooMX.