Project ORTHRUS

Automated vulnerability discovery & exploitation-confirmation framework for authorized security testing.

ORTHRUS crawls a target, fingerprints its stack, runs 59 vulnerability scanners,
and then re-proves the interesting findings with a dedicated
exploitation-confirmation phase — so a report distinguishes "this looks
vulnerable" (tentative) from "this was demonstrably exploited" (confirmed). It
produces JSON / CSV / HTML / PDF / SARIF / Markdown reports with CVSS v3.1 + v4.0
scoring and OWASP / CWE / PCI-DSS / NIST-CSF / MITRE ATT&CK mappings — and, optionally,
an AI-written consultant report (Markdown / HTML / PDF)
grounded strictly in those findings and their verbatim evidence.

Run a scan, then explore the results in the built-in dashboard (orthrus serve):

_{The dashboard shows findings by severity/confidence/CWE, an interactive attack-surface graph (orthrus surface), and a Repeater for hands-on verification. Prefer the terminal? The full run renders there too:}

_{A real scan of the bundled, 127.0.0.1-only practice target. Regenerate this view from any JSON report with examples/render_report_ui.py.}

Try it in one command

# no clone, no Python setup — pull the image and scan the bundled practice target
docker run --rm ghcr.io/ankitjha67/orthrus scan -t http://127.0.0.1:8791 --scope 127.0.0.1
# or grab a standalone binary (no dependencies) from the Releases page:
#   https://github.com/ankitjha67/orthrus/releases  →  ./orthrus scan -t … --scope …

📊 Proof it works on real targets: docs/PROOF.md records
reproducible live findings against an authorized range (DVGA GraphQL, an Oracle
WebLogic console matched to 7 CISA-KEV CVEs, unauthenticated Redis) plus the
1065-test / lint-clean quality gates.

🎬 See it run: docs/DEMO.md — a 6-step walkthrough (scan →
attack-graph → runbook → patches → cloud posture → agent) with real output,
reproducible in one command via demo.sh.

📐 Full system spec: docs/PRD.md — the granular,
implemented-system PRD: every subsystem (59 scanners, 19 confirmers, 18 recon
modules), the data/config/scope/store models, the confirmation doctrine, and the
roadmap for advanced scanners & methods.

Status & positioning. ORTHRUS is an early (v0.1.0), actively-developed
project built as a deep, hands-on exploration of how a modern DAST pipeline
fits together end to end. It's an integrated framework — recon → scan →
exploitation-confirmation → correlation → reporting in one tool — meant to
complement, not replace, mature and battle-tested tools like Burp Suite,
OWASP ZAP, or nuclei. Verify its findings, and expect rough edges. Bug reports,
false-positive reports, and feedback are very welcome.

⚠️ Legal & Ethical Use — read before running anything

ORTHRUS is an offensive security tool. It sends real attack payloads and, in
its confirmation phase, actively attempts to exploit findings.

• ✅ Use it only against systems you own, or for which you hold
  explicit, written authorization to test (a signed engagement / scope
  document, bug-bounty program rules, or your own lab).
• ❌ Scanning, exploiting, or accessing systems without permission is
  illegal in most jurisdictions (e.g. the U.S. CFAA, the UK Computer
  Misuse Act, the EU directive on attacks against information systems) and can
  result in criminal prosecution and civil liability.
• 🧭 You are solely responsible for how you use this software and for
  staying within the bounds of your authorization and local law.
• 🚫 The authors and contributors provide this tool as-is, with no warranty,
  and accept no liability for misuse or for any damage it causes.

If you do not have written permission to test a target, do not point ORTHRUS
at it. Use the bundled deliberately-vulnerable practice target or a
self-hosted lab instead (see Try it safely).

As a guardrail, ORTHRUS is deny-by-default: every outbound request is
validated against your declared engagement scope before it is sent, and the
resolved scope is printed at the start of every run. This is a safety aid, not
a substitute for authorization. See Scope enforcement.

Table of contents

• Features
• How it works
• Scope enforcement
• Requirements
• Installation
• Run in VS Code or Google Colab
• Quickstart
• Try it safely
• Usage guide
• Configuration
• Reporting
• Production: PostgreSQL & distributed scanning
• Architecture & project layout
• Extending ORTHRUS (plugins)
• Development
• Legal & Ethical Use
• Contributing
• License

✨ Features

Reconnaissance (18 modules)

• Scope-aware web crawler, passive technology fingerprinting
• Headless-browser (dynamic) crawl + SPA client-side route discovery — captures JS-rendered XHR/fetch endpoints
• Parameter mining (Arjun-style hidden-parameter discovery)
• JavaScript analysis (endpoint + secret extraction), source-map recovery (recover endpoints from leaked .map files), content discovery
• robots.txt / sitemap.xml endpoint discovery (sitemap index + .gz) and /.well-known/ probing (security.txt, OpenID/OAuth config → auth endpoints)
• Subdomain enumeration, DNS enumeration (+ AXFR attempt), WAF detection
• REST/GraphQL API discovery, Wayback Machine historical URLs
• Passive IP-address intelligence (reverse-DNS / ASN / geo / cloud attribution) + co-hosted host gathering
• Nmap port scan (optional; needs the nmap binary)

Vulnerability scanners (59)

Active injection scanners share a WAF-evasion encoder library (URL / double-URL /
mixed-case / comment-spacing / HTML-entity / unicode); transport-surviving
variants are tried automatically under --aggressive.

Exploitation confirmation (18 modules) — re-proves findings to upgrade their
confidence to confirmed:

• Injection — SQLi, command injection, SSTI, LFI, XXE, NoSQL (driver-error replay)
• XSS — browser-executed by default when Playwright is present (window-flag/dialog + screenshot)
• Redirect / headers — open redirect, CRLF / response splitting (fresh-nonce header survives), host-header injection (a freshly-forged attacker host re-reflected into links/redirects)
• Access / objects — IDOR (sequential object enumeration reproduced: adjacent IDs resolve, an implausible ID does not), mass assignment (a fresh per-field nonce re-bound into the response object)
• Cross-origin / tokens — CORS (arbitrary-origin reflection re-proven with a freshly-minted attacker origin), JWT (a weak HMAC secret is recovered and used to forge a validly-signed token — the secret is never emitted)
• JS-runtime / DoS — server-side prototype pollution (a fresh __proto__ sentinel re-persists onto a new object via a clean-before/polluted-after differential), GraphQL DoS (query-batching and alias-overloading amplification re-issued and re-observed)
• Out-of-band — SSRF (collaborator callback)

Confirmation works on query-string and POST/JSON body parameters and runs
concurrently (bounded by concurrency) so WAN round-trips overlap instead of
summing.

It deliberately covers the actively-exploitable classes. Findings already
definitively proven by observation (missing security headers, deprecated TLS,
known-CVE product exposure, banner disclosure, exposed services, request
smuggling, GraphQL introspection) ship as firm/confirmed from detection
itself. A few classes are intentionally detection-only because no safe,
generic automated exploit exists — most notably insecure deserialization
(a passive serialized-blob signature; proving RCE needs a target-specific gadget
chain) — so ORTHRUS reports them rather than inventing a misleading confirmation.

Reporting

• Formats: JSON, CSV, HTML, PDF, SARIF, Markdown, MITRE ATT&CK Navigator layer
• Templates: executive, technical, compliance
• CVSS v3.1 + v4.0 scoring; OWASP Top 10 / CWE / PCI-DSS / NIST-CSF / MITRE ATT&CK mappings
• Severity filtering, logo branding, embedded screenshots & raw request/response evidence

Platform

• Async core (httpx, HTTP/2), per-host token-bucket rate limiting, User-Agent rotation
• Headless-browser engine (Playwright/Chromium) for DOM/stored XSS & JS-rendered crawling
• Out-of-band callback server (local listener) for blind SSRF/RCE detection
• Pluggable scanner/exploit/recon/reporter modules auto-discovered at startup
• SQLite (dev) or PostgreSQL (+ Alembic migrations); optional distributed scanning via Celery/Redis
• OpSec: AES-256-GCM evidence-at-rest encryption, operator audit log, HAR export

Platform & integrations

• REST API (orthrus serve, FastAPI) with auto Swagger docs at /docs, plus a served web dashboard
• MCP server (orthrus mcp) exposing scans/findings as tools for AI agents
• External-tool orchestration (--tools nuclei) — runs best-of-breed CLIs and normalizes their output into ORTHRUS findings
• IaC misconfiguration audit (orthrus iac) — Dockerfile / docker-compose / Terraform, fully offline

🔁 How it works

ORTHRUS runs a four-phase pipeline. Every network request — in every phase — goes
through the scope-enforced HTTP client.

flowchart LR
    A[Target + Scope] --> B[Recon]
    B --> C[Scan]
    C --> D[Exploit / Confirm]
    D --> E[Report]
    B -. assets & endpoints .-> DB[(Findings DB)]
    C -. findings .-> DB
    D -. confirmations .-> DB
    DB --> E
    subgraph guard [Scope-enforced HTTP client deny-by-default]
        B
        C
        D
    end

1. Recon — discover hosts, endpoints, parameters, and technology.
2. Scan — run the selected scanners against discovered injection points;
   emit findings with a confidence of tentative/firm.
3. Exploit / Confirm — re-issue a controlled payload (and, for XSS, execute
   it in a real browser; for SSRF, await an out-of-band callback) to upgrade
   proven findings to confirmed.
4. Report — render the findings (with CVSS, compliance mappings, and
   evidence) to your chosen format.

🛡️ Scope enforcement (the safety boundary)

orthrus.utils.scope.ScopeValidator is the load-bearing safety control. It is
deny-by-default: a host / port / path is only contacted if your
ScopeConfig explicitly authorizes it. orthrus.core.http_client.HttpClient
consults it before every request and re-validates every redirect hop, and
the headless browser is bound by the same check. Scanner modules must use
HttpClient rather than raw httpx, so the boundary cannot be bypassed.

The resolved scope is printed at the start of every run so you can confirm the
engagement boundary before any traffic leaves your machine:

Authorized scope - domains=['*.target.com'] ip_ranges=['10.0.0.0/24'] ports=[80, 443] exclude=['/admin/delete/.*']

--scope auto derives a minimal scope from the target host; real engagements
should always pass an explicit --scope.

📋 Requirements

• Python 3.11+ (developed on 3.14, Windows 11)
• The "lean core" dependencies are pure-Python / wheels and install on Windows
  with no external binaries. Heavier integrations are opt-in extras.

📦 Installation

git clone https://github.com/ankitjha67/orthrus.git
cd orthrus

python -m venv .venv
# Windows:  .\.venv\Scripts\Activate.ps1
# Linux/macOS:  source .venv/bin/activate

pip install -e .

Optional dependency groups:

pip install -e ".[browser]"      # Playwright headless browser (DOM/stored XSS, PDF)
pip install -e ".[scanners]"     # pyjwt, cryptography, sslyze, paramiko, websockets
pip install -e ".[recon]"        # python-nmap (needs the nmap binary too)
pip install -e ".[reporting]"    # weasyprint (alt PDF backend; default PDF uses [browser])
pip install -e ".[postgres]"     # asyncpg + alembic
pip install -e ".[distributed]"  # celery + redis
pip install -e ".[dev]"          # pytest, ruff, mypy

# After installing [browser], download the Chromium runtime once:
playwright install chromium

Or skip the clone — run the published container image or a standalone binary:

# Docker (core + scanners + API/dashboard; no local Python needed)
docker run --rm ghcr.io/ankitjha67/orthrus scan -t http://TARGET --scope TARGET
docker run --rm -p 8000:8000 ghcr.io/ankitjha67/orthrus serve --host 0.0.0.0   # dashboard

# Standalone binary (no dependencies) — download from Releases, then:
./orthrus scan -t http://TARGET --scope TARGET

Prebuilt binaries for Linux / macOS / Windows and the container image are attached
to each GitHub release.

The jwt and tls scanners need [scanners]; dom-xss / stored-xss
and XSS confirmation need [browser] + playwright install chromium. Each
module self-disables cleanly if its extra is missing — the lean core still runs
everything else.

💻 Run in VS Code or Google Colab

Prefer a guided, copy-paste setup? Two detailed step-by-step walkthroughs live in
docs/USAGE_VSCODE_COLAB.md:

• VS Code — virtual-environment setup, recommended extensions, running the
  bundled practice target, breakpoint debugging (launch.json), and the
  test/lint workflow.
• Google Colab — zero local install, all in the browser. Open the
  ready-to-run notebook and choose Runtime → Run all:
  

🚀 Quickstart

# Recon only, scope auto-derived from the target
orthrus recon -t https://example.com --crawl-depth 3

# Full pipeline (recon → scan → confirm → report) → JSON
orthrus scan -t https://example.com -o report.json

# See every option
orthrus --help
orthrus scan --help

🧪 Try it safely

Do not learn the tool on someone else's systems. Use one of these authorized
targets:

• Bundled practice target. This repo ships a deliberately-vulnerable app at
  tests/integration/reflecting_target.py that exercises every scanner locally:

  python tests/integration/reflecting_target.py 8791     # terminal 1
  orthrus scan -t http://127.0.0.1:8791 --aggressive -o report.json   # terminal 2
  

• Self-hosted labs (you own the instance): OWASP Juice Shop, DVWA, OWASP
  WebGoat, bWAPP, OWASP Mutillidae II.

• Vendor-sanctioned public test sites that explicitly permit scanning:
  testphp.vulnweb.com, testasp.vulnweb.com, rest.vulnweb.com (Acunetix),
  demo.testfire.net (IBM), ginandjuice.shop (PortSwigger).

⚠️ Public exploit/CVE databases (e.g. Exploit-DB) catalog vulnerabilities,
not authorized targets. Never point ORTHRUS at a live system you found
listed somewhere; that is unauthorized access.

📖 Usage guide

ORTHRUS's core sub-commands are recon, scan, exploit, and report, plus
post-scan analysis and delivery: findings (terminal triage view), triage
(dedup/cluster + optional LLM false-positive judge), chains / graph
(correlate findings into attack paths / maximal kill-chains), runbook
(consolidated remediation plan, ordered so the highest-leverage fix — one that
breaks an attack path — comes first), finding (set a finding's status/owner),
notify (push high-severity findings to Slack / Jira, with --dry-run),
patch (generate concrete config/code remediation patches per finding), and
ai-report (a Big-Four-grade consultant report — deterministic evidence + AI
narrative, via a local or any market LLM).
Autonomous & posture: agent (a bounded LLM planner that sequences the existing
scope-enforced, non-destructive scanners — no shells, no arbitrary code), cloud
(read-only CSPM/IAM posture + toxic-combination analysis), and proxy (a
scope-aware capturing proxy that feeds the scanner from a manual browse).
Utility commands: doctor (environment readiness), modules (module inventory),
diff (compare two scans), scans (list past scans), benchmark
(detection-accuracy harness), update (refresh CISA-KEV intel), serve (REST
API + dashboard), mcp (MCP server for AI agents), iac (Infrastructure-as-Code
audit), and completion (shell completion). Run orthrus --help for the full
list.

orthrus scan — the full pipeline

# Explicit engagement scope (wildcard domains + CIDR), exclude sensitive paths
orthrus scan -t https://app.target.com \
  --scope "*.target.com,api.target.com,10.0.0.0/24" \
  --exclude-paths "/admin/delete/.*,/api/v1/payments" \
  -o report.html --format html --template technical

# Run only specific scanner modules
orthrus scan -t https://app.target.com --modules sqli,xss,ssti,ssrf -o report.json

# Aggressive mode also enables time-based blind tests (SQLi/cmd) and race conditions
orthrus scan -t https://app.target.com --aggressive -o report.json

# Authenticated scan (re-use a captured session cookie + extra headers)
orthrus scan -t https://app.target.com \
  --auth-cookie "session=abc123; csrf=def456" \
  --headers '{"Authorization": "Bearer eyJ..."}' \
  -o report.json

# Route through a proxy (e.g. Burp), cap the request rate, raise the timeout
orthrus scan -t https://app.target.com --proxy http://127.0.0.1:8080 --rate-limit 10 --timeout 45

# Skip the confirmation phase (also disables the OOB callback server)
orthrus scan -t https://example.com --no-exploit -o report.json

# Disable the headless browser (skips DOM/stored XSS + browser confirmation)
orthrus scan -t https://example.com --no-browser -o report.json

Common scan options: --modules, --aggressive, --rate-limit,
--crawl-depth, --max-pages, --timeout, --proxy, --auth-cookie,
--user-agent, --callback, --no-exploit, --browser/--no-browser,
--exclude-paths, --headers, --threads, --scan-id, -o/--output,
--format, --template, --min-severity, --logo, --har, -v/--verbose.

Full end-to-end scan of a site you own (recommended workflow)

orthrus scan runs all four phases — recon → scan → exploit-confirm → report — in
a single command, and writes the report when you pass -o + --format. With the
[browser] extra installed, DOM/stored-XSS and JS-rendered crawling are included
automatically. A safe, live-site-friendly flow for a site you own or are
explicitly authorized to test:

# 1) Preview the engagement scope + plan — sends NO traffic
orthrus scan -t https://yoursite.com --scope "yoursite.com,*.yoursite.com" --dry-run

# 2) Run the full pipeline with gentle settings → technical HTML report
orthrus scan -t https://yoursite.com \
  --scope "yoursite.com,*.yoursite.com" \
  --rate-limit 10 \
  --crawl-depth 3 --max-pages 200 \
  --exclude-paths "/logout,/admin/delete/.*" \
  -o reports/yoursite.html --format html --template technical

# 3) Export more formats from the SAME stored scan (no re-scan needed)
orthrus scans                                                          # list scans, copy the id
orthrus report --scan-id <id> --format pdf   --template executive -o reports/yoursite_exec
orthrus report --scan-id <id> --format sarif -o reports/yoursite     # CI / code-scanning
orthrus report --scan-id <id> --format json  -o reports/yoursite     # machine-readable

Tune it for your target:

• Deeper testing (more load — use deliberately, ideally on staging): add
  --aggressive for time-based blind SQLi/command tests and race-condition probes.
• Authenticated areas: add --auth-cookie "session=…; csrf=…" (copy a logged-in
  cookie from your browser's dev tools), or drive a login with --login-url and the
  related flags (orthrus scan --help).
• Watch every request: route through Burp/ZAP with --proxy http://127.0.0.1:8080.
• Gate CI: add --fail-on high to exit non-zero when a high-or-worse finding appears.

Only scan hosts you own or hold written authorization for, and keep
--scope tight (deny-by-default — only listed hosts are contacted). On shared
hosting, check your provider's policy before active scanning.

orthrus recon — reconnaissance only

# All recon modules (fingerprint, crawl, JS, content, WAF, API, DNS)
orthrus recon -t https://example.com -o recon.json

# Turn modules on/off; add subdomain enum (needs a *.domain scope) and Wayback
orthrus recon -t https://target.com --scope "*.target.com" \
  --subdomains --wayback --no-content --crawl-depth 5

orthrus report — render an existing scan

# Reports are generated from the stored scan; pick format + template
orthrus report --scan-id scan-abcd1234 --format pdf --template executive -o exec_report
orthrus report --scan-id scan-abcd1234 --format csv -o findings
orthrus report --scan-id scan-abcd1234 --format html --template compliance --min-severity high -o audit

orthrus exploit

orthrus exploit --scan-id scan-abcd1234

Note: confirmation runs automatically during orthrus scan. Standalone
replay-from-DB is not yet implemented — re-run the scan to (re-)confirm.

orthrus bounty — authorized bug-bounty engagements

Runs a whole engagement from a program's authorized scope: enumerate in-scope
subdomains, scan every asset, confirm what it can, and write submission-ready
reports shaped for the target platform. It is deny-by-default and refuses a public
scope with no authorization, or a high-sensitivity host (gov/mil/edu/health)
without explicit attestation.

# save a program, record its rules, then run it (re-run later by name)
orthrus bounty --program acme --in-scope '*.acme.com' \
  --authorization https://hackerone.com/acme --dry-run
orthrus program-policy --program acme --max-rps 5 --identify 'X-Bug-Bounty: you'
orthrus bounty --program acme --platform hackerone --enumerate -o acme-report/

Program-anchored, so it carries cross-run intelligence: new in-scope assets
since the last run are flagged, bugs you reported before are marked as likely
duplicates, and per-program mute rules drop known noise. Companion
commands cover the rest of the workflow — program-policy, bounty-assets,
suppress/suppressions, submission/submissions, note/notes, copilot
(RAG over your own data), cost, audit, bounty-report (re-render without
re-scanning), and bounty-status (one-view cockpit). Optional external tools
fold in via --tools, spanning web (nuclei / dalfox / testssl / ffuf / nikto /
wpscan), code (semgrep), cloud & IaC (checkov), and web3 (slither) — each
self-skips if its binary is absent. Full guide:
docs/BUG_BOUNTY.md.

⚙️ Configuration

Runtime settings are read from environment variables (prefix ORTHRUS_) or a
.env file. None are required for a basic SQLite run.

# Example: PostgreSQL + at-rest encryption
export ORTHRUS_DB_URL="postgresql+asyncpg://orthrus:orthrus@localhost:5432/orthrus"
export ORTHRUS_ENCRYPTION_KEY="$(python -c 'import base64,os;print(base64.b64encode(os.urandom(32)).decode())')"

📑 Reporting

• JSON — full structured output (every field, evidence, exploitation results).
• CSV — one row per finding (severity, confidence, CVSS, type, URL, parameter,
  param location, CWE, OWASP) for spreadsheets/triage.
• HTML — styled report; technical includes raw request/response evidence and
  screenshots, executive is a summary, compliance emphasises framework mappings.
• PDF — the HTML report rendered to PDF via headless Chromium (needs [browser]).
• SARIF — Static Analysis Results Interchange Format for CI / code-scanning
  dashboards (e.g. GitHub code scanning); pair with --fail-on to gate a pipeline.
• Markdown — portable plain-text report for tickets, pull requests, and wikis.
• ATT&CK Navigator (--format navigator) — a MITRE ATT&CK Navigator layer JSON,
  heat-mapped by finding count; drop it into
  mitre-attack.github.io/attack-navigator
  to see the scan on the ATT&CK matrix.

🌟 AI consultant report (orthrus ai-report)

Turn a scan into a Big-Four-grade penetration-test deliverable: every finding,
CVSS score, and recorded request/response is rendered verbatim, and a language
model writes the consultant narrative around those facts — executive summary,
per-finding technical description / business impact / likelihood / exploitation
walkthrough / remediation, correlated attack-chain stories, and a phased
remediation roadmap. Because the findings are fixed and the evidence is quoted,
the model cannot hallucinate a vulnerability — it explains and contextualises
only what the scanner already proved.

orthrus ai-report --scan-id <id> -o report.md            # Claude (ANTHROPIC_API_KEY)
orthrus ai-report --scan-id <id> --format pdf            # client-ready PDF (styled HTML → Chromium)
orthrus ai-report --scan-id <id> --format html          # self-contained, styled HTML deliverable
orthrus ai-report --scan-id <id> --llm ollama:llama3.1   # fully local — nothing leaves the host
orthrus ai-report --scan-id <id> --llm openai:gpt-4o     # OpenAI (OPENAI_API_KEY)
orthrus ai-report --scan-id <id> --dry-run               # full structure + evidence, no model call

Native PDF / HTML, not Markdown. --format html|pdf renders a styled,
paginated Big-Four document (cover, classification banner, document-control table,
severity-shaded finding tables); PDF reuses the headless-Chromium pipeline. Markdown
(--format md, default) stays available for diffing and pipelines.

Deduplicated like a consultant would write it. Findings that share a root
cause — e.g. reflected XSS across seven parameters, or a cookie missing a flag on
four responses — collapse into one finding with an affected-instances table
listing every endpoint/parameter, instead of seven near-identical entries
(--no-group to keep them separate). Inherited default CVSS scores are reconciled
against each finding's own severity, so a low-severity sub-finding never shows a
critical score.

Model-agnostic: Claude, OpenAI, any OpenAI-compatible endpoint (Azure, Groq,
OpenRouter, vLLM, LM Studio — via ORTHRUS_LLM_BASE_URL), or a local Ollama
model so sensitive findings never leave your infrastructure. Credentials and
cookies in captured evidence are redacted before anything is sent to a remote
model. The narrative is AI-generated and grounded in the recorded evidence —
review before client delivery. Slow or cold-starting hosted models can be given
more headroom with ORTHRUS_LLM_TIMEOUT (seconds per call; default 180).

See samples/ for a full report generated this way against the
bundled test target (HTML, PDF, JSON, and SARIF).

Every finding carries CVSS v3.1 + v4.0 vectors/scores and is mapped to OWASP Top
10, CWE, PCI-DSS, NIST-CSF, MITRE ATT&CK (structured technique IDs), and
MITRE D3FEND countermeasures. The per-vuln ATT&CK technique selection was
informed by the Anthropic-Cybersecurity-Skills
catalogue (Apache-2.0); the IDs are public MITRE facts.

Share the terminal view. examples/render_report_ui.py renders any JSON
report into the themed terminal UI (banner, scope panel, summary, OWASP coverage,
findings table) and exports an SVG + HTML frame (and a PNG when the
[browser] extra is installed) — useful for docs, slides, and tickets:

orthrus scan -t http://127.0.0.1:8791 -o report.json
python examples/render_report_ui.py report.json -o out/scan
# → out/scan.svg, out/scan.html, out/scan.png

🏭 Production: PostgreSQL & distributed scanning

# PostgreSQL backend (needs [postgres]: asyncpg + alembic)
export ORTHRUS_DB_URL="postgresql+asyncpg://orthrus:orthrus@localhost:5432/orthrus"
alembic upgrade head

# Distributed scanning across Celery workers (needs [distributed] + Redis)
celery -A orthrus.distributed.celery_app worker --loglevel=info
orthrus scan --distributed --workers 4 --redis redis://localhost:6379/0 -t targets.txt

# Or bring up the whole stack (app + workers + redis + postgres) with Docker
docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml run --rm app scan -t https://example.com

Distributed out-of-band detection needs a shared, externally-reachable callback
server (e.g. Interactsh); the built-in local listener only serves same-host targets.

🧱 Architecture & project layout

orthrus/
  core/        config, scope-enforced HTTP client, browser engine, callback server, orchestrator, schemas
  recon/       crawler, dynamic/SPA crawl, param-mining, fingerprint, JS analyzer, source-map recovery, content discovery, subdomain/DNS enum, WAF, API, wayback, ports
  scanners/    59 scanners + base interface + registry
  exploits/    19 confirmation modules + base interface + registry
  integrations/ external-tool adapters (nuclei, ...) normalized into findings
  intel/       CVE threat-intel enrichment (CISA KEV + EPSS)
  iac/         Infrastructure-as-Code misconfig analyzer (Dockerfile/compose/Terraform)
  api/         FastAPI REST API + web dashboard;  mcp_server.py = MCP server
  reporting/   JSON/CSV/HTML/PDF/SARIF/Markdown generator, CVSS engine, Jinja2 templates
  db/          SQLAlchemy 2.0 models, async store, Alembic migrations
  distributed/ Celery app, tasks, target dispatcher
  utils/       logger, scope validator, rate limiter, encoding
  main.py      Click CLI entry point
docker/        Dockerfile + docker-compose (app, workers, redis, postgres)
examples/      render_report_ui.py (report → themed SVG/HTML/PNG) + a sample report
docs/          screenshots and supporting images
tests/         unit tests + a bundled deliberately-vulnerable integration target

🔌 Extending ORTHRUS (plugins)

Scanners, exploits, recon modules, and reporters are auto-discovered via
decorators. Drop a module that subclasses the relevant base class and registers
itself into ORTHRUS_PLUGINS_DIR (or the in-tree package) and it joins the
pipeline — no core changes needed. A new scanner is roughly:

from orthrus.scanners.base_scanner import BaseScanner
from orthrus.scanners.registry import register

@register
class MyScanner(BaseScanner):
    name = "my-scanner"
    vuln_type = "my-vuln"

    async def scan(self, ctx):
        # use ctx.http (scope-enforced) only; yield Finding(...) objects
        ...

🧰 Development

pip install -e ".[dev]"
ruff check orthrus tests
mypy orthrus
pytest -q

The suite is offline and deterministic (unit tests + a bundled vulnerable target);
it does not touch the network or any external host.

⚖️ Legal & Ethical Use

This software is provided for authorized security testing, education, and
research only.

• Only use ORTHRUS against systems you own or are explicitly authorized in
  writing to test. Keep a copy of that authorization.
• Define an accurate --scope and respect it. Scope enforcement is a safety aid,
  not legal cover.
• Running active scanners/exploits against systems without permission may violate
  computer-misuse laws (CFAA, UK CMA, EU 2013/40, and equivalents) and can lead to
  criminal and civil liability.
• The software is provided "AS IS", without warranty of any kind. The authors
  and contributors are not liable for any misuse, damage, data loss, or legal
  consequence arising from its use.
• By using ORTHRUS you accept full responsibility for your actions and confirm you
  have the authorization required for every target you test.

If in doubt, don't. Practice on the bundled target or a self-hosted lab.

📚 Documentation

🤝 Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md
for dev setup, the quality gates (ruff check orthrus tests + pytest -q), and
docs/WRITING_A_SCANNER.md for a full walkthrough of
adding a scanner. Keep changes scope-safe (all network access goes through the
scope-enforced HttpClient) and add tests for new detectors. A one-click dev
environment is available via the bundled .devcontainer (VS Code / GitHub Codespaces).

Found a security issue in ORTHRUS itself? Please follow the responsible-disclosure
process in SECURITY.md rather than opening a public issue.

💼 Commercial support

ORTHRUS is MIT-licensed and free to use. Commercial support — priority help,
custom scanner development, or a managed/hosted deployment — is on the roadmap; the
paid layer and its terms are still being defined.

⚑ your call: decide the model (hosted scan-as-a-service · managed instance ·
priority support/SLA · custom scanner development) and drop a contact link here
(email or a Cal.com booking). Stating a commercial path — even before it fully
exists — is what lets enterprise users adopt an open-source tool. See
docs/ROADMAP.md (item A15). The TRADEMARKS.md
policy keeps the name protected while the code stays MIT.

📄 License

MIT © 2026 Ankit Jha. See the additional authorized-use notice in
the LICENSE file and the Legal & Ethical Use section above.