bastian-red/webaudit

# webaudit 一个基础的 Web 安全审计工具：对目标进行爬取，运行映射至 OWASP 的检查（安全标头、cookie 标志、HTTPS/混合内容、版本泄露，以及对暴露的敏感文件进行可选的主动探测），并生成按严重程度排名的报告，支持输出为文本、JSON 或独立的 HTML 页面。 ## 截图 由 `webaudit scan` 针对内置演示应用（`samples/vulnerable_app.py`）生成的 HTML 报告，展示了在所有五个检查类别中发现的所有植入问题，并带有按严重程度标记颜色的行：  ## 功能 - **爬虫**：有界的、同源、广度优先爬取（`requests` + `BeautifulSoup`），默认感知 robots.txt，通过 `--max-pages`/`--max-depth` 进行限制，因此在无需监督的情况下运行也是安全的。 - **标头检查**：HSTS、CSP、X-Frame-Options（或 CSP `frame-ancestors`）、X-Content-Type-Options、Referrer-Policy、Permissions-Policy。 - **Cookie 检查**：Secure、HttpOnly、SameSite（包括 `SameSite=None` 必须包含 `Secure` 的边缘情况），并且对于类似 session/auth 的 cookie 名称会赋予更高的严重级别。 - **表单/传输检查**：HTTP 方案的表单 action（尤其是带有密码字段的表单）、通过纯 HTTP 提供的页面，以及 HTTPS 页面上的混合活动内容。 - **暴露检查**：`Server`/`X-Powered-By` 标头中的版本字符串、`` 标签，以及类似版本号的 HTML 注释。 - **主动路径探测**（可选，仅限实验环境）：检查常见暴露路径（`.git/HEAD`、`.git/config`、`.env`、备份文件、`.htpasswd`、私钥等）的真实非 soft-404 响应。 - **报告**：文本（适合 CLI 阅读）、JSON（机器可读），以及带有严重程度颜色编码的独立 HTML 页面 —— 从扫描站点提取的每个值在渲染前都会进行 HTML 转义，因此带有恶意的目标无法对报告本身进行存储型 XSS。 - **CI 门禁**：`--fail-on ` 会在存在任何达到或超过该严重级别的发现时以非零状态退出。 ## 架构 ``` webaudit/ |-- core/ models.py: Severity, Finding, PageResult, AuditConfig, AuditReport |-- crawler/ crawl.py: bounded same-origin BFS crawl, robots.txt aware |-- checks/ headers.py, cookies.py, forms.py, exposure.py -- one check(page) per category |-- offensive/ guard.py (lab-target restriction) + path_probe.py (active sensitive-path probe) |-- report/ generator.py: dedupe + sort + render as text / json / html |-- evals/ corpus.py (seeded synthetic PageResult corpus) + run_checks.py (precision/recall gate) |-- samples/ vulnerable_app.py: tiny deliberately-insecure Flask app used as a demo/test target |-- tests/ pytest suite, incl. one real end-to-end scan against samples/vulnerable_app.py |-- webaudit.py engine assembly: build_config() + the WebAuditor class `-- cli.py argparse CLI (`scan` subcommand) ``` 数据流：`crawler/crawl.py` 为每个爬取的页面生成一个 `PageResult` -> `checks/` 中的每个函数都会针对它运行（如果设置了 `--active-probes` 且守卫条件允许，还会运行 `offensive/path_probe.py`）-> 累积的 `Finding` 会被去重、按严重程度排序，并由 `report/generator.py` 渲染。`cli.py` 和测试套件都导入 `webaudit.py`，因此只有唯一的一个引擎实现。 ## 安装说明 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements-dev.txt scripts/install-hooks.sh # one-time: wires the gitleaks + pytest pre-commit gate ``` ## 用法 在一个终端中启动内置的演示目标（一个微型的、故意设计为不安全的 Flask 应用）： ``` python samples/vulnerable_app.py ``` 在另一个终端中扫描它： ``` # 输出至 stdout 的易读报告 python cli.py scan http://127.0.0.1:5000 # 包含 active path probing 的完整扫描，以 HTML report 形式写入 python cli.py scan http://127.0.0.1:5000 \ --active-probes --format html --output reports/demo.html # CI 风格的门禁：如果发现任何 HIGH 或以上级别的问题则 exit 1 python cli.py scan http://127.0.0.1:5000 --fail-on high ``` ``` usage: webaudit scan [-h] [--max-pages MAX_PAGES] [--max-depth MAX_DEPTH] [--timeout TIMEOUT] [--user-agent USER_AGENT] [--no-robots] [--active-probes] [--i-understand-lab] [--format {text,json,html}] [--output OUTPUT] [--fail-on {critical,high,medium,low,info}] [--verbose] url ``` 扫描 localhost/私有 IP/或 `.local`-`.test`-`.internal`-`.lab` 主机名之外的任何内容，需要使用 `--i-understand-lab`；仅扫描您拥有或获得明确授权测试的系统。 ## OWASP Top 10 (2021) 映射 | 检查模块 | 类别 | OWASP 参考 | |--------------------------|-------------|-----------------------------------------------------------| | `checks/headers.py` | headers | A05:2021 - Security Misconfiguration | | `checks/cookies.py` | cookies | A05:2021 / A07:2021 - Security Misconfiguration / Auth Failures | | `checks/forms.py` | forms | A02:2021 - Cryptographic Failures | | `checks/exposure.py` | exposure | A06:2021 - Vulnerable and Outdated Components | | `offensive/path_probe.py`| offensive | A05:2021 / A01:2021 - Security Misconfiguration / Broken Access Control | 严重程度等级：**critical**（暴露的密钥、`.git`、`.env`），**high**（HTTPS 站点缺少 HSTS、不安全的 session cookie、混合内容或 HTTP 表单 action），**medium**（缺少 CSP/X-Frame-Options），**low**（缺少 Referrer-Policy/SameSite），**info**（版本泄露）。 ## 测试与评估 ``` pytest -q # gate tests: 82 cases, <1s, fully offline (responses-mocked HTTP) python -m evals.run_checks # periodic eval: precision/recall gate per check category ``` 门禁测试套件涵盖了独立状态下的每个检查模块、爬虫（同源边界、`max_pages`/`max_depth`、robots.txt、多 cookie 响应）、实验环境目标守卫（IP 范围、TLD、DNS 解析边缘情况）、主动路径探测（包括 soft-404 检测）、报告渲染器（包括一项证明恶意目标无法对生成的报告进行存储型 XSS 的 HTML 转义测试）、CLI，以及一个真正的端到端测试，该测试会在临时的 localhost 端口启动 `samples/vulnerable_app.py`，并断言整个流水线能找出所有植入的问题。 `evals/run_checks.py` 会对一个预设的安全/不安全 `PageResult` 合成语料库（`evals/corpus.py`）运行每个检查模块，包括对抗性边缘情况（HSTS `max-age=0`、继承页面协议的相对表单 action、带/不带 `Secure` 的 `SameSite=None`），并要求每个类别的精确率/召回率 >= 0.98。每个用例的结果都会写入 `evals/corpus/dataset.jsonl`。 ## 这展示了什么 具体应用的 OWASP Top 10 知识（标头/cookie/传输/暴露层面的错误配置，映射到具体的 2021 类别），Web 抓取与同源爬虫，用于安全界定主动侦察的实验环境守卫模式，在显示不受信任第三方内容的报告渲染器中的输出编码规范，以及用于对基于规则的检测器进行回归测试的合成语料库评估方法论。

标签：Python, Splunk, Web安全, 主机安全, 安全规则引擎, 密码管理, 无后门, 蓝队分析, 逆向工具