hardikpatel29/DarkLens
GitHub: hardikpatel29/DarkLens
DarkLens 是一个自动化检测网站暗黑模式的可解释框架，融合 DOM 规则、NLP 分类和计算机视觉来标记操纵性设计并提供可验证证据。
Stars: 0 | Forks: 0
# DarkLens
DarkLens 是一个用于自动化检测和报告网站 dark patterns 的框架。它结合使用 DOM 规则检查、NLP 分类和计算机视觉来分析网页，以清晰且可验证的证据标记具有操纵性的设计模式。
每项发现都包含了触发它的确切 DOM 元素、规则匹配、模型预测或视觉边界框。
## 当前状态
核心 pipeline、规则引擎、融合系统、API、CLI 和报告工具已完全构建并测试完毕。机器学习模型（NLP 和 CV）已集成到架构中，如果不存在训练好的权重，则提供降级支持。
| 组件 | 技术栈 / 方法 | 状态 |
|---|---|
| **核心架构** | Clean Architecture, Dependency Injection | ✅ 完成 |
| **页面捕获** | Playwright (Headless Chromium) | ✅ 完成 |
| **规则引擎** | 确定性 DOM 和 CSS 检查（4 条规则） | ✅ 完成 |
| **NLP 分类器** | DistilBERT（在 Mathur/Yamana 数据集上微调） | ✅ 完成（F1 Macro: 97.8%, Precision: 97.7%） |
| **CV 检测器** | YOLOv8 + EasyOCR（视觉 UI 元素） | 🟡 代码已完成（数据集标注待定） |
| **证据融合** | 概率 Noisy-OR + 规则下限 | ✅ 完成 |
| **报告与导出** | JSON, HTML, CSV, PDF（Playwright PDF 渲染） | ✅ 完成 |
| **CLI 和 API** | FastAPI, argparse, Docker | ✅ 完成 |
如果 `models/` 中不存在训练好的模型权重，系统会优雅地禁用这些检测器，并使用规则引擎运行，而不会崩溃：
```
python -c "from darklens.container import build_detectors; print([d.name for d in build_detectors()])"
# Output: ['rule_engine']
```
## 项目结构
代码库严格遵守 Clean Architecture 原则：
```
src/darklens/
├── domain/ # Core business logic, entities, & rule interfaces (zero external ML dependencies)
├── application/ # Orchestration, use cases, ports, & evidence fusion engine
├── infrastructure/ # Concrete implementations (Playwright, PyTorch, YOLO, EasyOCR, Reports)
├── interfaces/ # FastAPI web service & CLI entry points
└── container.py # Composition root for dependency injection
```
第三方依赖（Playwright、PyTorch、Ultralytics、EasyOCR）被严格隔离在 ports 之后，因此 domain 和 application 层保持整洁，并且无需安装繁重的依赖即可进行测试。
## 快速开始
### 前置条件
* Python 3.10+
* Playwright 和 Chromium 浏览器二进制文件
### 设置
```
# Clone 仓库
git clone https://github.com/hardikpatel29/DarkLens.git
cd DarkLens
# 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
# 安装 Playwright 浏览器
playwright install chromium
```
## 快速入门
### 1. 通过 CLI 运行
扫描网站并生成 JSON、HTML、CSV 或 PDF 格式的报告：
```
python -m darklens.interfaces.cli.main https://example.com --formats json,html,csv,pdf
```
报告将保存到 `data/reports/`。
### 2. 运行 API 服务器
启动 FastAPI 服务器以访问 REST endpoints 和交互式 Swagger UI：
```
uvicorn darklens.interfaces.api.main:app --reload
```
可通过 `http://localhost:8000` 访问的 Endpoints：
* `POST /api/v1/scan` — 返回原始 JSON `ScanResult`
* `POST /api/v1/scan/report` — 渲染 HTML 报告
* `POST /api/v1/scan/report.pdf` — 下载 PDF 报告
### 3. 使用 Docker 运行
在容器中启动整个应用程序：
```
docker compose up --build
```
## 测试与验证
运行单元测试（不需要浏览器或庞大的机器学习库）：
```
pytest tests/unit
```
运行集成测试（启动 headless Chromium 对本地 HTML fixtures 进行测试）：
```
pytest tests/integration
```
运行实时性能基准测试（测量扫描延迟、CPU 时间和 RAM 使用量）：
```
python scripts/benchmark.py https://example.com
```
## 模型训练与微调
`scripts/` 中提供了用于数据集准备和微调的脚本：
```
# 训练 NLP Classifier
python scripts/train_nlp_classifier.py \
--train-csv data/nlp/train.csv \
--val-csv data/nlp/val.csv \
--output-dir models/nlp_classifier
# 训练 CV Detector
python scripts/train_cv_detector.py \
--data data/cv/data.yaml \
--output-dir models/cv_detector
```
## 数据集引用
* **NLP 数据集：** 微调使用了来自 Mathur 等人的 dark pattern 语料库，*"Dark Patterns at Scale: Findings from a Crawl of 11K Shopping Websites"* (2019)，以及 Yamana Lab (`yamanalab/ec-darkpattern`, IEEE BigData 2022)。
* **CV 截图：** 使用自定义 Playwright 脚本在电子商务和旅游网站上收集，用于视觉模式标注。
标签：AV绕过, FastAPI, Playwright, Web分析, 云计算, 凭据扫描, 深色模式检测, 特征检测, 网络测绘, 规则引擎, 计算机视觉, 请求拦截, 逆向工具