raccioly/websec-validator

# websec-validator 它不是一个自主扫描器，也不是一个SaaS。它是缺失的前半部分：将仓库转换成一个精确、事实为基础的安全简报的东西，一个AI代理（带有人工智能）可以采取行动——一个自动填充、仓库感知的高级渗透测试员的“这里是要测试什么以及如何测试”的交接版本。它的工作原理以及每个检查背后的推理：[`docs/METHODOLOGY.md`](docs/METHODOLOGY.md). ## 快速入门——只需将其指向您的仓库 **最简单：告诉您的AI代理。** 在Claude Code（或任何编码代理）中，打开您的项目并说： 它安装、运行，并带您查看结果。没有要托管的内容和网站——它是本地的。到达那里的四种方式，都以您的代理采取行动的相同`AGENT-BRIEFING.md`结束： | 路径 | 单次设置 | 然后 | |---|---|---| | **告诉您的代理**（最简单） | — | 说上面的行 | | **CLI**（终端） | `pipx install websec-validator` | `websec run /path/to/your/app` | | **Claude Code插件**（斜杠） | `/plugin marketplace add raccioly/websec-validator` → `/plugin install websec-validator@websec-plugins` | 调用**security-pass**技能，或者只是询问 | | **Docker**（无需安装） | `docker build -t websec-validator .` | `docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/scan" websec-validator run /scan --out /scan/websec-out` | ➡️ **想要了解每个检查背后的推理吗？** 阅读文档**[docs/METHODOLOGY.md](docs/METHODOLOGY.md)**——每个测试做什么以及为什么。 ## 安装 ``` pipx install websec-validator # from PyPI brew install noir # OWASP Noir — the route engine (50+ frameworks); regex fallback if absent websec --version ``` _直到第一个PyPI发布（或对于边缘版本），直接从源安装：_ `pipx install git+https://github.com/raccioly/websec-validator`（或从克隆版：`pipx install .`）。 需要**Python 3.11+**（在标准macOS上，`python3`通常是3.9——使用`pipx`，它选择一个较新的解释器，或者通过Homebrew/pyenv安装）。零Python运行时依赖：它将shell输出到扫描器（Trivy、Gitleaks、Semgrep/OpenGrep、Checkov、Prowler）和Noir（当存在时），报告缺少的内容，并且如果工具不存在，永远不会硬失败。 ### 或者通过Docker运行（所有内容捆绑，零安装） 无需安装Noir或任何扫描器——镜像捆绑了所有内容（架构感知，amd64 + arm64）： ``` docker build -t websec-validator . docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/scan" websec-validator run /scan --out /scan/websec-out ``` 该镜像包含Noir + Trivy + Gitleaks + Semgrep + Checkov；将您的仓库挂载到`/scan`，并将生成的工件放在`/scan/websec-out`。 ## 使用 ``` websec run ./my-app # ← the one command: recon + stage tailored probes + emit the briefing websec ./my-app # same thing — a bare path defaults to `run` websec run ./my-app --scan # …and also execute the available static scanners websec doctor ./my-app # (optional) which scanners are installed? ``` 然后让您的代理指向输出：**“阅读`websec-out/AGENT-BRIEFING.md`并按照它执行。”** ## 它提取的内容（11个确定性的提取器，没有LLM） | | 维度 | 显著输出 | |---|---|---| | stack | 语言、框架、数据存储 | 单一仓库感知（聚合每个清单） | | routes | 通过**OWASP Noir**的每个端点 | 方法 · 路径 · 类型参数 · 代码路径 | | auth | 方案 + 登录表面 | 多方案（主要jwt > passport），PyJWT/NextAuth/session感知 | | **authz** | 访问控制映射 | 守卫覆盖率 + **没有可见守卫的写入端点** + 角色 | | tenant | 多租户关键候选者 | BOLA边界，按频率 | | surface | 12个用户输入门控的接收器类 | SSRF/SQLi/NoSQLi/遍历/SSTI/重定向/反序列化/XXE/协议污染/ReDoS/命令/评估 | | schemas | 数据模型 + **特权字段** | Pydantic/SQLAlchemy/Django/Prisma/Mongoose/TypeORM/Zod → `role`/`isAdmin`/`groupId`用于批量分配目标 | | iac_ci | IaC + CI/CD | GitHub Actions注入，未固定操作，Dockerfile-root，tfstate | | client_exposure | 浏览器泄漏 | `NEXT_PUBLIC_*`机密，服务器秘密在客户端，源映射 | | graphql | GraphQL表面 | 内省/游乐场/缺少深度限制 | | integrations | 第三方 + Webhook | Webhook缺少签名验证 | 此外，还有**派生目标**——IDOR / SSRF / 开放重定向 / 上传 / 写入 / 认证端点候选者——因此探测器会指向*精确*的端点，而不是盲目地发射。 ## 您获得的内容（`websec-out/`） | 工件 | 它是什么 | |---|---| | `AGENT-BRIEFING.md` | **产品。** 行军命令：检测到的表面、访问控制映射、目标、发现、方法和分阶段探测器列表。 | | `FACTS.json` | 完整的结构化重建。 | | `findings.json` | 静态扫描器结果，**跨工具去重**和按严重程度排序（使用`--scan`）。 | | `findings-ledger.json` / `REPORT.md` | 可追踪的账本：每个发现都有一个证据链、CWE/ASVS/OWASP-API引用、修复方案和**校准的`P(real)`**（实际漏洞率 + 95% CI + 样本大小）。 | | `probes/` | 为*此*应用程序选择的探测器脚本和分阶段。 | ## 流程 ``` 🔧 websec (deterministic) 🤖 your agent + 🧑 you ───────────────────────────────── ───────────────────────────────── 1. recon → full attack surface → confirm the tenant boundary + auth model 2. run + de-dup static scanners → triage real-vs-noise 3. stage tailored probes → fill placeholders, run vs a TEST instance 4. emit AGENT-BRIEFING.md → propose fixes, re-run to confirm, report back ``` 静态重建和简报只需要**代码**。*运行*探测器需要实时测试实例+测试凭据（人类提供）——工具本身永远不会接触运行中的应用程序。 ## 证明工具 `websec proof`克隆了一个漏洞应用程序语料库（VAmPI、NodeGoat、DVGA）并评分是否重建表面每个应用程序的文档化攻击表面——一个确定性的、CI可追踪的代理（目前**10/10**）。 真正的杀手标准（简报是否提高了代理的漏洞发现能力与通用提示相比？）是手动A/B测试在[`corpus/PROOF-PROTOCOL.md`](corpus/PROOF-PROTOCOL.md). ## 校准信心 `websec calibrate`将账本与标记的语料库进行对比，衡量每个*(攻击类，置信度)*桶是**真实**的文档化漏洞的频率，并写入`calibration.json`（随软件分发并在运行时应用）。每个发现都携带`P(real)`以及**95% Wilson置信区间**和样本大小`n`——因此“中等”不再是感觉，而是“在语料库中大约57%的时间（CI 43–70%，n=51）”。与没有文档化的漏洞匹配的发现被视为假阳性（语料库是经过良好记录的）。**诚实的警告：**语料库是*故意有漏洞的*，因此对于干净的生成代码，这些比率是**乐观的**，并且小样本意味着**宽区间**——CI是头条新闻，而不是点估计，并且随着语料库的增长而缩小。在数据稀薄的情况下，桶会回退到每个标签的聚合，然后到明显标记的未校准先验。没有机器学习，没有依赖——二项比例 + Wilson区间；如果存在大量标记的集合，结构会升级到等调回归。 **它会自我改进。** `websec dynamic`是一个*先知*：未经身份验证执行的写入是已确认的真实漏洞，并且被重建标记的端点最终是受认证的，是已确认的假阳性。每次动态运行都会将这些已确认的标签折叠到一个**本地覆盖层**（`~/.cache/websec-validator/`，git忽略，从未分发）中，该覆盖层合并到公共表中——因此随着您运行它的次数越多，数字**个性化到您的应用程序**，无需额外步骤，也没有东西离开您的机器。要手动标记，请将一个`{attack_class, confidence, is_real}`文件提供给`websec calibrate --ingest`. ## 动态阶段（v2——目前为只读） 当您有一个*运行中的测试实例*时，`websec dynamic`会发行角色令牌并运行静态重建指向的探测器。v1是**只读的**：在组作用域的GET端点上重建的认证**跨租户BOLA**。 ``` cp dynamic-config.example.json dynamic-config.json # TEST target + role creds (gitignored) websec run ./my-app # static recon → websec-out/FACTS.json websec dynamic --config dynamic-config.json --facts websec-out/FACTS.json # → "14/14 cross-tenant GET reads blocked — all isolated" (or 🚨 LEAK with the exact endpoint) ``` 永远不要指向生产环境。写入动词BOLA、JWT/auth攻击和ZAP/Nuclei双角色差异是下一个动态探测器（明确门控——它们会更改）。 ## 验证 一个生产Next.js应用程序、一个大型Express/AWS单仓库，以及VAmPI / NodeGoat / DVGA漏洞应用程序语料库——独立地重现了手动渗透测试的结果（租户边界、SSRF、文件上传、跨租户BOLA、角色/authz差距）。 ## 测试 ``` python3 -m unittest discover -s tests # stdlib only, no Noir/network — 23 tests ``` ## 发布（维护者） 通过**受信任发布**（OIDC）发布到PyPI。要发布： ``` # 1. bump the version in pyproject.toml (e.g. 0.2.1 → 0.2.2) # 2. tag it and push — the tag must match pyproject's version (CI verifies): git tag v0.2.2 && git push origin v0.2.2 # → publish.yml builds, INSTALLS + smoke-tests the wheel (version match, # calibration ships, a real `websec run`), then publishes. A bad build fails # CI instead of reaching PyPI — so you never have to yank after the fact. ``` 一次性PyPI设置（在第一次发布之前）：在pypi.org → **Account → Publishing → Add a pending publisher** with project `websec-validator`，owner `raccioly`，repo `websec-validator`，workflow `publish.yml`，environment `pypi`。项目在第一次成功发布时创建。 ## 状态/路线图 **完成：** 11个提取器重建（包括schema/entity → 批量分配目标）、跨工具去重、定制探测器分阶段、代理简报、可追踪的发现账本带有**校准的信心（CJE — Wilson CI）**、证明工具、测试套件、**Docker捆绑**（所有扫描器 + Noir，架构感知）、**动态阶段v1**（认证的只读跨租户BOLA——现场验证，重现了手动渗透测试的14/14）。 **下一个：** 动态写入动词BOLA + JWT/auth探测器 + ZAP/Nuclei双角色差异（门控，它们会更改）、在手动标记的真实仓库上进行校准（更具代表性的基础率）、ASVS索引查找、可选的模型-SDK适配器以备无代理回退。 ## 将其用作Claude Code技能/插件 此仓库**是**一个Claude Code插件。安装一次— ``` /plugin marketplace add raccioly/websec-validator /plugin install websec-validator@websec-plugins ``` —并捆绑的**security-pass**技能（[`skills/security-pass/SKILL.md`](skills/security-pass/SKILL.md）） 让您只需用普通英语请求安全通行证：它运行`websec`，阅读简报，并与您一起处理发现。对于其他代理，通用接口保持不变：运行CLI，阅读`AGENT-BRIEFING.md`. **安装注意事项（经过现场测试）：** - 安装ID是`plugin@marketplace`——`websec-validator@websec-plugins`（市场名称来自`.claude-plugin/marketplace.json`），**不是**`@websec-validator`（仓库）。 - 插件只提供*说明*；实际的扫描是一个**单独的Python CLI**（`websec`）。技能的步骤0会安装它（`pipx install websec-validator`），如果它缺失的话。 - **`/plugin …`仅在终端CLI中工作。** 在Claude **应用程序/代理SDK**（没有`/plugin`），在`.claude/settings.json`中配置它代替： { "extraKnownMarketplaces": { "websec-plugins": { "source": { "source": "github", "repo": "raccioly/websec-validator" } } }, "enabledPlugins": { "websec-validator@websec-plugins": true } } 这**注册并启用**了插件，但**不会**自动获取它——第一次下载仍然需要CLI（`/plugin install websec-validator@websec-plugins`）一次。（团队的项目`.claude/settings.json`；仅您的`~/.claude/settings.json`）。 ## 致谢 方法和探测器库是从真实的认证渗透测试中提炼出来的。这个工具将手写的方法定制成一个AI代理可以在任何仓库上运行的工具产品。

标签：AI辅助安全, DNS解析, Docker, Python, Web安全, 代码安全, 代码审计工具, 反取证, 安全扫描工具, 安全报告, 安全方法论, 安全漏洞检测, 安全评估, 安全防御评估, 开源项目, 无后门, 本地安全检测, 漏洞枚举, 网络安全, 蓝队分析, 请求拦截, 逆向工具, 隐私保护