更新: 77 个文件 - 2026-03-17 00:30:01

2026-03-17 00:30:01 -07:00
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,19 @@
+# 项目文档总览
+
+> `LAB ONLY` | `AUTHORIZED TARGETS ONLY` | `NOT A PRODUCTION BASELINE`
+
+本目录汇总本项目的功能说明、数据面说明和前端展示设计，服务于两个目标：
+
+- 让仓库使用者快速理解“项目做什么、怎么跑、哪些能力已经落地”。
+- 让本地 dashboard 的展示、交互、日志查看、折叠/展开和实时刷新有明确设计准则，不再只是临时页面。
+
+## 文档入口
+
+- [项目功能与特性总览](/Users/x/websafe/docs/project-features.md)
+- [本地前端工作台设计文档](/Users/x/websafe/docs/frontend-dashboard-design.md)
+
+## 文档边界
+
+- 仅描述 `lab-local`、`lab-public`、`authorized-third-party` 三类授权目标下的功能与前端展示。
+- 不把本仓库内容包装成生产安全最佳实践，也不为未授权互联网资产提供工作流语境。
+- 页面中出现的利用、注入、日志、失败原因、源头链接和思路说明，均应绑定到授权实验或自有测试资产。
--- a/docs/frontend-dashboard-design.md
+++ b/docs/frontend-dashboard-design.md
@@ -0,0 +1,309 @@
+# 本地前端工作台设计文档
+
+> `LAB ONLY` | `AUTHORIZED TARGETS ONLY`
+
+## 1. 设计目标
+
+本地 dashboard 要从“简单索引页”升级成“完整的授权攻防实证工作台”。它需要同时满足三类使用场景：
+
+1. 运行中观察
+   - 看当前 run 进度
+   - 看失败原因和阻塞点
+   - 实时打开日志和证据
+2. 复盘分析
+   - 查看 timeline、思路、利用路径、来源与修复主题
+   - 对比真实版本与 synthetic 复现差异
+3. 审阅归档
+   - 从一个前端入口点进 `report.md`, `report.html`, `run.json`, 原始日志和截图
+
+## 2. 页面定位
+
+### 2.1 页面名称
+
+- 页面名称：`Authorized Lab Dashboard`
+- 页面语境：本地静态前端 + 本地文件 JSON 数据源
+- 非目标：在线 SaaS、多用户后端、生产管理台
+
+### 2.2 核心原则
+
+- 所有展示都围绕授权目标
+- 失败信息不能被隐藏在深层页面里
+- 信息密度高，但必须可折叠、可筛选、可逐层展开
+- 日志与原始 JSON 必须能直接预览
+- 页面视觉应更生动，但不能牺牲扫描效率
+
+## 3. 信息架构
+
+```mermaid
+flowchart LR
+  A["Hero + Global Status"] --> B["Sidebar Filters"]
+  A --> C["Run Queue List"]
+  C --> D["Run Detail Hero"]
+  D --> E["Progress Timeline"]
+  D --> F["Attack Plan & Reasoning"]
+  D --> G["Evidence Explorer"]
+  D --> H["Live Log Viewer"]
+  D --> I["Sources & Fix Topics"]
+  D --> J["Raw JSON Panels"]
+```
+
+## 4. 页面布局
+
+### 4.1 顶部 Hero
+
+必须展示：
+
+- 页面名称
+- 授权实验语境说明
+- 刷新按钮
+- 自动刷新开关
+- 当前同步状态
+- 核心 metric cards
+
+视觉要求：
+
+- 不能是纯白表格页
+- 需要有分层背景、渐变光晕、轻微动态氛围
+- 顶栏 sticky，滚动时仍可看到刷新和状态
+
+### 4.2 左侧侧栏
+
+包含四块：
+
+- Filters
+  - 搜索
+  - system filter
+  - status filter
+  - profile filter
+- Systems
+  - 系统覆盖度
+  - browser evidence 覆盖
+  - latest update
+- Recent Failures
+  - 最近 blocker
+  - status
+  - 原因摘要
+- Run Queue View
+  - 最近 run 卡片列表
+  - 可选中并切换到 detail panel
+
+### 4.3 右侧 Detail Workspace
+
+必须包含：
+
+- Run Hero
+  - advisory 标题
+  - system / profile / artifact / verification 状态
+  - report / bundle / markdown 入口
+- Progress Timeline
+  - 每一步的时间、状态、说明
+- Attack Plan & Reasoning
+  - success criteria
+  - seed / attack notes
+  - failure reason
+  - 当前 blocker
+- Evidence Explorer
+  - reports
+  - compose
+  - browser evidence
+  - request logs
+  - container logs
+- Live Log Viewer
+  - 预览 text/json/html/image
+  - refresh preview
+  - open artifact
+- Sources & Fix Topics
+  - official source
+  - secondary sources
+  - aliases
+  - secure code topics
+- Raw JSON
+  - run JSON
+  - advisory JSON
+  - profile JSON
+
+## 5. 交互要求
+
+### 5.1 折叠 / 展开
+
+所有 detail 分区都应支持折叠：
+
+- Progress Timeline
+- Attack Plan & Reasoning
+- Evidence Explorer
+- Live Log Viewer
+- Sources & Fix Topics
+- Raw JSON sections
+
+折叠要求：
+
+- 默认展开常用分区
+- 次级原始数据可以默认收起
+- 折叠状态视觉要清晰，不靠小箭头弱提示
+
+### 5.2 Run 切换
+
+- 点击左侧 run card 后，右侧 detail panel 即时刷新
+- 当前选中项要有强视觉区别
+- URL hash 应保留 `#run=<id>`，方便直接打开特定 run
+
+### 5.3 Artifact 预览
+
+点击 artifact button 后：
+
+- JSON 自动格式化
+- 日志文件以 `<pre>` 方式显示
+- 图片以内联方式展示
+- HTML 报告可 iframe 预览或新窗口打开
+
+### 5.4 自动刷新
+
+- 默认每 5 秒刷新一次 dashboard JSON
+- 用户可以关闭自动刷新
+- 当前正在查看的 artifact 在自动刷新开启时应支持重新抓取
+
+### 5.5 失败原因高亮
+
+对于 `blocked-*` 和 `triage-manual`：
+
+- 顶部 hero 要显示状态 pill
+- reasoning 面板要显示 failure callout
+- 左侧 Recent Failures 要保留最近失败摘要
+
+## 6. 展示字段清单
+
+### 6.1 Hero 区
+
+- run_id
+- advisory_id
+- advisory title
+- verification_status
+- verification_mode
+- artifact_mode
+- system_id
+- repro_profile_id
+- finished_at
+
+### 6.2 Timeline 区
+
+- `timeline[].at`
+- `timeline[].step`
+- `timeline[].status`
+- `timeline[].detail`
+
+### 6.3 Reasoning 区
+
+- advisory summary
+- profile seed messages
+- profile attack messages
+- profile success criteria
+- blocked reason
+
+### 6.4 Sources 区
+
+- official_source_url
+- secondary_source_urls
+- aliases
+- secure_code_topics
+
+### 6.5 Evidence 区
+
+- report.html
+- report.md
+- timeline.mmd
+- bundle json
+- compose.yaml
+- browser screenshots / DOM / console / network
+- request logs
+- container logs
+
+## 7. 动效与视觉要求
+
+### 7.1 必须有的视觉增强
+
+- 顶部背景渐变和环境光
+- status pill 发光色彩区分
+- 卡片 hover 浮起
+- sticky hero
+- 折叠面板开合层次
+- gallery 缩略图点击查看
+
+### 7.2 推荐但必须受控
+
+- 状态小圆点 pulse
+- 背景网格或轻微数据面纹理
+- 面板玻璃感和浅透视阴影
+
+### 7.3 不允许
+
+- 花哨但影响可读性的动画
+- 大面积纯装饰 3D 效果
+- 自动播放噪音式动效
+- 让日志区难以复制文本的视觉处理
+
+## 8. 实时日志与细节查看要求
+
+### 8.1 日志查看器
+
+日志查看器必须支持：
+
+- 选中文件后即刻预览
+- JSON 格式化
+- text/json/html/image 四类预览
+- 打开原文件
+- 在自动刷新开启时重新抓取当前文件
+
+### 8.2 重点要看的日志
+
+- compose / environment 文件
+- baseline / attack / browser json
+- container logs
+- request logs
+- timeline / bundle
+
+### 8.3 失败排查导向
+
+失败时应优先展示：
+
+- `blocked_reason`
+- 当前 step
+- 上一个完成 step
+- 当前可打开的日志 / 报告 / run bundle
+- 对应 advisory 来源与 profile success criteria
+
+## 9. 数据源契约
+
+前端依赖的本地 JSON/文件源：
+
+- `summary.json`
+- `runs.json`
+- `systems.json`
+- `advisories.json`
+- `profiles.json`
+- `runs/<run-id>/report.html`
+- `runs/<run-id>/report.md`
+- `runs/<run-id>/run.json`
+- `runs/<run-id>/logs/*`
+- `runs/<run-id>/assets/*`
+
+前端不直接写这些数据，只读取并展示。
+
+## 10. 落地约束
+
+- 保持静态前端，不引入长期运行后端
+- 本地 `serve-dashboard` 即可查看
+- 对于正在跑的 case，前端通过轮询读取新 JSON 实现“近实时”
+- 不依赖第三方 CDN UI 库
+- 优先使用原生 HTML/CSS/JS，可长期维护
+
+## 11. 验收标准
+
+页面完成后，应满足：
+
+- 能从 run list 切换到 detail panel
+- 能折叠与展开各信息区
+- 能打开并预览 JSON / text / image / html artifact
+- 能看到失败原因、思路、来源、修复主题
+- 能筛选 system / status / profile
+- 能在自动刷新开启时重新载入 dashboard 数据
+- 页面视觉比“普通表格页”更生动，但仍适合高密度阅读
--- a/docs/project-features.md
+++ b/docs/project-features.md
@@ -0,0 +1,162 @@
+# 项目功能与特性总览
+
+> `LAB ONLY` | `AUTHORIZED TARGETS ONLY`
+
+## 1. 项目定位
+
+`websafe` 是一套“授权攻防实验与研究知识库 + 本地实证系统”。它不是生产安全基线库，也不是面向任意第三方站点的扫描平台。
+
+项目覆盖：
+
+- 本地靶场、Docker 集群、内网实验节点
+- 自建且可公网访问的测试网站、服务器、设备
+- 已明确授权的验证性测试目标
+
+项目不覆盖：
+
+- 无归属证明、无授权的公网资产
+- 公共知名网站
+- 泛互联网画像、枚举、对外大规模探测
+
+## 2. 功能版图
+
+### 2.1 情报与入库
+
+- `08-threat-intel/source-map.yaml`
+  - 定义系统范围、来源、覆盖策略、输出目录、secure-code 主题
+- `08-threat-intel/repro-map.yaml`
+  - 定义系统到 repro family、浏览器要求、日志策略和报告模板的映射
+- `08-threat-intel/repro-profiles/`
+  - family 级和 advisory 级复现说明
+- `08-threat-intel/registry/`
+  - advisory、system、run、triage 的唯一真值层
+- `08-threat-intel/generated/`
+  - coverage matrix、latest ingest、dashboard 等人类可读产物
+
+### 2.2 本地实证与编排
+
+- `00-environments/catalog/`
+  - 记录系统、镜像、源码、依赖和健康检查的 catalog
+- `00-environments/profiles/`
+  - 记录具体版本或 current profile 的 compose / baseline / seed 参数
+- `scripts/lab/main.py`
+  - 唯一 lab CLI 入口
+- `scripts/lab/`
+  - `catalog`, `provision`, `compose`, `seed`, `baseline`, `attack`, `browser`, `evidence`, `render`, `queue`, `validators`
+
+### 2.3 攻击验证工具
+
+- `01-sql-injection/`
+  - `sqli-scanner.py`, `blind-sqli.py`, `sqli-exploit.go`
+- `02-xss/`
+  - `xss-fuzzer.py`, `xss-scanner.go`
+- `03-authentication/`
+  - `web-brute.py`, `jwt-cracker.py`, `session-lab.py`
+- `04-server-security/`
+  - `port-scanner.py`, `tls-scanner.py`, `site-scope-mapper.py`, `misconfig-lab.py`
+
+### 2.4 结果展示
+
+- `06-case-studies/generated-runs/<run-id>/`
+  - `report.md`, `report.html`, `timeline.mmd`, `assets/`, `logs/`
+- `08-threat-intel/generated/dashboard/`
+  - 静态前端工作台
+- `07-framework-security/`
+  - 系统级 README、INDEX、案例页，自动显示本地实证状态
+
+## 3. 数据流与自动化链路
+
+```mermaid
+flowchart LR
+  A["Threat Intel Sources"] --> B["registry/advisories"]
+  B --> C["repro-map + repro-profiles"]
+  C --> D["00-environments catalog/profiles"]
+  D --> E["scripts/lab run-case / run-batch"]
+  E --> F["generated-runs/<run-id>"]
+  F --> G["registry/runs"]
+  G --> H["case pages / system INDEX"]
+  G --> I["dashboard JSON + local UI"]
+  H --> J["README / docs / PR"]
+  I --> J
+```
+
+## 4. 关键特性
+
+### 4.1 完整覆盖语义
+
+- 每条 advisory 至少进入 `registry/advisories`
+- 每条 advisory 必须有明确的实证状态
+- 状态只允许：
+  - `verified-real`
+  - `verified-synthetic`
+  - `blocked-artifact`
+  - `blocked-destructive`
+  - `triage-manual`
+
+### 4.2 浏览器证据强制
+
+- XSS、DOM XSS、Token 存储、前端路由绕过、前端配置暴露等浏览器类 case
+  - 必须生成截图
+  - 必须生成 DOM 快照
+  - 必须生成 console / network 证据
+  - 没有浏览器证据不得升级为 `verified-*`
+
+### 4.3 受控攻击语义
+
+- 默认模式是 `minimal-proof`
+- 只读探测、最小化注入、可审计回显、可回滚验证
+- 破坏性利用、越权下载真实数据、不可回滚行为默认禁用
+
+### 4.4 双展示面
+
+- 静态归档报告
+  - 适合证据留存、归档、PR 审阅
+- 本地前端工作台
+  - 适合实时查看进度、日志、失败原因、来源、思路、截图和原始 JSON
+
+### 4.5 自动化提交
+
+- `scripts/intel/run-hourly.sh`
+  - hotlane ingest + hotlane repro
+- `scripts/intel/run-nightly.sh`
+  - 常规 ingest + batch repro + render + validate + PR
+- `scripts/intel/run-weekly-reconcile.sh`
+  - reconcile + retry failures + rerender + validate + PR
+
+## 5. CLI 能力
+
+### 5.1 Intel CLI
+
+```bash
+python3 /Users/x/websafe/scripts/intel/main.py hotlane
+python3 /Users/x/websafe/scripts/intel/main.py ingest --since last-success
+python3 /Users/x/websafe/scripts/intel/main.py reconcile
+python3 /Users/x/websafe/scripts/intel/main.py render
+python3 /Users/x/websafe/scripts/intel/main.py validate
+python3 /Users/x/websafe/scripts/intel/main.py open-pr --dry-run
+```
+
+### 5.2 Lab CLI
+
+```bash
+python3 /Users/x/websafe/scripts/lab/main.py catalog sync
+python3 /Users/x/websafe/scripts/lab/main.py validate
+python3 /Users/x/websafe/scripts/lab/main.py run-case --case gitea--CVE-2025-68939
+python3 /Users/x/websafe/scripts/lab/main.py run-case --case nextjs--CVE-2025-29927 --dry-run
+python3 /Users/x/websafe/scripts/lab/main.py run-batch --limit 10
+python3 /Users/x/websafe/scripts/lab/main.py serve-dashboard --port 8734
+```
+
+## 6. 前端工作台当前目标
+
+前端不只是“一个结果页”，而是本地实验控制台与证据阅读器。它需要：
+
+- 快速定位系统 / advisory / repro profile
+- 折叠与展开 timeline、evidence、sources、raw JSON
+- 直接查看 compose、JSON、日志、截图、报告
+- 高亮失败原因、当前 blocker、利用思路、成功判据
+- 自动刷新生成数据，适配正在进行中的本地 run
+
+详细设计见：
+
+- [本地前端工作台设计文档](/Users/x/websafe/docs/frontend-dashboard-design.md)