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.

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

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 --recon                      # recon only: ports + service/version, no attack traffic
wraith target.com -P web                       # sweep HTTP/alt-HTTP ports; -P all for a full scan
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 target.com --delay 0.5 --jitter 0.5     # quiet: pace requests, randomise the timing
wraith target.com --random-agent               # send a real browser UA, not wraith/<ver>
wraith target.com --proxy http://127.0.0.1:8080  # route through Burp (or any HTTP/SOCKS proxy)
wraith target.com --tor                        # route via Tor — verified, fails closed
wraith target.com --ghost                      # max-opsec preset: Tor + random UA + low-and-slow, one flag
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 under a fixed per-user location — ~/.local/share/wraith/runs/ by default (set WRAITH_RUNS to move it, or --workdir per run) — so hickok finds it from anywhere:

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

A run against the bundled lab (examples/vuln_app.py) — every finding shown is one wraith actually catches:

--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 vulnerability checks
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:

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

Evasion / opsec

By default wraith scans flat out from a wraith/<ver> User-Agent — loud, and easy to attribute in a target's logs. For an authorized engagement where the footprint matters, control it:

wraith target.com --ghost                      # the safest footprint, one flag: Tor + random UA + low-and-slow
wraith target.com --delay 0.5 --jitter 0.5     # pace requests (+ random jitter)
wraith target.com -A "Mozilla/5.0 …"           # an explicit User-Agent
wraith target.com --random-agent               # a random real-browser UA per run
wraith target.com -H "X-Forwarded-For: 1.2.3.4" --cookie "session=…"
wraith target.com --proxy socks5h://127.0.0.1:9050   # any HTTP/SOCKS proxy (Burp, …)
wraith target.com --tor                        # route via Tor, verified
wraith --check-tor --tor                       # just confirm the exit, then exit

The quietest run of all is --recon: it sends no attack traffic at all — just port discovery and service/version fingerprinting, like an nmap -sV (a couple of requests, not a wordlist of /wp-login.php probes). Pair it with the knobs below to map a target before deciding whether to bring the loud phases.

--delay is enforced across every phase (the scan goes serial while it's set), so the whole run is paced, not just one phase. SOCKS/Tor is native (no PySocks) and resolves DNS remotely (socks5h) so the hostname never leaks to your resolver. --tor fails closed: wraith verifies the exit really is Tor before sending any attack traffic and aborts otherwise, so a misconfigured run can't deanonymise you.

Don't want to remember the knobs? --ghost is the one-flag preset for the safest footprint — Tor (fail-closed), a random browser UA, low-and-slow pacing and serial requests, all at once. Override any single piece with its own flag (--ghost --delay 2). The same flag works in hickok.

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 call          # picks up wraith's latest run on its own, flags the 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. Its /db?id= is a boolean-blind SQLi over a real (tiny) SQLite database — point hickok's hickok sql at it to walk and dump it.

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

For a bigger, leveled target — a whole town of rooms, tutorial to impossible — there's deadwood, the dedicated practice range for wraith and hickok:

pipx install deadwood-sec && deadwood serve   # http://127.0.0.1:8666
wraith 127.0.0.1:8666 -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.

the aces Wild Bill was holding — Deadwood, 1876.