m524security/CORVUS

一款自主的攻防安全扫描器，能自主决定测试内容，进行带外验证，并报告证据——而非猜测。

## 目录 - [概述](#overview) - [CORVUS 的独特之处](#why-corvus-is-different) - [🔬 真实性证明（非伪造）](#-proof-its-real-not-fake) - [功能概述](#feature-summary) - [🎯 检测覆盖范围](#-detection-coverage) - [🧰 外部工具库](#-external-tool-arsenal) - [工作原理](#how-it-works) - [安装说明](#installation) - [使用方法](#usage) - [自主引擎 — `corvus.py`](#autonomous-engine--corvuspy) - [扫描配置](#scan-profiles) - [带外验证 (OAST)](#out-of-band-verification-oast) - [经典接口 — `corvus_core.py`](#classic-interface--corvus_corepy) - [企业级扫描器集成](#enterprise-scanner-integrations) - [插件](#plugins) - [报告生成](#reporting) - [测试与 CI](#testing--ci) - [项目结构](#project-structure) - [扩展 CORVUS](#extending-corvus) - [故障排除](#troubleshooting) - [负责任的使用](#responsible-use) - [路线图](#roadmap) - [作者与许可协议](#author--license) ## 概述 CORVUS 是一款专为单操作员设计的 Web 与 API 攻击面扫描器，其核心构建基于 **决策引擎**而非固定的检查清单。它会维护关于目标的*状态*，并根据预期价值选择下一个检查项—— 优先执行高信噪比的模块，跳过被指纹规则排除的项目，并在请求预算耗尽时停止。 每个发现都会使用符合规范的 **CVSS v3.1** 引擎进行评分，打上 **OWASP Top 10 (Web + API)** 和 **MITRE ATT&CK** 标签，最后导出为五种 报告格式。盲测类的漏洞会通过真实的**带外回调**进行确认，因此每一个发现都是证据，绝非猜测。 CORVUS 是一款**检测与报告**工具。它负责发现并验证 漏洞；不会进行武器化、漏洞利用或持久化操作。 **概览** | | | |---|---| | 检测模块 | **100** (OWASP Web Top 10 2021 + API Top 10) | | 外部工具集成 | **58** (仅在 `PATH` 中存在时使用) | | 默认凭证对 | **130** | | 技术指纹 | **85** | | CVSS v3.1 模块预设 | **41** | | 报告格式 | JSON · HTML · CSV · **SARIF 2.1.0** · Markdown | | 扫描配置 | Passive · Safe · Aggressive | | 硬依赖 | 仅需 `requests` (Python 3.8+) | ## CORVUS 的独特之处 | 大多数扫描器 | CORVUS | |---|---| | 按照固定顺序执行所有检查 | **决策引擎**根据预期价值 + 指纹门控选择下一个检查 | | 仅凭单次反射/报错就标记漏洞 | 在得出结果前进行**多级门控确认**（基准 → 编码 → 上下文 → 带外） | | 盲载荷发现全凭“相信我” | **OAST 验证** —— 盲 SSRF/RCE/XXE/SSTI 必须由真实的带外回调确认，否则不触发 | | 凭感觉定级 | 采用 **CVSS v3.1** 评分，与 FIRST.org 参考向量 11/11 完全匹配 | | 仅声称准确 | **实时验证套件** —— 在内置的易受攻击目标上进行真实发现 + 阴性对照，可在 CI 中运行 | ## 🔬 真实性证明（非伪造） 关于准确性的声明并不值钱。CORVUS 内置了一个**故意设计的易受攻击目标** (`tests/integration/vuln_server.py`) 以及一个**实时集成测试**，它会对该目标运行 真实的检测模块——既断言真正的阳性漏洞会被触发，*又* 确保干净的端点保持静默（没有误报）。 自己尝试一下吧，无需外部目标： ``` python examples/demo_local_scan.py ``` ``` CORVUS demo — scanning bundled vulnerable app at http://127.0.0.1:xxxxx [Critical] cvss=9.1 Error-Based SQL Injection in 'id' (MySQL) (A03/T1190) [High ] cvss=4.3 Reflected XSS in Parameter 'q' (A03/T1059.007) [Medium ] cvss=4.3 Open Redirect in 'url' (A01/T1071) [Critical] cvss=7.5 Git Repo Exposed (A05/T1552) [Critical] cvss=7.5 Environment File Exposed (A05/T1552) [High ] cvss=5.3 Missing Strict-Transport-Security (+5 more) (A05/T1071) 11 findings. Every one carries a CVSS vector, OWASP id, and MITRE technique. ``` **阴性对照证明了误报控制是有效的** —— HTML 编码的输出、 不反射的参数，以及不可注入的参数都正确地**未产生任何发现**。 此外，CVSS 引擎已通过官方 FIRST.org 规范的验证： ``` $ pytest tests/test_cvss.py -q 11/11 reference vectors matched FIRST.org published base scores 9.8 CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H (unauth RCE) 10.0 CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H (scope-changed) 6.1 CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N (reflected XSS) ``` 关于审计过程及所发现 bug 的完整报告：[`SECURITY_REVIEW.md`](SECURITY_REVIEW.md)。 ## 功能概述 **覆盖范围** —— 跨越 OWASP Web Top 10 (2021) 和 API Top 10 的 100 个检测模块； 130 对默认凭证；85 种技术指纹。 **准确性** —— 符合规范的 CVSS v3.1（对比 FIRST.org 验证为 11/11）；多级门控 误报控制；针对盲测类别的 OAST 带外确认。 **自主性** —— 具备指纹门控、请求与时间预算、基准缓存、响应去重以及三种扫描配置的预期价值决策引擎。 **集成** —— 机会性使用 58 种外部工具（nuclei、sqlmap、nmap、httpx、ffuf、sslyze、 wpscan、trufflehog 等），以及可选的企业级扫描器 (ZAP, Nessus, OpenVAS, Burp, Qualys, Acunetix, Tenable, Akto)。 **报告生成** —— JSON · HTML · CSV · SARIF 2.1.0 · Markdown，每个发现都包含 CVSS 评分 + 向量、OWASP ID、MITRE 技术和证据。支持扫描 `--diff`（与上次运行的差量对比）和 `--resume`（检查点恢复）。 **默认安全** —— 仅作检测；非交互式运行永远不会自动安装 系统软件包（可通过 `--install-tools` 开启）；不使用 `shell=True`，不对 动态数据使用 `eval`/`exec`。 ## 🎯 检测覆盖范围 映射到 OWASP Top 10 2021 (Web) 和 OWASP API Security Top 10 的 100 个模块。 **OWASP Web Top 10 (2021)** | 类别 | 代表性检查 | |---|---| | **A01 失效的访问控制** | IDOR / BOLA, 403/401 绕过, 开放重定向, CSRF, 子域名接管 | | **A02 加密机制失效** | SSL/TLS 状态, 弱加密指标, 响应中的机密泄露 | | **A03 注入** | SQLi (报错/布尔/时间), XSS (反射型, 多级门控), SSTI, XXE, NoSQL, Host 头, 邮件头, HTTP 参数污染 | | **A04 不安全的设计** | 批量赋值, 业务逻辑缺陷 | | **A05 安全配置错误** | 安全标头, CORS, 点击劫持, HTTP 方法, 信息泄露, 敏感文件, GraphQL 内省, 缓存中毒, SPF/DMARC/DKIM | | **A06 易受攻击的组件** | 过时组件检测, 版本指纹识别 | | **A07 身份验证失效** | 默认凭证 (130 对), JWT 弱点, Cookie 标志, 速率限制, OAuth/OIDC 配置错误 | | **A08 软件与数据完整性失效** | 子资源完整性缺失 | | **A09 安全日志与监控失效** | 日志/监控暴露指标 | | **A10 SSRF** | 服务端请求伪造 (OAST 验证) | **OWASP API Top 10** —— BOLA, 失效的功能级授权 (BFLA), 过度 数据暴露, API 版本控制/清单, 业务逻辑滥用, 以及 HTTP 请求 走私。 ## 🧰 外部工具库 当 `PATH` 中存在时，CORVUS 会编排 **58** 种业界最佳工具——它 从不会强制要求安装它们，缺失的工具会被直接跳过。 - **侦查 / 发现** —— amass, subfinder, sublist3r, dnsx, dnsrecon, theHarvester, whatweb, wafw00f, httpx, katana, gospider, gau, waybackurls, waymore, paramspider, arjun - **内容 / 模糊测试** —— ffuf, feroxbuster, gobuster, snallygaster - **网络 / 端口** —— nmap, naabu, masscan - **漏洞扫描** —— nuclei, nikto, wpscan, nuclei_v8, nikto_v8, nmap_v8 - **注入 / 漏洞利用检查** —— sqlmap, dalfox, xsstrike, commix, tplmap, nosqlmap, ssrfmap, graphqlmap, jwt_tool, corsy, corscanner - **机密 / SCA** —— trufflehog, gitleaks, semgrep, retire, js_analysis - **TLS** —— sslyze, sslscan, testssl - **企业级 (通过 API)** —— OWASP ZAP, Nessus, OpenVAS/GVM, Burp Suite, Qualys, Acunetix, Tenable, Akto, ThreatMapper, Metasploit check ## 工作原理 ``` ┌────────────────────────────────────────────────────────────┐ │ CORVUS engine │ │ │ target ─▶ recon / fingerprint ─▶ ScanState (what we know) │ │ │ │ │ │ ▼ ▼ │ │ TECH_SIGNATURES Decision engine ── picks next ──┐│ │ (85 sigs) value = cvss·confidence·budget ││ │ / cost, gated by fingerprint ││ │ │ ││ │ ▼ ││ │ ┌──────────── module (e.g. module_sqli) ────────────┐ ││ │ │ multi-gate confirm: baseline → error/boolean/time │ ││ │ │ → encoding → context → OAST callback │ ││ │ └───────────────────────┬───────────────────────────┘ ││ │ ▼ ││ │ Finding (+CVSS v3.1, OWASP, MITRE, evidence)─┘│ │ │ │ │ ▼ │ │ JSON · HTML · CSV · SARIF · Markdown report │ └────────────────────────────────────────────────────────────┘ ``` 引擎会持续运行剩余价值最高的检查项，直到请求 预算耗尽——例如，识别出是 WordPress 的目标会优先执行 WordPress 检查， 且绝不会将预算浪费在无关的项目上。发现的结果会向 状态中反馈新任务（发现的参数会成为新的注入候选目标）。 **多级门控确认**是保持极低误报率的原因。例如，基于报错的 SQLi 必须 满足：稳定的基准 → 基准无数据库报错 → 响应与基准不同 → 出现了数据库报错特征 → 并且它不在注释内。反射型 XSS 要求原始载荷标记能够原封不动地保留下来，同时能够正确跳过 真正经过编码的输出。盲测类别则增加了真实的带外回调门控。 完整设计：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · 引擎内部原理：[`docs/ENGINE.md`](docs/ENGINE.md)。 ## 安装说明 ``` git clone https://github.com/m524security/CORVUS.git cd CORVUS pip install -r requirements.txt ``` **环境要求** - Python **3.8+** - 唯一的硬依赖是 `requests`。 - 58 个外部工具是**可选的**，仅在 `PATH` 中找到时才会使用。安装 您需要的工具（通过您的包管理器、`go install` 等），或者让 CORVUS 检测并跳过其余工具。 **可选 —— 自动安装缺失工具**（可能会运行 `sudo apt`/`gem`/`go`）： ``` python corvus.py https://target --install-tools ``` ## 使用方法 CORVUS 拥有同一个引擎和两种驱动方式——请根据您想要的控制程度进行选择： - **`corvus.py`** *（推荐）* —— **自主**执行入口。它会进行爬取、 指纹识别，并让决策引擎在预算范围内选择要运行的检查。这是大多数用户 应该使用的方式。 - **`corvus_core.py`** —— **引擎核心与经典接口**。它是一个 包含所有 100 个检测模块、CVSS 引擎和 58 种工具 集成的库，并公开了一个全手动的 CLI（多目标扫描、企业级 扫描器集成、`--resume`/`--diff`，以及所有报告格式）。当您 想要显式运行所有内容而不是让引擎做决定时，请使用它。 两者共享完全相同的模块和评分机制——`corvus.py` 是智能驱动程序， 而 `corvus_core.py` 是其下方的全手动控制台。 ### 自主引擎 — `corvus.py` ``` # 最简单的运行（safe profile） python corvus.py https://target.example.com # 选择 profile 并限制预算 python corvus.py https://target --profile safe --max-requests 800 # Aggressive profile（需要显式授权 flag） python corvus.py https://target --profile aggressive --i-have-authorization # 为 blind classes 启用 out-of-band 验证 python corvus.py https://target --oast # 限制范围，加载 plugins，写入 JSON 报告 python corvus.py https://target --scope "*.target.com" --plugins ./plugins -o report.json ``` | 参数 | 用途 | |---|---| | `--profile {passive,safe,aggressive}` | 扫描强度 (默认: `safe`) | | `--scope SCOPE` | 额外的作用域模式: `host`, `*.host`, 或 `re:REGEX` | | `--i-have-authorization` | 运行 `aggressive` 配置的必需条件 | | `--max-requests N` / `--max-seconds N` | 覆盖请求 / 时间预算 | | `--oast` | 启用带外验证监听器 | | `--oast-public` / `--oast-public-host HOST` | 针对面向互联网的目标使用公共协同服务器 | | `--plugins DIR` | 加载即插即用的插件模块 | | `--extra-tools` | 注册额外集成 (testssl/retire/gitleaks/witi/…) | | `-o, --output PATH` | JSON 报告路径 (默认: `corvus_report_.json`) | | `-q, --quiet` / `-v, --verbose` | 更安静 / 针对每个模块的详细日志记录 | ### 扫描配置 | 配置 | 行为 | |---|---| | **passive** | 非侵入式侦查与观察；最小化请求 | | **safe** *(默认)* | 平衡、对生产环境友好；保守的载荷与预算 | | **aggressive** | 广泛的载荷集、更高的并行度、更深入的爬取 —— 需要 `--i-have-authorization` | ### 带外验证 (OAST) 盲 SSRF / RCE / XXE / SSTI 只有在唯一的载荷 token 实际发生带外联系时才会产生发现： ``` # Local listener（适用于可以访问到您的内部 targets） python corvus.py https://internal.app --oast --oast-public-host 10.0.0.5 # Public collaborator（interactsh），适用于 internet-facing targets python corvus.py https://target --oast --oast-public ``` ### 经典接口 — `corvus_core.py` 功能齐全，非常适合多目标扫描和报告格式控制： ``` # 单个 URL，所有报告格式 python corvus_core.py -u https://target --format all # Target 文件，10 个线程，HTML 报告，最低严重级别为 Medium python corvus_core.py -f targets.txt --threads 10 --html --min-severity Medium # 整个子网 python corvus_core.py --cidr 10.0.0.0/24 --output-dir ./reports # 通过 proxy 进行带 cookie + 自定义 header 的已认证扫描 python corvus_core.py -u https://app \ --cookie 'session=abc123' \ --header 'Authorization: Bearer TOKEN' \ --proxy http://127.0.0.1:8080 # 恢复中断的扫描，或与之前的运行进行 diff python corvus_core.py -u https://target --resume python corvus_core.py -u https://target --diff previous_report.json ``` | 参数 | 用途 | |---|---| | `-u URL` / `-f FILE` / `--cidr CIDR` | 单个目标 / 包含目标的文件 / 子网 | | `-o` / `--output-dir` | 输出文件 / 目录 (多目标) | | `--format {json,html,csv,sarif,markdown,all}` | 报告格式 | | `--html` | 额外生成一份 HTML 报告 | | `--cookie` / `--header` | 经过身份验证的扫描 (标头可重复) | | `--min-severity {Info,Low,Medium,High,Critical}` | 过滤已报告的发现 | | `--proxy URL` | 通过代理路由流量 (例如 Burp) | | `--threads N` | 多目标的并发数 | | `--no-crawl` | 跳过爬取 | | `--resume` / `--diff FILE` | 检查点恢复 / 与之前扫描的差量对比 | | `--nmap-mode {quick,full,vuln,stealth,aggressive,udp}` | nmap 深度 | | `--install-tools` / `--no-install` | 开启 / 强制禁用工具安装 | ### 企业级扫描器集成 `corvus_core.py` 可以通过 API 从商业/企业级扫描器中拉取结果， 并将它们合并到统一的报告中： ``` python corvus_core.py -u https://target --enterprise \ --zap-url http://127.0.0.1:8080 --zap-key \ --nessus-host https://nessus:8834 --nessus-user u --nessus-pass p \ --burp-url http://127.0.0.1:1337 --burp-key ``` 支持：OWASP ZAP, Nessus, OpenVAS/GVM, Burp Suite, Qualys, Acunetix, Tenable, Akto, ThreatMapper（查看 `--help` 获取完整的参数列表）。 ### 插件 将一个 `module_(target, session)` 函数放入 `plugins/` 目录中，CORVUS 就会像加载内置模块一样 加载并调度它。模板：`plugins/example_security_txt.py`。 ``` python corvus.py https://target --plugins ./plugins ``` ## 报告生成 每一个发现——无论采用何种格式——都会包含： - `severity` 和 **CVSS v3.1** `cvss_score` + `cvss_vector` + `cvss_rating` - `owasp_id` / `owasp_name` (OWASP Top 10 2021) 和 `mitre_id` / `mitre_technique` - `title`, `description`, `recommendation`, `url`, `payload`, `cwe`, `evidence`, `confidence`, `timestamp` | 格式 | 最适合 | |---|---| | **JSON** | 管道, 机器解析 | | **HTML** | 人工审查, 分享 | | **CSV** | 电子表格, 漏洞分类筛选 | | **SARIF 2.1.0** | GitHub 代码扫描, IDE 集成 | | **Markdown** | 工单, PR 评论 | JSON 发现示例： ``` { "title": "Error-Based SQL Injection in 'id' (MySQL)", "severity": "Critical", "cvss_score": 9.1, "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N", "cvss_rating": "Critical", "owasp_id": "A03", "mitre_id": "T1190", "cwe": "CWE-89", "url": "https://target/item?id=%27", "payload": "'", "evidence": "You have an error in your SQL syntax ... MySQL", "confidence": "High" } ``` ## 测试与 CI ``` pip install -r requirements-dev.txt pytest -q # 43 tests (unit + live integration) pytest tests/integration -q # live scan vs the bundled vulnerable app ``` **覆盖范围** —— CVSS 参考向量 (对比 FIRST.org 为 11/11)，预设完整性， 发现模式 + CVSS 附加信息，纯辅助功能测试，导入/引擎冒烟测试，以及 包含真阳性与阴性对照断言的完整实时扫描套件。 CI (`.github/workflows/ci.yml`) 会对每个源文件进行字节码编译，在 **Python 3.8 / 3.10 / 3.12** 上运行整个测试套件，并在每次推送时对两个 CLI 进行冒烟测试。 ## 项目结构 ``` CORVUS/ ├─ corvus.py # primary entrypoint → autonomous decision engine ├─ corvus_core.py # engine core + classic interface: CVSS, 100 modules, 58 tools, reporters ├─ corvus/ # decision-engine package │ ├─ engine.py # expected-value scheduler + fingerprint gating │ ├─ state.py # ScanState: everything learned about a target │ ├─ oast.py # out-of-band callback listener │ ├─ profiles.py # Passive / Safe / Aggressive │ ├─ asynccore.py # throughput accelerator (optional) │ ├─ plugins.py # plugin loader │ └─ banner.py # CLI banner ├─ plugins/ # drop-in community modules │ └─ example_security_txt.py ├─ tests/ # unit + live integration suite (43 tests) │ ├─ test_cvss.py test_presets.py test_findings.py test_helpers.py test_smoke.py │ └─ integration/ # vuln_server.py + test_live_scan.py ├─ examples/ │ └─ demo_local_scan.py # runnable, no external target needed ├─ docs/ │ ├─ ARCHITECTURE.md ENGINE.md │ └─ assets/corvus-banner.svg ├─ .github/workflows/ci.yml ├─ requirements.txt requirements-dev.txt pytest.ini ├─ CHANGELOG.md CONTRIBUTING.md SECURITY_REVIEW.md LICENSE ``` ## 扩展 CORVUS ``` # plugins/my_check.py from corvus_core import make_finding, safe_get def module_my_check(target, session): findings = [] resp = safe_get(session, target) if resp is not None and "X-Powered-By" in resp.headers: findings.append(make_finding( "info_disclosure", "Server technology disclosed via X-Powered-By", "Low", "The response advertises backend technology.", "Remove or obfuscate the X-Powered-By header.", url=target, cwe="CWE-200")) return findings ``` `make_finding()` 会自动附加 CVSS、OWASP 和 MITRE 标签。使用以下命令加载 `--plugins ./plugins`。 ## 故障排除 | 症状 | 解决方案 | |---|---| | `ModuleNotFoundError: requests` | `pip install -r requirements.txt` | | 输出中提示某个工具“未找到” | 该集成是可选的 —— 安装该二进制文件或忽略 | | Aggressive 配置拒绝运行 | 添加 `--i-have-authorization` | | 针对互联网目标没有 OAST 发现 | 使用 `--oast --oast-public` (interactsh) | | 扫描太慢 / 太具攻击性 | 降低 `--max-requests` / `--max-seconds`，或使用 `--profile passive` | | 想要通过 Burp 运行 | `corvus_core.py --proxy http://127.0.0.1:8080` | ## 负责任的使用 CORVUS **仅用于授权的安全测试**。请扫描您拥有或获得 明确书面测试许可的系统。您需对保持在授权范围内及 遵守所有适用法律负责。`aggressive` 配置特意要求提供 `--i-have-authorization`。作者对滥用行为不承担任何责任。 ## 路线图 - 统一这两个入口，使引擎能够驱动所有 100 个模块（目前约有 37 个已接入） - POST / JSON 主体 / Header 注入点（目前的注入核心为 GET/查询） - 打包内置的 DVWA / Juice-Shop CI 作业，以实现更广泛的黄金目标覆盖 - 将单体应用拆分为可安装的软件包 (`corvus/…`) ## 作者与许可协议 **Manish Jaju** 基于 [MIT 许可协议](LICENSE) 发布。

_{CORVUS · 代号 NIGHT REAPER · 证据，而非猜测}

标签：API安全, CISA项目, JSON输出, OAST带外验证, Python, Web安全, 代码生成, 加密, 无后门, 渗透测试工具, 漏洞扫描器, 蓝队分析, 逆向工具