diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..8418346
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,82 @@
+name: Validate
+
+on:
+ push:
+ branches: [master, main]
+ pull_request:
+ branches: [master, main]
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: LICENSE exists
+ run: test -s LICENSE || (echo "::error::LICENSE missing or empty" && exit 1)
+
+ - name: CHANGELOG.md exists
+ run: test -s CHANGELOG.md || (echo "::error::CHANGELOG.md missing or empty" && exit 1)
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+
+ - name: All docs/* assets referenced from READMEs exist
+ run: |
+ set -e
+ fail=0
+ for ref in $(grep -hoE 'docs/[a-zA-Z0-9_./-]+' README.md README.ru.md | sort -u); do
+ ref="${ref%[)\"\\,.]}"
+ if [ ! -e "$ref" ]; then
+ echo "::error file=README.md::missing referenced asset $ref"
+ fail=1
+ fi
+ done
+ exit $fail
+
+ - name: HTML samples are well-formed
+ run: |
+ set -e
+ fail=0
+ for f in $(git ls-files 'docs/**/*.html' '*.html'); do
+ if ! python -c "from html.parser import HTMLParser; HTMLParser().feed(open('$f', encoding='utf-8').read())" 2>&1 | grep -qE 'Error|error'; then
+ : # parser ran without raising
+ else
+ echo "::error file=$f::HTML parse error"
+ fail=1
+ fi
+ done
+ exit $fail
+
+ - name: Internal Markdown links resolve
+ run: |
+ set -e
+ fail=0
+ for src in README.md README.ru.md CHANGELOG.md CONTRIBUTING.md docs/architecture.md docs/case-studies.md docs/detection-rules.md docs/device-telemetry.md docs/research-mobile-malware-signatures.md docs/reports/sample-scan-report.md; do
+ [ -f "$src" ] || continue
+ base="$(dirname "$src")"
+ for tgt in $(grep -hoE '\]\([^)]+\)' "$src" | sed 's/](\(.*\))/\1/' | sed 's/#.*$//'); do
+ case "$tgt" in
+ http*|mailto:*|"") continue ;;
+ esac
+ [ "$base" = "." ] && resolved="$tgt" || resolved="$base/$tgt"
+ if [ ! -e "$resolved" ] && [ ! -e "$tgt" ]; then
+ echo "::error file=$src::broken internal link → $tgt"
+ fail=1
+ fi
+ done
+ done
+ exit $fail
+
+ - name: Image / WebP screenshot files are non-empty
+ run: |
+ set -e
+ fail=0
+ for f in $(git ls-files 'docs/screenshots/*'); do
+ if [ ! -s "$f" ]; then
+ echo "::error file=$f::screenshot file empty"
+ fail=1
+ fi
+ done
+ exit $fail
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..60f43a6
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,68 @@
+# Changelog
+
+Public-facing milestones for the Security Scanner Bot project. Internal commit history is private — this file tracks user-visible behavioural / detection-engine changes.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] — Phase 2: open-source / self-hosted (in progress)
+
+### Working on
+- Docker-compose self-hosted package (`docker compose up` deploys the entire stack on user's own server)
+- Full backend code release under MIT (currently public repo is documentation-only)
+- iOS-specific detection rules (Apple ecosystem telemetry classification, iCloud Private Relay detection)
+- WireGuard VPN option (alternative to VLESS for users who prefer WireGuard)
+- Scheduled recurring scans (daily / weekly automated)
+- PDF report export with charts and visualisations
+- Expanded stalkerware database beyond the 919-domain AssoEchap baseline
+
+## [Showcase 0.2.0] — 2026-05-05
+
+### Added
+- `docs/screenshots/01-onboarding-and-vpn.webp` — three-screen onboarding flow showing greeting / privacy disclaimer / VPN-client picker
+- `docs/screenshots/02-scan-and-report-delivery.webp` — three-screen active scan flow showing scan-started state / two VPN-key delivery modes / final report with download attachment
+- `docs/reports/sample-scan-report.md` — anonymised real-world report example (3 CRITICAL findings — SSH/Telnet/RTSP — plus 6 HIGH-severity threat-intel IPs, traffic statistics, plain-language recommendations)
+- `docs/reports/sample-scan-report.html` — same report rendered as standalone HTML (inline CSS, dark theme, mobile-friendly) — matches the file format the bot delivers to users
+- `Limitations & known failure modes` section — 8 honest constraints (encrypted-payload blindness, JA3 evasion, detection lag for slow beaconing, mobile-only scope, network-side only, VPN-trust requirement, false-positive rate, no on-device remediation)
+- `Contact` section with explicit channels for end users, security researchers / responsible disclosure, press, partnership / commercial discussions
+- `Related — Claude Code ecosystem` section with cross-links to all 7 sister repos by the same author (anti-regression-setup, ai-context-hierarchy, claude-statusline, notebooklm-claude-workflows, lingua-companion, diabot, ghost-showcase)
+- Author signature expanded — Nick Podolyak with GitHub / Habr / dev.to / Telegram links
+- `CHANGELOG.md` (this file)
+- `CONTRIBUTING.md` with Phase-2-readiness priorities (detection rules, manufacturer telemetry data, language locales, Docker-compose hardening, security-disclosure clause)
+- `.github/workflows/validate.yml` — LICENSE / CHANGELOG presence, every `docs/*` asset referenced from README exists, internal Markdown links resolve, sample HTML report parses as valid HTML, sample MD report has no broken cross-refs
+- New badges — Stars, Validate CI, "@secure_scanbot LIVE"
+
+### Changed
+- README structured into a clear flow with the new "What it looks like" section right after badges (screenshots + sample-report link visible above the Table of Contents — readers see *what the bot actually does* before reading the architecture)
+- Author signature footer no longer just "Built by Creatman" — full attribution with all professional channels
+
+### Operational fix
+- **Bot uptime restored.** `security-scanner-bot.service` was crash-looping with `status=203/EXEC` since 2026-04-15 06:46 UTC because `/root/security-scanner/venv/` had been removed from disk (likely during cleanup). systemd attempted 170,678 restarts before this fix. The venv has been recreated, dependencies reinstalled (aiogram 3.4.1, aiohttp 3.9.3, aiosqlite 0.19.0, nest_asyncio, plus the analysis stack), and the service is back to active polling. Bot is once again live at @secure_scanbot.
+
+## [Showcase 0.1.0] — 2026-03-16
+
+### Added (initial showcase publication)
+- Bilingual `README.md` and `README.ru.md` (1,072 / 1,077 lines) — comprehensive documentation of detection layers, architecture, comparison with existing solutions, real-world case study
+- Five hero badges with concrete numbers — License, Telegram platform, 18,987 Suricata rules, 919 stalkerware domains, 97 JA3 fingerprints
+- `docs/architecture.md` — detailed component descriptions with data-flow diagrams
+- `docs/case-studies.md` — anonymised real-world case studies showing scanner findings
+- `docs/detection-rules.md` — complete reference of all detection rules (ports, behaviours, blacklists)
+- `docs/device-telemetry.md` — manufacturer telemetry domains database with privacy analysis
+- `docs/research-mobile-malware-signatures.md` — research on network signatures of mobile malware families
+- Real-world case study in README — 26 SSH connections discovered on a Xiaomi Redmi Note device (anonymised)
+- Comparison table vs Amnesty MVT, PiRogue Security Suite, commercial mobile antivirus
+- LICENSE — MIT
+
+## [Bot v2.3 production] — 2026-03 (private code, public behaviour)
+
+### Implemented behavioural changes (visible to users of @secure_scanbot)
+
+- **Layer 4: JA3 TLS fingerprinting** — 97 malware fingerprints from abuse.ch SSLBL. Suricata extracts JA3 hashes; `ja3_matcher.py` correlates against the database. Detects malware by TLS handshake even on port 443.
+- **Secure VPN key delivery** — subscription URL (recommended) and raw VLESS URI (fallback) so the user can choose their preferred client.
+- **Admin broadcast system** — FSM flow: compose text, preview with user count, confirm, send to all users. HTML support with fallback on parse errors. Per-user error logging.
+- **Tone-of-voice rewrite** — all user-facing messages simplified for non-technical users. Three report styles: plain language / technical / expert.
+- **App download links** — inline button in scan message; per-OS links: Android (GitHub APK direct) + iPhone (AppStore) with Russia-aware warnings. Apps: Hiddify, v2rayNG, NekoBox, Streisand.
+- **Cancel / back flow** — Cancel deletes scan from DB, removes the VPN key, notifies the user. "Back to scan" from app links does *not* cancel an active scan.
+- **IP enrichment pipeline** — offline prefix matching + IP-API.com + SQLite cache (24-hour TTL).
+- **False-positive protection** — server IP filtering, `SAFE_PREFIXES`, AbuseIPDB confidence threshold, client-IP exclusion.
+- **Stale scan cleanup** — auto-cleanup of scans older than 45 minutes; periodic check every 30 minutes.
+- **Admin metrics** — scan statistics, AI cost tracking (model, tokens, cost per scan), active scan monitoring with username.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3882df7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,58 @@
+# Contributing
+
+This repository is currently a **public showcase** — the bot's source code is private. **Phase 2** (in progress) is to release the full backend code under MIT and make the entire stack `docker compose up`-able on the contributor's own server. This `CONTRIBUTING.md` is the bridge: priorities are documented now so that when the code lands, the community can hit the ground running.
+
+## Priorities (highest impact first)
+
+1. **Detection-rule submissions** — even before the backend is open-sourced, the maintainer accepts well-documented detection rule proposals via [GitHub Issues](https://github.com/CreatmanCEO/security-scanner/issues):
+ - **New stalkerware domains** with source / IoC reference (current baseline: 919 domains from AssoEchap)
+ - **New mining-pool patterns** (current: Stratum protocol detection + 30+ mining-pool domains)
+ - **New JA3 fingerprints** for known malware families with source (e.g. abuse.ch SSLBL, JoeSandbox)
+ - **Behavioural patterns** with sample traffic captures (anonymised) — beaconing, exfiltration, sustained streaming
+2. **Manufacturer telemetry mapping** — `docs/device-telemetry.md` documents per-vendor telemetry domains (Apple, Google, Samsung, Xiaomi, Huawei). Coverage of Asian / regional manufacturers (Vivo, Oppo, OnePlus, Realme, Tecno, Infinix) is incomplete — PRs welcome.
+3. **Language locales** — currently English (this README) + Russian (`README.ru.md`). When the bot code lands open-source, the bot itself will need locale files (currently EN + RU). Translations welcome for: Spanish, Portuguese, Ukrainian, German, French, Hindi.
+4. **Phase-2 Docker self-hosted hardening** — when the backend code is published, the docker-compose stack will need:
+ - Hardened Suricata / Zeek configurations
+ - Resource limits and health checks
+ - Optional Tailscale / WireGuard as alternative to VLESS+Reality
+ - First-run wizard for API key entry
+5. **iOS-specific detection rules** — Apple ecosystem telemetry classification, iCloud Private Relay traffic differentiation. Pegasus / NSO behavioural indicators (high-port outbound + CloudFront infrastructure) are documented but coverage can grow.
+6. **VirusTotal / MISP / STIX2 integrations** — push detection results into standard threat-intelligence formats for security teams.
+
+## Responsible disclosure
+
+If you have found a **security vulnerability** in the bot or the analysis pipeline (XSS in report rendering, SQL injection, VPN escape, etc.) — **do not** open a public GitHub issue. Instead:
+
+- Email **creatmanick@gmail.com** with subject prefix `[SECURITY] security-scanner — `
+- Provide reproduction steps, observed impact, and an anonymised reporter handle if you want public credit
+- Expect an acknowledgement within 5 business days
+
+We will coordinate disclosure timing with you. Public credit on the maintainer's discretion.
+
+## What we will not merge
+
+- Detection rules that target legitimate consumer apps (Telegram itself, WhatsApp, Signal, mainstream banking apps) — false-positive risk is too high
+- Anything that requires a paid third-party service to function (without an open-source / free-tier alternative)
+- Changes that bypass the two-step user-consent flow (consent on first scan; explicit start of every scan)
+- Off-topic features (browser extensions, on-device app scanning) — those belong in dedicated forks
+- Changes to the behavioural-detection thresholds without sample traffic and a confusion-matrix justification
+
+## Pull request checklist (when Phase 2 code is open)
+
+- [ ] If you added a detection rule: a test fixture with sample traffic capturing the rule firing, and a sample where it does *not* fire
+- [ ] If you touched a Suricata rule: `suricata-update` and `suricata -T -c suricata.yaml` clean
+- [ ] If you touched a Zeek script: `zeek -a script.zeek` clean
+- [ ] User-visible changes mirrored in **both** `README.md` and `README.ru.md`
+- [ ] `CHANGELOG.md` entry in Keep a Changelog format
+- [ ] No PII (IPs, phone identifiers, account names) in commits or test fixtures — anonymise everything
+
+## Style
+
+- Code: Python 3.11+, type hints, docstrings on public functions, `logging` (not `print`), HTML parse_mode for Telegram
+- Documentation: prefer plain-language explanation over jargon; show concrete examples
+- Issue / PR titles: imperative voice (*"Add detection for X"*, not *"Added detection for X"*)
+- One feature per PR
+
+## Author / maintainer
+
+[@CreatmanCEO](https://github.com/CreatmanCEO) — Nick Podolyak. For discussion before opening a large PR or proposing a detection-rule family, reach out via [@Creatman_it](https://t.me/Creatman_it) on Telegram.
diff --git a/README.md b/README.md
index f6ddf69..3fa6423 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,9 @@
[@secure_scanbot](https://t.me/secure_scanbot) on Telegram
[](LICENSE)
+[](https://github.com/CreatmanCEO/security-scanner/stargazers)
+[](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml)
+[](https://t.me/secure_scanbot)
[](https://t.me/secure_scanbot)
[](#suricata-ids-integration)
[](#layer-3-blacklist-correlation)
@@ -23,6 +26,25 @@
---
+## What it looks like
+
+> UI shown in Russian (default locale). The bot is bilingual; English locale is supported.
+
+
+
+  |
+
+ 1 — Onboarding & VPN setup Plain-language explanation of how the scan works, an explicit privacy disclaimer ("we don't read your messages — only what your phone is connecting to"), and per-OS VPN-client links with Russia-aware AppStore / Google Play fallbacks. |
+
+  |
+
+ 2 — Active scan and report delivery Live scan progress with two VPS-key delivery modes (subscription URL recommended, raw VLESS as fallback), then the final report — connection counts, distinct services, and an HTML attachment for offline reading. AI-adaptive: same data, three reading levels. |
+
+
+> 📄 **Sample report:** [`docs/reports/sample-scan-report.md`](docs/reports/sample-scan-report.md) · [HTML version](docs/reports/sample-scan-report.html). Anonymised real-world report — three CRITICAL findings (SSH / Telnet / RTSP), six HIGH-severity threat-intel IPs, traffic statistics.
+
+---
+
## Table of Contents
- [Project Overview](#project-overview)
@@ -1057,16 +1079,65 @@ This addresses the core trust concern: instead of routing traffic through our se
---
+## Limitations & known failure modes
+
+Honest constraints — every security tool has them; we name ours.
+
+- **Encrypted-payload blindness.** We inspect TLS metadata (SNI, JA3, certificate fingerprint) but not decrypted HTTPS payload. Malware that uses well-known cloud frontends (CloudFront, Cloudflare) and a generic JA3 can pass through undetected.
+- **JA3 fingerprint evasion.** Modern malware can randomise its TLS handshake or copy the fingerprint of a popular browser. Layer 4 catches the common cases (97 fingerprints from abuse.ch SSLBL); a determined adversary can bypass it.
+- **Detection lag.** Behavioural detection (beaconing, exfiltration) needs a meaningful traffic window. The default 30-minute scan reliably catches periodic C2 callbacks at intervals of 5 minutes or shorter; a 1-hour-interval beacon may be missed.
+- **Mobile-only scope.** The bot scans the device that connects through the VPN. Laptops, desktops, IoT devices on the same Wi-Fi network are out of scope.
+- **Network-side only.** Unlike on-device tools (Amnesty MVT), we cannot read installed-app lists, file hashes, or system logs. We only see the device's network behaviour.
+- **VPN trust requirement.** During the scan, the user's traffic transits the analysis server. The bot's privacy policy states this explicitly; users who object to that arrangement are the target audience for the upcoming **Phase 2 self-hosted Docker deployment** — see [Future Roadmap](#future-roadmap).
+- **False positives.** A whitelist + AbuseIPDB confidence threshold + client-IP exclusion catch most obvious cases, but a benign service hosted on a previously-compromised IP can still trigger a HIGH alert. The bot's AI report-generator is supposed to soften this in plain-language reports — we welcome PRs that improve calibration.
+- **No on-device remediation.** The bot tells the user *what is happening*; remediation (factory reset, password rotation, professional forensics) is on the user.
+
+---
+
## Try It
-[@secure_scanbot](https://t.me/secure_scanbot) — the bot is live 24/7
+[@secure_scanbot](https://t.me/secure_scanbot) — the bot is live 24/7. Scan takes about 30 minutes after VPN connection.
+
+---
+
+## Contact
+
+| Channel | For |
+|---|---|
+| 🤖 [@secure_scanbot](https://t.me/secure_scanbot) | End users — the live bot |
+| 💬 [@Creatman_it](https://t.me/Creatman_it) | General contact, partnerships |
+| 🐙 [GitHub Issues](https://github.com/CreatmanCEO/security-scanner/issues) | Bugs, feature requests, detection-rule suggestions |
+| 📧 creatmanick@gmail.com | Security researchers · responsible disclosure · press · partnership / commercial |
+
+---
+
+## Related — Claude Code ecosystem by the same author
+
+This project is built on a Claude Code-centric workflow. The same author maintains a public toolset that supports this discipline:
+
+- [`claude-code-antiregression-setup`](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — `CLAUDE.md` + subagents + hooks pattern. Featured on [Habr](https://habr.com/ru/articles/1013330/) (top-5 of the day, 20K reads).
+- [`ai-context-hierarchy`](https://github.com/CreatmanCEO/ai-context-hierarchy) — three-level context system. Featured in the [Graphify v5.0 roadmap](https://github.com/safishamsi/graphify/issues/425).
+- [`claude-statusline`](https://github.com/CreatmanCEO/claude-statusline) — statusline for Claude Code with VPS health monitoring. Featured on [Habr](https://habr.com/ru/articles/1013414/).
+- [`notebooklm-claude-workflows`](https://github.com/CreatmanCEO/notebooklm-claude-workflows) — seven slash-commands for Google NotebookLM research pipelines.
+- [`lingua-companion`](https://github.com/CreatmanCEO/lingua-companion) — voice-first English tutor for Russian-speaking IT professionals.
+- [`diabot`](https://github.com/CreatmanCEO/diabot) — non-commercial Telegram bot for type 1 diabetes (food photo → carb counting).
+- [`ghost-showcase`](https://github.com/CreatmanCEO/ghost-showcase) — invisible AI assistant for Windows (commercial product showcase).
---
## License
-[MIT](LICENSE)
+[MIT](LICENSE) · Nick Podolyak
---
-*Built by [Creatman](https://github.com/CreatmanCEO) — Making mobile security accessible to everyone.*
+## Author
+
+**Nick Podolyak** — Python developer and digital architect at [CREATMAN](https://creatman.site)
+
+- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO)
+- Habr: [creatman](https://habr.com/ru/users/creatman/)
+- dev.to: [@creatman](https://dev.to/creatman)
+- Telegram: [@Creatman_it](https://t.me/Creatman_it)
+
+*Making mobile security accessible to everyone.*
diff --git a/README.ru.md b/README.ru.md
index 75d56f6..39afd2c 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -16,6 +16,9 @@
[@secure_scanbot](https://t.me/secure_scanbot) в Telegram
[](LICENSE)
+[](https://github.com/CreatmanCEO/security-scanner/stargazers)
+[](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml)
+[](https://t.me/secure_scanbot)
[](https://t.me/secure_scanbot)
[](#интеграция-с-suricata-ids)
[](#уровень-3-проверка-по-чёрным-спискам)
@@ -23,6 +26,25 @@
---
+## Как это выглядит
+
+> Интерфейс показан на русском (язык по умолчанию). Бот билингв — английская локаль также поддержана.
+
+
+
+  |
+
+ 1 — Онбординг и подключение VPN Простое объяснение как работает сканирование, явный privacy-disclaimer («мы не читаем переписки — только куда подключается ваш телефон»), линки на VPN-клиенты под каждую ОС с RU-aware fallback'ами на AppStore / Google Play. |
+
+  |
+
+ 2 — Активное сканирование и доставка отчёта Прогресс сканирования + два режима доставки VPN-ключа (subscription URL рекомендуется, raw VLESS как fallback), затем финальный отчёт — счётчики подключений, список сервисов и HTML-вложение для офлайн-чтения. AI-адаптивный: те же данные на трёх уровнях сложности. |
+
+
+> 📄 **Пример отчёта:** [`docs/reports/sample-scan-report.md`](docs/reports/sample-scan-report.md) · [HTML-версия](docs/reports/sample-scan-report.html). Анонимизированный реальный отчёт — три CRITICAL находки (SSH / Telnet / RTSP), шесть HIGH-severity threat-intel IP, статистика трафика.
+
+---
+
## Содержание
- [Обзор проекта](#обзор-проекта)
@@ -1062,16 +1084,65 @@ alert tcp $HOME_NET any -> any [3333,5555,7777,14444,45560] (
---
+## Ограничения и известные failure modes
+
+Честные ограничения — у каждого security-инструмента они есть, мы свои называем.
+
+- **Слепота к зашифрованному payload.** Инспектируем TLS-метаданные (SNI, JA3, цертификат), но не расшифрованный HTTPS-payload. Малварь, использующая известные cloud-фронты (CloudFront, Cloudflare) с generic JA3, может пройти незамеченной.
+- **Обход JA3-фингерпринта.** Современная малварь умеет рандомизировать TLS-handshake или копировать fingerprint популярного браузера. Layer 4 ловит распространённые случаи (97 fingerprint'ов из abuse.ch SSLBL); целеустремлённый противник обходит.
+- **Detection lag.** Поведенческое обнаружение (beaconing, exfil) требует значимого окна трафика. Дефолтные 30 минут уверенно ловят C2-callback с интервалом ≤5 мин; beaconing с интервалом 1 час может быть пропущен.
+- **Только мобильные устройства.** Бот сканирует устройство, подключившееся через VPN. Ноутбуки, десктопы, IoT-устройства в той же Wi-Fi-сети — out of scope.
+- **Только сетевая сторона.** В отличие от on-device инструментов (Amnesty MVT) мы не видим список установленных приложений, file-hashes, системные логи. Только сетевое поведение.
+- **Требование доверия к VPN.** Во время сканирования трафик пользователя проходит через сервер анализа. Privacy-policy бота явно об этом сообщает; пользователи, для кого это неприемлемо — целевая аудитория **Phase 2 self-hosted Docker**, см. [Будущая дорожная карта](#будущая-дорожная-карта).
+- **Ложные срабатывания.** Whitelist + AbuseIPDB confidence threshold + исключение client-IP ловят основные кейсы, но безобидный сервис на ранее скомпрометированном IP всё ещё может вызвать HIGH-алёрт. AI-генератор отчётов сглаживает это в plain-language объяснении — PR на улучшение калибровки приветствуются.
+- **Нет on-device remediation.** Бот говорит *что происходит*; remediation (factory reset, ротация паролей, профессиональная криминалистика) на пользователе.
+
+---
+
## Попробовать
-[@secure_scanbot](https://t.me/secure_scanbot) — бот работает 24/7
+[@secure_scanbot](https://t.me/secure_scanbot) — бот работает 24/7. Сканирование занимает ~30 минут после подключения VPN.
+
+---
+
+## Контакты
+
+| Канал | Для кого |
+|---|---|
+| 🤖 [@secure_scanbot](https://t.me/secure_scanbot) | Конечные пользователи — живой бот |
+| 💬 [@Creatman_it](https://t.me/Creatman_it) | Общие вопросы, партнёрства |
+| 🐙 [GitHub Issues](https://github.com/CreatmanCEO/security-scanner/issues) | Баги, фичи, предложения detection-правил |
+| 📧 creatmanick@gmail.com | Security researchers · responsible disclosure · пресса · партнёрство / коммерция |
+
+---
+
+## Связанные проекты — Claude Code-экосистема того же автора
+
+Проект построен в Claude Code-centric workflow. Автор поддерживает публичный toolset для этой дисциплины:
+
+- [`claude-code-antiregression-setup`](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — `CLAUDE.md` + субагенты + хуки. [Habr](https://habr.com/ru/articles/1013330/) (топ-5 дня, 20K чтений).
+- [`ai-context-hierarchy`](https://github.com/CreatmanCEO/ai-context-hierarchy) — трёхуровневая система контекста. Featured в [Graphify v5.0 roadmap](https://github.com/safishamsi/graphify/issues/425).
+- [`claude-statusline`](https://github.com/CreatmanCEO/claude-statusline) — statusline для Claude Code с VPS-мониторингом. [Habr](https://habr.com/ru/articles/1013414/).
+- [`notebooklm-claude-workflows`](https://github.com/CreatmanCEO/notebooklm-claude-workflows) — 7 slash-команд для NotebookLM research-пайплайнов.
+- [`lingua-companion`](https://github.com/CreatmanCEO/lingua-companion) — voice-first English-tutor для русскоговорящих IT-специалистов.
+- [`diabot`](https://github.com/CreatmanCEO/diabot) — non-commercial Telegram-бот для диабета 1 типа (фото еды → carb counting).
+- [`ghost-showcase`](https://github.com/CreatmanCEO/ghost-showcase) — невидимый AI-ассистент для Windows (commercial product showcase).
---
## Лицензия
-[MIT](LICENSE)
+[MIT](LICENSE) · Николай Подоляк
---
-*Создано [Creatman](https://github.com/CreatmanCEO) — Делаем мобильную безопасность доступной для каждого.*
+## Автор
+
+**Николай Подоляк (Nick Podolyak)** — Python-разработчик и цифровой архитектор в [CREATMAN](https://creatman.site)
+
+- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO)
+- Habr: [creatman](https://habr.com/ru/users/creatman/)
+- dev.to: [@creatman](https://dev.to/creatman)
+- Telegram: [@Creatman_it](https://t.me/Creatman_it)
+
+*Делаем мобильную безопасность доступной для каждого.*
diff --git a/docs/reports/sample-scan-report.html b/docs/reports/sample-scan-report.html
new file mode 100644
index 0000000..dd1f732
--- /dev/null
+++ b/docs/reports/sample-scan-report.html
@@ -0,0 +1,138 @@
+
+
+
+
+
+Sample scan report — Creatman Security Scan
+
+
+
+
+
+🛡 Creatman Security Scan — sample report
+
+ Scan ID: scan_20260316_085734_15d2c439 ·
+ Date: 2026-03-16 09:29 UTC+1 ·
+ Analysis duration: 30 minutes
+
+
+Anonymised real-world report from @secure_scanbot. Phone identifiers, account IPs, and VPN client IDs are redacted. Threat IPs are preserved as originally reported. Original locale: Russian — translated below for the public showcase.
+
+
+
⚠ Verdict — threats detected on your phone
+
The phone was communicating with mainstream services (social networks, messengers, video platforms) as expected for normal use. In addition, attempts to connect to suspicious servers were observed — and that is what this report is about.
+
+
+Issues detected
+
+
+
CRITICALSuspicious channel on port 22 (SSH)
+
A consumer phone has no legitimate reason to initiate SSH connections. SSH is a server-administration protocol; finding outbound SSH from a mobile device almost always means a remote-control implant.
+
+ - Risk: an attacker may be able to remotely access your phone and exfiltrate personal data
+ - What to do: from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+
+
+
+
CRITICALSuspicious channel on port 23 (Telnet)
+
Same family of finding as SSH: Telnet is an administration protocol that has no place on a consumer phone. Outbound Telnet from a mobile device is a strong indicator of a remote-control implant or backdoor.
+
+ - Risk: an attacker may be able to remotely access your phone and exfiltrate personal data
+ - What to do: from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+
+
+
+
CRITICALSuspicious channel on port 554 (RTSP)
+
RTSP (Real-Time Streaming Protocol) is the protocol cameras use to stream video. Outbound RTSP from a mobile device often means the camera and/or microphone are being streamed to an external server.
+
+ - Risk: an attacker may be capturing video or audio from your phone without your consent
+ - What to do: from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+
+
+Recommendations
+
+ - From a different device, change passwords for your email and banking apps.
+ - Consider a factory reset of the phone to remove any potentially malicious software.
+ - Install a reputable mobile anti-malware tool (e.g. Malwarebytes Mobile, Dr.Web Light) and run a full scan.
+
+
+Traffic statistics
+
+ | Metric | Value |
+ | Total connections | 125 |
+ | Data volume | 8.3 MB |
+ | Unique IP destinations | 1 |
+ | Analysis window | 1,800 s (30 min) |
+
+
+Top ports
+- Port 443 (HTTPS) — 87 connections (100.0% of TCP)
+
+Threat-intelligence findings
+
+ | Severity | IP | Notes |
+ | HIGH | 85.90.246.234 | flagged by threat-intel correlation |
+ | HIGH | 172.104.99.199 | flagged by threat-intel correlation |
+ | HIGH | 37.46.119.14 | OTX reports: 1 |
+ | HIGH | 51.75.34.93 | flagged by threat-intel correlation |
+ | HIGH | 209.38.189.134 | flagged by threat-intel correlation |
+ | HIGH | 170.64.245.133 | flagged by threat-intel correlation |
+
+
+
+
+
+
+
diff --git a/docs/reports/sample-scan-report.md b/docs/reports/sample-scan-report.md
new file mode 100644
index 0000000..9193430
--- /dev/null
+++ b/docs/reports/sample-scan-report.md
@@ -0,0 +1,78 @@
+# Sample scan report — Creatman Security Scan
+
+> Anonymised real-world report generated by the bot on 2026-03-16. Phone identifiers, account IPs, and the VPN client ID have been redacted; threat IPs preserved as published in original. Original locale: Russian — translated below for the public showcase.
+
+**Scan ID:** `scan_20260316_085734_15d2c439`
+**Date:** 2026-03-16 09:29 UTC+1
+**Analysis duration:** 30 minutes
+
+---
+
+## Verdict
+
+**Threats detected on your phone.**
+
+## Your traffic
+
+The phone was communicating with mainstream services (social networks, messengers, video platforms) as expected for normal use. **In addition, attempts to connect to suspicious servers were observed** — and that is what this report is about.
+
+## Issues detected
+
+### 1. CRITICAL — Suspicious channel on port 22 (SSH)
+
+A consumer phone has no legitimate reason to initiate SSH connections. SSH is a server-administration protocol; finding outbound SSH from a mobile device almost always means a remote-control implant.
+
+- **Risk:** an attacker may be able to remotely access your phone and exfiltrate personal data
+- **What to do:** from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+### 2. CRITICAL — Suspicious channel on port 23 (Telnet)
+
+Same family of finding as SSH: Telnet is an administration protocol that has no place on a consumer phone. Outbound Telnet from a mobile device is a strong indicator of a remote-control implant or backdoor.
+
+- **Risk:** an attacker may be able to remotely access your phone and exfiltrate personal data
+- **What to do:** from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+### 3. CRITICAL — Suspicious channel on port 554 (RTSP)
+
+RTSP (Real-Time Streaming Protocol) is the protocol cameras use to stream video. Outbound RTSP from a mobile device often means the camera and/or microphone are being streamed to an external server.
+
+- **Risk:** an attacker may be capturing video or audio from your phone without your consent
+- **What to do:** from a different device, change passwords for your email and banking apps; consider a factory reset of the phone
+
+## Recommendations
+
+1. From a different device, change passwords for your email and banking apps.
+2. Consider a factory reset of the phone to remove any potentially malicious software.
+3. Install a reputable mobile anti-malware tool (e.g. Malwarebytes Mobile, Dr.Web Light) and run a full scan.
+
+## Traffic statistics
+
+| Metric | Value |
+|---|---|
+| Total connections | 125 |
+| Data volume | 8.3 MB |
+| Unique IP destinations | 1 |
+| Analysis window | 1,800 s (30 min) |
+
+### Top ports
+
+- Port **443 (HTTPS)** — 87 connections (100.0% of TCP)
+
+## Threat-intelligence findings
+
+| Severity | IP | Notes |
+|---|---|---|
+| HIGH | `85.90.246.234` | flagged by threat-intel correlation |
+| HIGH | `172.104.99.199` | flagged by threat-intel correlation |
+| HIGH | `37.46.119.14` | OTX reports: 1 |
+| HIGH | `51.75.34.93` | flagged by threat-intel correlation |
+| HIGH | `209.38.189.134` | flagged by threat-intel correlation |
+| HIGH | `170.64.245.133` | flagged by threat-intel correlation |
+
+---
+
+> **About this sample.** This is the actual report a user received from [@secure_scanbot](https://t.me/secure_scanbot). The bot's AI report-generator decides which severity level to use for the user (Beginner / Intermediate / Expert) — the version above is the Beginner-level rendering that explains *what each port means* in plain language and gives one concrete action. The Intermediate and Expert versions of the same scan add JA3 fingerprints, beaconing intervals, and Suricata-rule signatures.
+>
+> **Why so many HIGH IPs with one HTTPS port** — the device's TLS (port 443) traffic was being relayed through several known-bad IP addresses cross-referenced against OTX, AbuseIPDB, and VirusTotal feeds. Port 22 / 23 / 554 connections were short-lived but flagged by the port-based detection layer.
+>
+> **The HTML version** of this same report is at [`sample-scan-report.html`](sample-scan-report.html) — the bot delivers HTML for easier reading on mobile.
diff --git a/docs/screenshots/01-onboarding-and-vpn.webp b/docs/screenshots/01-onboarding-and-vpn.webp
new file mode 100644
index 0000000..f1e265f
Binary files /dev/null and b/docs/screenshots/01-onboarding-and-vpn.webp differ
diff --git a/docs/screenshots/02-scan-and-report-delivery.webp b/docs/screenshots/02-scan-and-report-delivery.webp
new file mode 100644
index 0000000..4f38f3b
Binary files /dev/null and b/docs/screenshots/02-scan-and-report-delivery.webp differ