Documentation

• User — Getting started · User guide · Scripting · Configuration · FAQ
• Reference — Module reference (all 73 modules) · Reporting
• Developer — Architecture · Contributing · Changelog
• Governance — Security · Code of Conduct · License

Install

One-liner installers fetch the prebuilt binary for your platform from the latest release, verify its SHA-256 checksum and add it to your PATH. If no prebuilt binary exists yet they build from source instead.

Linux / macOS:

Windows (PowerShell):

Or from a checkout:

Install options (Unix): --prefix <dir> (default: /usr/local/bin as root, else ~/.local/bin), --no-path to skip editing your shell rc, --from-source to build instead of downloading, and TOHA3EE_VERSION=<tag> to pin a release. Run with sudo sh ... to install system-wide. The Windows installer puts the binary in %LOCALAPPDATA%\Programs\toha3ee\bin and updates your user PATH; Windows-on-ARM64 runs the x64 build.

On Linux the installer also registers the app with the desktop environment: it installs the logo to the hicolor icon theme and drops a .desktop entry next to the install prefix (e.g. /usr/local/share or ~/.local/share), so toha3ee shows up in GNOME's search with its icon. On Windows it copies the .ico and creates a Start Menu shortcut. The release tarball/zip carry the icon so the installer can register it from the same verified artifact.

Uninstall: delete the binary and the PATH line the installer added to your shell rc (or %LOCALAPPDATA%\Programs\toha3ee on Windows).

Build

Requires Go 1.26+ and libpcap.

Linux builds need libpcap headers (the installer's from-source fallback checks for them and prints the right apt/dnf command if they are missing). macOS ships libpcap with Xcode Command Line Tools.

Quick start

Most attack modules require root (raw sockets, packet capture and IP forwarding). Run as root or with CAP_NET_ADMIN/CAP_NET_RAW where possible. Add --no-color to disable colored output, -v for verbose logging.

The tool runs with admin privileges by default: on Linux/macOS it re-executes itself under sudo and prompts for the admin (root) password on every invocation. Pass --no-sudo (or set TOHA3EE_NO_SUDO=1) to run unprivileged, e.g. for a quick toha3ee --no-sudo version.

Architecture

Everything is a module. Modules self-register in their package init() and are surfaced automatically by the registry; adding an attack means adding a package under internal/attacks/ that implements the attacks.Module contract (see internal/attacks/attacks.go):

• Meta() — ID, category, risk, targets, description, limitations
• Preflight(ctx) — check preconditions before running
• Run(ctx, opts) — the attack loop (must respect ctx.Done)
• Verify(ctx) — report what happened
• Cleanup(ctx) — undo everything, restore the network

A central safety lifecycle (internal/safety) tracks registered cleanups and heartbeats so every attack is torn down even on panic or SIGINT, and a shared store keeps the host inventory, captured credentials, sessions and the event log that feeds the report generator.

Layers

Modules

Run toha3ee modules for the full, current catalogue. Highlights:

Console

Bare toha3ee (or toha3ee interactive) opens a bettercap/metasploit-style console: the @@@ banner, a red-accented toha3eeλ > prompt with tab-completion, and a persistent one-line status HUD above the prompt that shows the interface, running modules and live host/port/credential/event counts. Output is grouped and aligned in a green/amber/white palette — red is used deliberately, for the prompt accent, hard errors ([x]), the HUD edge mark and critical-risk modules (high risk is amber). Every command's output is sectioned (─── modules ───), tables are column-aligned (colors are ignored when computing alignment), and module messages are colorized centrally, so every module gets consistent status glyphs with no per-module work. Output falls back to plain text automatically when piped, and the prompt stays visible and live while any module runs, like bettercap.

Status glyphs follow bettercap's convention:

The red block ▮ at the left edge of the HUD marks the status strip; the HUD is reprinted after every command so counts stay current without extra typing.

Example session:

set <module.key> <value> stores per-module settings (module IDs are dotted, so the split happens on the last dot: set arp.spoof.targets 10.0.0.5); config dumps everything set so far. Sessions keep captured data across module runs; report.generate renders a Markdown assessment from the in-memory store.

Scripting

.toha3ee files drive the full recon → exploit → report pipeline with a Python-like language that reads like English. Execute one with toha3ee script <file>, from the REPL with script <file>, or run any .toha3ee file with run <file>. toha3ee build <file> (or REPL build <file>) validates the file and prints a dry-run plan without touching the network. scripts/full- pipeline.toha3ee is a working end-to-end example.

Language notes:

• Statements — set, get, on/start/run, off/stop, wait for <module> [max <secs>], sleep <secs>, echo/say/print, show <module>, report <file>, exec <command>, if/else/end, for each _x in <list>, repeat N times, while <cond>, break, continue, and a bare stop halts the script.
• Assignments — _name -> value, _name = value or _name >> value; [...] builds a list from a property, $(_name.size) and $(_list.size) are the lengths.
• Interpolation — $(...) resolves live session state: $(hosts.count), $(net.hosts), $(creds.count), $(sessions.count), $(running.list), $(iface.ip), $(iface.cidr), $(iface.mac), $(iface.gateway), $(config.<module.key>); underscore-prefixed paths read script variables.
• Conditions — == != < > <= >=, &&, ||, !, numbers compare numerically. while loops are capped so a bad condition can never hang the script.
• Modules — every statement drives the exact same module lifecycle and preflight/risk gates as the REPL, so a script cannot do anything the console cannot.

Configuration

Configuration defaults to toha3ee.json (--config to override). Per-module settings are read by each module from its own namespace, e.g. report.generate.out, switch.portsteal.victim_mac, http.harvest.pcap.

Stealth

Stealth is always on, in every phase, down to the individual packet. Every packet-sending module ships a randomized, jittered profile by default; there is nothing to enable, and disabling it (set <module>.stealth false) is explicitly unsupported by the design intent.

• Ordering — probe targets are shuffled (stealth_shuffle) so sweeps do not walk the subnet in the predictable ascending order scanners are fingerprinted by.
• Pacing — probes are sent in bursts with per-probe jitter (stealth_jitter, stealth_burst, stealth_pause) so traffic is neither a flat uniform stream nor a single synchronized flood.
• ARP — who-has requests use randomized Ethernet padding (stealth_pad) instead of the zero-padded frames most scanners emit, and the active net.scan sweep is collected by a single capture loop while the passive listener keeps ingesting traffic.
• SYN scan — every probe varies its source port (stealth_ports), IP TTL and identification (stealth_ttl, stealth_id), TCP sequence number and window, and occasionally clears the DF bit, so the probe stream does not resolve to a single tool signature.
• Fingerprinting — HTTP probing rotates realistic browser user agents and banner grabs are jittered, so service identification does not advertise the framework.

Tunables are read per module, e.g. set net.scan.stealth_jitter 5ms, set service.synscan.stealth_burst 128. The REPL prompt stays visible and live while any module runs, like bettercap.

Tests

The suite covers the frame crafters (DHCP, NDP, 802.11, STP/CDP/LLDP), the store and report renderer, and a registry contract test that pins the full module catalogue.

CI (.github/workflows/ci.yml) runs gofmt, go vet, go build and go test -race on Linux plus tests on Windows and macOS for every push/PR; CodeQL runs static security analysis. Dependency updates are handled by Dependabot.

Contributing

See CONTRIBUTING.md, docs/contributing.md and CODE_OF_CONDUCT.md. Report security issues via SECURITY.md — not as public issues.