JMarchiori13/xerxes-project

# xerxes **Xerxes 项目 —— 基于 Rust 的模块化渗透测试框架：具备插件架构、异步扫描功能，专为授权的安全评估而设计。** [](https://attack.mitre.org/tactics/TA0007/) [](https://attack.mitre.org/techniques/T1046/) [](https://github.com/JMarchiori13/xerxes-project/actions/workflows/ci.yml) [](https://www.rust-lang.org/) [](LICENSE) ## 演示

模块注册表，随后对 scanme.nmap.org 进行实时 connect 扫描，包含 banner 抓取、指标和报告输出。

## 概述 `xerxes`（即 Xerxes 项目）是一个插件式的渗透测试框架：包含一个小型核心（模块 注册表、目标管理、任务编排、报告生成）以及实现了同一异步 trait 的模块。 它涵盖了 MITRE ATT&CK **TA0007 (Discovery)** 和 **T1046 (Network Service Scanning)** 的主动侦察阶段，并内置了安全防护机制：全局的 `--dry-run` 模式 不会发送任何数据包，在执行破坏性操作前会进行确认提示、 有界并发，以及针对每个目标的故障隔离。 ## 功能 - 🧩 **插件架构** — 模块实现一个文档化的 `Module` trait，并在中心注册表中注册，且带有启动依赖验证；外部 crate 可以在后期添加模块 - 🔌 **port-scan** — 异步 TCP connect 扫描器（基于信号量实现有界并发），支持端口范围/列表，在 HTTP/SSH/FTP/SMTP 上进行 banner 抓取；SYN 扫描保留在文档化的 feature flag 之后 - 🌐 **subdomain-brute** — 通过 DNS-over-HTTPS 进行字典枚举，支持本地解析器回退、通配符检测与过滤 - 📁 **web-fuzz** — 目录模糊测试，支持合并的字典、GET/POST/PUT/DELETE、自定义 headers、状态码包含/排除过滤器、响应大小；PUT/DELETE 操作需经过确认 - 🛰️ **shodan** — 被动主机画像（需设置 SHODAN_API_KEY 环境变量；未设置时优雅跳过） - 🔑 **cred-brute** — HTTP Basic Auth 测试，需经过确认（SSH/FTP = 在 Roadmap 中） - 🎯 **目标管理** — 单个 IP、CIDR（限制最高至 /24 并给出警告）、目标文件、具备双栈 DNS TTL 缓存的域名，支持 IPv4 + IPv6 - ⚡ **tokio 异步** — 有界并发（默认 100）、每主机延迟、超时设置、实时进度计数器 - 📤 **报告** — JSON、CSV 以及带有指标（请求数、成功数、失败数、rps）的单文件暗色主题 HTML，自动保存至 ./reports - 🧾 **日志** — 带有日志级别的 tracing，彩色控制台输出，每日滚动的日志文件位于 ./logs/pentest.log - 🛡️ **安全防护** — `--dry-run` 仅进行计划且不发送任何数据包；破坏性操作需要输入 `yes` 或设置 `--confirm-destructive`；仅在遇到致命的配置错误时以非零状态码退出 ## 安装 ``` cargo install --git https://github.com/JMarchiori13/xerxes-project ``` 或者从源码构建：`git clone`，`cargo build --release`。针对 Windows、Linux 和 macOS 的预编译 二进制文件（以及 sha256 校验和）已附加在每一次的 [GitHub Release](https://github.com/JMarchiori13/xerxes-project/releases) 中。 ## 快速开始 ``` # 列出带有 metadata 的 modules xerxes list # Port scan（scanme.nmap.org 受 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，然后进行少量实际运行） 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 需要明确同意 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（需要确认） xerxes run cred-brute --target lab.local --wordlist wordlists/creds.txt --confirm-destructive # 针对单个 target 执行所有操作 xerxes run-all --target lab.local --dry-run ``` ## 全局选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `--target ` | 无 | 单个 IP、CIDR（最高至 /24）或域名 | | `--target-file ` | 无 | 每行一个目标（支持 `#` 注释） | | `--concurrency ` | 100 | 最大并发操作数 | | `--timeout ` | 3 | 每个连接/请求的超时时间（秒） | | `--delay ` | 无 | 主机操作间的延迟 | | `--dry-run` | 关闭 | 仅做计划；不发送任何数据包 | | `--confirm-destructive` | 关闭 | 跳过 PUT/DELETE 和 cred-brute 的交互式 `yes` 确认 | | `--proxy ` | 无 | `http://`, `socks4://`, `socks5://`（原始 TCP 扫描会绕过代理） | | `--report ` | all | json, csv, html, 或 all；保存至 ./reports | | `--log-level ` | info | trace, debug, info, warn, error | ## 报告 每次运行的结果都会保存至 `./reports/--.`： - **JSON** — 完整文档：时间戳、目标、模块、使用的选项、 结果、指标（发送的请求数、成功数、失败数、持续时间、rps）、备注 - **CSV** — 扁平化结果行（已对异构行结构进行规范化处理） - **HTML** — 独立的单个文件，内联 CSS，暗色主题 ## 项目结构 ``` 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 ``` ## 可视化

## Roadmap - [ ] SYN 扫描正式发布 (GA)（通过 pnet 实现原始套接字，支持所有平台，置于 `syn-scan` feature 之后） - [ ] SSH/FTP 凭证暴力破解模块 - [ ] 插件脚本化（在运行时加载的 rhai 或 wasm 模块） - [ ] 漏洞 banner 匹配（Nmap 风格的服务 → CVE 提示） ## 开发 ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test cargo build --release ``` 欢迎贡献；请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。授权测试的 框架设定以及无破坏性默认值的规则是 不可妥协的。 ## 许可证 [MIT](LICENSE) © 2026 JMarchiori13。请参阅 LICENSE 文件中的研究用途声明以及上方的免责声明。