Spam Scanner

Командная строка

Text
spamscanner <command> [options]
КомандаЧто делает
scan [file|-]Проверяет письмо из файла или стандартного ввода
filter -f <sender> -- <recipients...>Контент-фильтр Postfix: проверяет стандартный ввод, добавляет заголовки, передаёт письмо дальше
milterMilter для Postfix и Sendmail, порт 7831
httpHTTP API, порт 7832
serverПростой TCP-сервер, порт 7830
spamdСервер spamd, совместимый со SpamAssassin, порт 783
trainОбучает модель на файлах mbox, каталогах Maildir, папках или наборах данных
evalИзмеряет качество модели на размеченной почте
learn spam|ham [file|-] --model <file>Обучает модель на одном письме
llm-testПроверяет настройки языковой модели на трёх примерах писем
modelsВыводит список рекомендуемых открытых моделей
version, help

scan#

Shell
spamscanner scan message.eml
spamscanner scan - < message.eml
spamscanner scan message.eml --json
spamscanner scan message.eml --headers > tagged.eml
spamscanner scan message.eml --subject-tag "[SPAM]" > tagged.eml
ПараметрЗначение
--jsonВывести полный результат в JSON
--headersВывести письмо с добавленными заголовками X-Spam-*
--subject-tag <tag>Также добавлять префикс к теме спама
--verboseПоказать все тесты и самые сильные признаки классификатора
--threshold <n>Оценка, при которой письмо считается спамом (по умолчанию 5)
--reject-threshold <n>Оценка, при которой письмо отклоняется (по умолчанию 15)
--model <file>Файл модели вместо встроенной
--no-classifierНе использовать классификатор
--config <file>JSON-файл с параметрами библиотеки
--allow-language <codes>Допустимые языки, например en,de,fr

Коды выхода: 0 — hamНужная почта: противоположность спама., 1 — спам, 2 — ошибка.

SMTP-сессия#

ПараметрЗначение
--ip <address>IP-адрес клиента, отправившего письмо
--hostname <name>Проверенное имя клиента в обратной зоне DNS
--helo <name>Имя, которое клиент указал в HELO или EHLO
--from <address>Отправитель в конверте (MAIL FROM)
--to <address>Получатель в конверте; повторите для нескольких

Проверки#

ПараметрЗначение
--authПроверять SPF, DKIM, DMARC и ARC (нужен --ip)
--dnsbl <zone>Чёрный список IP, например zen.spamhaus.org; можно повторять
--uribl <zone>Чёрный список доменов для ссылок, например dbl.spamhaus.org; можно повторять
--dns-server <ip>Сервер имён для DNS-проверок; можно повторять
--no-cloudflareНе спрашивать фильтрующие резолверы Cloudflare о ссылках
--clamav [socket]Проверять вложения через clamd на сокете по умолчанию или указанном
--allowlist <value>Всегда принимать этот IP-адрес, домен или адрес; можно повторять
--denylist <value>Всегда отклонять этот IP-адрес, домен или адрес; можно повторять

Языковая модель#

ПараметрЗначение
--llm <provider>ollama, clef-flash, jev, openai, anthropic и другие (список)
--llm-model <name>Модель, например qwen3.5:4b или claude-haiku-4-5
--llm-method <method>decision (вероятность каждого вердикта за один шаг; по умолчанию, где доступно) или generate (методы)
--llm-account <id>ID аккаунта Cloudflare, для clef и clef-flash
--llm-url <url>Базовый URL, например http://10.0.0.5:11434
--llm-host, --llm-port, --llm-path, --llm-protocolИзменить одну часть URL провайдера
--llm-api-key <key>Ключ API; см. также переменные окружения ниже
--llm-auth <type>bearer, x-api-key, api-key, basic, header или none
--llm-auth-header <name>Заголовок для ключа, вместе с --llm-auth header
--llm-username, --llm-passwordДля --llm-auth basic
--llm-header "Name: value"Дополнительный заголовок запроса; можно повторять
--llm-mode <mode>auto (только спорные случаи, по умолчанию) или always
--llm-timeout <ms>По умолчанию 30000
--llm-policy <text>Дополнительные правила для модели, например «Мы никогда не отправляем счета»
--llm-redact, --no-llm-redactСначала удалять персональные данные; по умолчанию включено для удалённых провайдеров

filter#

Контент-фильтр Postfix. Он читает письмо из стандартного ввода, добавляет заголовки X-Spam-* и передаёт его sendmail с тем же конвертом.

Shell
spamscanner filter -f "$sender" -- "$recipient"
ПараметрЗначение
--sendmail <path>По умолчанию /usr/sbin/sendmail
--subject-tag <tag>Добавлять префикс к теме спама
--rejectВозвращать отправителю письма на пороге отклонения, а не передавать дальше
--discardУдалять письма на пороге отклонения, а не передавать дальше

Коды выхода следуют соглашениям sendmail, которые читает Postfix: 0 — доставлено (или удалено), 64 — не указаны получатели, 69 — отклонено как спам (Postfix возвращает его отправителю), 75 — любой сбой, и тогда Postfix сохраняет письмо и повторяет попытку позже.

milter, http, server и spamd#

Shell
spamscanner milter --port 7831 --reject --subject-tag "[SPAM]"
spamscanner http --port 7832 --token "$SPAMSCANNER_TOKEN"
spamscanner server --port 7830
spamscanner spamd --port 783

Порт 783 клиенты SpamAssassin используют по умолчанию. Для портов ниже 1024 нужны права root или привилегия CAP_NET_BIND_SERVICE; используйте другой порт, например --port 7833, и укажите его клиенту.

ПараметрЗначение
--port <n>TCP-порт
--host <ip>Адрес для прослушивания (по умолчанию 127.0.0.1)
--socket <path>Слушать вместо этого Unix-сокет
--rejectMilter: отклонять почту на пороге отклонения
--reject-code <n>Milter: 451, повторить позже (по умолчанию), или 550
--quarantineMilter: помещать спам в карантин почтового сервера
--name <hostname>Milter: имя этого сервера в Authentication-Results
--token <secret>HTTP: требовать Authorization: Bearer <secret>; нужно для /learn
--allow-tellspamd: принимать запросы TELL (spamc -L spam) для обучения
--out <file>HTTP и spamd: сохранять результаты обучения в этот файл модели
--subject-tag <tag>Milter и spamd: добавлять префикс к теме спама
--verboseMilter: записывать в журнал каждую проверку. TCP-сервер: отвечать одной строкой текста

Параметры проверки, описанные выше, применяются и к серверам. Milter, HTTP API, TCP-сервер и spamd.

train, eval и learn#

Shell
spamscanner train --spam ~/Mail/Junk --ham ~/Mail/Archive --out my-model.json
spamscanner eval --model my-model.json --spam test/spam.mbox --ham test/ham.mbox
spamscanner learn spam message.eml --model my-model.json
ПараметрЗначение
--spam <path>Спам: файл mbox, каталог Maildir или папка с файлами .eml; можно повторять
--ham <path>Ham, аналогично; можно повторять
--dataset <file>Файл CSV или JSON Lines со столбцами текста и метки; можно повторять
--text-column <name>, --label-column <name>Имена столбцов, если они не определяются автоматически
--out <file>Куда записать модель (по умолчанию spamscanner-model.json)
--mergeНачать со встроенной модели (или --model), а не с пустой

learn обновляет файл модели на месте, а при первом запуске создаёт его из встроенной модели. Обучение

llm-test и models#

Shell
spamscanner models
spamscanner llm-test --llm ollama --llm-model qwen3.5:4b

llm-test отправляет модели одно обычное письмо и два мошеннических, на английском и итальянском, выводит её вердикты, время на каждый, использованный метод и оборудование, и завершается с кодом 0, только если все три верны.

Файл конфигурации#

--config file.json (или переменная окружения SPAMSCANNER_CONFIG) загружает параметры библиотеки. Параметры командной строки имеют приоритет над файлом.

JSON
{
  "threshold": 6,
  "authentication": true,
  "dnsbl": {"ip": ["zen.spamhaus.org"], "domain": ["dbl.spamhaus.org"]},
  "dns": {"servers": ["127.0.0.1"]},
  "clamav": {"socket": "/var/run/clamav/clamd.ctl"},
  "llm": {"provider": "ollama", "model": "qwen3.5:4b"},
  "scores": {"deceptiveLink": 4, "FROM_NAME_BRAND": 3}
}

Переменные окружения#

ПеременнаяЗначение
SPAMSCANNER_CONFIGФайл конфигурации
SPAMSCANNER_MODELФайл модели, используемый вместо встроенной
SPAMSCANNER_TOKENТокен для HTTP API
SPAMSCANNER_LLM_API_KEYКлюч API для любого провайдера языковых моделей
CLOUDFLARE_API_TOKEN и CLOUDFLARE_ACCOUNT_ID, TYPESAFE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, CEREBRAS_API_KEY, HF_TOKEN, AZURE_OPENAI_API_KEYСобственный ключ каждого провайдера
NODE_DEBUG=spamscanner*Отладочный журнал

Редактировать эту страницу на GitHub · Markdown ·