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: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) +[![Stars](https://img.shields.io/github/stars/CreatmanCEO/security-scanner?style=flat&color=yellow)](https://github.com/CreatmanCEO/security-scanner/stargazers) +[![Validate](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml) +[![Bot](https://img.shields.io/badge/%40secure__scanbot-LIVE-22c55e?logo=telegram)](https://t.me/secure_scanbot) [![Platform](https://img.shields.io/badge/platform-Telegram-blue.svg)](https://t.me/secure_scanbot) [![IDS Rules](https://img.shields.io/badge/Suricata%20rules-18%2C987-orange.svg)](#suricata-ids-integration) [![Stalkerware DB](https://img.shields.io/badge/stalkerware%20domains-919-red.svg)](#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. + + + + + + + + + + +
Onboarding flow — three Telegram screens: phone-virus-scan greeting with the five-step explanation, the policy disclaimer 'we do not read your messages or see your passwords — only what your phone is connecting to', and the VPN-client picker for Android (Hiddify, v2rayNG, NekoBox) and iPhone (Streisand, Hiddify)
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.
Scan flow — three Telegram screens: scan started with VPN setup instructions, two ways to provide the VLESS key with copy-to-clipboard, and the final report-delivery screen reporting 'Your phone is safe — 729 connections to 29 services in 10 minutes' with a downloadable HTML report attachment
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: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) +[![Stars](https://img.shields.io/github/stars/CreatmanCEO/security-scanner?style=flat&color=yellow)](https://github.com/CreatmanCEO/security-scanner/stargazers) +[![Validate](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/security-scanner/actions/workflows/validate.yml) +[![Bot](https://img.shields.io/badge/%40secure__scanbot-LIVE-22c55e?logo=telegram)](https://t.me/secure_scanbot) [![Platform](https://img.shields.io/badge/platform-Telegram-blue.svg)](https://t.me/secure_scanbot) [![IDS Rules](https://img.shields.io/badge/Suricata%20rules-18%2C987-orange.svg)](#интеграция-с-suricata-ids) [![Stalkerware DB](https://img.shields.io/badge/stalkerware%20domains-919-red.svg)](#уровень-3-проверка-по-чёрным-спискам) @@ -23,6 +26,25 @@ --- +## Как это выглядит + +> Интерфейс показан на русском (язык по умолчанию). Бот билингв — английская локаль также поддержана. + + + + + + + + + + +
Онбординг — три экрана Telegram: проверка телефона на вирусы, политика приватности 'мы не читаем переписки и не видим пароли', выбор VPN-клиента под Android и iPhone
1 — Онбординг и подключение VPN
Простое объяснение как работает сканирование, явный privacy-disclaimer («мы не читаем переписки — только куда подключается ваш телефон»), линки на VPN-клиенты под каждую ОС с RU-aware fallback'ами на AppStore / Google Play.
Сканирование — три экрана Telegram: сканирование запущено с инструкцией по настройке VPN, два способа передачи VLESS-ключа с copy-to-clipboard, финальный отчёт «Ваш телефон в безопасности — 729 подключений к 29 сервисам за 10 минут» с прикреплённым HTML-отчётом
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.

+ +
+ +
+

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.

+ +
+ +
+

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.

+ +
+ +

Recommendations

+
    +
  1. From a different device, change passwords for your email and banking apps.
  2. +
  3. Consider a factory reset of the phone to remove any potentially malicious software.
  4. +
  5. Install a reputable mobile anti-malware tool (e.g. Malwarebytes Mobile, Dr.Web Light) and run a full scan.
  6. +
+ +

Traffic statistics

+ + + + + + +
MetricValue
Total connections125
Data volume8.3 MB
Unique IP destinations1
Analysis window1,800 s (30 min)
+ +

Top ports

+ + +

Threat-intelligence findings

+ + + + + + + + +
SeverityIPNotes
HIGH85.90.246.234flagged by threat-intel correlation
HIGH172.104.99.199flagged by threat-intel correlation
HIGH37.46.119.14OTX reports: 1
HIGH51.75.34.93flagged by threat-intel correlation
HIGH209.38.189.134flagged by threat-intel correlation
HIGH170.64.245.133flagged by threat-intel correlation
+ +
+ About this sample. This is the actual report format a user receives from @secure_scanbot. The bot's AI report-generator decides which severity level to use for the user (Beginner / Intermediate / Expert) — the version shown here is the Beginner-level rendering, explaining what each port means in plain language. Intermediate and Expert versions 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.

+ Markdown version at sample-scan-report.md. +
+ +
+ + 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