EladMoshe98/ThreatScope

# 威胁范围 - 网络安全文档命名实体识别 这是一个本地化部署的本地服务，它使用 **SecureBERT-NER** 从文本中提取 **网络安全威胁情报实体**。它以两个 Docker 容器形式交付——一个托管模型的 FastAPI 服务和一个 Streamlit UI。 该模型是在 **DNRTI** 数据集上对 **SecureBERT-NER 与 CyNER**（以及作为额外数据点的 SecureBERT2.0-NER）进行基准测试后选出的——参见[基准测试](#benchmark)。 ## 功能说明 上传一个 `.txt` 文件 → 在两列表格中按类别获取所有命名实体，以及内联高亮显示实体的文本。SecureBERT-NER 可识别 21 种细粒度类别（威胁行为者、恶意软件、CVE、IP、域名、哈希、文件、时间、位置等）。 ## 仓库结构 ``` NERF/ ├── api/ FastAPI service — hosts SecureBERT-NER │ ├── ner_model.py load model, chunk long text, merge tokens → clean entities │ ├── validation.py input hardening (type / size / decode / control chars) │ ├── logger.py structured logging │ ├── log_store.py SQLite request log (metadata only) │ ├── routers/ predict · health · history │ └── main.py app + startup model warm-up + Swagger /docs ├── ui/streamlit_app.py Streamlit client (Analyze · Model Comparison · History) ├── models/ SecureBERT-NER weights (run scripts/download_model.py) — gitignored ├── logs/ runtime request log (bind-mounted, visible) — gitignored ├── scripts/download_model.py downloads the weights into models/ ├── benchmark/ PREP ONLY (never containerized) │ ├── benchmark.ipynb SecureBERT-NER vs CyNER vs SecureBERT2.0-NER on DNRTI │ └── DNRTI.rar the dataset ├── docker/ Dockerfile.api · Dockerfile.ui · docker-compose.yml ├── .streamlit/config.toml UI theme ├── requirements-api.txt · requirements-ui.txt └── .env.example ``` ## 快速开始 **前置条件：** Docker Desktop，以及 Python 3.11（仅用于一次性获取权重）。 ``` # 1. 将 model weights 下载到 models/ 目录中 （一次性操作，需要互联网） python scripts/download_model.py # 2. 构建并运行两个 containers （从 repo 根目录开始） docker compose -f docker/docker-compose.yml up --build ``` 然后打开： | | URL | |---|---| | **Streamlit UI** | http://localhost:8501 | | **API (Swagger 文档)** | http://localhost:8000/docs | 使用 `docker compose -f docker/docker-compose.yml down` 停止。 在权重被构建到镜像中后，正在运行的堆栈**不需要互联网连接**。 ## 使用 UI - **分析** — 上传一个 `.txt` 文件 → 生成两列表格（类别 → 实体）、内联高亮文本、单文件延迟，以及 CSV/JSON 下载。参考表格解释了每个实体类别的含义。 - **模型对比** — DNRTI 基准测试摘要以及选择 SecureBERT-NER 的原因。 - **历史记录** — 最近的请求（仅元数据；绝不存储上传的文本）。 ## API | 方法 | 路径 | 描述 | |---|---|---| | `POST` | `/predict` | 上传一个 `.txt` 文件 → 按类别分组的实体 | | `GET` | `/health` | 存活状态以及模型是否已加载 | | `GET` | `/history?limit=N` | 最近的请求元数据 | | `GET` | `/docs` | 交互式 Swagger UI | ``` curl -F "file=@report.txt;type=text/plain" http://localhost:8000/predict ``` ``` { "filename": "report.txt", "num_entities": 4, "latency_ms": 88.8, "entities_by_class": { "APT": ["APT32"], "MAL": ["Cobalt Strike"], "IP": ["109.248.148.42"], "TIME": ["April 2018"] }, "entities": [ { "text": "APT32", "label": "APT", "start": 3, "end": 8, "score": 0.93 }, ... ] } ``` ## 基准测试 打开 `benchmark/benchmark.ipynb`（最好在 **Google Colab** 中运行——CyNER 在那里可以顺利安装；也可以在本地运行）。通过笔记本的上传框上传 `DNRTI.rar`，然后从头到尾运行。它会报告精确率 / 召回率 / F1（每个类别 + 总体）、延迟和模型占用量，并保存结果 JSON 和图表。 **结果（662 个 DNRTI 测试句子）：** | 模型 | F1 (micro) | 精确率 | 召回率 | 参数量 | |---|---|---|---|---| | **SecureBERT-NER** | **0.70** | 0.70 | 0.70 | 124M | | CyNER-base | 0.27 | 0.38 | 0.20 | 277M | | SecureBERT2.0-NER | 0.14 | 0.12 | 0.17 | 150M | **决策 — SecureBERT-NER：**最准确（2–5倍）、最快、最小，且是唯一涵盖时间/区域的模型。它是在 APTNER 上微调的，其分类法与 DNRTI 高度匹配，因此最适合此类数据。 （*CyNER-large 被跳过——其训练权重从未公开发布。*） ## 配置 所有参数均为可选（应用程序使用默认值运行）。参见 `.env.example`。关键变量： | 变量 | 默认值 | 使用方 | |---|---|---| | `NER_MODEL_PATH` | `models/securebert-ner` | API — 存放内置权重的位置 | | `MAX_FILE_SIZE_MB` | `2` | API — 上传大小限制 | | `LOG_LEVEL` / `LOG_FILE` / `LOG_DB_PATH` | `INFO` / `logs/nerf.log` / `logs/requests.db` | API 日志记录 | | `API_URL` | `http://api:8000` | UI — 访问 API 的位置 | ## 设计说明 - **离线 / 本地化部署：**模型权重在构建时被复制到 API 镜像中；容器自带副本，在运行时绝不向外发起调用。 - **输入加固：**仅限 `.txt`，有大小限制，安全的 UTF-8 解码，控制字符剥离；UI 在显示前对上传的文本进行 HTML 转义（防止脚本注入）。 - **隐私：**请求日志仅存储元数据（文件名、延迟、实体计数、状态）——绝不存储上传的文档文本。 - **双容器：**模型服务和 UI 是解耦的，因此 API 可以独立使用（curl / Swagger / 其他客户端），并且两者可以分别进行扩展。 - 已确保防范 XSS。 ## 已知限制 / 未来工作 - 无身份验证（假设为单租户本地部署）。 - 超长文档会在空白处进行分块，以确保不超过模型 512-token 的限制。 - CyNER-large 未进行基准测试（权重不可用）；集成多种模型可能是未来的 v2 版本。 - 暂不支持多用户友好。

标签：AI, AV绕过, Docker, FastAPI, Kubernetes, Streamlit, 命名实体识别, 威胁情报, 安全防御评估, 开发者工具, 网络安全, 网络测绘, 自动化代码审查, 访问控制, 请求拦截, 逆向工具, 隐私保护