wraith-sec 0.3.3__py3-none-any.whl

wraith/__init__.py

@@ -0,0 +1,3 @@
+"""wraith — offensive recon & exploitation pipeline."""
+
+__version__ = "0.3.3"

wraith/__main__.py

@@ -0,0 +1,4 @@
+from wraith.cli import main
+
+if __name__ == "__main__":
+    main()

wraith/art/wraith.txt

@@ -0,0 +1,38 @@
+                                  :========:
+                               -++-..    ..-++:
+                             -**:            :*+:
+                           :*+:                :**.
+                          =#- :-.                :*+
+                         #%-=-:      .::.     ..:  =#
+                        *@@*.     :+=*--*=+:    .-: *+
+                       -@*:    .=**-      -**-    --.%:
+                      :%+   .=##+:          :+*-     -%.
+                     .+*   =%#=      ::::     .+*=.   *=.
+                     =#   *#-    :-*#%@@%#*-:   .=#+   #-
+                    -#- .#+.  :*#@@@@%%%@@@@@%+:  .+#. -*-
+                    =+  ##  .+=====#%%%%%@#======   ##  *-
+                   :*=.+*   =-      .-%%-:      --  .*+ :=:
+                   ++ -#   :#=     .=%##%=.     *+    #= ++
+                  ++ -#    -%@%*++*%@*  *@%++++#@#.    #=.*=
+                 -=.:*-     .++--+%@%.-:.%@%+-=+=.     :*:-*-
+                -#- *=           +#%@#%%#@%#=           += -*-
+               -%-  %=           =:*=%+**==+:           +=  -%-
+             :+%+   -#:            . :--.*==-+-:--     =+.   =%+-
+         .-*#*--*-   :+-    :---=+--==++=+.=.-=:=+-=-- =    .+*:*#*=.
+        :##:.    +=    ==   *+-:-:::-:::%.--------.::#     .**   ..+#:
+       :#+  ::    :=:   .-  -+.:-::::- *+.=------=-.#.    .=-       +#-
+       +*   .*+.   :+-       *=:=---:.-%.--=-::::= ++           .-   *+
+      ++      -+:    -     ..-=.----- #= =:::--:-.:%       -:  -*.   .*+
+     .#=  .    :+:      :+=***:**++- -%.---::--=-=*+.     ..  :+      =#.
+     #=. .-+-   ..     :*#:::-=-=:=+.*= -= :*---::--*+*.         .:-:.-+*
+    +#=.   :**.       -+:**=--=:==*=.*--=- :+-+:*===.:=*.       -#+. . :*+
+  .=#.       :-.   . -=+=.++=-+-==+-       =+----:=-+*:-+..    -+       .+=.
+ .#-          .::+*==-==*=-+-:=--=-         *+:::++++.-+--=**-.           :#.
+ #+=- .-==+=+**-*%::====+--+*=::..           ==-+-:=:=====.-@***+:-=+=.  --+#
+-%=   .. :%#-: =%=.-=:=*+::                     .::==*-+-::.+# :+%+ .:+=   :**
+#:      -#=   .*+ .:+*-.                             .:=%-. :%=  .*=   --   .%
+:      =*.    -@-.--:.                                  :=+:.#:    +-        :
+      :=:     +%-.. :=                                 :-   :@*     =:
+      .:      +=   :=:                                 .+:  .+*
+              +:   +=                                   .-   :*
+                  ==                                         :*

wraith/cli.py

@@ -0,0 +1,406 @@
+"""Command-line entrypoint for wraith."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.parse import urlencode, urljoin, urlsplit
+
+import wraith.phases  # noqa: F401  (importing populates PHASE_REGISTRY)
+from wraith import __version__
+from wraith.core import report
+from wraith.core.console import THEMES, Console
+from wraith.core.context import Workspace
+from wraith.core.engine import Engine
+from wraith.core.models import Severity
+from wraith.core.phase import PHASE_REGISTRY
+from wraith.core.showdown import Showdown
+
+_SEVERITY_BY_NAME = {s.label.lower(): s for s in Severity}
+
+# Subcommands. Anything else on the command line is treated as a target for the
+# default `run` command, so `wraith example.com` works without typing `run`.
+_COMMANDS = {"run", "showdown", "phases", "shell", "login", "aces"}
+
+EXAMPLES = """\
+examples:
+  wraith example.com                     full scan — `run` is the default command
+  wraith example.com -p tcp-scan,http-probe   only these phases
+  wraith example.com -s sessions.json    add Broken Access Control / IDOR
+  wraith example.com -x high             exit 2 if a High+ finding turns up
+  wraith showdown                        toggle showdown mode (reveal on a find; sticks)
+  wraith login http://host/login -u alice -p secret -o sessions.json
+  wraith shell -l 9001                   catch a reverse shell
+
+run `wraith phases` to see the pipeline; phases run concurrently by dependency.
+"""
+
+
+class _Help(argparse.RawDescriptionHelpFormatter):
+    """Keep the examples block verbatim and give options room to breathe."""
+
+    def __init__(self, prog):
+        super().__init__(prog, max_help_position=30, width=86)
+
+
+def _with_default_command(argv):
+    """Insert `run` when the first non-option token isn't a known subcommand,
+    so the common case (`wraith TARGET ...`) needs no subcommand at all."""
+    out = list(argv)
+    i = 0
+    while i < len(out):
+        tok = out[i]
+        if tok in ("-h", "--help", "--version"):
+            return out                       # let argparse handle these as-is
+        if tok == "--theme":                 # the one global option that takes a value
+            i += 2
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        if tok not in _COMMANDS:             # first bare word is a target -> default to run
+            out.insert(i, "run")
+        return out
+    return out
+
+
+def _console(args) -> Console:
+    c = Console(
+        theme=getattr(args, "theme", None),
+        color=False if getattr(args, "no_color", False) else None,
+        banner=not getattr(args, "no_banner", False),
+    )
+    if _load_config().get("showdown"):       # mode on -> wire it to the console
+        c.showdown = Showdown(c)
+    return c
+
+
+# `wraith showdown` flips a mode that sticks between runs, so it's persisted here.
+_CONFIG_PATH = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "wraith" / "config.json"
+
+
+def _load_config() -> dict:
+    try:
+        return json.loads(_CONFIG_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_config(cfg: dict) -> None:
+    try:
+        _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _CONFIG_PATH.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def _select(names):
+    if not names:
+        return [cls() for cls in PHASE_REGISTRY.values()]
+    chosen = []
+    for n in names:
+        cls = PHASE_REGISTRY.get(n)
+        if not cls:
+            raise SystemExit(f"unknown phase: {n} (see `wraith phases`)")
+        chosen.append(cls())
+    return chosen
+
+
+def cmd_phases(args) -> None:
+    c = _console(args)
+    c.banner()
+    for name, cls in PHASE_REGISTRY.items():
+        deps = ", ".join(sorted(cls.requires)) or "—"
+        c.plain(f"  {name:<14} requires: {deps}")
+        if cls.description:
+            c.plain(f"  {'':<14} {cls.description}")
+    c.plain("")
+
+
+def _load_sessions(ws, path, console) -> None:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if data.get("base_url"):
+        ws.meta["base_url"] = data["base_url"]
+    if data.get("seeds"):
+        ws.meta["seeds"] = data["seeds"]
+    for s in data.get("sessions", []):
+        ws.add_session(
+            name=s["name"],
+            role=s.get("role", "low"),
+            headers=s.get("headers", {}),
+            cookies=s.get("cookies", {}),
+        )
+    console.info(f"loaded {len(ws.sessions)} session(s) from {path}")
+
+
+def cmd_run(args) -> None:
+    c = _console(args)
+    c.banner()
+
+    phases = _select(args.phases.split(",") if args.phases else None)
+    ws = Workspace.create(args.target, base_dir=args.workdir)
+    if args.sessions:
+        _load_sessions(ws, args.sessions, c)
+    if args.wordlist:
+        ws.meta["wordlist"] = args.wordlist
+    if args.templates:
+        ws.meta["templates"] = args.templates
+    c.info(f"target   {ws.target}")
+    c.info(f"workdir  {ws.workdir}")
+    c.info(f"phases   {', '.join(p.name for p in phases)}")
+
+    engine = Engine(ws, phases, c, concurrency=args.concurrency)
+    results = asyncio.run(engine.run())
+
+    report_md = report.write_markdown(ws, results)
+    report_html = report.write_html(ws, results)
+    report_json = report.write_json(ws)
+    ws.save()
+
+    c.rule("summary")
+    c.good(
+        f"hosts {len(ws.hosts)} · services {len(ws.services)} · "
+        f"endpoints {len(ws.endpoints)} · findings {len(ws.findings)}"
+    )
+    c.info(f"workspace  {ws.workdir / 'workspace.json'}")
+    c.info(f"report     {report_md}")
+    c.info(f"report     {report_html}")
+    c.info(f"findings   {report_json}")
+
+    worst = max((f.severity for f in ws.findings), default=Severity.INFO)
+    fail = bool(args.fail_on) and bool(ws.findings) and worst >= _SEVERITY_BY_NAME[args.fail_on]
+    if fail:
+        c.warn(f"findings at/above '{args.fail_on}' (worst: {worst.label}) — exit 2")
+
+    if c.showdown is not None:
+        # Showdown mode owns the ending: reveal, kill-chain, receipts, verdict.
+        c.showdown.close(ws)
+    else:
+        # Plain run: the findings, then the tally.
+        c.findings_report(ws.findings)
+        counts = {}
+        for f in ws.findings:
+            counts[f.severity.label] = counts.get(f.severity.label, 0) + 1
+        c.severity_summary(counts)
+
+    if fail:
+        sys.exit(2)
+
+
+def _login_form(html: str, page_url: str):
+    """Find the login form on the page and return (action_url, hidden_fields).
+
+    The login form is the one with a password input. We grab its action (where
+    the POST really goes — often /auth/login, not the page URL) and every hidden
+    field, so anti-CSRF tokens (ASP.NET __RequestVerificationToken, Django
+    csrfmiddlewaretoken, Rails authenticity_token...) ride along automatically.
+    Returns (None, {}) when no such form is found.
+    """
+    import re
+
+    for fm in re.finditer(r"<form\b([^>]*)>(.*?)</form>", html or "", re.I | re.S):
+        attrs, inner = fm.group(1), fm.group(2)
+        if not re.search(r'type\s*=\s*["\']password', inner, re.I):
+            continue  # not the login form
+        action_m = re.search(r'action\s*=\s*["\']([^"\']*)', attrs, re.I)
+        action = urljoin(page_url, action_m.group(1)) if action_m and action_m.group(1) else page_url
+        hidden = {}
+        for inp in re.finditer(r"<input\b([^>]*)>", inner, re.I):
+            a = inp.group(1)
+            if not re.search(r'type\s*=\s*["\']hidden', a, re.I):
+                continue
+            name = re.search(r'name\s*=\s*["\']([^"\']+)', a, re.I)
+            value = re.search(r'value\s*=\s*["\']([^"\']*)', a, re.I)
+            if name:
+                hidden[name.group(1)] = value.group(1) if value else ""
+        return action, hidden
+    return None, {}
+
+
+def cmd_login(args) -> None:
+    """Authenticate against a form login and emit a sessions.json snippet."""
+    import http.cookiejar
+    import ssl
+    import urllib.request
+
+    c = _console(args)
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    jar = http.cookiejar.CookieJar()
+    opener = urllib.request.build_opener(
+        urllib.request.HTTPSHandler(context=ctx),
+        urllib.request.HTTPCookieProcessor(jar),
+    )
+    ua = {"User-Agent": "wraith/0.1"}
+
+    # GET the login page first: seeds the session cookie *and* lets us read the
+    # form's real action and any hidden token it expects on submit.
+    action, hidden = args.url, {}
+    try:
+        with opener.open(urllib.request.Request(args.url, headers=ua), timeout=10) as resp:
+            html = resp.read(200000).decode("utf-8", "ignore")
+        found_action, hidden = _login_form(html, args.url)
+        if found_action:
+            action = found_action
+            if hidden:
+                c.info(f"form action {action} · carried {len(hidden)} hidden field(s): {', '.join(hidden)}")
+    except Exception as exc:
+        raise SystemExit(f"could not load login page: {exc}")
+
+    # hidden fields first, then our credentials and any --data overrides on top.
+    fields = dict(hidden)
+    fields[args.user_field] = args.username
+    fields[args.pass_field] = args.password
+    for pair in args.data or []:
+        if "=" in pair:
+            k, v = pair.split("=", 1)
+            fields[k] = v
+    body = urlencode(fields).encode()
+
+    try:
+        post = urllib.request.Request(action, data=body, headers={**ua, "Referer": args.url})
+        opener.open(post, timeout=10)
+    except Exception as exc:
+        raise SystemExit(f"login request failed: {exc}")
+
+    cookies = {ck.name: ck.value for ck in jar}
+    if not cookies:
+        c.warn("no cookies captured — check the field names/URL")
+
+    parts = urlsplit(args.url)
+    snippet = {
+        "base_url": f"{parts.scheme}://{parts.netloc}",
+        "seeds": ["/"],
+        "sessions": [{"name": args.name, "role": args.role, "cookies": cookies}],
+    }
+    text = json.dumps(snippet, indent=2)
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        c.good(f"captured {len(cookies)} cookie(s) -> {args.output}")
+    else:
+        print(text)
+
+
+def cmd_showdown(args) -> None:
+    """Toggle showdown mode on/off — it sticks between runs. While on, every run
+    that finds a vulnerability reveals the wraith (more mode behaviour to come)."""
+    c = _console(args)
+    cfg = _load_config()
+    cfg["showdown"] = not cfg.get("showdown", False)
+    _save_config(cfg)
+    if cfg["showdown"]:
+        if c.show_banner:
+            c.aces()
+        c.good("showdown mode ON — runs now play the catch out (run `wraith showdown` again to turn off)")
+    else:
+        c.info("showdown mode OFF — wraith runs plain again")
+
+
+def cmd_aces(args) -> None:
+    _console(args).aces()
+
+
+def cmd_shell(args) -> None:
+    from wraith.shell import payloads
+    from wraith.shell.handler import ShellServer
+
+    c = _console(args)
+    c.banner()
+    try:
+        ports = [int(p) for p in args.listen.split(",")]
+    except ValueError:
+        raise SystemExit("--listen expects comma-separated port numbers")
+    lhost = args.lhost or payloads.guess_lhost()
+    server = ShellServer(ports, lhost, c)
+    try:
+        asyncio.run(server.run())
+    except KeyboardInterrupt:
+        pass
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="wraith",
+        description="Offensive recon & exploitation pipeline.  Run is the default: `wraith TARGET`.",
+        epilog=EXAMPLES,
+        formatter_class=_Help,
+    )
+    p.add_argument("--version", action="version", version=f"wraith {__version__}")
+    p.add_argument("--theme", metavar="NAME", choices=list(THEMES),
+                   help="colour theme: " + " | ".join(THEMES) + " (default: crimson)")
+    p.add_argument("--no-color", action="store_true", help="disable coloured output")
+    p.add_argument("--no-banner", action="store_true", help="suppress the ASCII banner")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    def _add_scan_args(sp):
+        sp.add_argument("target", help="hostname, IP or URL")
+        sp.add_argument("-p", "--phases", metavar="LIST", help="comma-separated subset of phases (default: all)")
+        sp.add_argument("-s", "--sessions", metavar="FILE", help="sessions JSON — enables access-control / IDOR")
+        sp.add_argument("-w", "--wordlist", metavar="FILE", help="wordlist for content-discovery")
+        sp.add_argument("-t", "--templates", metavar="DIR", help="extra template-checks directory")
+        sp.add_argument("-x", "--fail-on", metavar="SEV", choices=list(_SEVERITY_BY_NAME),
+                        help="exit 2 on a finding at/above SEV (info|low|medium|high|critical)")
+        sp.add_argument("-c", "--concurrency", metavar="N", type=int, default=8,
+                        help="max phases running in parallel (default: 8)")
+        sp.add_argument("--workdir", metavar="DIR", default="wraith-runs",
+                        help="output directory (default: wraith-runs)")
+
+    run = sub.add_parser("run", help="scan a target (default command)", epilog=EXAMPLES,
+                         formatter_class=_Help, description="Run the phase pipeline against a target.")
+    _add_scan_args(run)
+    run.set_defaults(func=cmd_run)
+
+    sd = sub.add_parser("showdown", help="toggle showdown mode on/off (sticks between runs)",
+                        formatter_class=_Help,
+                        description="Toggle showdown mode. While it's on, every run reveals the "
+                                    "wraith when it catches a vulnerability. Run it again to turn off.")
+    sd.set_defaults(func=cmd_showdown)
+
+    ph = sub.add_parser("phases", help="list available phases", formatter_class=_Help)
+    ph.set_defaults(func=cmd_phases)
+
+    sh = sub.add_parser("shell", help="reverse-shell handler / post-exploitation console", formatter_class=_Help)
+    sh.add_argument("-l", "--listen", metavar="PORTS", default="9001",
+                    help="comma-separated ports to listen on (default: 9001)")
+    sh.add_argument("--lhost", metavar="IP", help="LHOST embedded in generated payloads (auto-detected)")
+    sh.set_defaults(func=cmd_shell)
+
+    lg = sub.add_parser("login", help="grab a session from a form login -> sessions.json", formatter_class=_Help)
+    lg.add_argument("url", help="login form URL (GET to seed cookies, POST to submit)")
+    lg.add_argument("-u", "--username", required=True)
+    lg.add_argument("-p", "--password", required=True)
+    lg.add_argument("-o", "--output", metavar="FILE", help="write the sessions.json here (default: stdout)")
+    lg.add_argument("--user-field", metavar="NAME", default="username", help="username form field name")
+    lg.add_argument("--pass-field", metavar="NAME", default="password", help="password form field name")
+    lg.add_argument("--data", metavar="K=V", action="append", help="extra form field (repeatable)")
+    lg.add_argument("--name", metavar="NAME", default="user", help="session name for the output")
+    lg.add_argument("--role", metavar="ROLE", default="low", help="session role (none/low/med/high)")
+    lg.set_defaults(func=cmd_login)
+
+    egg = sub.add_parser("aces")  # easter egg: no help= keeps it out of the listing
+    egg.set_defaults(func=cmd_aces)
+
+    return p
+
+
+def main(argv=None) -> None:
+    argv = sys.argv[1:] if argv is None else list(argv)
+    parser = build_parser()
+    if not argv:                         # bare `wraith` -> banner + help, not an error
+        Console().banner()
+        parser.print_help()
+        return
+    args = parser.parse_args(_with_default_command(argv))
+    if not hasattr(args, "func"):        # options but no command
+        parser.print_help()
+        return
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()