ph4ntom Vitrum 🧪

In vitro ("in glass"): automated static malware dissection behind hermetic glass — without a single execution tick of the sample on the host (in vivo is forbidden), turning the "black box" of a binary into transparent glass via Telegram, AI agents (Antigravity / OpenCode / Custom CLI) and IDA Pro 9.5 (ph4ntom-ida-bridge).

You send the bot on Telegram any file or archive (up to 2 GB) → the bot checks the user_id whitelist, downloads the file into quarantine, performs a quick deterministic pre-triage, if necessary launches an isolated IDA Pro 9.5 with ph4ntom-ida-bridge, performs static reverse engineering and config decryption (execute_idapython + local AST sandbox) and sends a ready-made Markdown report back to the same chat.

English Quickstart below ↓

---

Features

• Accepting any files and archives up to 2 GB: working over MTProto (Telethon) removes the 20 MB limit of the cloud Bot API without Docker or third-party proxies.
• Smart and safe extraction: support for ZIP (including WinZip AES-128/256 via pyzipper), 7z, RAR/RAR5 (auto-detection of 7z.exe/UnRAR.exe or explicit SEVENZIP_BIN/UNRAR_BIN, resilience to OEM encodings CP866/CP1251), tar/gz/bz2/xz, CAB, ISO; automatic password selection from the file caption (pass: ...), extracted neighboring text files (ПАРОЛЬ.txt, readme.txt in UTF-8/CP1251/CP866) before recursing into nested archives, and standard malware passwords (infected, malware, virus, etc.); protection against zip-slip, symlinks and zip bombs; preservation of .docm/.xlsm/.apk/.jar as containers with parallel extraction of nested binaries.
• Stage 1 (without spending AI tokens): hash calculation (MD5/SHA-1/SHA-256), entropy, PE (pefile: sections, RWX, imports by threat categories, overlay, TLS, Authenticode, .NET, priority scanning of .rdata/.data), deterministic recovery of stack strings and single-byte XOR buffers (mov byte ptr [rbp/rsp+disp], imm8), ELF, Mach-O, DEX, Office VBA macros (oletools), PDF (/JavaScript, /OpenAction, /URI), Windows .lnk, PowerShell -enc and IOC extractor.
• Stage 1.5 (OSINT orchestrator, optional by profile): when ORCHESTRATOR_INTERNET=1 is enabled (or the extended_static / full_local profile), the daemon passively checks SHA-256 and external domains/IPs from triage via MalwareBazaar, ThreatFox, VirusTotal REST v3 (if VT_API_KEY is set), DNS-over-HTTPS and RDAP without contacting attackers' live servers, saving jobs/<job_id>/osint_report.json. The chief agent also receives the CLI tools/osint_lookup.py (with SSRF protection).
• Stage 2 (AI + IDA Pro 9.5 + Anti-hallucination gate + VirusTotal):
  • Isolated launch of ida.exe -A via tools/ida_session.py with an automatic isolated staging directory IDAUSR (independent of sandbox permissions on %APPDATA%\Hex-Rays\IDA Pro\plugins\), 2-hop search for user functions by string XREF and auto-decompilation of the main function, strict binding by PID/port in ~/.ph4ntom_ida_instances.json, logging of session evidence to ida_evidence.json and guaranteed process termination — your manually opened IDA windows are not affected.
  • Two-level protection against hallucinations and lies (core/report_verifier.py): the prompt obliges the AI to split statements into [ПОДТВЕРЖДЕНО] / [ВЕРОЯТНО] / [НЕ ПОДТВЕРЖДЕНО] and to explicitly report confidence boundaries, while the script tools/send_telegram_report.py deterministically cross-checks the final report against triage_report.json and ida_evidence.json (blocking distorted SHA-256, fabricated sub_* / Hex-Rays when IDA was not run, and unfounded clean verdicts).
  • Configurable permission profiles (core/permissions.py and tools/configure_permissions.py): by default, the safe safe_static mode is used for public GitHub (strict command whitelist and AST sandbox), but with one click you can enable extended_static (+ internet/OSINT) or full_local (full PowerShell + internet for a dedicated analysis PC).
  • Support for custom static scripts for decrypting strings/configs: execute_idapython in IDA and the local sandbox tools/run_static_decoder.py (AST filter + sys.addaudithook, prohibiting process launch, registry access, and writes outside jobs/<id>/decoded/, with optional --allow-network / --unrestricted-imports when full_local is active).
• Multi-backend architecture and hot-switching (backends/): works out of the box with Antigravity, an autonomous local AI agent (local — Ollama / qwen2.5-coder:7b / LM Studio / vLLM with streaming generation control, auto-start of ollama serve, and a 16K context) and OpenCode (opencode run + ready-made config opencode.json.example), and switching between the cloud antigravity and the local model is done directly in Telegram with the command /mode local ↔ /mode antigravity (or a one-off #local tag in the file caption) without restarting the bot.
• Strict access control: the bot works only in direct messages for trusted user_id (data/allowed_users.json). Other users are completely ignored; the owner manages access via /allow and /revoke.

Architecture

[Доверенный user_id в Telegram]
       │  (любой файл / архив до 2 ГБ, опционально пароль в подписи)
       ▼
[bot_daemon.py (Telethon MTProto + Keepalive)]
  ├─ Белый список: data/allowed_users.json (/whoami, /allow, /revoke, /users, /status, /mode, /reset)
  ├─ Очередь (MAX_CONCURRENT_JOBS=1) → скачивание в jobs/<job_id>/sample/
  ├─ Этап 1: tools/triage.py → безопасная распаковка + стековый/XOR декодер + jobs/<job_id>/triage_report.json
  └─ Этап 2: backends/* (Antigravity | Local LLM [Ollama/LM Studio] | OpenCode | Custom CLI)
       │
       ▼
[ИИ-агент (строго статика)]
  ├─ VirusTotal MCP: проверка только SHA-256 / доменов / IP (без загрузки файла)
  ├─ IDA Pro 9.5: tools/ida_session.py open → MCP ida-bridge + static execute_idapython → close
  ├─ Локальные декодеры: tools/run_static_decoder.py (AST + audit hook sandbox)
  └─ Финал: tools/send_telegram_report.py → jobs/<job_id>/delivery_ready.json
       │
       ▼
[bot_daemon.py] → отправляет вердикт, сводку и файл report_<name>.md обратно в чат

Security Model and Permission Profiles (Static-Only + Configurable Profiles)

The public repository is configured according to the secure-by-default principle (PERMISSION_PROFILE=safe_static in .env.example and opencode.json.example), while on your personal PC or dedicated workstation permissions are flexibly extended: