sssnake/Autarch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Autarch/autarch_dev.md
DigiJ ffe47c51b5 Initial public release — AUTARCH v1.0.0 
Full security platform with web dashboard, 16 Flask blueprints, 26 modules,
autonomous AI agent, WebUSB hardware support, and Archon Android companion app.

Includes Hash Toolkit, debug console, anti-stalkerware shield, Metasploit/RouterSploit
integration, WireGuard VPN, OSINT reconnaissance, and multi-backend LLM support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 03:57:32 -08:00

30 KiB
Raw Blame History

AUTARCH Development Status

darkHal Security Group - Project AUTARCH

Last Updated: 2026-02-28

Project Overview

AUTARCH is a full-stack security platform built in Python. It combines a CLI framework with a Flask web dashboard, LLM integration (llama.cpp, HuggingFace transformers, Claude API), Metasploit/RouterSploit RPC integration, an OSINT database with 7,200+ sites, and physical hardware device management.

Codebase: ~40,000 lines of Python across 65 source files + 3,237 lines JS/CSS Location: /home/snake/autarch/ Platform: Linux (Orange Pi 5 Plus, RK3588 ARM64)

Current Architecture

autarch/
├── autarch.py                  # Main entry point (613 lines) - CLI + --web flag
├── autarch_settings.conf       # INI config (11 sections)
├── core/                       # 25 Python modules (~12,500 lines)
│   ├── agent.py                # Autonomous agent loop (THOUGHT/ACTION/PARAMS)
│   ├── banner.py               # ASCII banner
│   ├── config.py               # Config handler with typed getters
│   ├── cve.py                  # NVD API v2.0 + SQLite CVE database
│   ├── android_protect.py      # Anti-stalkerware/spyware shield
│   ├── hardware.py             # ADB/Fastboot/Serial/ESP32 manager
│   ├── llm.py                  # LLM wrapper (llama.cpp + transformers + Claude + HuggingFace)
│   ├── menu.py                 # Category menu system (8 categories)
│   ├── msf.py                  # Metasploit RPC client (msgpack)
│   ├── msf_interface.py        # Centralized MSF interface
│   ├── msf_modules.py          # MSF module library (45 modules)
│   ├── msf_terms.py            # MSF settings term bank (54 settings)
│   ├── pentest_pipeline.py     # PentestGPT 3-module pipeline
│   ├── pentest_session.py      # Pentest session persistence
│   ├── pentest_tree.py         # Penetration Testing Tree (MITRE ATT&CK)
│   ├── report_generator.py     # HTML report generator
│   ├── rsf.py                  # RouterSploit integration
│   ├── rsf_interface.py        # Centralized RSF interface
│   ├── rsf_modules.py          # RSF module library
│   ├── rsf_terms.py            # RSF settings term bank
│   ├── sites_db.py             # OSINT sites SQLite DB (7,287 sites)
│   ├── tools.py                # Tool registry (12+ tools + MSF tools)
│   ├── upnp.py                 # UPnP port forwarding manager
│   ├── wireshark.py            # tshark/pyshark wrapper
│   ├── wireguard.py            # WireGuard VPN + Remote ADB manager
│   ├── discovery.py            # Network discovery (mDNS + Bluetooth advertising)
│   └── mcp_server.py           # MCP server (expose AUTARCH tools to AI clients)
│
├── modules/                    # 26 modules (~11,000 lines)
│   ├── adultscan.py            # Adult site username scanner (osint)
│   ├── android_protect.py      # Android protection shield CLI (defense)
│   ├── agent.py                # Agent task interface (core)
│   ├── agent_hal.py            # Agent Hal v2.0 - AI automation (core)
│   ├── analyze.py              # File forensics (analyze)
│   ├── chat.py                 # LLM chat interface (core)
│   ├── counter.py              # Threat detection (counter)
│   ├── defender.py             # System hardening + scan monitor (defense)
│   ├── dossier.py              # OSINT investigation manager (osint)
│   ├── geoip.py                # GEO IP lookup (osint)
│   ├── hardware_local.py       # Local hardware access CLI (hardware)
│   ├── hardware_remote.py      # Remote hardware stub (hardware)
│   ├── msf.py                  # MSF interface v2.0 (offense)
│   ├── mysystem.py             # System audit + CVE detection (defense)
│   ├── nettest.py              # Network testing (utility)
│   ├── recon.py                # OSINT recon + nmap scanner (osint)
│   ├── rsf.py                  # RouterSploit interface (offense)
│   ├── setup.py                # First-run setup wizard
│   ├── simulate.py             # Attack simulation (simulate)
│   ├── snoop_decoder.py        # Snoop database decoder (osint)
│   ├── upnp_manager.py         # UPnP port management (defense)
│   ├── wireshark.py            # Packet capture/analysis (analyze)
│   ├── wireguard_manager.py    # WireGuard VPN manager CLI (defense)
│   ├── workflow.py             # Workflow automation
│   └── yandex_osint.py         # Yandex OSINT (osint)
│
├── web/                        # Flask web dashboard
│   ├── app.py                  # App factory (16 blueprints)
│   ├── auth.py                 # Session auth (bcrypt)
│   ├── routes/                 # 15 route files (~4,500 lines)
│   │   ├── analyze.py, android_protect.py, auth_routes.py, counter.py
│   │   ├── chat.py, dashboard.py, defense.py, hardware.py, msf.py, offense.py
│   │   ├── osint.py, settings.py, simulate.py, upnp.py, wireshark.py
│   │   └── wireguard.py
│   ├── templates/              # 18 Jinja2 templates
│   │   ├── base.html (dark theme, sidebar nav, HAL chat panel, debug popup)
│   │   ├── android_protect.html, dashboard.html, login.html
│   │   ├── hardware.html, wireshark.html, wireguard.html, defense.html, offense.html
│   │   ├── counter.html, analyze.html, osint.html, simulate.html
│   │   ├── msf.html (MSF RPC terminal console)
│   │   ├── settings.html, llm_settings.html, upnp.html, category.html
│   └── static/
│       ├── css/style.css       # Dark theme
│       ├── js/app.js           # Vanilla JS (HAL chat + debug console + hardware)
│       ├── js/hardware-direct.js  # WebUSB/Web Serial direct-mode API (752 lines)
│       └── js/lib/
│           ├── adb-bundle.js      # ya-webadb bundled (57KB)
│           ├── fastboot-bundle.js # fastboot.js bundled (146KB)
│           └── esptool-bundle.js  # esptool-js bundled (176KB)
│
├── autarch_companion/           # Archon Android app (29 files, Kotlin)
│   ├── app/src/main/kotlin/com/darkhal/archon/  # Kotlin source (8 files)
│   ├── app/src/main/res/       # Layouts, themes, icons (12 XML files)
│   └── app/src/main/assets/bbs/ # BBS terminal WebView (3 files)
│
├── data/                       # Persistent data
│   ├── android_protect/        # Per-device scan reports and configs
│   ├── wireguard/              # WireGuard client configs and state
│   ├── cve/cve.db              # CVE SQLite database
│   ├── hardware/               # Hardware operation data
│   ├── pentest_sessions/       # Pentest session JSON files
│   ├── sites/sites.db          # OSINT sites database
│   ├── stalkerware_signatures.json  # Stalkerware/spyware signature DB (275+ packages)
│   └── uploads/                # Web file uploads
│
├── .config/                    # Hardware config templates
│   ├── nvidia_4070_mobile.conf
│   ├── amd_rx6700xt.conf
│   ├── orangepi5plus_cpu.conf
│   ├── orangepi5plus_mali.conf
│   └── custom/                 # User-saved configs
│
├── dossiers/                   # OSINT dossier JSON files
└── results/                    # Reports and scan results

Categories & Menu System

# Category Modules Description
1 Defense defender, mysystem, upnp_manager, scan monitor, android_protect, wireguard_manager System audit, CVE detection, UPnP, scan monitoring, Android anti-stalkerware, WireGuard VPN
2 Offense msf, rsf, agent_hal (pentest pipeline) MSF/RSF automation, AI-guided pentesting
3 Counter counter Threat detection, rootkit checks, anomaly detection
4 Analyze analyze, wireshark File forensics, packet capture/analysis
5 OSINT recon, adultscan, dossier, geoip, yandex, snoop Username scan (7K+ sites), nmap, dossier management
6 Simulate simulate Port scan, password audit, payload generation
7 Hardware hardware_local, hardware_remote ADB/Fastboot/Serial/ESP32 device management
99 Settings setup LLM, MSF, OSINT, UPnP, web, pentest config

Technology Stack

  • Language: Python 3.10
  • Web: Flask, Jinja2, vanilla JS, SSE (Server-Sent Events)
  • LLM Backends: llama-cpp-python (GGUF), HuggingFace transformers (SafeTensors), Anthropic Claude API, HuggingFace Inference API
  • MCP: Model Context Protocol server (11 tools, stdio + SSE transports)
  • Databases: SQLite (CVEs, OSINT sites), JSON (sessions, dossiers, configs, stalkerware signatures)
  • Integrations: Metasploit RPC (msgpack), RouterSploit, NVD API v2.0, social-analyzer
  • Hardware: ADB/Fastboot (Android SDK), pyserial + esptool (ESP32), tshark/pyshark
  • Network: miniupnpc (UPnP), nmap, tcpdump, WireGuard (wg/wg-quick), USB/IP

Evolution Plan (from master_plan.md)

Phase Description Status
Phase 0 Backup & new working directory (~/autarch) DONE
Phase 1 UPnP Manager integration DONE
Phase 2 Flask web dashboard (12 blueprints, 14 templates) DONE
Phase 3 OSINT search engine (web UI) DONE
Phase 4 Wireshark module (tshark + pyshark) DONE
Phase 4.5 Hardware module (ADB/Fastboot/ESP32) DONE
Phase 4.6 Android Protection Shield (anti-stalkerware/spyware) DONE
Phase 4.7 Tracking Honeypot (fake data for ad trackers) DONE
Phase 4.8 WireGuard VPN + Remote ADB (TCP/IP & USB/IP) DONE
Phase 4.9 Archon Android Companion App DONE
Phase 4.10 HuggingFace Inference + MCP Server + Service Mode DONE
Phase 4.12 MSF Web Module Execution + Agent Hal + Global AI Chat DONE
Phase 4.13 Debug Console (floating log panel, 5 filter modes) DONE
Phase 4.14 WebUSB "Already In Use" fix (USB interface release on disconnect) DONE
Phase 4.15 LLM Settings sub-page (4 backends, full params, folder model scanner) DONE
Phase 5 Path portability & Windows support MOSTLY DONE
Phase 6 Docker packaging NOT STARTED
Phase 7 System Tray + Beta Release (EXE + MSI) TODO

Additions Beyond Original Plan

  • RSF (RouterSploit) integration (core/rsf*.py, modules/rsf.py)
  • Workflow module (modules/workflow.py)
  • Nmap scanner integrated into OSINT recon
  • Scan monitor integrated into defense module
  • Android Protection Shield — anti-stalkerware/spyware detection and remediation
  • MCP Server — expose 11 AUTARCH tools via Model Context Protocol
  • HuggingFace Inference API — remote model inference backend
  • Systemd Service — run web dashboard as background service
  • Sideload — push Archon APK to Android devices via ADB

What Was Recently Added (Phase 4.12–4.15)

MSF Web Module Execution + Agent Hal (Phase 4.12)

  • web/routes/offense.py — POST /offense/module/run SSE stream + POST /offense/module/stop
  • web/templates/offense.html — Run Module tabs (SSH/PortScan/OSDetect/Custom) + Agent Hal panel
  • web/routes/msf.py (NEW) — MSF RPC console blueprint at /msf/
  • web/templates/msf.html (NEW) — dark terminal MSF console UI
  • web/routes/chat.py (NEW) — /api/chat SSE, /api/agent/run|stream|stop
  • web/templates/base.html — global HAL chat panel (fixed bottom-right) + MSF Console nav link
  • web/static/js/app.js — halToggle/Send/Append/Scroll/Clear() functions
  • web/app.py — registered msf_bp + chat_bp
  • core/agent.py — added step_callback param to Agent.run() for SSE step streaming

Debug Console (Phase 4.13)

  • web/routes/settings.py — _DebugBufferHandler, _ensure_debug_handler(), 4 debug API routes
  • web/templates/settings.html — Debug Console section with enable toggle + test buttons
  • web/templates/base.html — draggable floating debug popup, DBG toggle button
  • web/static/js/app.js — full debug JS: stream, filter (5 modes), format, drag
  • 5 filter modes: Warnings & Errors | Full Verbose | Full Debug + Symbols | Output Only | Show Everything

WebUSB "Already In Use" Fix (Phase 4.14)

  • web/static/js/hardware-direct.js — adbDisconnect() releases USB interface; adbConnect() detects Windows "already in use", auto-retries, shows actionable "run adb kill-server" message

LLM Settings Sub-Page (Phase 4.15)

  • core/config.py — added get_openai_settings() (api_key, base_url, model, max_tokens, temperature, top_p, frequency_penalty, presence_penalty)
  • web/routes/settings.py — GET /settings/llm (sub-page), POST /settings/llm/scan-models (folder scanner), updated POST /settings/llm for openai backend
  • web/templates/settings.html — LLM section replaced with sub-menu card linking to /settings/llm
  • web/templates/llm_settings.html (NEW) — 4-tab dedicated LLM config page:
    • Local: folder browser → model file list (.gguf/.safetensors) + full llama.cpp AND transformers params
    • Claude: API key + model dropdown + basic params
    • OpenAI: API key + base_url + model + basic params
    • HuggingFace: token login + verify + model ID + 8 provider options + full generation params

What Was Recently Added (Phase 4.10)

HuggingFace Inference API Backend

  • core/llm.py — HuggingFaceLLM class using huggingface_hub.InferenceClient
  • Supports text_generation() and chat_completion() with streaming
  • Config section: [huggingface] (api_key, model, endpoint, max_tokens, temperature, top_p)
  • config.py — added get_huggingface_settings() method

MCP Server (Model Context Protocol)

  • core/mcp_server.py — FastMCP server exposing 11 AUTARCH tools
  • Tools: nmap_scan, geoip_lookup, dns_lookup, whois_lookup, packet_capture, wireguard_status, upnp_status, system_info, llm_chat, android_devices, config_get
  • Transports: stdio (for Claude Desktop/Code), SSE (for web clients)
  • CLI: python autarch.py --mcp [stdio|sse] with --mcp-port
  • Web: 4 API endpoints under /settings/mcp/ (status, start, stop, config)
  • Menu: option [10] MCP Server with start/stop SSE, show config, run stdio
  • Config snippet generator for Claude Desktop / Claude Code integration

Systemd Service + Sideload

  • scripts/autarch-web.service — systemd unit file for web dashboard
  • autarch.py --service [install|start|stop|restart|status|enable|disable]
  • Menu [8] Web Service — full service management UI
  • Menu [9] Sideload App — push Archon APK to Android device via ADB

Web UI LLM Settings

  • Settings page now shows all 4 backends with save+activate forms
  • Each backend has its own form with relevant settings
  • /settings/llm POST route switches backend and saves settings

What Was Recently Added (Phase 4.9)

Archon — Android Companion App

  • Location: autarch_companion/ (29 files)
  • Package: com.darkhal.archon — Kotlin, Material Design 3, Single Activity + Bottom Nav
  • Name origin: Greek ἄρχων (archon = ruler), etymological root of "autarch"
  • 4 Tabs:
    • Dashboard — ADB TCP/IP toggle, USB/IP export toggle, kill/restart ADB with 5s auto-restart watchdog, WireGuard tunnel status
    • Links — Grid of 9 cards linking to AUTARCH web UI sections (Dashboard, WireGuard, Shield, Hardware, Wireshark, OSINT, Defense, Offense, Settings)
    • BBS — Terminal-style WebView for Autarch BBS via Veilid protocol (placeholder — veilid-wasm integration pending VPS deployment)
    • Settings — Server IP, web/ADB/USB-IP ports, auto-restart toggle, BBS address, connection test
  • Key files:
    • service/AdbManager.kt — ADB TCP/IP enable/disable, kill/restart, status check via root shell
    • service/UsbIpManager.kt — usbipd start/stop, device listing, bind/unbind
    • util/ShellExecutor.kt — Shell/root command execution with timeout
    • util/PrefsManager.kt — SharedPreferences wrapper for all config
    • assets/bbs/ — BBS terminal HTML/CSS/JS with command system and Veilid bridge placeholder
  • Theme: Dark hacker aesthetic — terminal green (#00FF41) on black (#0D0D0D), monospace fonts
  • Build: Gradle 8.5, AGP 8.2.2, Kotlin 1.9.22, minSdk 26, targetSdk 34
  • Network Discovery:
    • Server: core/discovery.py — DiscoveryManager singleton, mDNS (_autarch._tcp.local.) + Bluetooth (name="AUTARCH", requires security)
    • App: service/DiscoveryManager.kt — NSD (mDNS) + Wi-Fi Direct + Bluetooth scanning, auto-configures server IP/port
    • Priority: LAN mDNS > Wi-Fi Direct > Bluetooth
    • Config: autarch_settings.conf [discovery] section, 3 API routes under /settings/discovery/

Previously Added (Phase 4.8)

WireGuard VPN + Remote ADB

  • See devjournal.md Session 15 for full details

Previously Added (Phase 4.7)

Tracking Honeypot — Feed Fake Data to Ad Trackers

  • Concept: Feed fake data to ad trackers (Google, Meta, data brokers) while letting real apps function normally
  • data/tracker_domains.json — 2000+ tracker domains from EasyList/EasyPrivacy/Disconnect patterns
    • 5 categories: advertising (882), analytics (332+), fingerprinting (134), social_tracking (213), data_brokers (226)
    • 12 company profiles (Google, Meta, Amazon, Microsoft, etc.) with SDK package names
    • 139 known Android tracker SDK packages
    • 25 tracking-related Android permissions
    • 4 ad-blocking DNS providers (AdGuard, NextDNS, Quad9, Mullvad)
    • Fake data templates: 35 locations, 42 searches, 30 purchases, 44 interests, 25 device models
  • core/android_protect.py — added ~35 honeypot methods to AndroidProtectManager
    • 3 tiers of protection: Tier 1 (ADB), Tier 2 (Shizuku), Tier 3 (Root)
    • Tier 1: Reset ad ID, opt out tracking, ad-blocking DNS, disable location scanning, disable diagnostics
    • Tier 2: Restrict background data, revoke tracking perms, clear tracker data, force-stop trackers
    • Tier 3: Hosts file blocklist, iptables redirect, fake GPS, rotate device identity, fake device fingerprint
    • Composite: Activate/deactivate all protections by tier, per-device state persistence
    • Detection: Scan tracker apps, scan tracker permissions, view ad tracking settings
  • modules/android_protect.py — added menu items 70-87 with 18 handler methods
  • web/routes/android_protect.py — added 28 honeypot routes under /android-protect/honeypot/
  • web/templates/android_protect.html — added 5th "Honeypot" tab with 7 sections and ~20 JS functions

Previously Added (Phase 4.6)

Android Protection Shield — Anti-Stalkerware & Anti-Spyware

  • core/android_protect.py - AndroidProtectManager singleton (~650 lines)
    • Stalkerware detection: scans installed packages against 275+ known stalkerware signatures across 103 families
    • Government spyware detection: checks for Pegasus, Predator, Hermit, FinSpy, QuaDream, Candiru, Chrysaor, Exodus, Phantom, Dark Caracal indicators (files, processes, properties)
    • System integrity: SELinux, verified boot, dm-verity, su binary, build fingerprint
    • Hidden app detection: apps without launcher icons (filtered from system packages)
    • Device admin audit: flags suspicious device admins against stalkerware DB
    • Accessibility/notification listener abuse: flags non-legitimate services
    • Certificate audit: user-installed CA certs (MITM detection)
    • Network config audit: proxy hijacking, DNS, VPN profiles
    • Developer options check: USB debug, unknown sources, mock locations, OEM unlock
    • Permission analysis: dangerous combo finder (8 patterns), per-app breakdown, heatmap matrix
    • Remediation: disable/uninstall threats, revoke permissions, remove device admin, remove CA certs, clear proxy
    • Shizuku management: install, start, stop, status check for privileged operations on non-rooted devices
    • Shield app management: install, configure, grant permissions to protection companion app
    • Signature DB: updatable from GitHub (AssoEchap/stalkerware-indicators), JSON format
    • Scan reports: JSON export, per-device storage in data/android_protect/<serial>/scans/
  • modules/android_protect.py - CLI module (CATEGORY=defense) with 30+ menu items
  • web/routes/android_protect.py - Flask blueprint with 33 routes under /android-protect/
  • web/templates/android_protect.html - Web UI with 4 tabs (Scan, Permissions, Remediate, Shizuku)
  • data/stalkerware_signatures.json - Threat signature database (103 families, 275 packages, 10 govt spyware, 8 permission combos)
  • Modified web/app.py — registered android_protect_bp blueprint
  • Modified web/templates/base.html — added "Shield" link in Tools sidebar section

Previously Added (Phase 4.5)

Hardware Module - ADB/Fastboot/ESP32 Access

  • core/hardware.py - HardwareManager singleton (646 lines)
    • ADB: device listing, info, shell (with command sanitization), reboot, sideload, push/pull, logcat
    • Fastboot: device listing, info, partition flash (whitelist), reboot, OEM unlock
    • Serial/ESP32: port listing, chip detection, firmware flash with progress, serial monitor
    • All long operations run in background threads with progress tracking
  • modules/hardware_local.py - CLI module with interactive menu (263 lines)
  • modules/hardware_remote.py - Web UI redirect stub (26 lines)
  • web/routes/hardware.py - Flask blueprint with ~20 endpoints + SSE streams (307 lines)
  • web/templates/hardware.html - Full UI with Android/ESP32 tabs (309 lines)
  • JS functions in app.js (16+ hw*() functions, lines 1100-1477)
  • CSS styles: --hardware: #f97316 (orange), progress bars, serial monitor, device grids

Session 11 (2026-02-14) - Nmap & Scan Monitor

  • Nmap scanner added to OSINT recon module (9 scan types, live-streaming output)
  • Scan monitor added to defense module (tcpdump SYN capture, per-IP tracking, counter-scan)

Session 12 (2026-02-14) - Path Portability & Bundled Tools (Phase 5)

  • Created core/paths.py — centralized path resolution for entire project
    • get_app_dir(), get_data_dir(), get_config_path(), get_results_dir(), etc.
    • find_tool(name) — unified tool lookup: project dirs first, then system PATH
    • get_platform_tag() — returns linux-arm64, windows-x86_64, etc.
    • Platform-specific tool directories: tools/linux-arm64/, tools/windows-x86_64/
    • Auto-sets NMAPDIR for bundled nmap data files
    • Windows support: checks .exe extension, system/user PATH env vars, well-known install paths
  • Copied Android platform-tools into android/ directory (adb, fastboot)
  • Copied system tools into tools/linux-arm64/ (nmap, tcpdump, upnpc, wg + nmap-data/)
  • Convention: ALL Android deps go in autarch/android/, all other tools in tools/<platform>/
  • Replaced ALL hardcoded paths across 25+ files:
    • core/hardware.py — uses find_tool('adb') / find_tool('fastboot')
    • core/wireshark.py — uses find_tool('tshark')
    • core/upnp.py — uses find_tool('upnpc')
    • core/msf.py — uses find_tool('msfrpcd')
    • core/config.py — uses get_config_path(), get_templates_dir()
    • core/cve.py, core/sites_db.py, core/pentest_session.py, core/report_generator.py — use get_data_dir()
    • modules/defender.py — uses find_tool('tcpdump')
    • modules/recon.py — uses find_tool('nmap')
    • modules/adultscan.py, modules/dossier.py, modules/mysystem.py, modules/snoop_decoder.py, modules/agent_hal.py, modules/setup.py — use get_app_dir() / get_data_dir() / get_reports_dir()
    • web/app.py, web/auth.py, web/routes/dashboard.py, web/routes/osint.py — use paths.py
    • core/menu.py — all Path(__file__).parent.parent replaced with self._app_dir
  • Zero /home/snake references remain in any .py file
  • Created requirements.txt with all Python dependencies

Tool resolution verification:

Platform: linux-arm64
  adb          autarch/android/adb             [BUNDLED]
  fastboot     autarch/android/fastboot        [BUNDLED]
  nmap         autarch/tools/linux-arm64/nmap  [BUNDLED]
  tcpdump      autarch/tools/linux-arm64/...   [BUNDLED]
  upnpc        autarch/tools/linux-arm64/...   [BUNDLED]
  wg           autarch/tools/linux-arm64/...   [BUNDLED]
  msfrpcd      /usr/bin/msfrpcd                [SYSTEM]
  esptool      ~/.local/bin/esptool            [SYSTEM]

Session 13 (2026-02-14) - Browser-Based Hardware Access (WebUSB/Web Serial)

  • Created android_plan.md — full implementation plan for direct browser-to-device hardware access
  • Architecture: Dual-mode — Server mode (existing, device on host) + Direct mode (NEW, device on user's PC)
  • Bundled 3 JavaScript libraries for browser-based hardware access:
    • @yume-chan/adb v2.5.1 + @yume-chan/adb-daemon-webusb v2.3.2 → adb-bundle.js (57KB)
    • android-fastboot v1.1.3 (kdrag0n/fastboot.js) → fastboot-bundle.js (146KB)
    • esptool-js v0.5.7 (Espressif) → esptool-bundle.js (176KB)
  • Build infrastructure: package.json, scripts/build-hw-libs.sh, src/*-entry.js
    • Uses esbuild to create IIFE browser bundles from npm packages
    • Build is dev-only; bundled JS files are static assets served by Flask
  • Created web/static/js/hardware-direct.js (752 lines) — unified browser API:
    • ADB via WebUSB: device enumeration, connect, shell, getprop, reboot, push/pull files, logcat, install APK
    • Fastboot via WebUSB: connect, getvar, flash partition with progress, reboot, OEM unlock, factory ZIP flash
    • ESP32 via Web Serial: port select, chip detect, firmware flash with progress, serial monitor
    • ADB key management via Web Crypto API + IndexedDB (persistent RSA keys)
  • Rewrote web/templates/hardware.html (309→531 lines):
    • Connection mode toggle bar (Server / Direct)
    • Direct-mode capability detection (WebUSB, Web Serial support)
    • Direct-mode connect/disconnect buttons for ADB, Fastboot, ESP32
    • File picker inputs (direct mode uses browser File API instead of server paths)
    • New "Factory Flash" tab (PixelFlasher PoC)
  • Updated web/static/js/app.js (1477→1952 lines):
    • All hw*() functions are now mode-aware (check hwConnectionMode)
    • Server mode: existing Flask API calls preserved unchanged
    • Direct mode: routes through HWDirect.* browser API
    • Mode toggle with localStorage persistence
    • Factory flash workflow: ZIP upload → flash plan → progress tracking
  • Updated web/static/css/style.css: mode toggle bar, checkbox styles, warning banners
  • Added {% block extra_head %} to web/templates/base.html for page-specific script includes

What's Left

Phase 7: System Tray + Beta Release — TODO

System Tray (pystray + Pillow)

  • autarch.py — add --tray flag to launch in system tray mode
  • core/tray.py — TrayManager using pystray + PIL.Image
  • Tray icon menu:
    • Open Dashboard (opens browser to http://localhost:8080)
    • Server Settings submenu:
      • Server address/port
      • Default model folder
      • Default tools folder
      • Auto-start on login toggle
    • Metasploit Integration submenu:
      • MSF RPC host + port + password
      • Start msfrpcd (runs find_tool('msfrpcd') with auto SSL)
      • Connect to existing msfrpcd
      • RPC connection status indicator
    • Separator
    • Start/Stop Web Server
    • View Logs
    • Separator
    • Quit

Beta Release

  • release/ — output folder for distribution artifacts
  • release/autarch.spec — PyInstaller spec file:
    • One-file EXE (--onefile) or one-dir (--onedir) bundle
    • Include: data/, web/, models/ (optional), tools/, android/, autarch_settings.conf
    • Console window: optional (--noconsole for tray-only mode, --console for CLI mode)
    • Icon: web/static/img/autarch.ico
  • release/build_exe.bat / release/build_exe.sh — build scripts
  • release/autarch.wxs or release/installer.nsi — MSI/NSIS installer:
    • Install to %PROGRAMFILES%\AUTARCH\
    • Create Start Menu shortcut
    • Register Windows service option
    • Include Metasploit installer link if not found
    • Uninstaller

Phase 4.5 Remaining: Browser Hardware Access Polish

  • Test WebUSB ADB connection end-to-end with a physical device
  • Test WebUSB Fastboot flashing end-to-end
  • Test Web Serial ESP32 flashing end-to-end
  • Test factory ZIP flash (PixelFlasher PoC) with a real factory image
  • Add boot.img patching for Magisk/KernelSU (future enhancement)
  • HTTPS required for WebUSB in production (reverse proxy or localhost only)
  • Note: WebUSB/Web Serial only work in Chromium-based browsers (Chrome, Edge, Brave)

Phase 5: Path Portability & Windows Support — MOSTLY DONE

Completed:

  • core/paths.py with full path resolution and tool finding
  • All hardcoded paths replaced
  • Platform-specific tool bundling structure
  • requirements.txt

Remaining:

  • Windows-specific sudo handling (use ctypes.windll.shell32.IsUserAnAdmin() check)
  • Bundle Windows tool binaries in tools/windows-x86_64/ (nmap.exe, tshark.exe, etc.)
  • Test on Windows and macOS
  • Add [hardware] config section for customizable tool paths

Phase 6: Docker Packaging

Goal: Portable deployment with all dependencies bundled.

Tasks:

  1. Create Dockerfile (python:3.11-slim base)
  2. Create docker-compose.yml (volume mounts for data/models/results)
  3. Create .dockerignore
  4. Create scripts/entrypoint.sh (start CLI, web, or both)
  5. Create scripts/install-tools.sh (nmap, tshark, miniupnpc, wireguard-tools)
  6. Expose ports: 8080 (web), 55553 (MSF RPC passthrough)
  7. Test full build and deployment

Known Issues / Gaps

  1. Hardcoded paths - FIXED (all use core/paths.py now)
  2. No requirements.txt - FIXED (created)
  3. No [hardware] config section - hardware settings not in autarch_settings.conf
  4. No HTTPS - web UI runs plain HTTP
  5. No test suite - no automated tests
  6. Large backup file - claude.bk (213MB) should be cleaned up
  7. tshark not installed - Wireshark/packet capture limited to scapy
  8. msfrpcd not bundleable - depends on full Metasploit ruby framework
  9. Windows/macOS untested - tool bundling structure ready but no binaries yet
  10. Local model folder hardcoded to models/ - should use AppData in release build (TODO: change for Phase 7 release)
  11. No OpenAI LLM backend implementation - config added; core/llm.py needs OpenAILLM class