HeinHtetZaw-hub/Helios-Web-VulnScanner
GitHub: HeinHtetZaw-hub/Helios-Web-VulnScanner
由 Helios 扫描引擎驱动的开源 Web 应用 DAST 漏洞扫描平台，提供 CVSS 评分、OWASP 映射、证据级发现和多格式安全报告。
Stars: 0 | Forks: 0
# VulnScanner
vulnscanner
cd vulnscanner
cp .env.example .env
docker compose up --build
```
打开：
- 前端：http://localhost
- 通过 nginx 访问的 API 文档：http://localhost/api/v1/docs
- 后端直接 API 文档：http://localhost:8000/docs
对于本地实验目标，包括受控的 VulnScanner 实验、DVWA 和 OWASP Juice Shop：
```
cd test-targets
docker compose up --build
```
受控实验环境位于 `http://localhost:8088/`。DVWA 位于
`http://localhost:8080/`，Juice Shop 位于
`http://localhost:3000/`。
仅在授权的本地实验中设置 `APP_ENV=demo` 或 `ALLOW_PRIVATE_TARGETS=true`。
在发布前运行扫描器准确度基准测试：
```
python benchmarks/scanner_accuracy/run_benchmark.py
```
基准测试仅限本地实验环境，并且会拒绝公共目标。有关结果字段、
expected-results JSON 格式和安全使用指南，请参阅
[docs/local-benchmarks.md](docs/local-benchmarks.md)。
## Docker 设置
该仓库包含用于 FastAPI 后端和由 nginx 服务的 React 前端的 Dockerfile，以及 `docker-compose.yml`。
```
cp .env.example .env
docker compose up --build
docker compose down
```
对于强化的 PostgreSQL 生产配置，请设置 `API_KEY`、`POSTGRES_PASSWORD`、
`CORS_ALLOW_ORIGINS` 和 `TRUSTED_HOSTS`，然后运行：
```
docker compose -f docker-compose.yml -f docker-compose.production.yml up --build -d
```
生产环境的运行应使用：
```
APP_ENV=production
SAFE_MODE=true
API_KEY_ENABLED=true
API_KEY_REQUIRED_IN_PRODUCTION=true
ALLOW_PRIVATE_TARGETS=false
ALLOW_DESTRUCTIVE_TESTS=false
```
### 生产环境控制
- `POST /api/v1/scans/{scan_id}/pause`、`/resume` 和 `/cancel` 用于控制持久的扫描任务。
- `GET /api/v1/scan-jobs/queue/status` 用于报告 worker、活动、待处理和暂停的任务计数。
- 失败的尝试会在 `SCAN_JOB_MAX_ATTEMPTS` 范围内重试；整个尝试会在 `SCAN_JOB_TIMEOUT_SECONDS` 时停止。
- 证据将在 `EVIDENCE_RETENTION_DAYS` 后过期；管理员可以触发 `POST /api/v1/evidence/purge-expired`。
- 扫描启动、暂停、恢复、取消、导出、删除和保留期清除操作都将写入审计日志。
- 原始 Cookie、密码、Bearer token、API 密钥、会话 ID 和包含凭据的 URL 在持久化之前会被脱敏处理。
## 手动开发设置
后端：
```
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pytest
uvicorn app.main:app --reload --port 8000
```
前端：
```
cd frontend
npm ci
npm run build
npm run dev
```
## CLI 模式
后端包提供本地和 CI/CD 扫描功能：
```
cd backend
python -m app.cli passive-scan --target https://app.example --authorized --scope-domain app.example --format json --output vulnscanner-report.json
```
有关命令、退出代码、CI 失败规则以及 GitHub Actions/GitLab CI 示例，请参阅 [docs/cli.md](docs/cli.md)。
## 扫描器模块
- SQL 注入：基于错误、基于布尔和基于时间的检查。
- 反射型 XSS：反射型 payload 和上下文检查。
- 存储型 XSS：表单提交和后续反射检查。
- DOM XSS：基于 Selenium 的浏览器检查。
- 访问控制失效：IDOR 和 SSRF 类型的检查。
- 安全配置错误：缺失的 header 和暴露的敏感文件。
- 敏感数据暴露：凭据、密钥、token、内部标识符和 PEM 指示符。
- 本地文件包含：目录遍历和 wrapper 类型的 payload 检查。
- 操作系统命令注入：命令分隔符和时间检查。
- API 优先扫描：OpenAPI 路径/查询/header/body 覆盖、安全的 JSON 变异、JWT 安全态势、CORS、批量分配 canary、有界的速率限制探测、GraphQL 发现和双账户 BOLA 检查。
未经过测试、文档记录、安全模式审查和证据质量审查，不得添加任何新模块。
### YAML 检测模板
选择启用的 template_scanner 模块，以运行位于
backend/app/scanner/template_packs/starter 中经过验证的入门包。模板支持请求方法、路径、
header、body 和 payload 变量；支持状态、header、body-regex、word 和安全的 DSL
匹配器；有界的 regex 提取器；安全性和扫描模式要求；以及 CWE、OWASP
Top 10:2025、CVSS v3.1 和修复元数据。
模板通过 yaml.safe_load 加载，并受到大小/数量限制、严格的字段验证
以及原始密钥拒绝的限制。每个渲染后的请求仍然会经过扫描器的
同源范围守卫、共享速率限制器、请求预算、超时、扫描模式策略、
CSRF 处理和证据脱敏。POST 模板需要处于 authenticated-active 或
lab 模式，并且需要明确的更改状态请求权限。该模块被排除在
默认和计划扫描选择之外。
## 身份验证支持
VulnScanner 支持基于 Cookie 的经过身份验证的扫描。一次性扫描 Cookie 会在内存中传递给扫描引擎，不应存储在报告、日志或数据库行中。实验室工作流支持基于 DVWA 凭据的登录。
在 `authenticated_active` 模式下支持授权的双账户访问控制测试。
账户 A 和账户 B 可以使用存储的身份验证配置或临时的浏览器会话导入；扫描器会比较针对 IDOR/BOLA、功能级授权失效、角色绕过和权限混淆的受限只读对象和功能访问。
可选的数字对象 ID 变异是单独启用的，经过范围检查，是只读的，有速率限制，并且最多限制为十次变异。
报告会记录确切的访问账户/角色、预期账户/角色、对象和操作，同时对身份验证材料进行脱敏。
API 导入可以作为 OpenAPI JSON/YAML、GraphQL schema/内省数据、HAR 或 Postman 集合提供。默认情况下可进行被动 API 检查；更改状态的 JSON 探测和 GraphQL 内省需要明确的策略许可。API 覆盖范围和发现结果包含在 JSON 和 PDF 报告中，但不会持久化导入的规范、JWT、身份验证 header 或机密 URL 值。
可选的带外回调扫描仅在 `oob_enabled=true`、选择了 `oob_scanner` 模块并且扫描模式为 `authenticated_active` 或 `lab_aggressive` 时可用。回调接收器保持在 `/api/v1/oob/c/{token}` 下，使用唯一的 canary token，仅存储经过清理的回调元数据，并报告回调类型、时间戳、来源、受影响的请求和 token，而不会持久化回调 header、body、Cookie、Bearer token、密码、API 密钥或会话机密。
默认情况下，存储的身份验证配置不会持久化原始 Cookie、Bearer token、API 密钥、密码、JWT、会话 ID 或记录的登录机密。新的配置会存储环境变量引用，例如 `VULNSCANNER_AUTH_PROFILE__BEARER_TOKEN`，扫描器会在扫描时读取这些值。`raw_secret_storage` / `ALLOW_RAW_AUTH_PROFILE_SECRET_STORAGE` 兼容路径是不安全的，已被弃用，在生产环境中必须保持禁用状态。
登录表单的机密字段可以使用 `login_form_fields_env` 引用；在类似机密的表单字段中提交的原始密码/token/会话值默认会被转换为环境变量引用。
请参阅 [docs/authenticated-scans.md](docs/authenticated-scans.md)。
## 报告格式
- JSON：结构化的扫描和发现结果导出，包含分组的证据、经过清理的复现 cURL、重测历史以及 OWASP WSTG/ASVS 5.0.0 映射。
- CSV：包含 52 列，通过 UTF-8 BOM 支持电子表格，包括 WSTG/ASVS 参考、Baseline Request、Attack Request、response-diff 摘要、置信度原因、证明类别、人工审查分类、经过身份验证/未经身份验证的探测上下文、PR:N 支持、重放命令、访问控制上下文以及经过清理的 Evidence Request 和 Evidence Response 字段。
- PDF：面向利益相关者的报告，包含单独的可报告、人工验证和信息部分，以及 CVSS、CWE、OWASP、WSTG、ASVS、影响和修复建议。
- SARIF 2.1.0：与 GitHub/代码扫描兼容的安全结果，具有稳定的指纹和标准映射。
- CI JSON 和 JUnit XML：经过清理的流水线结果，具有生命周期感知的失败/跳过计数。支持可选的严重程度和置信度查询过滤器。
- 报告将 Report Findings 用于分组的面向用户的发现结果，将 Raw Detector Results 用于未分组的检测器输出。
## 发现生命周期和重测
发现结果支持运行生命周期状态：open、fixed、accepted_risk、false_positive 和 retest_required，并保留额外的现有审查状态以保持兼容性。质量更改和重放记录在重测历史中，不存储会话机密。
使用 POST /api/v1/scans/retest-compare 以及已完成的基线扫描和新扫描 ID 来分类已修复、新发现和未更改的发现结果。仅在比较应持久化基线转换时才设置 apply_lifecycle=true：缺失的发现结果变为 fixed，而仍然存在的发现结果变为 retest_required。
### 证据质量和证明类别
每个主动扫描器的发现结果都包含经过清理的基线请求、攻击请求、基线信号、攻击信号、response-diff 摘要、payload、置信度原因和重放命令。当检测器无法建立可靠的差异性时，该发现结果将被保留供分析师审查，而不是提升为已确认的风险。
证明类别包括 `confirmed_exploit`、`strong_evidence`、`needs_manual_verification`、`informational` 和 `likely_false_positive`。仅有标记的反射型 XSS 仍然是需要人工验证的线索，而缺失的 header 和 `security.txt` 观察结果仍然属于信息性质，除非证明了其存在可被利用的影响。
请参阅 [docs/reporting.md](docs/reporting.md)。
## 安全模式
安全模式默认启用，旨在减少更改状态的行为。仅对您拥有的资产、私有实验目标或具有明确书面授权的目标使用 VulnScanner。在开始任何主动扫描或 Fuzzer 运行之前，请保留关于范围、允许的主机、排除的路径/参数、速率限制、联系详细信息和测试窗口的书面记录。
Fuzzer 会在插入 payload 后验证每个最终出站 URL。Payload 在 URL、header、表单和 JSON 上下文中进行编码，并且不能更改目标协议、主机名、端口或范围。在遵循重定向之前会重新进行检查。
公共和生产环境的使用应保持：
```
SAFE_MODE=true
ALLOW_FILE_UPLOAD_TESTS=false
ALLOW_ACTIVE_SSRF=false
ALLOW_DESTRUCTIVE_TESTS=false
ALLOW_PRIVATE_TARGETS=false
```
本地演示模式可以允许 DVWA 和 Juice Shop 的私有目标：
```
APP_ENV=demo
ALLOW_PRIVATE_TARGETS_IN_DEMO=true
```
请参阅 [docs/scanning-policy.md](docs/scanning-policy.md)。
## 真实场景扫描配置
可重用的扫描配置可用于生产安全的深度扫描、暂存环境的身份验证扫描、DevSecOps PR 检查、紫队检测验证、红队授权验证、高管风险快照和本地 lab-aggressive 测试。配置目录由 `GET /api/v1/scan-policies` 返回，每个配置都记录了其强度、环境、速率限制、证据级别、导出、权限和安全边界。
在创建扫描时使用 `policy_slug`，例如 `production_safe_deep` 或 `devsecops_pr_scan`。通过省略 `policy_slug` 并传递模块/爬虫覆盖配置，自定义扫描配置仍然有效。
## 团队工作流验证
在发布前验证蓝队、红队、队、DevSecOps 以及高管/GRC 的工作流：
```
python scripts/team_workflow_validation.py --fail-on-error
```
请参阅 [docs/team-workflow-validation.md](docs/team-workflow-validation.md)。
## Bug Bounty 安全模式
Bug Bounty 安全模式是一个用于明确授权的
项目测试的保守配置。它要求在扫描前配置范围，使用默认为
每秒 1 个请求的速率限制，禁用破坏性测试，设置明确的
`VulnScanner/1.0 BugBountySafe contact=` 用户代理，并将
可报告的发现结果与扫描器的线索分开。
安全模式分类包括可报告、需要人工验证、
不可报告/安全加固、极有可能是误报以及超出范围。未经
人工验证，不应提交临时发现结果，建议的 P 级别评级仅
作为指导。
请参阅 [docs/bug-bounty-safe-mode.md](docs/bug-bounty-safe-mode.md)、
[docs/scope-manager.md](docs/scope-manager.md)、
[docs/reportable-findings.md](docs/reportable-findings.md)、
[docs/bug-bounty-report-export.md](docs/bug-bounty-report-export.md) 和
[docs/false-positive-control.md](docs/false-positive-control.md)。
## 配置
将 `.env.example` 复制到 `.env` 并调整值。重要选项：
| 变量 | 安全默认值 | 用途 |
| --- | --- | --- |
| `APP_ENV` | `development` | `development`、`demo` 或 `production` |
| `SAFE_MODE` | `true` | 保持禁用破坏性操作 |
| `API_KEY_ENABLED` | `.env.example` 中为 `true` | 要求 `X-API-Key` 或 `?api_key=` |
| `API_KEY_REQUIRED_IN_PRODUCTION` | `true` | 生产环境身份验证守卫 |
| `AUTH_PROFILE_ENV_PREFIX` | `VULNSCANNER_AUTH_PROFILE` | 基于环境变量的身份验证配置机密的前缀 |
| `ALLOW_RAW_AUTH_PROFILE_SECRET_STORAGE` | `false` | 用于存储原始身份验证机密的不安全/已弃用的兼容开关；在生产环境中必须保持为 false |
| `CORS_ALLOW_ORIGINS` | 开发环境为 `*` | 逗号分隔的允许 UI 来源；在生产环境中必须明确指定 |
| `TRUSTED_HOSTS` | 开发环境为 `*` | 逗号分隔的允许主机标头；在生产环境中必须明确指定 |
| `API_DOCS_ENABLED` | 自动 | 在非生产环境默认开启，在生产环境默认关闭 |
| `SECURITY_HEADERS_ENABLED` | `true` | 添加防御性 API 响应标头 |
| `MAX_REQUEST_BODY_BYTES` | `10485760` | 根据 `Content-Length` 拒绝过大的请求体 |
| `ALLOW_PRIVATE_TARGETS` | `false` | 阻止私有/内部目标范围 |
| `ALLOW_PRIVATE_TARGETS_IN_DEMO` | `true` | 当 `APP_ENV=demo` 时允许私有目标 |
| `ALLOW_DESTRUCTIVE_TESTS` | `false` | 为破坏性测试预留的明确启用选项 |
| `DATABASE_URL` | SQLite | 异步 SQLAlchemy 数据库 URL |
| `GLOBAL_RATE_LIMIT_RPS` | `10` | 所有扫描中进程范围内的出站请求上限 |
| `GLOBAL_PER_TARGET_CONCURRENCY` | `1` | 每个目标来源允许的并发请求/扫描数 |
| `SCAN_WORKER_CONCURRENCY` | `1` | 有界的后台扫描 worker 数量 |
| `SCAN_JOB_MAX_ATTEMPTS` | `2` | 失败或超时任务的最大尝试次数 |
| `SCAN_JOB_TIMEOUT_SECONDS` | `3600` | 整体扫描尝试的超时时间 |
| `EVIDENCE_RETENTION_DAYS` | `90` | 自动证据过期策略 |
| `REPORTS_DIR` | `./reports` | 本地报告输出目录 |
请参阅 [docs/configuration.md](docs/configuration.md)。
## API 使用示例
```
curl -X POST http://localhost:8000/api/v1/scans \
-H "Content-Type: application/json" \
-H "X-API-Key: change-this-dev-key-before-production" \
-d '{
"target_url": "http://localhost:8080/DVWA/",
"authorisation_confirmed": true,
"config": {
"modules": ["sqli", "xss_reflected", "misconfig"],
"crawl_depth": 2
}
}'
```
下载报告：
```
curl -H "X-API-Key: change-this-dev-key-before-production" \
-o report.json \
http://localhost:8000/api/v1/scans//report/json
```
## 文档
- [安装](docs/installation.md)
- [配置](docs/configuration.md)
- [扫描策略](docs/scanning-policy.md)
- [身份验证扫描](docs/authenticated-scans.md)
- [检测模块](docs/detection-modules.md)
- [报告](docs/reporting.md)
- [演示实验环境](docs/demo-lab.md)
- [API 参考](docs/api-reference.md)
- [开发](docs/development.md)
- [路线图](docs/roadmap.md)
## 路线图
- v0.1：专业版本准备、安全默认设置、文档、CI、模板。
- v0.2：Docker 和 CI 强化、lint 清理、截图示例。
- v0.3：检测模块扩展 API。
- v0.4：技术指纹识别扩展。
- v0.5：API 扫描支持。
- v1.0：具有文档兼容性保证的稳定公开版本。
## 许可证
MIT 许可证。请参阅 [LICENSE](LICENSE)。
## 免责声明
VulnScanner 仅用于授权的安全测试、学习和防御性评估。在扫描任何目标之前，您有责任获得许可。对于因使用此软件而导致的误用、损害、中断、法律问题或策略违规，作者不承担任何责任。
标签：AV绕过, CISA项目, DAST, DOE合作, FastAPI, React, Syscalls, Web安全, 恶意软件分析, 测试用例, 蓝队分析, 请求拦截, 逆向工具