sssnake/autarch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

AUTARCH v1.9 — remote monitoring, SSH manager, daemon, vault, cleanup

Browse Source 
- Add Remote Monitoring Station with PIAP device profile system
- Add SSH/SSHD manager with fail2ban integration
- Add privileged daemon architecture for safe root operations
- Add encrypted vault, HAL memory, HAL auto-analyst
- Add network security suite, module creator, codex training
- Add start.sh launcher script and GTK3 desktop launcher
- Remove Output/ build artifacts, installer files, loose docs
- Update .gitignore for runtime data and build artifacts
- Update README for v1.9 with new launch method, screenshots, and features

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
SsSnake
2026-03-24 06:59:06 -07:00
parent 1092689f45
commit da53899f66
382 changed files with 15277 additions and 493964 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
docs/esp32_capture_probe.md Normal file
View File

@@ -0,0 +1,213 @@
# ESP32 WiFi Capture Probe — Design Document
**Project:** AUTARCH Hardware Probe
**Status:** Planned
**Author:** darkHal Security Group
---
## Problem
The Orange Pi 5 Plus built-in WiFi adapter (managed mode only) cannot:
- Enter monitor mode for raw 802.11 frame capture
- Detect deauthentication attacks (requires reading management frames)
- Do passive channel hopping while staying connected to a network
- Capture probe requests, beacon frames, or association traffic
USB WiFi adapters that support monitor mode (Alfa AWUS036ACH, etc.) work but are bulky, expensive, and require specific driver support.
## Solution
A small ESP32-based WiFi capture probe that runs custom firmware. The ESP32's WiFi chipset natively supports promiscuous mode and can capture raw 802.11 frames on both 2.4GHz and 5GHz (ESP32-S3/C6). The probe connects to AUTARCH over USB serial or TCP and streams captured frames in real time.
AUTARCH already has ESP32 flashing built into the Hardware page — users can flash the probe firmware directly from the web UI.
## Hardware
**Minimum:**
- ESP32 dev board (any variant) — ~$5
- USB cable
**Recommended:**
- ESP32-S3 or ESP32-C6 (dual-band 2.4/5GHz support)
- External antenna connector (IPEX/U.FL) for better range
- Small 3D-printed case
- Optional: LiPo battery + charging circuit for portable deployment
**Cost:** Under $10 for a complete probe
## Capabilities
### Capture Modes
1. **Promiscuous Mode** — capture all 802.11 frames on a channel (data, management, control)
2. **Channel Hopping** — cycle through channels 1-13 (2.4GHz) and 36-165 (5GHz on S3/C6)
3. **Targeted Capture** — lock to a specific channel and BSSID
4. **Beacon Monitor** — capture only beacon and probe frames (low bandwidth, good for SSID mapping)
### Detection
- Deauthentication frame detection (count, source MAC, target MAC, reason code)
- Evil twin detection (same SSID, different BSSID appearing)
- Probe request tracking (which devices are looking for which networks)
- Rogue AP detection (new BSSIDs appearing)
- Karma attack detection (AP responding to all probe requests)
- Association flood detection
### Output Formats
- Raw pcap over serial (AUTARCH reads with scapy)
- JSON event stream over serial (parsed on ESP32, lighter bandwidth)
- TCP stream over WiFi (ESP32 connects to AUTARCH's network in station mode on one radio, captures on the other — dual-radio ESP32 only)
## Firmware Architecture
```
esp32-capture-probe/
main/
main.c Entry point, WiFi init, mode selection
capture.c Promiscuous mode callback, frame parsing
channel_hop.c Channel hopping logic with configurable dwell time
serial_output.c Frame/event output over USB serial (SLIP framing)
tcp_output.c Frame/event output over TCP socket
detector.c Deauth/evil twin/karma detection logic
config.c Runtime configuration via serial commands
led.c Status LED control (capturing, alert, idle)
CMakeLists.txt
sdkconfig ESP-IDF configuration
```
### Frame Processing Pipeline
```
802.11 Frame (promiscuous callback)
|
+-- Parse header (type, subtype, addresses, sequence)
|
+-- Filter (by type, BSSID, channel)
|
+-- Detection engine
| +-- Deauth counter (threshold alert)
| +-- SSID/BSSID tracker (evil twin check)
| +-- Probe request log
|
+-- Output
+-- JSON event (for alerts/detections)
+-- Raw frame bytes (for pcap capture)
```
### Serial Protocol
Commands from AUTARCH to probe (newline-delimited JSON):
```json
{"cmd": "start", "mode": "promiscuous", "channel": 0}
{"cmd": "start", "mode": "beacon_only"}
{"cmd": "set_channel", "channel": 6}
{"cmd": "hop", "channels": [1,6,11], "dwell_ms": 200}
{"cmd": "stop"}
{"cmd": "status"}
{"cmd": "set_filter", "bssid": "aa:bb:cc:dd:ee:ff"}
{"cmd": "set_output", "format": "json"}
{"cmd": "set_output", "format": "pcap"}
```
Events from probe to AUTARCH:
```json
{"event": "deauth", "src": "aa:bb:cc:dd:ee:ff", "dst": "11:22:33:44:55:66", "reason": 7, "channel": 6, "rssi": -45, "count": 15}
{"event": "beacon", "ssid": "FreeWiFi", "bssid": "aa:bb:cc:dd:ee:ff", "channel": 1, "rssi": -60, "security": "open"}
{"event": "evil_twin", "ssid": "HomeNetwork", "bssid_original": "aa:bb:cc:dd:ee:ff", "bssid_rogue": "11:22:33:44:55:66"}
{"event": "probe_req", "src": "aa:bb:cc:dd:ee:ff", "ssid": "MyPhone_Hotspot", "rssi": -70}
{"event": "karma", "ap_bssid": "aa:bb:cc:dd:ee:ff", "responded_to": ["Network1", "Network2", "Network3"]}
{"event": "frame", "hex": "80000000...", "channel": 6, "rssi": -55}
{"event": "status", "mode": "hopping", "channel": 6, "frames_captured": 1547, "alerts": 3, "uptime": 120}
```
## AUTARCH Integration
### Hardware Page
The probe appears as an ESP32 device on the Hardware page. Users can:
- Flash the capture firmware (one click from the ESP32 tab)
- Monitor probe status (connected, capturing, channel, frame count)
- Configure capture settings (mode, channels, filters)
### Network Security Page
New sub-features when a probe is connected:
- **Live 802.11 Monitor** — real-time frame stream with protocol breakdown
- **Deauth Alert** — instant notification when deauth frames detected (with source tracking)
- **Channel Survey** — signal strength and AP count per channel (helps pick the cleanest channel)
- **Hidden Network Discovery** — find SSIDs that don't broadcast beacons by watching probe responses
- **Client Tracker** — which devices (MACs) are associated to which APs
### Capture Agent Integration
The capture agent (`core/capture_agent.py`) gains a new action:
```json
{"action": "probe_start", "serial_port": "/dev/ttyUSB0", "mode": "promiscuous", "channels": [1,6,11]}
{"action": "probe_stop"}
{"action": "probe_status"}
```
The capture agent reads the serial stream, converts to pcap or forwards JSON events to Flask via its existing socket.
### WiFi Audit Integration
With the probe providing monitor mode:
- Deauth attacks actually work (raw frame injection)
- Handshake capture works (WPA 4-way handshake monitoring)
- Channel hopping during audit scans
- Passive reconnaissance without disconnecting from the network
## Implementation Phases
### Phase 1: Basic Capture (1-2 days)
- ESP-IDF project setup
- Promiscuous mode callback
- Serial output (JSON events)
- Channel hopping
- Flash from AUTARCH Hardware page
### Phase 2: Detection Engine (1-2 days)
- Deauth frame counter with threshold alerting
- Evil twin detection (SSID/BSSID tracking)
- Probe request logging
- AUTARCH integration (Network Security page reads probe events)
### Phase 3: Advanced Features (2-3 days)
- pcap output mode (raw frame bytes over serial)
- TCP streaming mode (dual-radio only)
- Karma attack detection
- Client association tracking
- Channel survey with signal heatmap data
- Hidden network discovery
### Phase 4: WiFi Audit Integration (1-2 days)
- Frame injection for deauth (if supported by ESP32 variant)
- Handshake capture and forwarding to aircrack-ng
- Automated WPA audit workflow
## Bill of Materials
| Component | Purpose | Price |
|-----------|---------|-------|
| ESP32-S3 DevKitC | Dual-band WiFi, USB-C | ~$8 |
| IPEX antenna | Better range | ~$2 |
| USB-C cable | Connection to AUTARCH host | ~$3 |
| 3D printed case | Protection (optional) | ~$1 |
| **Total** | | **~$14** |
For budget builds, any ESP32 board works ($3-5) but is limited to 2.4GHz only.
## Comparison to Alternatives
| Feature | ESP32 Probe | Alfa Adapter | HackRF | Built-in WiFi |
|---------|------------|-------------|--------|---------------|
| Cost | ~$14 | ~$40-70 | ~$300 | $0 |
| Monitor mode | Yes | Yes | N/A | Usually no |
| 5GHz | ESP32-S3/C6 | Model dependent | Yes | Model dependent |
| Portable | Very (tiny) | Medium | Large | N/A |
| Driver issues | None (serial) | Frequent | Complex | N/A |
| Frame injection | Limited | Yes | Yes | No |
| Power | USB powered | USB powered | USB powered | N/A |
| AUTARCH integration | Native | Requires airmon-ng | Complex | Limited |
The ESP32 probe fills the gap between "no monitor mode" and "expensive USB adapter with driver hell." It's cheap, reliable, driver-free (serial protocol), and integrates natively with AUTARCH.
---
*darkHal Security Group & Setec Security Labs*
*Planned for AUTARCH v2.5*

565
docs/user_manual.md
View File

@@ -22,27 +22,33 @@ No prior hacking experience is needed to use most features. This manual will wal
1. [Getting Started](#1-getting-started)
2. [The Main Menu (CLI)](#2-the-main-menu-cli)
3. [The Web Dashboard](#3-the-web-dashboard)
4. [Defense Tools](#4-defense-tools)
5. [Offense Tools](#5-offense-tools)
6. [Counter-Intelligence](#6-counter-intelligence)
7. [Analysis & Forensics](#7-analysis--forensics)
8. [OSINT (Intelligence Gathering)](#8-osint-intelligence-gathering)
9. [Attack Simulation](#9-attack-simulation)
10. [Hardware & Device Management](#10-hardware--device-management)
11. [Android Protection Shield](#11-android-protection-shield)
12. [WireGuard VPN](#12-wireguard-vpn)
13. [Reverse Shell](#13-reverse-shell)
14. [Archon Companion App](#14-archon-companion-app)
15. [AI Chat & Agents](#15-ai-chat--agents)
16. [MCP Server](#16-mcp-server)
17. [Advanced Offense Tools](#17-advanced-offense-tools)
18. [Advanced Defense Tools](#18-advanced-defense-tools)
19. [Advanced Analysis Tools](#19-advanced-analysis-tools)
20. [SDR/RF & Starlink Tools](#20-sdrrf--starlink-tools)
21. [Configuration & Settings](#21-configuration--settings)
22. [Troubleshooting](#22-troubleshooting)
23. [Quick Reference](#23-quick-reference)
24. [Safety & Legal Notice](#24-safety--legal-notice)
4. [The Privileged Daemon](#4-the-privileged-daemon)
5. [Network Security](#5-network-security)
6. [Defense Tools](#6-defense-tools)
7. [Offense Tools](#7-offense-tools)
8. [Counter-Intelligence](#8-counter-intelligence)
9. [Analysis & Forensics](#9-analysis--forensics)
10. [OSINT (Intelligence Gathering)](#10-osint-intelligence-gathering)
11. [Attack Simulation](#11-attack-simulation)
12. [Hardware & Device Management](#12-hardware--device-management)
13. [Android Protection Shield](#13-android-protection-shield)
14. [WireGuard VPN](#14-wireguard-vpn)
15. [Reverse Shell](#15-reverse-shell)
16. [Archon Companion App](#16-archon-companion-app)
17. [AI Chat & Agents](#17-ai-chat--agents)
18. [HAL AI Analyst](#18-hal-ai-analyst)
19. [MCP Server](#19-mcp-server)
20. [Encrypted Vault](#20-encrypted-vault)
21. [Module Creator](#21-module-creator)
22. [Desktop Launcher](#22-desktop-launcher)
23. [Advanced Offense Tools](#23-advanced-offense-tools)
24. [Advanced Defense Tools](#24-advanced-defense-tools)
25. [Advanced Analysis Tools](#25-advanced-analysis-tools)
26. [SDR/RF & Starlink Tools](#26-sdrrf--starlink-tools)
27. [Configuration & Settings](#27-configuration--settings)
28. [Troubleshooting](#28-troubleshooting)
29. [Quick Reference](#29-quick-reference)
30. [Safety & Legal Notice](#30-safety--legal-notice)
---
@@ -55,14 +61,64 @@ No prior hacking experience is needed to use most features. This manual will wal
- A web browser (for the dashboard)
- An Android phone (optional, for companion app features)
### Starting AUTARCH for the First Time
### Setting Up the Virtual Environment
Open a terminal and type:
Before running AUTARCH for the first time, set up an isolated Python environment so that dependencies do not conflict with your system packages:
```
python autarch.py
bash scripts/setup-venv.sh
```
This creates a `venv/` directory inside the AUTARCH folder. Once the venv exists, you can use it explicitly with:
```
./venv/bin/python autarch.py
```
All of the launch methods described below (the launcher, `start.sh`, manual start) will use the venv automatically if it exists. If you skip this step, AUTARCH falls back to your system Python.
### Starting AUTARCH
There are three ways to start AUTARCH. Pick whichever fits your workflow.
#### Option A: The Desktop Launcher (Recommended)
```
python3 launcher.py
```
This opens a GTK window with a splash screen, EULA acknowledgement, and buttons for Start All / Stop All / Reload. It starts both the privileged daemon and the web dashboard for you. See [Section 22: Desktop Launcher](#22-desktop-launcher) for full details.
#### Option B: Shell Scripts
```
bash start.sh # Start daemon + web dashboard
bash stop.sh # Stop everything
```
`start.sh` handles the correct startup order — it launches the privileged daemon first (with `sudo`), waits for it to be ready, then starts the Flask web server. `stop.sh` tears everything down cleanly.
#### Option C: Manual Start
If you want full control, start each component yourself:
```
sudo python3 core/daemon.py # Step 1: start the privileged daemon
python3 autarch.py --web # Step 2: start the web dashboard
```
The daemon must be running before the web dashboard so that tools requiring root access (iptables, WiFi scanning, packet capture, etc.) work correctly. See [Section 4: The Privileged Daemon](#4-the-privileged-daemon) for why this matters.
#### Starting the CLI Only
If you just want the terminal menu (no web dashboard, no daemon needed for basic tools):
```
python3 autarch.py
```
### First-Time Setup
The first time you run AUTARCH, a **setup wizard** appears. It asks you to pick an AI backend:
| Option | What It Is | Do You Need It? |
@@ -109,9 +165,13 @@ python autarch.py --list # Show all available tools
| `python autarch.py --setup` | Re-run the setup wizard |
| `python autarch.py --skip-setup` | Skip AI setup, run without LLM |
| `python autarch.py --show-config` | Show current settings |
| `python autarch.py --mcp stdio` | Start MCP server for Claude |
| `python autarch.py --mcp stdio` | Start MCP server (stdio) for Claude |
| `python autarch.py --mcp sse` | Start MCP server (SSE) for web clients |
| `python autarch.py --service start` | Start as background service |
| `python autarch.py -h` | Show all command line options |
| `bash start.sh` | Start daemon + web (recommended) |
| `bash stop.sh` | Stop everything |
| `python3 launcher.py` | Open the GTK desktop launcher |
---
@@ -148,7 +208,7 @@ When you start AUTARCH, you'll see a menu like this:
## 3. The Web Dashboard
The web dashboard gives you the same tools as the CLI, but in a visual browser interface.
The web dashboard gives you the same tools as the CLI, but in a visual browser interface. AUTARCH v2.4 includes 1,130 web routes across 63 route files, rendering 74 templates, backed by 40 core files and 73 CLI modules.
### Starting the Dashboard
@@ -158,6 +218,8 @@ From the CLI menu, select **[8] Web Service**, or run:
python autarch.py --web
```
Or use `bash start.sh` to start both the daemon and the web dashboard together.
### Navigating the Dashboard
The left sidebar has these sections:
@@ -201,6 +263,7 @@ The left sidebar has these sections:
- **SDR/RF Tools** — Software-defined radio & drone detection
- **Starlink Hack** — Starlink terminal exploitation
- **RCS Tools** — SMS/RCS message exploitation
- **Network Security** — Connection monitoring, IDS, rogue device detection, WiFi scanning, attack detection
**System** — Infrastructure management:
- **UPnP** — Port forwarding
@@ -208,6 +271,8 @@ The left sidebar has these sections:
- **DNS Server** — Built-in DNS service
- **MSF Console** — Metasploit terminal
- **Chat** — AI chat interface
- **Module Creator** — Create new AUTARCH modules from the browser
- **MCP Settings** — Model Context Protocol server configuration
- **Settings** — All configuration options
### Running as a Background Service
@@ -223,9 +288,142 @@ python autarch.py --service status # Check if it's running
---
## 4. Defense Tools
## 4. The Privileged Daemon
Defense tools help you check and strengthen your system's security.
AUTARCH uses a split-privilege architecture. The web dashboard runs as your normal user (so `pip install` and Python packages work without permission issues), while a separate daemon runs as root to handle operations that require elevated privileges.
### Why It Exists
Many security tools need root access — `iptables` for firewall rules, raw sockets for WiFi scanning, `tcpdump` for packet capture, ARP table manipulation, and more. Rather than running the entire Flask web server as root (which would be a security risk), AUTARCH runs only the daemon as root. The web server sends requests to the daemon when it needs a privileged operation.
### How It Works
The daemon listens on a Unix domain socket at:
```
/var/run/autarch-daemon.sock
```
When the web dashboard needs to run a privileged command (for example, flushing an ARP entry or starting a WiFi scan), it sends a signed request to the daemon over this socket. The daemon validates the request, checks the command against its whitelist, and executes it.
### Security Measures
The daemon implements multiple layers of protection:
- **HMAC-SHA256 signed requests** — Every request from the web server must be signed with a shared secret. The daemon rejects unsigned or incorrectly signed requests.
- **SO_PEERCRED peer verification** — The daemon checks the identity of the connecting process via the kernel's socket credentials. Only the expected user can communicate with it.
- **Nonce replay protection** — Each request includes a unique nonce. The daemon tracks recent nonces and rejects duplicates, preventing replay attacks.
- **Command whitelist** — Only 68 specific commands are allowed. Everything else is denied.
- **Built-in actions** — In addition to the 68 whitelisted shell commands, the daemon handles packet capture and WiFi scanning as built-in actions that bypass the shell entirely:
- `__capture__` — Runs scapy's `sniff()` as root, writes pcap files with 644 permissions so the unprivileged web server can read them. No separate capture agent is needed.
- `__wifi_scan__` — Runs `iw dev scan` as root for WiFi enumeration.
- **Blocked patterns** — 45 dangerous patterns (like `rm -rf /`, pipe to shell, etc.) are explicitly blocked even if they appear inside an allowed command.
### Starting the Daemon
The daemon is started automatically by `start.sh` and the desktop launcher. To start it manually:
```
sudo python3 core/daemon.py
```
### Cleanup
When the daemon shuts down (via `stop.sh`, the launcher, or a signal), it cleans up after itself:
- Removes the Unix socket file
- Removes its PID file
- Removes the shared secret file
This prevents stale socket files from blocking the next startup.
---
## 5. Network Security
The Network Security page is a dedicated section of the web dashboard for monitoring and defending your local network. It is organized into 8 tabs, each focused on a different aspect of network defense.
### Connections Tab
Displays your machine's current network state:
- **Active Connections** — All TCP/UDP connections from `ss`, showing local address, remote address, state, and process
- **ARP Table** — Every device your machine has communicated with recently, listed by IP and MAC address
- **Network Interfaces** — All network interfaces (Ethernet, WiFi, VPN, loopback) with their IP addresses and status
This is the first place to look when you want to understand what your machine is talking to right now.
### Intrusion Detection Tab
Runs a battery of checks to detect active attacks on your network:
- **ARP Spoof Detection** — Checks if two different IPs claim the same MAC address (a sign of ARP poisoning)
- **Promiscuous Mode Detection** — Flags network interfaces that are in promiscuous mode (may indicate a sniffer)
- **Unauthorized DHCP Servers** — Scans for DHCP servers that should not be on your network (rogue DHCP is a common MITM technique)
- **Suspicious Connections** — Identifies connections to known-bad ports or unusual destinations
- **Raw Socket Processes** — Lists processes that have opened raw sockets (used for packet sniffing or crafting)
### Rogue Devices Tab
Helps you detect unknown devices on your network:
- Scans the ARP table and compares it against a **known device baseline** you build over time
- New or unknown devices are flagged for your review
- You can **trust** a device (add it to your baseline) or **block** it
- Useful for detecting unauthorized devices that have joined your WiFi or plugged into your switch
### Monitor Tab
A real-time connection feed powered by Server-Sent Events (SSE):
- Shows new connections as they appear, without needing to refresh the page
- Useful for watching network activity during an investigation or while running other tools
- Runs continuously in the background — just leave the tab open
### WiFi Scanner Tab
Scans for nearby wireless networks using `nmcli` or `iwlist`:
- Lists all visible access points with SSID, BSSID (MAC), channel, signal strength, and security type (Open, WEP, WPA2, WPA3)
- Helps you identify your own networks, detect neighbors, and spot rogue access points
- No monitor-mode adapter required — uses your normal WiFi interface
### Attack Detection Tab
Automated detection of common wireless and network attacks:
- **Deauth Flood Detection** — Identifies mass deauthentication frames (used to knock devices off WiFi)
- **Evil Twin Detection** — Finds access points that clone your SSID but have a different BSSID
- **Pineapple / Rogue AP Detection** — Identifies access points with suspicious characteristics (known pineapple MACs, Karma-like behavior)
- **MITM / ARP Poisoning** — Detects when your gateway's MAC address changes unexpectedly
- **SSL Strip Detection** — Identifies signs of HTTPS downgrade attacks
Each detection includes links to the relevant pentest tools in AUTARCH's offense suite, so you can investigate further or simulate the attack yourself in a lab.
### ARP Spoof Tab
A deep-dive tool specifically for ARP spoofing defense:
- **Gateway MAC Baseline** — Records your gateway's legitimate MAC address so AUTARCH can detect when it changes
- **Deep Scan** — Sends ARP requests to every host on the subnet and compares responses to the baseline
- **Remediation Tools:**
- **Flush & Static** — Clears the ARP cache and sets a static entry for your gateway, preventing spoofing
- **Kernel Protection** — Enables kernel-level ARP validation (`arp_accept`, `arp_announce`, `arp_ignore`)
- **Per-Entry Flush** — Flush a single suspicious ARP entry without clearing the entire cache
- **How-To Guide** — Built-in step-by-step guide explaining what ARP spoofing is, how to detect it, and how to fix it
### SSID Map Tab
Groups all detected access points by SSID:
- Shows every SSID visible in your area
- Under each SSID, lists all BSSIDs (individual access points) broadcasting that name
- Useful for identifying networks with multiple access points (mesh, enterprise) vs. potential evil twins (same SSID, unexpected BSSID)
---
## 6. Defense Tools
Defense tools help you check and strengthen your system's security. In AUTARCH v2.4, every defense tool automatically sends its output to the HAL AI Analyst for intelligent analysis. See [Section 18: HAL AI Analyst](#18-hal-ai-analyst) for details.
### What's Available
@@ -253,16 +451,18 @@ Defense tools help you check and strengthen your system's security.
1. Click **Defense** in the sidebar
2. Click any tool button
3. Results appear on the page
4. HAL automatically analyzes the output — look for the risk badge and recommendations in the HAL chat panel
### Tips
- Run the **Full Security Audit** first to get an overview
- If you see red warnings, address those first — they're the most critical
- The **Scan Monitor** runs continuously — press Ctrl+C to stop it in CLI mode
- When HAL identifies a fixable issue, you can click "Let HAL Fix It" to apply the recommended remediation
---
## 5. Offense Tools
## 7. Offense Tools
Offense tools are for testing your own systems' security. These are professional penetration testing tools.
@@ -298,11 +498,11 @@ The reverse shell lets you control Android devices remotely through the Archon c
3. **Connect** — Tap Connect in the Archon app's Modules tab
4. **Use** — You can now run commands, take screenshots, download files, etc.
See [Section 13: Reverse Shell](#13-reverse-shell) for detailed instructions.
See [Section 15: Reverse Shell](#15-reverse-shell) for detailed instructions.
---
## 6. Counter-Intelligence
## 8. Counter-Intelligence
Counter-intelligence tools help you detect if someone is already inside your system.
@@ -328,9 +528,9 @@ Counter-intelligence tools help you detect if someone is already inside your sys
---
## 7. Analysis & Forensics
## 9. Analysis & Forensics
These tools help you examine files, network traffic, and system artifacts.
These tools help you examine files, network traffic, and system artifacts. Like defense tools, analysis results are automatically sent to HAL for intelligent commentary.
### File Analysis
@@ -350,20 +550,22 @@ Capture and analyze network traffic:
3. Start capture
4. Browse the results — protocols, source/destination, payload data
Packet capture goes through the privileged daemon — no separate capture agent is needed. The daemon runs scapy's `sniff()` as root via the `__capture__` built-in action and writes pcap files with 644 permissions so the web dashboard can read them.
**In the web UI:** The Wireshark page gives you a visual packet inspector.
---
## 8. OSINT (Intelligence Gathering)
## 10. OSINT (Intelligence Gathering)
OSINT (Open Source Intelligence) tools help you find publicly available information about people, domains, and IP addresses.
OSINT (Open Source Intelligence) tools help you find publicly available information about people, domains, and IP addresses. AUTARCH v2.4 checks against **25,475 sites** across all OSINT modules.
### Username Lookup
Check if a username exists across **7,200+ websites**:
Check if a username exists across thousands of websites:
1. Enter a username
2. AUTARCH checks hundreds of sites simultaneously
2. AUTARCH checks sites simultaneously using parallel threads
3. Results show which sites have that username registered
**Categories searched:** Social media, forums, dating sites, gaming, email providers, developer platforms, and more.
@@ -424,7 +626,7 @@ Checks usernames across 50+ adult content sites. This is useful for investigatin
---
## 9. Attack Simulation
## 11. Attack Simulation
Simulation tools let you test attack scenarios in a controlled way.
@@ -438,7 +640,7 @@ Simulation tools let you test attack scenarios in a controlled way.
---
## 10. Hardware & Device Management
## 12. Hardware & Device Management
AUTARCH can directly control physical devices connected to it.
@@ -476,7 +678,7 @@ Toggle between modes in the Hardware page header.
---
## 11. Android Protection Shield
## 13. Android Protection Shield
The Shield protects Android devices from stalkerware, spyware, and tracking.
@@ -527,7 +729,7 @@ The honeypot feeds fake data to ad trackers, making their profiles of you useles
---
## 12. WireGuard VPN
## 14. WireGuard VPN
AUTARCH includes a full WireGuard VPN server for secure connections.
@@ -563,7 +765,7 @@ Share USB devices from remote machines over the VPN:
---
## 13. Reverse Shell
## 15. Reverse Shell
The Reverse Shell lets you remotely manage Android devices through the Archon companion app.
@@ -619,7 +821,7 @@ The reverse shell has multiple safety measures:
---
## 14. Archon Companion App
## 16. Archon Companion App
The Archon app runs on your Android phone and connects to AUTARCH for remote management.
@@ -699,7 +901,7 @@ adb shell /data/local/tmp/arish pm list packages -3
---
## 15. AI Chat & Agents
## 17. AI Chat & Agents
AUTARCH can connect to AI language models for intelligent security assistance.
@@ -742,27 +944,71 @@ The agent will use the appropriate tools, show you what it's doing, and present
| **Transformers** | Medium | Free | Good |
| **Claude API** | Fast | Paid | Excellent |
| **HuggingFace** | Fast | Free tier available | Good |
| **OpenAI API** | Fast | Paid | Excellent |
Configure in Settings → LLM Settings, or edit `autarch_settings.conf`.
---
## 16. MCP Server
## 18. HAL AI Analyst
MCP (Model Context Protocol) lets AI assistants like Claude use AUTARCH's tools directly.
HAL is AUTARCH's built-in AI analyst. It watches the output of every defensive and analysis tool and provides automatic, intelligent commentary — explaining what the results mean, highlighting risks, and suggesting next steps.
### How It Works
1. **You run a tool** — for example, a firewall check, an ARP spoof scan, or a forensic analysis
2. **HAL receives the output** — the tool's results are automatically sent to whatever LLM backend you have configured (Claude, OpenAI, local model, HuggingFace)
3. **HAL analyzes** — while the AI is thinking, the HAL button in the web interface pulses with status messages so you know it is working
4. **Results appear** — HAL's analysis shows up in the HAL chat panel on the right side of the page, complete with a risk level badge (Info, Low, Medium, High, Critical)
You do not need to copy/paste output or ask HAL to look at anything. It happens automatically for every tool that produces security-relevant output.
### The HAL Chat Panel
The HAL panel is always visible on the right side of the web dashboard. It contains:
- **Analysis messages** — Each analysis includes a risk badge, a plain-English explanation of what was found, and specific recommendations
- **Auto-Fix button** — When HAL identifies a problem it knows how to fix, it extracts the remediation commands from its analysis. A "Let HAL Fix It" button appears, and clicking it executes those commands (via the privileged daemon if root is needed)
- **Feedback toggle (FB button)** — In the HAL panel header, the FB button lets you disable automatic analysis. When disabled, HAL will not analyze tool output until you re-enable it. Useful if you are running many tools quickly and do not want to wait for AI processing
- **Stop button** — Stops HAL mid-generation if you do not need the rest of the analysis
### Supported Backends
HAL works with every LLM backend AUTARCH supports:
- Claude API
- OpenAI API
- Local GGUF models
- HuggingFace Inference API
- Local Transformers models
If no LLM is configured, HAL stays inactive. Configure a backend in Settings → LLM Settings to enable it.
---
## 19. MCP Server
MCP (Model Context Protocol) lets AI assistants like Claude Desktop and Claude Code use AUTARCH's tools directly.
### What It Is
The Model Context Protocol is a standard that allows AI applications to call external tools. When you enable AUTARCH's MCP server, Claude (or any MCP-compatible client) can run scans, look up IPs, capture packets, and more — all through natural language conversation.
### Starting the MCP Server
```
# For Claude Desktop or Claude Code
# For Claude Desktop or Claude Code (stdio transport)
python autarch.py --mcp stdio
# For web-based clients
# For web-based clients (SSE transport)
python autarch.py --mcp sse --mcp-port 8081
```
You can also configure and start the MCP server from the web dashboard under **Settings → MCP Server**.
### What Tools Are Exposed
AUTARCH exposes 11 tools via MCP:
| Tool | What It Does |
|------|-------------|
| `nmap_scan` | Network scanning |
@@ -779,7 +1025,8 @@ python autarch.py --mcp sse --mcp-port 8081
### How to Use with Claude Desktop
Add to your Claude Desktop config:
Add to your Claude Desktop configuration file (`claude_desktop_config.json`):
```json
{
"mcpServers": {
@@ -793,11 +1040,130 @@ Add to your Claude Desktop config:
Then in Claude Desktop, you can say things like "Use AUTARCH to scan 192.168.1.1" and Claude will use the tools.
### How to Use with Claude Code
In your Claude Code MCP configuration, add AUTARCH the same way — point the command at `autarch.py --mcp stdio`. Claude Code will discover the available tools and use them when relevant.
---
## 17. Advanced Offense Tools
## 20. Encrypted Vault
AUTARCH v2.3 includes a comprehensive suite of offense modules for authorized penetration testing.
AUTARCH v2.4 stores sensitive credentials (API keys, tokens, passwords) in an encrypted vault rather than in plaintext configuration files.
### How It Works
- All secrets are stored in `data/vault.enc`
- The vault uses **AES-256-CBC** encryption
- The encryption key is derived using **PBKDF2-HMAC-SHA256** with a high iteration count
- The key derivation is tied to your **machine identity** (from `/etc/machine-id`), so the vault file cannot be decrypted on a different machine
### What Gets Stored
Any API key or token that you enter in Settings is stored in the vault:
- Claude API key
- OpenAI API key
- HuggingFace token
- Metasploit RPC password
- Any other credential managed by AUTARCH
### Automatic Migration
If you are upgrading from an earlier version of AUTARCH that stored API keys in plaintext inside `autarch_settings.conf`, the vault handles migration automatically:
1. On first run, AUTARCH checks `autarch_settings.conf` for plaintext API keys
2. Any keys found are encrypted and stored in `data/vault.enc`
3. The plaintext values are cleared from the config file
You do not need to do anything — the migration is transparent. After migration, the `.conf` file will have empty key fields, and the actual values will live safely in the vault.
### Security Notes
- The vault is only as secure as your machine. If someone has root access to your AUTARCH host, they can decrypt the vault (because they can read `/etc/machine-id`)
- The vault protects against casual file browsing, accidental exposure in screenshots, and config file leaks (e.g., if you share your `.conf` file)
- Back up `data/vault.enc` if you need to preserve your credentials. Remember that the backup is only usable on the same machine
---
## 21. Module Creator
The Module Creator lets you build new AUTARCH modules directly from the web dashboard — no need to manually create files or remember the module structure.
### What It Does
- **Template generator** — Select a module category (Defense, Offense, Counter, Analyze, OSINT, Simulate) and the creator generates a properly structured Python module with all the boilerplate filled in
- **Python syntax validation** — Before saving, the creator checks your code for syntax errors and highlights problems
- **Module browser** — Browse all existing modules, view their source code, and edit them in place
### How to Use
1. In the web dashboard, click **Module Creator** in the sidebar
2. Choose a category for your new module
3. Fill in the module name, description, and any custom code
4. Click **Create** — the creator validates the syntax and writes the file to the `modules/` directory
5. Your new module immediately appears in the CLI menu and web dashboard
### Editing Existing Modules
1. Open the Module Creator
2. Use the module browser to find the module you want to edit
3. Click on it to load its source code into the editor
4. Make your changes and save
---
## 22. Desktop Launcher
The Desktop Launcher is a GTK application for Linux desktops (GNOME, KDE, and other GTK-compatible environments). It provides a graphical way to manage AUTARCH without touching the terminal.
### Starting the Launcher
```
python3 launcher.py
```
Or, if you have installed the `.desktop` file (located at `scripts/autarch.desktop`), you can launch it from your GNOME/KDE application menu like any other app.
### Splash Screen
On first launch, the launcher displays a splash screen with:
- The AUTARCH EULA (End User License Agreement)
- Privacy acknowledgements
- A consent button you must accept before proceeding
This only appears once. After acceptance, the launcher opens directly to the control panel.
### Controls
The launcher window provides:
- **Start All** — Starts the privileged daemon and web dashboard together (equivalent to `bash start.sh`)
- **Stop All** — Stops both the daemon and web server cleanly (equivalent to `bash stop.sh`)
- **Reload** — Restarts the web server without stopping the daemon (picks up config changes)
- **Individual controls** — Start or stop the daemon and web server independently
### Settings Tabs
The launcher includes built-in settings editors:
- **WebUI tab** — Configure the web dashboard host, port, and authentication
- **Daemon tab** — Configure daemon socket path, logging, and behavior
- **Whitelist editor** — View and modify the daemon's command whitelist (the 68 allowed commands)
### Installing the Desktop Entry
To add AUTARCH to your application launcher:
```
cp scripts/autarch.desktop ~/.local/share/applications/
```
After this, AUTARCH appears in your GNOME Activities or KDE application menu.
---
## 23. Advanced Offense Tools
AUTARCH v2.4 includes a comprehensive suite of offense modules for authorized penetration testing.
### Vulnerability Scanner
@@ -1023,7 +1389,7 @@ Starlink terminal security analysis and exploitation for authorized testing.
---
## 18. Advanced Defense Tools
## 24. Advanced Defense Tools
### Container Security
@@ -1075,7 +1441,7 @@ Multi-source log aggregation and security event correlation.
---
## 19. Advanced Analysis Tools
## 25. Advanced Analysis Tools
### Reverse Engineering
@@ -1175,7 +1541,7 @@ Password analysis, generation, and cracking tools.
---
## 20. SDR/RF & Starlink Tools
## 26. SDR/RF & Starlink Tools
### SDR/RF Tools
@@ -1195,22 +1561,22 @@ Software-defined radio spectrum analysis with HackRF and RTL-SDR support.
### Starlink Hack
See [Section 17: Advanced Offense Tools — Starlink Hack](#starlink-hack) for full details.
See [Section 23: Advanced Offense Tools — Starlink Hack](#starlink-hack) for full details.
---
## 21. Configuration & Settings
## 27. Configuration & Settings
### The Config File
All settings live in `autarch_settings.conf` in the AUTARCH directory. You can edit it with any text editor, or use the Settings menu.
All settings live in `autarch_settings.conf` in the AUTARCH directory. You can edit it with any text editor, or use the Settings menu. API keys and tokens are stored separately in the encrypted vault (see [Section 20: Encrypted Vault](#20-encrypted-vault)).
### Key Settings
**LLM (AI Model)**
```ini
[autarch]
llm_backend = local # local, transformers, claude, or huggingface
llm_backend = local # local, transformers, claude, openai, or huggingface
[llama]
model_path = /path/to/model.gguf
@@ -1220,11 +1586,11 @@ temperature = 0.7 # Creativity (0.0 = precise, 1.0 = creative)
max_tokens = 2048 # Max response length
[claude]
api_key = sk-ant-... # Your Anthropic API key
api_key = <stored in vault>
model = claude-sonnet-4-20250514
[huggingface]
api_key = hf_... # Your HuggingFace token
api_key = <stored in vault>
model = mistralai/Mistral-7B-Instruct-v0.3
```
@@ -1271,7 +1637,7 @@ mappings = 443:TCP,51820:UDP,8080:TCP
---
## 22. Troubleshooting
## 28. Troubleshooting
### "Module not found" error
- Run `python autarch.py --list` to see available modules
@@ -1283,10 +1649,20 @@ mappings = 443:TCP,51820:UDP,8080:TCP
- Try a different port: `python autarch.py --web --web-port 9090`
- Check the terminal for error messages
### Daemon won't start
- Make sure you are running it with `sudo`: `sudo python3 core/daemon.py`
- Check if the socket file already exists: `ls -la /var/run/autarch-daemon.sock` — if it does, a previous daemon may not have shut down cleanly. Remove the stale socket file and try again
- Check the terminal output for permission errors
### Web tools say "daemon not running" or "permission denied"
- Make sure the daemon is running: check for the process with `ps aux | grep daemon.py`
- If you started the web server manually, make sure you started the daemon first
- Use `bash start.sh` to start both in the correct order
### AI chat says "no model configured"
- Run `python autarch.py --setup` to configure an AI backend
- For local models: make sure `model_path` points to a valid `.gguf` file
- For cloud APIs: verify your API key is correct
- For cloud APIs: verify your API key is correct (check Settings → LLM Settings)
### Metasploit won't connect
- Make sure Metasploit is installed
@@ -1310,39 +1686,59 @@ mappings = 443:TCP,51820:UDP,8080:TCP
- Increase timeout if on a slow connection
- Some nmap scans (UDP, Idle) are inherently slow — use SYN scan for speed
### HAL not analyzing tool output
- Make sure an LLM backend is configured (Settings → LLM Settings)
- Check that the Feedback toggle (FB button) in the HAL panel header is not set to "off"
- If using a cloud API, verify your API key and check for rate limits
### Vault errors or lost API keys
- The vault is tied to your machine identity. If `/etc/machine-id` has changed (e.g., after an OS reinstall), the old vault cannot be decrypted
- Re-enter your API keys in Settings — they will be stored in a new vault
### Packet capture not working
- Make sure the daemon is running (`bash start.sh`). The daemon runs scapy as root for packet capture
- Check daemon status with: `ls -la /var/run/autarch-daemon.sock`
### App crashes or hangs
- Check the terminal for Python traceback errors
- Run with `--verbose` for more detail: `python autarch.py --verbose`
- Make sure all Python dependencies are installed: `pip install -r requirements.txt`
- If using the venv: `./venv/bin/pip install -r requirements.txt`
---
## 23. Quick Reference
## 29. Quick Reference
### Most-Used Commands
```bash
python autarch.py # Interactive menu
python autarch.py --web # Web dashboard
bash start.sh # Start daemon + web (recommended)
bash stop.sh # Stop everything
python3 launcher.py # GTK desktop launcher
python autarch.py # Interactive CLI menu
python autarch.py --web # Web dashboard only (no daemon)
sudo python3 core/daemon.py # Daemon only (manual start)
python autarch.py -m chat # AI chat
python autarch.py -m adultscan # Username scanner
python autarch.py osint <username> # Quick OSINT
python autarch.py -l # List all modules
python autarch.py --setup # Setup wizard
python autarch.py --show-config # View settings
python autarch.py --mcp stdio # MCP server
python autarch.py --mcp stdio # MCP server (stdio)
python autarch.py --mcp sse # MCP server (SSE)
python autarch.py --service status # Check web service
bash scripts/setup-venv.sh # Create virtual environment
```
### Module Categories
| # | Category | Color | What's In It |
|---|----------|-------|-------------|
| 1 | Defense | Blue | System hardening, shield, VPN, scan monitor, threat intel, container/email sec, incident response |
| 1 | Defense | Blue | System hardening, shield, VPN, scan monitor, threat intel, container/email sec, incident response, network security |
| 2 | Offense | Red | Metasploit, reverse shell, C2 framework, WiFi audit, deauth, vuln scanner, exploit dev, AD audit, MITM, pineapple, social eng, SMS forge, RCS tools, Starlink hack |
| 3 | Counter | Purple | Threat detection, rootkit scanning, steganography, anti-forensics |
| 4 | Analyze | Cyan | File forensics, packet capture, reverse engineering, BLE/RFID, malware sandbox, SDR/RF, drone detection |
| 5 | OSINT | Green | Username/email/domain/IP lookup, IP capture |
| 5 | OSINT | Green | Username/email/domain/IP lookup across 25,475 sites, IP capture |
| 6 | Simulate | Yellow | Port scanning, payload generation, Legendary Creator |
### Key Ports
@@ -1355,23 +1751,44 @@ python autarch.py --service status # Check web service
| 17322 | Reverse Shell listener |
| 51820 | WireGuard VPN |
### Key Sockets
| Path | Service |
|------|---------|
| `/var/run/autarch-daemon.sock` | Privileged daemon |
### File Locations
| File | Purpose |
|------|---------|
| `autarch.py` | Main entry point |
| `autarch_settings.conf` | All configuration |
| `modules/` | CLI tool modules |
| `core/` | Core framework libraries |
| `web/` | Web dashboard (Flask) |
| `launcher.py` | GTK desktop launcher |
| `start.sh` | Start daemon + web |
| `stop.sh` | Stop everything |
| `core/daemon.py` | Privileged daemon |
| `core/vault.py` | Encrypted credential vault |
| `core/hal_analyst.py` | HAL AI analyst engine |
| `modules/` | CLI tool modules (73 modules) |
| `core/` | Core framework libraries (40 files) |
| `web/` | Web dashboard (Flask) — 63 route files, 74 templates |
| `web/routes/module_creator.py` | Module creator backend |
| `web/templates/module_creator.html` | Module creator UI |
| `web/routes/network.py` | Network security backend |
| `web/templates/network.html` | Network security UI |
| `web/templates/mcp_settings.html` | MCP server settings UI |
| `scripts/setup-venv.sh` | Virtual environment setup |
| `scripts/autarch.desktop` | GNOME/KDE desktop entry |
| `scripts/autarch-daemon.service` | Systemd unit for daemon |
| `tools/linux-arm64/` | Bundled tools (nmap, tcpdump, etc.) |
| `android/` | ADB and Fastboot binaries |
| `autarch_companion/` | Android companion app source |
| `data/` | Runtime data (screenshots, downloads, databases) |
| `data/vault.enc` | Encrypted API key vault |
---
## 24. Safety & Legal Notice
## 30. Safety & Legal Notice
AUTARCH is a powerful security platform. Use it responsibly.
@@ -1401,5 +1818,5 @@ If you discover your device has been compromised:
---
*AUTARCH v2.3 — By darkHal Security Group and Setec Security Labs*
*This manual covers all features including 59 web modules, 72 CLI modules, SDR drone detection, Starlink hacking, SMS/RCS exploitation, and the Archon companion app (March 2026)*
*AUTARCH v2.4 — By darkHal Security Group and Setec Security Labs*
*This manual covers all features including 1,130 web routes, 73 CLI modules, 74 templates, 63 route files, 40 core files, 25,475 OSINT sites, the privileged daemon, HAL AI analyst, encrypted vault, network security suite, MCP server, module creator, desktop launcher, and the Archon companion app (March 2026)*