wraith-sec 0.3.3

Offensive security orchestration framework — walks the kill-chain as a pipeline.

wraith

An offensive security scanner that runs the recon-to-exploitation 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. 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 — one file, zero dependencies, no clone and no build step:

python3 -m venv ~/.local/share/wraith-venv
~/.local/share/wraith-venv/bin/pip install \
  https://github.com/gusta-ve/wraith/releases/latest/download/wraith_sec-0.3.3-py3-none-any.whl
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 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 -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          reflected XSS, error-based SQLi, 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 tests each: reflected XSS needs a raw </>/" payload to come back unencoded, SQLi needs a single quote to raise a database error the baseline didn't, and open redirect needs a redirect param to land in Location.

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

wraith shell is a separate interactive console — recon is batch work, landing a shell isn't:

wraith shell -l 9001,9002
  payloads          reverse-shell one-liners for your LHOST
  sessions          list connected shells
  cmd 1 id          run a command on session 1
  upgrade 1         turn a dumb shell into a PTY
  interact 1        attach (detach with Ctrl-])

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, XSS, SQLi, open redirect, CORS, insecure cookies, missing headers):

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

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.