xerxes

The Xerxes Project — modular pentest harness in Rust: plugin architecture, async scanning, for authorized security assessments.

⚠️ DISCLAIMER — FOR AUTHORIZED SECURITY ASSESSMENTS ONLY

This tool performs active techniques: port scanning, directory fuzzing, and credential testing. Running it against systems without explicit written authorization from the owner is a crime under Brazil's Lei nº 12.737/2012, the U.S. Computer Fraud and Abuse Act (CFAA), and equivalent laws elsewhere. Destructive actions (PUT/DELETE fuzzing, credential testing) require explicit confirmation by design. You are solely responsible for how you use this software. The author assumes no liability for misuse.

Demo

The module registry, then a live connect scan against scanme.nmap.org with banner grab, metrics and report output.

Overview

xerxes (the Xerxes Project) is a plugin-style pentest harness: a small core (module registry, target management, orchestration, reporting) plus modules that implement one async trait. It covers active reconnaissance phases of MITRE ATT&CK TA0007 (Discovery) and T1046 (Network Service Scanning) with built-in safety rails: a global --dry-run mode that sends zero packets, confirmation prompts before destructive actions, bounded concurrency, and per-target fault isolation.

Features

• 🧩 Plugin architecture — modules implement a documented Module trait and register in a central registry with startup dependency validation; external crates can add modules later
• 🔌 port-scan — async TCP connect scanner (semaphore-bounded), port ranges/lists, banner grab on HTTP/SSH/FTP/SMTP; SYN scan reserved behind a documented feature flag
• 🌐 subdomain-brute — wordlist enumeration via DNS-over-HTTPS with native-resolver fallback, wildcard detection and filtering
• 📁 web-fuzz — directory fuzzing with merged wordlists, GET/POST/PUT/DELETE, custom headers, status include/exclude filters, response sizes; PUT/DELETE gated by confirmation
• 🛰️ shodan — passive host profile (SHODAN_API_KEY env var; graceful skip without it)
• 🔑 cred-brute — HTTP Basic Auth testing, confirmation-gated (SSH/FTP = roadmap)
• 🎯 Target management — single IP, CIDR (capped at /24 with warning), target files, domains with dual-stack DNS TTL cache, IPv4 + IPv6
• ⚡ tokio async — bounded concurrency (default 100), per-host delay, timeouts, live progress counter
• 📤 Reports — JSON, CSV, and single-file dark-theme HTML with metrics (requests, successes, failures, rps), auto-saved to ./reports
• 🧾 Logging — tracing with levels, colored console, daily rolling file at ./logs/pentest.log
• 🛡️ Safety rails — --dry-run plans everything and sends zero packets; destructive actions need yes or --confirm-destructive; non-zero exit only on fatal config errors

Installation

cargo install --git https://github.com/JMarchiori13/xerxes-project

Or build from source: git clone, cargo build --release. Prebuilt binaries for Windows, Linux and macOS (plus sha256 checksums) are attached to every GitHub Release.

Quickstart

# List modules with metadata
xerxes list

# Port scan (scanme.nmap.org is publicly sanctioned by the Nmap project)
xerxes run port-scan --target scanme.nmap.org --ports 22,80,443
xerxes run port-scan --target scanme.nmap.org --ports 1-100 --dry-run

# Subdomain brute force (DoH + wildcard filtering)
xerxes run subdomain-brute --target example.com --wordlist wordlists/subdomains.txt

# Web fuzzing (dry run first, then a small real run)
xerxes run web-fuzz --target example.com --wordlist wordlists/dirs.txt --dry-run
xerxes run web-fuzz --target example.com --wordlist wordlists/dirs.txt -H "X-Test: 1"

# PUT/DELETE need explicit consent
xerxes run web-fuzz --target lab.local --wordlist wordlists/dirs.txt --method PUT --confirm-destructive

# Shodan passive profile
SHODAN_API_KEY=... xerxes run shodan --target 93.184.215.14

# HTTP Basic Auth testing (confirmation required)
xerxes run cred-brute --target lab.local --wordlist wordlists/creds.txt --confirm-destructive

# Everything against one target
xerxes run-all --target lab.local --dry-run

Global options

Option	Default	Description
--target <t>	none	Single IP, CIDR (capped at /24), or domain
--target-file <f>	none	One target per line (# comments)
--concurrency <n>	100	Max concurrent operations
--timeout <s>	3	Per-connection/request timeout (seconds)
--delay <ms>	none	Per-host delay between operations
--dry-run	off	Plan only; zero packets sent
--confirm-destructive	off	Skip the interactive yes for PUT/DELETE and cred-brute
--proxy <url>	none	http://, socks4://, socks5:// (raw TCP scans bypass proxies)
--report <fmt>	all	json, csv, html, or all; saved to ./reports
--log-level <lvl>	info	trace, debug, info, warn, error

Reports

Every run saves to ./reports/<module>-<target>-<timestamp>.<ext>:

• JSON — full document: timestamp, target, module, options used, results, metrics (requests sent, successes, failures, duration, rps), notes
• CSV — flat result rows (heterogeneous row shapes normalized)
• HTML — self-contained single file, inline CSS, dark theme

Project structure

xerxes/
├── Cargo.toml
├── .github/workflows/
│   ├── ci.yml                  # fmt / clippy -D warnings / test / build
│   └── release.yml             # tag v* → win/linux/mac binaries + checksums
├── src/
│   ├── main.rs                 # CLI, banner, tracing init, wiring
│   ├── core/
│   │   ├── module.rs           # Module trait, options, results, metrics
│   │   ├── registry.rs         # central registry + dependency validation
│   │   ├── target.rs           # IP/CIDR/domain/file parsing, DNS TTL cache
│   │   ├── runner.rs           # orchestration, summaries
│   │   └── report.rs           # JSON/CSV/HTML reports
│   ├── modules/
│   │   ├── mod.rs              # registry builder, shared HTTP client
│   │   ├── port_scan.rs        # TCP connect scanner + banner grab
│   │   ├── subdomain_brute.rs  # DoH wordlist enum + wildcard filtering
│   │   ├── web_fuzz.rs         # directory fuzzing, methods/headers/status
│   │   ├── shodan.rs           # passive Shodan host profile
│   │   └── cred_brute.rs       # HTTP Basic Auth testing (confirmed)
│   └── utils/
│       ├── wordlist.rs         # wordlist load/merge/dedup
│       ├── doh.rs              # dns.google DoH client
│       ├── confirm.rs          # destructive-action confirmation
│       └── progress.rs         # live progress counter
├── wordlists/                  # small built-in samples (testing only)
│   ├── subdomains.txt          # ~50 entries
│   ├── dirs.txt                # ~50 entries
│   └── creds.txt               # ~20 test-only pairs
├── docs/
│   ├── architecture.md         # plugin trait walkthrough
│   ├── modules.md              # per-module options
│   └── lab.md                  # safe targets (scanme.nmap.org, httpbin.org)
├── tests/cli.rs                # network-free CLI integration tests
├── reports/                    # auto-saved reports (git-ignored)
├── logs/                       # rolling file logs (git-ignored)
├── CONTRIBUTING.md
├── LICENSE                     # MIT + research-use notice
└── README.md

Visualizations

Roadmap

• SYN scan GA (raw sockets via pnet, all platforms, behind the syn-scan feature)
• SSH/FTP credential brute force modules
• Plugin scripting (rhai or wasm modules loaded at runtime)
• Vulnerability banner matching (Nmap-style service → CVE hints)

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release

Contributions welcome; see CONTRIBUTING.md. The authorized-testing framing and the no-destructive-defaults rule are non-negotiable.

License

MIT © 2026 JMarchiori13. See the research-use notice in the LICENSE file and the disclaimer above.