Threatripper

Платформа для повышения осведомлённости о кибербезопасности. Вставьте подозрительное SMS, электронное письмо, сообщение в чате или ссылку — и она покажет, какие мошеннические приёмы обнаружены, почему каждый из них важен и что делать дальше.

Живая демонстрация: https://threatripper.onrender.com (бесплатный тариф Render — первый визит после периода неактивности может занять минуту на пробуждение.)

Это обучающий инструмент, а не средство защиты. Здесь нет антивирусного движка, нет сканирования на вредоносное ПО, нет проверки отправителя и нет сервиса репутации доменов. Ссылки никогда не открываются.

Назначение и область применения. Threatripper — это защитный образовательный инструмент для обнаружения мошеннических признаков в тексте. Он не содержит вредоносного ПО, эксплойтов, фишинговых наборов, списков учётных данных или каких-либо наступательных возможностей и никогда не выполняет сетевых запросов. Все примеры сообщений и доменов в репозитории используют вымышленные зарезервированные имена .example и существуют только для демонстрации логики обнаружения.

Используйте его только для защиты себя и других. Злоупотребление противоречит цели проекта; сообщайте о мошенничестве через официальные каналы (см. Ограничения).

Что он делает

Четыре страницы, без этапа сборки, без JavaScript-фреймворка, без CDN:

Страница	Путь	Назначение
Анализ	`/`	Вставьте сообщение или ссылку и получите оценённый вердикт с объяснением
Осведомлённость	`/awareness.html`	Семь руководств по типам мошенничества плюс советы по сообщению о них
Викторина	`/quiz.html`	Двенадцать сценариев, оцениваемых на сервере с пояснениями
История	`/history.html`	Ваши недавние анализы с уже отредактированными идентификаторами

Анализ намеренно объяснимый, а не авторитетный. Каждый балл по шкале соответствует именованному правилу с уровнем серьёзности, уверенностью и предложением, объясняющим, почему это важно. Интерфейс показывает весь расчёт, включая комбинационные бонусы, так что с результатом можно спорить, а не просто доверять ему.

Чего он не делает:

не проверяет, кто отправил сообщение, и не аутентифицирует личность отправителя
не открывает, не загружает и не переходит по каким-либо ссылкам
не проверяет домен или URL по чёрному списку или сервису репутации
не сканирует файлы или вложения на вредоносное ПО
не гарантирует, что низкая оценка означает «безопасно»

Быстрый старт

Требуется Python 3.11 или новее.

git clone <your-repo-url> threatripper
cd threatripper

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# Use "python3 -m pip", not a bare "pip": on a hardened distro (Kali, Debian,
# Fedora) pip may be an externally managed system binary that is blocked by
# PEP 668, and a bare "pip" will not resolve to the venv.
python3 -m pip install -r requirements.txt

python3 -m uvicorn backend.main:app --reload

Откройте http://127.0.0.1:8000.

Весь продукт — API, каталог правил, база данных и веб-интерфейс — работает в рамках одного процесса на одном источнике. Интерактивная документация API находится по адресу /docs, исходная схема OpenAPI — по адресу /openapi.json.

Чтобы запустить тесты:

python3 -m pip install -r requirements-dev.txt
python3 -m pytest

Терминальный интерфейс

Тот же анализ выполняется из терминала. Это второй интерфейс, а не вторая реализация: каждое правило, оценка, объяснение и рекомендуемое действие берутся из того же AnalysisService, который использует веб-приложение, поэтому они не могут расходиться в том, что опасно.

Ни сервера, ни порта, ни сети — полезно, когда сообщение, на которое вы смотрите, и есть инцидент.

# Analyse a pasted message
./threatripper.sh "URGENT: your account will be closed, share the OTP"

# Or pipe it in, which is the natural way to use it
pbpaste | ./threatripper.sh

# A bare link
./threatripper.sh "http://verify-account.example/login"

# The API payload, for scripts
./threatripper.sh "share your OTP" --json | jq .result.risk_level

# Only fail when it is serious
./threatripper.sh --fail-on critical "see you tomorrow" ; echo $?          # 0
./threatripper.sh --fail-on critical "your bank account will be suspended in 24 hours, verify at http://bank-verify.example/login and share the OTP" ; echo $?   # 1

# Stored history, shared with the web app
./threatripper.sh history
./threatripper.sh history --level critical --json

# Analyse without keeping any record
./threatripper.sh "share your OTP" --no-store

В начале интерактивного запуска выводится красный баннер THREATRIPPER, отрисованный шрифтом ANSI Shadow. Он направляется в stderr и пропускается при --json, а также всякий раз, когда вывод передаётся через конвейер или перенаправляется, поэтому он никогда не попадает в лог и не ломает конвейер. --no-color сохраняет баннер, но убирает цвет.

Каждый глиф в ANSI Shadow — это восточноазиатский символ неоднозначной ширины, поэтому на некоторых терминалах — как правило, в локали CJK или в окне уже 78 колонок — строки отрисовываются с разной шириной, и буквы расползаются. В этом случае баннер незаметно переключается на чисто ASCII-шрифт. Переопределить выбор можно с помощью --banner shadow|ascii|none:

./threatripper.sh --banner shadow "message"   # force the block letters
./threatripper.sh --banner ascii  "message"   # force the terminal-safe face
./threatripper.sh --banner none   "message"   # no banner at all

Как и в веб-приложении, анализ по умолчанию добавляется в общую историю — то же отредактированное превью, никогда не исходный текст. Передайте --no-store, чтобы выполнить анализ без сохранения записи.

./threatripper.sh analyze --help и ./threatripper.sh history --help перечисляют все опции. Лаунчер предпочитает интерпретатор .venv проекта и определяет своё собственное расположение, поэтому он работает из любого каталога и независимо от того, активирован ли virtualenv. python3 -m backend.cli эквивалентен.

Коды выхода

Терминальный инструмент используется в скриптах, поэтому на вопрос «нашёл ли он что-нибудь?» нужно уметь ответить без разбора текста.

Код	Значение
`0`	Ничего не найдено, на уровне порога `--fail-on` или ниже
`1`	Что-то найдено на уровне порога или выше
`2`	Командная строка была неверной
`3`	Анализировать было нечего, или анализ не удалось выполнить

Порог по умолчанию — suspicious. Передайте --fail-on с любым уровнем (low, suspicious, medium, high, critical), чтобы изменить его.

# Fail a deploy pipeline only on a serious finding
./threatripper.sh --fail-on critical "$MESSAGE" || echo "review this message"

Ошибка использования намеренно никогда не разделяет код с находкой, поэтому скрипт может отличить «это сообщение опасно» от «вы неправильно ввели флаг». Нераспознанная полоса риска также завершается с ненулевым кодом, а не сообщает о полном отсутствии проблем.

threatripper