dr4gon123/flores

# FLORES — FortiGate 日志消息参考抓取器 FLORES 从 Fortinet 官方的 Log Message Reference 文档中提取 FortiGate 日志字段文档，并将其转换为整洁、结构化的 CSV 数据集。它专为需要机器可读的 syslog schema 以进行解析器开发、日志规范化或字段参考的安全工程师和数据团队而设计。 Schema 规范化使得防火墙日志在现代安全体系中变得可查询、可关联且可操作。将 FortiGate 日志字段针对 ECS、OCSF 或自定义 schema 进行规范化，需要跨越 Traffic、Event 和 UTM 日志类型中数百个 LOGID 的确切字段名称、数据类型和描述——而这些信息被 Fortinet 分散在了各个次要版本的文档页面中。 FLORES 提供了完整的 pipeline：收集、整合并追踪次要版本间的 schema 变化，然后将其转换为准备好用于您的规范化工作流的 ECS 和 OCSF 字段映射。 ## 快速开始 所有抓取的数据和生成的输出均已提交到此仓库中——您可以直接使用这些 CSV 和 Markdown 文件，无需运行任何内容。 要添加新的 FortiOS 版本或重新生成输出： ``` pip install httpx[http2] beautifulsoup4 pandas lxml pyyaml python3 fortigate_scraper.py # scrape Fortinet docs python3 generate_changelog.py # changelogs, field matrices, consolidated CSVs, INDEX.md python3 generate_ecs_mappings.py # ECS mapping CSVs ``` 输出将存放在当前工作目录下的大版本子目录（例如 `7.6/`）中。 ## 输出 ``` INDEX.md # root index: all versions, all sections {major}/ # e.g. 7.6/ INDEX.md # per-major index: changelog, fields, ECS, matrices {minor}/ # e.g. 7.6.4/ LOGID/ # one CSV per LOGID {LOGID_description}.csv CHANGELOG.md # intra-version conflicts + inter-version diffs traffic_matrix.csv # field × subtype occurrence counts event_matrix.csv utm_matrix.csv fields/ traffic_fields.csv # consolidated across all minor versions event_fields.csv utm_fields.csv action_descriptions.csv # UTM action field variants (one column per subtype) ECS/ traffic_ecs.csv # FortiGate fields mapped to ECS targets event_ecs.csv utm_ecs.csv ``` **`{LOGID_description}.csv`** — 从 Fortinet 文档中抓取的单个 LOGID 的原始日志字段表。 列：`Type`、`Log Field Name`、`Description`、`Data Type`。 **`fields/{log_type}_fields.csv`** — 聚合了该大版本下所有次要版本的某种日志类型的整合字段参考。当某个字段在不同 subtype 下有不同的描述时，每种变体都会被标记为 `subtype: description`。 **`CHANGELOG.md`** — 记录次要版本的更新日志，包含版本内描述冲突（相同字段名，跨 LOGID 的不同描述）和跨版本差异（自上一个次要版本以来添加或删除的字段和 LOGID）。 **`{log_type}_matrix.csv`** — field × subtype 矩阵，显示哪些字段出现在哪些 subtype 中，并附带出现次数。列标题是该版本确定的 subtype 列表。 ## 索引文件 两个层级的 `INDEX.md` 提供了进入该仓库的可导航入口： **[INDEX.md](INDEX.md)** — 涵盖所有大版本的根索引。对于每个大版本，它列出了： - **Changelog** — 指向各次要版本 `CHANGELOG.md` 的链接 - **Consolidated Fields** — 指向 `fields/{log_type}_fields.csv` 的链接 - **ECS** — 指向 `ECS/{log_type}_ecs.csv` 的链接 - **Field Occurrence Matrix** — 指向 `traffic_matrix.csv · event_matrix.csv · utm_matrix.csv` 的次要版本链接 **`{major}/INDEX.md`** (例如 [7.6/INDEX.md](7.6/INDEX.md)) — 作用域限定于单个大版本的相同章节，包含相对于该文件夹的链接。 这两个文件均由 `python3 generate_changelog.py --index` 自动生成。 ## Elastic Common Schema (ECS) 映射 FortiGate 字段通过对照 Elastic Common Schema (ECS) 进行交叉引用，以便用于 SIEM 的摄取和规范化。 | 日志类型 | 状态 | 输出 | |----------|--------|--------| | Traffic | 已映射 45/295 个字段 | `{major}/ECS/traffic_ecs.csv` | | Event | 已映射 22/404 个字段 | `{major}/ECS/event_ecs.csv` | | UTM | 已映射 51/567 个字段 | `{major}/ECS/utm_ecs.csv` | 在抓取新版本后，运行 `python3 generate_ecs_mappings.py` 以重新生成 ECS CSV。 有关映射表示法、覆盖范围详情、有意未映射的字段以及扩展映射的指南，请参见 [FIELD_NAMING_NORMALIZATION.md](FIELD_NAMING_NORMALIZATION.md)。 ## 配置 编辑 `fortigate_scraper_config.yaml` 以自定义行为： | 设置 | 默认值 | 效果 | |---------|---------|--------| | `base_delay` | `1.0` | HTTP 请求之间的秒数（速率限制） | | `max_retries` | `3` | 每个URL发生错误后的额外尝试次数（`0` = 不重试） | | `retry_backoff` | `2.0` | 指数退避乘数：`base_delay × (backoff ^ attempt)` | | `concurrency` | `5` | 每个版本的最大并行 LOGID 获取数（`asyncio.Semaphore`） | | `force_rescrape` | `false` | 重新抓取本地已存在的版本 | | `dry_run` | `false` | 仅记录抓取计划，不获取任何页面 | | `output_dir` | `"."` | 所有输出的根目录 | ## 添加新的 FortiOS 版本 在 `fortigate_scraper_config.yaml` 中的 `versions` 下添加一个新条目： ``` versions: - "7.6.7" ``` 除非设置 `force_rescrape: true`，否则 FLORES 将跳过本地已存在的版本。 ## FortiGate 文档说明 FortiGate 的日志 schema 在结构上具有异构性，这给规范化 pipeline 带来了复杂性。UTM subtype 是独立开发的：仅 `action` 字段在 16 个 subtype 中就具有不同的值和长度，并且其中六个 subtype 根本没有对其进行描述。GTP 日志在结构上与 UTM 的其余部分不兼容（字段类型冲突，约 150 个未记录字段）。该 schema 并非单向棘轮——在次要版本之间，字段和 LOGID 都会被添加和移除，且日志流中未嵌入任何版本字段。LOGID 分类法没有一致的规则：某些 subtype 将结果编码在单独的 LOGID 中（VideoFilter、DNS、CASB），其他则将其编码在 `action` 字段中（Anomaly、Virus），而 SIEM 必须知道 subtype 遵循哪种模式才能正确分类事件。 每一个结构性发现、字段冲突和 schema 演化细节都记录在 [ANALYSIS.md](ANALYSIS.md) 中，按日志类型组织，并包含 LOGID 分布、字段计数、跨类型冲突以及各次要版本更改计数的表格。 ## 面向开发者与维护者 请参阅 [DEVELOPERS_GUIDE.md](DEVELOPERS_GUIDE.md) 了解： - 架构概述和 pipeline 演练 - 数据流图（scraper → changelog → fields → ECS） - 关键方法参考 *对 FortiGate 不感兴趣？看看 [PALOS - PAN-OS 日志抓取器](https://github.com/dr4gon123/palos)*

标签：ECS, OCSF, PB级数据处理, Python, Terraform, 安全运维, 恶意代码分类, 数据清洗, 数据规范化, 无后门, 日志处理, 运行时操纵, 逆向工具, 防火墙日志