wraith-sec 0.3.3__tar.gz

wraith_sec-0.3.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+**What happened**
+
+**Steps to reproduce**
+1.
+2.
+
+**Expected**
+
+**Environment**
+- wraith version (`wraith --version`):
+- Python:
+- OS:
+
+**Logs / output**
+```
+paste here
+```

wraith_sec-0.3.3/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest a phase, template, or improvement
+labels: enhancement
+---
+
+**What would you like**
+
+**Why / use case**
+
+**Notes**
+(If it's a new phase or template, see docs/writing-a-phase.md and
+docs/writing-a-template.md — contributions welcome.)

wraith_sec-0.3.3/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+
+<!-- what this changes and why -->
+
+## Checklist
+
+- [ ] `pytest` passes locally
+- [ ] new detection logic has a test (and stays low false-positive)
+- [ ] tested against `examples/vuln_app.py` if it touches a phase

wraith_sec-0.3.3/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

wraith_sec-0.3.3/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write   # lets PyPI Trusted Publishing mint a short-lived token (no secrets stored)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the environment set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

wraith_sec-0.3.3/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# test / build caches
+.pytest_cache/
+.ruff_cache/
+
+# wraith run output
+wraith-runs/
+
+# editors / OS
+.vscode/
+.idea/
+.DS_Store

wraith_sec-0.3.3/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is loosely
+based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.3.3] - 2026-06-10
+
+### Changed
+- Published to PyPI as `wraith-sec` (the name `wraith` was taken) — install with
+  `pipx install wraith-sec`; the command is still `wraith`. Releases now build
+  and publish to PyPI automatically via Trusted Publishing.
+
+## [0.3.2] - 2026-06-10
+
+### Added
+- `wraith login` now reads the login form on the page: it submits to the form's
+  real `action` and carries every hidden field, so anti-CSRF tokens (ASP.NET
+  `__RequestVerificationToken`, Django `csrfmiddlewaretoken`, Rails
+  `authenticity_token`...) ride along and the login actually succeeds.
+
+### Fixed
+- `access-control` no longer reports false bypasses against single-page apps: a
+  lower principal redirected away (to login or its own area) is treated as
+  denied, static assets and framework files are excluded, and a resource a
+  no-cookie request can already read is suppressed as public.
+
+## [0.3.1] - 2026-06-10
+
+### Fixed
+- `http-probe` now probes the original hostname instead of the resolved IP, so
+  SNI / virtual-hosted sites respond (raw-IP probing fails TLS on modern hosts);
+  the IPv4/IPv6 pair of a service collapses to one probe.
+- `content-discovery` no longer reports blanket redirects (e.g. HTTP→HTTPS) as
+  discovered paths — if a random path is redirected too, it's not a hit.
+- `vhost` baselines against a host that can't exist and drops candidates that
+  match it, so catch-all servers stop inventing virtual hosts.
+
+## [0.3.0] - 2026-06-10
+
+### Added
+- `run` is the default command (`wraith TARGET`, no subcommand needed), short
+  flags (`-p -s -w -t -x -c -l`) and a `--help` with copy-paste examples.
+- End-of-run vulnerability report — a clean, severity-coloured, deduplicated
+  list of everything exploitable (Low and up); Info noise stays in the files.
+- `wraith showdown` — a toggleable mode (off by default, sticks between runs)
+  that plays a run's catch out: findings called out live, the hooded spectre
+  revealed, the kill-chain retold, each finding shown with its evidence, and a
+  poker verdict on the target. Flagged in the banner while on.
+
+### Fixed
+- `access-control` reports one finding per bypassed resource (was one per
+  session), so counts and the report no longer double up.
+
+## [0.2.0] - 2026-06-09
+
+### Added
+- ASCII banner with truecolor gradient and selectable themes
+  (`--theme crimson|matrix|ice|amber|mono`), severity-coloured findings and an
+  end-of-run severity summary. `--no-color` / `--no-banner` / `WRAITH_THEME`.
+- `security-headers` phase — audits security headers, cookie flags and CORS.
+- `injection` phase — reflected XSS, error-based SQLi and open redirect on
+  discovered query/form parameters.
+- `wraith login` — authenticate to a form login and emit a `sessions.json`.
+- JSON findings output (`findings.json`) and `--fail-on <severity>` for CI gating.
+- `--version`.
+- Expanded `examples/vuln_app.py` lab (XSS, SQLi, open redirect, CORS, insecure
+  cookie, missing headers, login) and contributor docs under `docs/`.
+
+## [0.1.0]
+
+### Added
+- Phase engine: DAG scheduling, async workers, failure isolation, persisted
+  workspace, Markdown + dark HTML reports.
+- Phases: `resolve`, `tcp-scan`, `http-probe`, `content-discovery`,
+  `tech-detect`, `vhost`, `template-checks`, `access-control` (Broken Access
+  Control + IDOR).
+- `wraith shell` — reverse-shell handler with multi-listener, PTY upgrade and
+  payload generation.
+- pytest suite and GitHub Actions CI (Python 3.10–3.12).

wraith_sec-0.3.3/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for taking a look. wraith is built to be extended — most new capability
+is a single file.
+
+## Setup
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The core runs on the standard library; `httpx` is an optional speed-up
+(`pip install -e ".[http]"`).
+
+## Ways to contribute
+
+- **A new phase** — see [docs/writing-a-phase.md](docs/writing-a-phase.md).
+- **A new template** — see [docs/writing-a-template.md](docs/writing-a-template.md).
+  Templates need no Python.
+- **Tech-detect signatures** — extend the maps in `wraith/phases/tech_detect.py`.
+
+## Ground rules
+
+- Keep detection low false-positive; add a test that proves it.
+- Run `pytest` before opening a PR — CI runs it on Python 3.10–3.12.
+- Only test against systems you own or are authorized to test. The `examples/`
+  lab is there for exactly this.
+
+## Trying changes against the lab
+
+```bash
+python3 examples/vuln_app.py &
+wraith run 127.0.0.1
+```

wraith_sec-0.3.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Almeida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wraith_sec-0.3.3/Makefile

@@ -0,0 +1,20 @@
+.PHONY: install dev test lab run clean
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+test:
+	pytest -q
+
+lab:
+	python3 examples/vuln_app.py
+
+run:
+	wraith run 127.0.0.1 --sessions examples/sessions.json
+
+clean:
+	rm -rf wraith-runs build dist *.egg-info
+	find . -name __pycache__ -type d -prune -exec rm -rf {} +

wraith_sec-0.3.3/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: wraith-sec
+Version: 0.3.3
+Summary: Offensive security orchestration framework — walks the kill-chain as a pipeline.
+Project-URL: Homepage, https://github.com/gusta-ve/wraith
+Project-URL: Repository, https://github.com/gusta-ve/wraith
+Project-URL: Issues, https://github.com/gusta-ve/wraith/issues
+Project-URL: Changelog, https://github.com/gusta-ve/wraith/blob/main/CHANGELOG.md
+Author-email: Gustavo Almeida <gustavoalm09@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,offensive-security,pentest,recon,red-team,security
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == 'http'
+Description-Content-Type: text/markdown
+
+# wraith
+
+<p align="center">
+  <img src="docs/hero.svg" alt="wraith — offensive recon & exploitation pipeline" width="900">
+</p>
+
+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.
+
+[![CI](https://github.com/gusta-ve/wraith/actions/workflows/ci.yml/badge.svg)](https://github.com/gusta-ve/wraith/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/gusta-ve/wraith?color=crimson)](https://github.com/gusta-ve/wraith/releases)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![MIT](https://img.shields.io/badge/license-MIT-green)
+
+- [Install](#install)
+- [Usage](#usage)
+- [Phases](#phases)
+- [Web testing](#web-testing)
+- [Post-exploitation](#post-exploitation)
+- [Extending](#extending)
+- [Lab](#lab)
+
+## Install
+
+pipx gives you a global `wraith` (the right call on Kali, which blocks system
+pip via PEP 668):
+
+```bash
+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:
+
+```bash
+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`.
+
+<details>
+<summary>Restricted network (proxy / broken IPv6 / HTTP-2 hiccups)</summary>
+
+If `pip`/`git` time out on PyPI or GitHub, grab the prebuilt wheel — one file,
+zero dependencies, no clone and no build step:
+
+```bash
+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`.
+</details>
+
+## Usage
+
+`run` is the default command, so a target is all you need:
+
+```bash
+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:
+
+![a wraith run](docs/demo.svg)
+
+`--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:
+
+```bash
+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](docs/writing-a-phase.md) and
+[docs/writing-a-template.md](docs/writing-a-template.md).
+
+```python
+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):
+
+```bash
+python3 examples/vuln_app.py &
+wraith 127.0.0.1 -s examples/sessions.json
+```
+
+## Tests
+
+```bash
+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.*