# 项目功能与特性总览

> `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/`
  - 静态前端工作台
  - `/index.html` 为本地化 Lovart 正式 UI
  - `/legacy/index.html` 为旧版工作台回退入口
  - `/docs/*.html` 为本地可访问的说明、真值配置与设计镜像页
  - `architecture.json` 为当前架构库结构化真值
- `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)

当前地址布局固定为：

- `/index.html`
  - 默认新 UI，基于本地化 Lovart 视觉壳层，绑定真实 dashboard JSON
- `/legacy/index.html`
  - 旧版工作台显式保留，用于快速回退和对照
- `/docs/design-source.html`
  - 设计来源、vendor manifest 与本地化说明