GuardianAI

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

GuardianAI анализирует текст, ссылки, контекст переписки и изображения с текстом, чтобы находить подозрительные сообщения до того, как пользователь успеет перейти по ссылке, продиктовать код или перевести деньги. Проект рассчитан на использование как backend-ядро для Android, desktop-клиентов и локальных инструментов проверки.

Что Умеет

Гибридная проверка: правила, статистические признаки, Random Forest, RuBERT-эмбеддинги и ONNX-инференс.
Понятный результат: API возвращает score, risk_level, reasons, signals, model_version и latency_ms.
LinkHunter: находит короткие ссылки, IP вместо домена, подозрительные TLD, IDN/punycode, смешение кириллицы и латиницы, а также домены-подделки вроде sberbamk.ru или gosuslugl.ru.
Контекст переписки: можно передать прошлые сообщения, чтобы модель лучше понимала ситуацию.
NER и эвристики: Natasha помогает находить организации, срочность, родственников и запросы чувствительных данных.
OCR: Flet UI может распознавать текст на изображениях через EasyOCR.
Privacy mode: история и feedback не сохраняются без явного согласия.
Batch API: можно анализировать пачку сообщений одним запросом.
Админ-инструменты качества: последние отзывы, false positive / false negative и экспорт feedback в датасет.
CI и Git LFS: есть GitHub Actions, smoke-тесты API и LFS-настройки для моделей/крупных датасетов.

Зачем Это Нужно

Мошеннические сообщения редко выглядят как простой набор ключевых слов. Они давят срочностью, маскируются под банки, госуслуги, доставку, родственников или поддержку мессенджеров. GuardianAI пытается смотреть на сообщение шире:

что написано;
есть ли давление или просьба раскрыть данные;
похожа ли ссылка на официальный домен;
есть ли подозрительные сущности;
насколько уверена ML-модель;
почему система решила, что сообщение опасно.

Итоговый ответ подходит не только для блокировки, но и для объяснения пользователю: “опасно вот из-за этого”.

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

1. Клонирование

git clone https://github.com/f4rceful/GuardianAI.git
cd GuardianAI

Если нужны модели и большие датасеты, подтяните Git LFS-артефакты:

git lfs install
git lfs pull

2. Установка

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Можно установить проект в editable-режиме:

pip install -e .

После этого будут доступны команды:

guardian-api
guardian-ui

3. Настройка

По умолчанию проект работает с настройками из src/config.py. Для переопределения создайте .env на основе .env.example:

GUARDIAN_HOST=0.0.0.0
GUARDIAN_PORT=8550
GUARDIAN_MODEL_PATH=models/model_hybrid.joblib
GUARDIAN_ONNX_MODEL_PATH=models/rubert_tiny2.onnx
GUARDIAN_MODEL_VERSION=2.1
GUARDIAN_STRICT_THRESHOLD=0.6
GUARDIAN_ENABLE_OCR=true
GUARDIAN_ENABLE_NER=true
GUARDIAN_ENABLE_SENTIMENT=true

Для лёгкого dev-режима без тяжёлых optional-компонентов:

GUARDIAN_ENABLE_OCR=false
GUARDIAN_ENABLE_NER=false
GUARDIAN_ENABLE_SENTIMENT=false

4. Запуск API

python src/api/server.py

или:

guardian-api

Адреса:

Swagger UI: http://127.0.0.1:8550/docs
OpenAPI contract: http://127.0.0.1:8550/openapi.json
Healthcheck: http://127.0.0.1:8550/health
Version: http://127.0.0.1:8550/version

5. Запуск UI

python src/ui/main.py

или:

guardian-ui

API

OpenAPI-контракт доступен из коробки:

http://127.0.0.1:8550/docs
http://127.0.0.1:8550/openapi.json

Клиентское Android-приложение живёт отдельно: GuardianAIApp. Оно совместимо с GuardianAI API >= 2.0 и может подключаться к локальному backend через API_BASE_URL.

`GET /health`

Показывает состояние сервиса:

загружена ли модель;
найден ли ONNX-файл;
доступны ли Natasha, OCR и sentiment;
сколько заняла загрузка;
uptime сервиса.

`GET /version`

Возвращает версию API, версию модели и пути к model artifacts.

`POST /predict`

Анализирует одно сообщение.

Запрос:

{
  "text": "Сбер: ваша карта заблокирована. Срочно перейдите на https://sberbamk.ru/pay",
  "strict_mode": false,
  "context": ["SMS"],
  "save_history": false
}

Ответ:

{
  "is_scam": true,
  "score": 0.85,
  "verdict": "DANGEROUS",
  "risk_level": "DANGEROUS",
  "reasons": [
    "срочно",
    "Домен похож на официальный (sberbank.ru)"
  ],
  "signals": {
    "rules": {
      "score": 1.0,
      "triggers": ["срочно"],
      "safe_pattern": false
    },
    "ml": {
      "score": 0.42,
      "verdict": "Safe",
      "threshold": 0.6
    },
    "links": {
      "score": 0.85,
      "has_links": true
    },
    "ner": {
      "score": 0.0,
      "entities": {}
    }
  },
  "model_version": "2.1",
  "latency_ms": 8.41,
  "entities": {},
  "explanation": []
}

`POST /batch_predict`

Анализирует пачку сообщений.

{
  "items": [
    {"text": "Привет, как дела?"},
    {"text": "Срочно переведи деньги на карту"}
  ]
}

`POST /feedback`

Сохраняет feedback только при явном согласии:

{
  "text": "Сообщение было ошибочно помечено как опасное",
  "is_scam_report": false,
  "original_score": 0.78,
  "original_is_scam": true,
  "consent_to_store": true,
  "source": "android"
}

Если consent_to_store=false, API вернёт ошибку и ничего не сохранит.

Админ-ручки

GET /admin/quality
POST /admin/export_feedback

/admin/quality показывает последние отзывы и счётчики false positive / false negative.
/admin/export_feedback экспортирует сохранённый feedback в dataset/scam_samples.txt и dataset/safe_samples.txt.

Как Работает Детекция

сообщение
  -> нормализация гомоглифов
  -> whitelist
  -> regex/rule signals
  -> ML score
  -> LinkHunter score
  -> NER heuristics
  -> final decision
  -> explainable result

Основные модули:

src/core/classifier.py — оркестратор: scoring, final decision, единый формат результата.
src/core/link_hunter.py — анализ ссылок, коротких доменов, punycode и похожести на доверенные домены.
src/core/patterns.py — регулярные правила мошенничества и срочности.
src/core/ner.py — извлечение сущностей через Natasha.
src/core/explainer.py — объяснения и подсветка факторов.
src/api/server.py — FastAPI endpoints.
src/ui/views.py — Flet-интерфейс и локальная симуляция сообщений.

Структура Проекта

GuardianAI/
├── .github/workflows/       # CI: compileall, smoke tests, Docker build
├── dataset/                 # Датасеты для обучения и проверки
├── logs/                    # Runtime logs, папка сохранена через .gitkeep
├── models/                  # ONNX и joblib модели
├── scripts/                 # Локальные проверки, stress-test, аугментация
├── src/
│   ├── api/                 # FastAPI server
│   ├── core/                # Движок анализа
│   ├── ui/                  # Flet UI
│   └── utils/               # Обработка текста
├── tests/                   # Smoke и verification тесты
├── Dockerfile
├── LICENSE
├── pyproject.toml
└── requirements.txt

Обучение И Проверка

Обучение модели:

python train.py

Локальные проверки:

python scripts/test_baseline.py
python scripts/stress_test.py
python scripts/evaluate_and_augment.py

Артефакты для защиты и регрессионной проверки:

python scripts/threshold_report.py --dataset evaluation/golden_test.jsonl
python scripts/run_adversarial_regression.py
python scripts/build_defense_charts.py

Они создают отчеты в evaluation/reports/, SVG-графики в evaluation/charts/ и используют adversarial-набор evaluation/adversarial_cases.jsonl.

Тесты:

python -m compileall src tests scripts
python -m pytest tests/test_api_smoke.py

Docker

docker build -t guardianai .
docker run --rm -p 8550:8550 guardianai

Для локального тестирования Android-приложения против backend удобнее использовать Compose:

docker compose up --build

После запуска Android Emulator может обращаться к API по адресу:

http://10.0.2.2:8550/

Git LFS

Большие файлы вынесены под Git LFS:

models/*.onnx
models/*.joblib
dataset/phishing_dataset_*.txt

Перед коммитом новых моделей или крупных датасетов:

git lfs install
git add --renormalize models dataset/phishing_dataset_*.txt

Privacy

GuardianAI не обязан хранить сообщения, чтобы анализировать риск.

/predict сохраняет историю только при save_history=true.
/feedback сохраняет данные только при consent_to_store=true.
В UI история и feedback выключены по умолчанию, пока пользователь сам не включит сохранение в настройках.

CI

GitHub Actions проверяет:

компиляцию Python-файлов;
smoke-тесты API;
Docker build.

Workflow: .github/workflows/ci.yml.

Лицензия

MIT. Подробнее в LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GuardianAI

Что Умеет

Зачем Это Нужно

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

1. Клонирование

2. Установка

3. Настройка

4. Запуск API

5. Запуск UI

API

`GET /health`

`GET /version`

`POST /predict`

`POST /batch_predict`

`POST /feedback`

Админ-ручки

Как Работает Детекция

Структура Проекта

Обучение И Проверка

Docker

Git LFS

Privacy

CI

Лицензия

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.github/workflows		.github/workflows
data		data
dataset		dataset
evaluation		evaluation
frontend		frontend
logs		logs
models		models
requirements		requirements
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements-ci.txt		requirements-ci.txt
requirements.txt		requirements.txt
train.py		train.py
train_hybrid.py		train_hybrid.py

Folders and files

Latest commit

History

Repository files navigation

GuardianAI

Что Умеет

Зачем Это Нужно

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

1. Клонирование

2. Установка

3. Настройка

4. Запуск API

5. Запуск UI

API

GET /health

GET /version

POST /predict

POST /batch_predict

POST /feedback

Админ-ручки

Как Работает Детекция

Структура Проекта

Обучение И Проверка

Docker

Git LFS

Privacy

CI

Лицензия

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /health`

`GET /version`

`POST /predict`

`POST /batch_predict`

`POST /feedback`

Packages