wraith-sec 0.4.0

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 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 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                           # narrate the attack (payloads, oracles, confirmations)
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	—

Run with -v / --verbose to watch each payload, its oracle measurement (similarity ratios, response timings) and the confirmation step live:

wraith target.com -p injection -v

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, 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.