wraith-sec 0.5.1

Offensive web recon & vulnerability detection — a pipeline of composable phases.

wraith

An offensive security scanner that runs the recon-to-detection workflow as a pipeline of small composable phases. Point it at a target; it resolves hosts, scans ports, maps the web surface, tests it and reports what it finds — then hand the catch to hickok to act on it. The core has no third-party dependencies.

• Install
• Usage
• Phases
• Web testing
• Post-exploitation
• Extending
• Lab

Install

pipx gives you a global wraith (the right call on Kali, which blocks system pip via PEP 668):

sudo apt install -y pipx && pipx ensurepath
pipx install wraith-sec            # the command is `wraith`
pipx install "wraith-sec[http]"    # + httpx, faster probing

From a clone:

git clone https://github.com/gusta-ve/wraith && cd wraith
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[http]"

Or without installing anything: PYTHONPATH=src python3 -m wraith run target.

Restricted network (proxy / broken IPv6 / HTTP-2 hiccups)

If pip/git time out on PyPI or GitHub, grab the prebuilt wheel from the releases page — one file, zero dependencies, no clone and no build step:

python3 -m venv ~/.local/share/wraith-venv
~/.local/share/wraith-venv/bin/pip install ./wraith_sec-*.whl   # the wheel you downloaded
ln -sf ~/.local/share/wraith-venv/bin/wraith ~/.local/bin/wraith

git clone failing with "HTTP2 framing layer"? Force HTTP/1.1: git config --global http.version HTTP/1.1.

Usage

run is the default command, so a target is all you need:

wraith target.com                              # full pipeline (no subcommand needed)
wraith -u https://target.com:8443              # target as a URL (-u/--url); the port is scanned too
wraith 10.10.10.5 -p resolve,tcp-scan,http-probe   # only these phases
wraith target.com -s sessions.json             # adds access-control / IDOR
wraith target.com -v                           # progress; -v 2 = attack detail (payloads/requests), -v 3 = responses
wraith target.com -x high                      # exit code 2 on a High+ finding
wraith --theme matrix target.com               # crimson (default) | matrix | ice | amber | mono
wraith showdown                                # toggle "showdown mode" — wraith plays the catch out (reveal + verdict)
wraith phases                                  # list phases and their dependencies

A run writes a self-contained directory:

wraith-runs/target.com-<ts>/
  workspace.json   every host, service, endpoint and finding (resumable)
  report.md
  report.html      dark, self-contained
  findings.json

A real run against the bundled lab:

--no-banner and --no-color (or NO_COLOR) strip the cosmetics for logs and CI; WRAITH_THEME sets a default theme.

Phases

Each phase declares the phases it depends on. The engine resolves that graph and runs independent phases concurrently; a failing phase is isolated and its dependents are skipped. Everything is shared through one persisted workspace.

resolve            DNS resolution
tcp-scan           async TCP connect scan of common ports
http-probe         status, Server header and title
content-discovery  path/file wordlist with soft-404 filtering
tech-detect        server / language / framework / CMS fingerprint
vhost              virtual-host discovery via Host-header fuzzing
template-checks    declarative JSON/YAML checks (nuclei-style)
security-headers   security headers, cookie flags and CORS
injection          XSS, SQLi (error/boolean/time), command injection, SSTI, LFI, open redirect
access-control     Broken Access Control and IDOR (needs sessions)

Web testing

injection crawls the target, pulls parameters from query strings and forms, and probes each with a battery of techniques. Every technique has a single, explainable oracle — and every hit is confirmed a second way before it's reported, so a finding is evidence, not a guess:

Technique	Oracle	Confirmed by
Reflected XSS	a raw </>/" marker reflects unencoded	—
SQLi (error-based)	a single quote raises a DB error	a balanced quote clears it
SQLi (boolean-blind)	a TRUE condition page matches normal, FALSE diverges	a second, different injection context
SQLi (time-blind)	SLEEP/pg_sleep/WAITFOR delays the response	a longer sleep delays proportionally more
Command injection	; sleep N delays the response	same time-correlation proof
SSTI	{{a*b}} comes back evaluated (the product)	a second random product
Path traversal / LFI	../../etc/passwd returns a root:x:0:0: signature	read twice
Open redirect	a redirect param lands in Location	—

Verbosity is levelled like other scanners. -v (level 1) is lightweight progress — which parameter is being tested, crawl brackets — so a run never looks frozen. -v 2 is the full attack play-by-play: every payload, its oracle measurement (similarity ratios, response timings) and the confirmation step, plus each HTTP request. -v 3 adds the responses:

wraith target.com -p injection -v      # level 1 — progress only
wraith target.com -p injection -v 2    # the detailed attack trace

security-headers reports missing CSP/HSTS/X-Frame-Options/nosniff, weak cookie flags and CORS that reflects an arbitrary origin.

access-control needs authenticated sessions. It crawls as the privileged session and replays every request as the lower-privilege and anonymous ones; a lower principal getting identical content is a vertical bypass, and mutating numeric ids surfaces IDOR. Grab a session with:

wraith login http://target/login -u alice -p secret \
    --user-field user --pass-field password -o sessions.json

Post-exploitation — hickok

wraith finds and proves the way in; landing a shell and working the box is hickok's job — wraith's companion. It reads a wraith run and acts on it:

hickok hand wraith-runs/<run>/findings.json   # flags the code-exec footholds
hickok -l 9001                                # catch the reverse shell

wraith holds the aces, hickok brings the eights — aces and eights, the dead man's hand.

Extending

A phase is one file; a check can be pure data. See docs/writing-a-phase.md and docs/writing-a-template.md.

from wraith.core.phase import Phase, register

@register
class MyPhase(Phase):
    name = "my-phase"
    requires = frozenset({"http-probe"})

    async def run(self, ws, console):
        for ep in ws.endpoints:
            ...  # ws.add_finding(...)

Lab

examples/vuln_app.py is a deliberately vulnerable app to practise against and to exercise every web phase: BAC, IDOR, reflected XSS, SQLi (error/boolean/time), command injection, SSTI, path traversal/LFI, open redirect, CORS, insecure cookies and missing headers.

python3 examples/vuln_app.py &
wraith 127.0.0.1 -s examples/sessions.json -v

Tests

pip install -e ".[dev]" && pytest

Disclaimer

Built for security research and testing — point it where you're meant to. What anyone does with it from there is theirs alone; the author takes no responsibility for misuse or for any damage caused.

License

MIT.

---

You never saw it coming — the wraith was already holding aces.