Aquaxs

      ██     ██  ▄▄▄  ▄▄ ▄▄ ▄▄▄▄▄   ██████ ▄▄▄   ▄▄▄  ▄▄     ▄▄▄▄
      ██ ▄█▄ ██ ██▀██ ██▄██ ██▄▄      ██  ██▀██ ██▀██ ██    ███▄▄
       ▀██▀██▀  ██▀██  ▀█▀  ██▄▄▄     ██  ▀███▀ ▀███▀ ██▄▄▄ ▄▄██▀

[!NOTE] WaveTools includes dual-use network, OSINT and website-recon tools (port/host scanners, subdomain/directory finders, dictionary hash/ZIP crackers). They are for authorized use only — your own systems and accounts, engagements you are contracted for, CTFs, and education. See the Security & Legal Notice.

About The Project

WaveTools is an animated terminal UI (TUI), built on Textual, for security, OSINT, network, and utility tools. Every tool is driven through the same guided step-by-step flow — Banner → Description → Questions → Live Run → Result — all wrapped in a continuously animated gradient border.

The real value of WaveTools is its plugin system: tools aren't hardcoded menu entries, they're loaded at runtime from a folder. Drop a Python file with a TOOL dict and a run() function into wavetools/tools/, restart, and it shows up in the menu — categories, validation, streaming output, and result rendering all come for free.

Highlights:

• Animated TUI with selectable gradient themes, ASCII-only fallback mode, and a full onboarding wizard on first launch.
• Runtime plugin loading — native Python plugins or JSON manifests for external commands, no core changes required.
• 66 tools across Network, OSINT, Roblox, Website, Generator, Crypto and Minecraft — plus built-in System/Text utilities.
• Stable plugin API (plugin_api) with fail-soft HTTP, file, clipboard, and browser helpers.
• Reusable input folder for tokens, webhooks, cookies, proxies, and wordlists — fill fields with Ctrl+F instead of retyping secrets every run.
• Multi-language UI — English, German, Spanish, Russian.
• Versioned plugin API with graceful compatibility/legacy handling and per-tool dependency checks.

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

• Python 3.10+ (CPython). All core dependencies are pinned in requirements.txt.
• On Windows, install.bat / start.bat handle the Python launcher detection for you.

Installation

1. Get the code (clone your fork / this repository) and enter the folder

   cd WaveTools
   

2. Install dependencies

   pip install -r requirements.txt
   

   On Windows you can instead double-click / run install.bat, which finds a Python launcher, upgrades pip, and installs everything for you.
3. Launch WaveTools

   python run.py
   

   On Windows, start.bat does the same with launcher auto-detection.

(back to top)

Usage

On first launch, a one-time setup wizard walks you through language, theme, browser, ASCII mode, and folder configuration. After that, pick a category on the left, pick a tool, answer the guided questions, and watch it run.

Keybindings

Also always shown in the status bar at the bottom of the app:

(back to top)

Plugin Architecture

Components at a Glance

                          ┌──────────────────────────────────────┐
                          │               run.py                  │
                          │   from wavetools.core.app import main │
                          └──────────────────┬─────────────────────┘
                                             │
                 ┌───────────────────────────▼────────────────────────────┐
                 │                  wavetools/app.py                       │
                 │   WaveToolsApp (Textual App) + all Screens              │
                 │   Loader → Start → Main (Categories+Tools) → ToolScreen │
                 └───────┬───────────────────────────────┬─────────────────┘
                         │                               │
        ┌────────────────▼──────────────┐   ┌────────────▼──────────────────┐
        │  builtin_tools.builtin_tools()│   │ plugins.discover_all(dir, …)   │
        │  hardcoded built-in tools      │   │ loads tools from ./tools/      │
        │  (System, Utility, Faker, …)   │   │  • *.py   → Python plugin       │
        └────────────────┬──────────────┘   │  • *.json → external command    │
                         │                   └────────────┬──────────────────┘
                         └───────────────┬────────────────┘
                                         ▼
                            self.all_tools = builtin + plugins
                                         │
        ┌────────────────────────────────┼─────────────────────────────────┐
        │ Support modules                                                    │
        │  gradients.py  Themes/gradients     browsers.py  Browser picking  │
        │  config.py     ~/.wavetools/config  clipboard.py Clipboard        │
        │  plugin_api.py stable plugin API    ascii_art.py Banners/glyphs   │
        │  faker_render.py Faker images (PIL)                                │
        └──────────────────────────────────────────────────────────────────┘

Core idea: the UI knows nothing about individual tools. A tool is a Tool data object with a run/job function. ToolScreen asks the declared questions, calls run/job, and renders the returned ToolResult. That's why a hand-written plugin looks and behaves exactly like a built-in tool.

File Layout

wavetools/
├── run.py                  # entry point: python run.py
├── requirements.txt
├── README.md                (this file)
└── wavetools/               # the actual package
    ├── __main__.py         # python -m wavetools
    ├── core/               # app engine + shared non-tool modules
    │   ├── app.py          # Textual app + screens (UI)
    │   ├── builtin_tools.py # Tool/Step/ToolResult/JobContext + built-in tools
    │   ├── plugins.py      # plugin loader (discover_all) for ../tools
    │   ├── plugin_api.py   # stable helper API for plugins (http_get, save_file, …)
    │   ├── config.py       # persistent config (~/.wavetools/config.json)
    │   ├── gradients.py    # color gradients / themes
    │   ├── browsers.py     # browser detection & selection
    │   ├── clipboard.py    # clipboard (pyperclip)
    │   ├── ascii_art.py    # logo / wave glyphs
    │   ├── i18n.py         # UI translations (en/de/es/ru)
    │   ├── input_folder.py # reusable input folders
    │   ├── text_clean.py   # text cleanup
    │   ├── tutorial.py     # onboarding tutorial
    │   └── faker_render.py # Faker tools (PIL image output)
    ├── input/              # saved inputs per category
    ├── output/             # default output folder for generated files
    ├── utils/              # shared helpers (logging, networking)
    └── tools/              # >>> every plugin lives here <<<
        ├── osint_dns.py          # native Python tool (TOOL + run())
        ├── net_port_scanner.py   # …
        ├── crack_hash_cracker.py # …
        └── …

Everything under wavetools/tools/ is scanned at startup. Files whose name starts with _ or . are skipped (which is why the manifest generator is named _generate_embedded_manifests.py — a build helper, not a tool).

Tool Lifecycle

ToolScreen (app.py) runs through three phases:

 ask  ──►  run  ──►  result
  │         │          │
  │         │          └─ render ToolResult (text/list/table/file),
  │         │             "run again" console, Ctrl+C to copy
  │         └─ run(opts) or job(ctx, opts) on a background thread;
  │            streaming tools write live lines via ctx.line()/ctx.status()
  └─ ask the declared Step()s in order, validate,
     collect into an `answers` dict → reaches run/job as `opts`

Where Tools Come From

WaveToolsApp.__init__ (in app.py) builds the full tool list:

builtin = builtin_tools()                       # hardcoded built-in tools
community_dir = config.resolve_community_tools_dir(cfg)
plugins, reports = discover_all(BUILTIN_TOOLS_DIR, community_dir)
self.all_tools = builtin + plugins

There are three tool origins (Tool.origin):

For 99% of cases, the recommended path is a .py plugin in wavetools/tools/ — see below.

Three dataclasses (in builtin_tools.py) are the entire vocabulary:

• Tool — describes a tool: name, categories, description, the run/job function, the Steps to ask, and metadata.
• Step — one question in the guided flow (kind, prompt, default, validation, condition, …).
• ToolResult — the outcome of a run (ok, summary, log, optional table/items/path/copy).

Streaming adds JobContext — see the reference below.

(back to top)

Writing a Plugin

Adding a New Category

Categories are not hardcoded. The left-hand column of the main menu is derived at runtime from the tools (MainScreen._build_categories in app.py): any category named by any tool shows up automatically.

TOOL = {
    "name": "My New Tool",
    "category": "FORENSICS",      # <-- doesn't exist yet? -> created automatically
    # ...
}

A tool can appear in multiple categories at once via categories (a list). category stays the primary category (shown in the tool view's header):

TOOL = {
    "name": "IP Localise",
    "category": "OSINT",                 # primary category
    "categories": ["OSINT", "NETWORK"],  # appears under BOTH
    # ...
}

Order within a category is controlled via order (lower = higher up; equal values keep load order):

TOOL = { "name": "...", "category": "NETWORK", "order": -10 }

There's no central category list to maintain. To retire a category, just remove it from every tool that references it.

Python Plugin (.py)

The recommended way to add a tool to an existing category is a native Python plugin: a file in wavetools/tools/ that defines a TOOL dict and a run function.

Complete minimal example — wavetools/tools/reverse_text.py:

"""Reverses text — minimal example of a WaveTools plugin."""

TOOL = {
    "name": "Reverse Text",
    "category": "TEXT",               # existing category
    "description": "Reverses the string. Pure offline tool.",
    "api_version": 1,                 # which plugin API this was written against
    "author": "you",
    "version": "1.0.0",
    "capabilities": [],                # uses neither network nor filesystem
    "supported_os": ["Windows", "Linux", "Darwin"],
    "steps": [
        {
            "key": "text",             # ends up as opts["text"]
            "prompt": "Text to reverse",
            "kind": "text",
            "default": "",
        },
    ],
}

def run(opts):
    text = str(opts.get("text", ""))
    reversed_text = text[::-1]
    return {
        "ok": True,
        "summary": f"Reversed {len(text)} characters",
        "log": [reversed_text],
        "copy": reversed_text,        # what Ctrl+C copies
    }

Save the file, restart WaveTools — done. The tool shows up under TEXT.

Two execution styles:

The loader detects which one you wrote from its parameter count. Streaming example:

def run(opts, ctx):
    ctx.status("Working …")
    for i in range(100):
        if ctx.cancelled:                       # user pressed Esc
            return {"ok": False, "summary": "Cancelled."}
        ctx.line(f"Step {i}", style="muted")
    return {"ok": True, "summary": "Done."}

Return value: a dict (as above), an (ok, summary, log) tuple, or a plain string are all accepted — the loader coerces them into a ToolResult (_coerce_result). Important: the keys are ok/summary/log — not success/message. A dict using success/message still loads, but those fields are silently ignored (the tool just shows "Done.").

External Command Plugin (.json)

If your tool isn't Python (a shell script, an .exe, a Node script, …), describe it with a JSON manifest instead. No Python required.

wavetools/tools/my_ping.json:

{
  "name": "Quick Ping",
  "category": "NETWORK",
  "description": "Pings a host using the system ping.",
  "api_version": 1,
  "author": "you",
  "version": "1.0.0",
  "capabilities": ["network", "exec"],
  "supported_os": ["Windows", "Linux", "Darwin"],
  "steps": [
    { "key": "host", "prompt": "Host", "kind": "text", "default": "8.8.8.8" }
  ],
  "command": {
    "Windows": ["ping", "-n", "4", "{host}"],
    "Linux":   ["ping", "-c", "4", "{host}"],
    "Darwin":  ["ping", "-c", "4", "{host}"]
  },
  "timeout": 30
}

How execution works (_make_external_runner in plugins.py):

• command is either an OS map (Windows/Linux/Darwin/default) or a single value.
• {key} placeholders in the command list are substituted with collected answers (str.format(**opts)). In the example, {host} becomes the input.
• timeout (seconds) bounds the run; 0 or null = no limit.
• stdout/stderr are captured and shown as the result log; exit code 0 counts as success.

Watch out for interactive scripts: external commands run without a TTY/stdin. Scripts that call input(), draw a menu, or clear the screen won't work sensibly this way. For those, a native Python port (above) is the right fix.

(back to top)

Plugin API Reference

The TOOL Manifest

All fields (apply equally to .py TOOL dicts and .json manifests unless noted):

.py plugins may additionally define these module functions: run (required), steps_for(answers), setup(), teardown().

Step Kinds

Every entry in steps is a dict. Common keys: key (answer key in opts), prompt (question, alias: label), kind, default (alias: value).

"steps": [
    {"key": "domain", "prompt": "Domain", "kind": "text", "default": "example.com"},
    {"key": "port",   "prompt": "Port",   "kind": "number", "min": 1, "max": 65535, "integer": True},
    {"key": "deep",   "prompt": "Deep scan?", "kind": "bool", "default": False},
    {"key": "proto",  "prompt": "Protocol", "kind": "choice", "choices": ["http", "https"]},
    {"key": "types",  "prompt": "Record types", "kind": "multiselect",
     "choices": ["A", "AAAA", "MX"], "default": ["A"]},
]

Validation & Conditions

Declarative per-step validation (works in .py and .json) via validate:

{"key": "url", "prompt": "URL", "kind": "text",
 "validate": {"required": True, "url": True, "message": "Please enter an http(s) URL"}}

Supported validation keys (_compile_validate in plugins.py): required, min_len, max_len, integer, url, email, regex (+ flags: "i"), message. In .py plugins you can instead supply a function validate(value, answers) -> str|None (error text or None).

number/date/file steps have additional built-in checks (numeric bounds, date format, file exists).

A step can be shown only under a condition (when, alias condition). If the condition isn't met, the step is skipped and its default is stored:

{"key": "platform", "prompt": "Platform", "kind": "choice", "choices": ["TikTok", "X"]},
{"key": "handle",   "prompt": "TikTok handle", "kind": "text",
 "when": {"key": "platform", "equals": "TikTok"}}

Supported condition keys (_compile_condition): equals, is, not, in (list), truthy, falsy. In .py, a function condition(answers) -> bool is also allowed.

The ToolResult Format

run/job return a dict (or a ToolResult). Fields:

return {
    "ok": True,
    "summary": "3 records found",
    "headers": ["Type", "Value"],
    "table": [["A", "93.184.216.34"], ["MX", "mail.example.com"]],
    "copy": "A 93.184.216.34\nMX mail.example.com",
}

The JobContext (Streaming Tools)

A job/run(opts, ctx) receives ctx and uses it to drive the live window. All callbacks are thread-safe (the job runs on a background thread):

The plugin_api helpers are also available directly on ctx: ctx.save_file(...), ctx.http_get(...), ctx.copy(...), ctx.open_path(...), ctx.get_config().

plugin_api Helpers

Importable from any plugin (even from an atomic run(opts)):

from wavetools.core.plugin_api import http_get, save_file, copy_text, get_store, open_url, open_path, get_config

Everything is fail-soft: a helper never raises, it reports success/failure in its return value instead.

Persistent Plugin Storage (PluginStore)

An isolated key/value store per plugin, saved under ~/.wavetools/plugin_data/<id>.json. One plugin can neither read nor overwrite another's data.

ctx.store.set("last_target", target)
last = ctx.store.get("last_target", "")
ctx.store.all()        # everything as a dict
ctx.store.delete("k")  # delete one key
ctx.store.clear()      # delete everything

Lifecycle hooks — optional module functions in a .py plugin:

def setup():
    """Runs once when the tool is opened."""

def teardown():
    """Runs when the tool is left."""

Errors in hooks are fail-soft (noted in diagnostics, never crash the app).

Repeatable question groups — if a .py plugin defines steps_for(answers), the step list is recomputed from it after every answer. This lets questions grow dynamically ("Message #N" + "one more?") as long as the user keeps saying yes. The already-answered prefix must stay stable — only the tail may grow/shrink.

def steps_for(answers):
    steps = [{"key": "msg1", "prompt": "Message #1", "kind": "text"}]
    n = 1
    while answers.get(f"more{n}") is True:
        n += 1
        steps.append({"key": f"msg{n}", "prompt": f"Message #{n}", "kind": "text"})
        steps.append({"key": f"more{n}", "prompt": "One more?", "kind": "bool"})
    return steps

Versioning & Compatibility

• PLUGIN_API_VERSION (in builtin_tools.py) is the current API version.
• A plugin declares, via api_version, which version it was written against. The loader decides from that (_version_decision):
  • newer than the app → skipped (app is too old),
  • older than MIN_SUPPORTED_API_VERSION → skipped,
  • no api_version → compatibility mode ("legacy"), still loads,
  • older but still supported → compatibility mode.
• If a library named in requires is missing, the tool still loads (visibly), but explains what to pip install at startup (_deps_guard).

Every load produces a PluginReport (status loaded/compat/needs-deps/skipped), viewable in the app's diagnostics window.

Capabilities & security model: capabilities is a self-declaration (network/filesystem/exec) shown transparently in the tool description — it is not an enforced sandbox. Plugins (origin bundled/community) require a one-time confirmation before their first run (remembered in config); community tools are additionally flagged as "third-party, unverified". A plugin runs with the user's own privileges. Only install/enable tools whose source you understand.

(back to top)

Configuration

Configuration lives in ~/.wavetools/config.json (creatable/editable via the settings menu, key S on the main menu). Environment variables take precedence:

Stored values include: language, gradient (theme), browser, input_dir, output_dir, community_tools_dir, ascii_only, editor, configured (first-run done), accepted plugins, and optional per-tool default answers. A missing/broken config silently falls back to safe defaults.

First-run wizard & languages: on the very first launch (configured = false), a one-time setup wizard appears: language, theme, browser, ASCII mode, input/output/community folders, and editor. Everything can be changed later under Settings (S). Available UI languages: English (default), German, Spanish, Russian. Only the program's own UI (menus, status lines, settings, wizard) is translated — text produced by tools stays in its original language.

Input folder (reusable inputs): instead of pasting the same cookie / proxy / wordlist on every run, drop it once into the input folder (wavetools/input, created automatically with subfolders + a README on first launch):

When a tool asks for one of these values, WaveTools shows "Use from Input-Folder (N)" automatically — Ctrl+F fills the field straight from the folder (cycle through single values, or insert everything for lists). .txt files are validated and deduplicated.

(back to top)

Tool Catalog

66 bundled tools (plus built-in System/Text utilities). = use only where you are authorized; may carry Terms-of-Service or legal weight depending on the target.

Tools whose filename starts with _ or . are skipped by the plugin loader (build helpers, not tools).

(back to top)

Security & Legal Notice

WaveTools includes network, OSINT and website-recon tooling. Use it exclusively against systems, accounts, and networks you have explicit permission to test — your own infrastructure, authorized penetration tests, CTFs, and education. Scanning, enumeration, dictionary cracking and automated account actions can carry Terms-of-Service or legal weight depending on how and where you use them — that responsibility is yours. Tools flagged in the Tool Catalog are the ones to be especially careful with (they actively probe a target, run dictionary attacks, or automate account changes such as the Minecraft name snipe, which is against Mojang's ToS and should only ever target your own account).

Plugins run with your own privileges and without a sandbox. Only load tools from sources you understand and trust, and consciously confirm a plugin before its first run.

(back to top)

Roadmap

• [x] Runtime plugin loader (.py + .json)
• [x] Reusable input folder with Ctrl+F autofill
• [x] Multi-language UI (en/de/es/ru)
• [x] Plugin API versioning & compatibility mode
• [ ] Automated test suite / CI
• [ ] Plugin marketplace / community index
• [ ] Additional language packs

Track proposed features and known issues in your repository's issue tracker.

(back to top)

Contributing

Contributions make the open-source community an amazing place to learn, get inspired, and build. Any contribution you make is greatly appreciated.

If you have a suggestion, fork the repo and open a pull request, or simply open an issue tagged "enhancement". Don't forget to star the project — thanks again!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a pull request

New tool plugins are the easiest way to contribute — see Writing a Plugin above; a single well-formed .py file in wavetools/tools/ is a complete contribution.

(back to top)

License

Distributed under the MIT License. See LICENSE for the full text.

(back to top)

Contact

WaveTools — a blue, wave-themed multi-tool TUI, by AquA.

For bugs and feature requests, use the issue tracker of the repository you cloned this from.

(back to top)

Acknowledgments

• Textual and Rich — the TUI engine this project is built on
• Best-README-Template — structure and inspiration for this README
• Img Shields — the badges up top
• Choose an Open Source License

(back to top)