jnthans/wazuh-proofpoint

# Proofpoint TAP Wazuh 集成 这是一个 Wazuh wodle，通过 Proofpoint TAP API 将 Proofpoint Targeted Attack Protection (TAP) 的**威胁事件**和**人员情报**采集到 Wazuh SIEM 中。 ## 仪表板  *Wazuh Threat Hunting 仪表板按集成 `proofpoint` 过滤，显示了已采集事件及其严重级别、规则 ID 和描述。*  *Proofpoint TAP 仪表板 —— 按状态统计的消息、允许的点击、隔离数量、顶级威胁 URL、源 IP、收件人和 VAP 用户。* ## 功能特性 - **全覆盖威胁状态** — 在每个时间窗口的单次 API 调用中获取所有三个 `threatStatus` 值（active, cleared, falsePositive）。 - **六种事件类型** — 被拦截的消息、已投递的消息、被拦截的点击、允许的点击、VAP 用户、顶级点击者。 - **单一 wodle 配置块** — 一个定时命令同时驱动 SIEM 和 People API 轮询。People 的采集节奏通过状态文件在内部管理。 - **自动追赶机制** — 超过 1 小时的间隔会被分块为顺序的 API 调用，并对每个块进行检查点保存。追赶过程中发生超时绝不会丢失进度。 - **独立故障隔离** — SIEM API 故障绝不会阻止 People 获取，反之亦然。每次故障都会生成一个结构化的错误事件。 - **原子状态管理** — 使用 `tempfile` + `os.replace` 确保写入过程中进程被终止不会损坏状态。 - **安全凭证链** — systemd 加密凭证 > `.secrets` 文件 > 环境变量。凭证永远不会被记录。 - **真正的嵌套 JSON** — `threatsInfoMap`、`messageParts`、`identity` 和统计信息作为原生 JSON 对象输出，无需预处理即可实现丰富的 OpenSearch 查询。 - **零外部 Python 依赖** — 仅使用标准库。 ## 安装说明 1. 将 `wodle/*` 复制到 Wazuh manager 上的 `/var/ossec/wodles/proofpoint/`。根据 `.secrets.example` 创建 `.secrets` — 设置 `PP_PRINCIPAL` 和 `PP_SECRET`。设置权限 `chmod 640, chown root:wazuh`。 2. 将 `rules/proofpoint_rules.xml` 复制到 `/var/ossec/etc/rules/`，将 `rules/proofpoint_decoder.xml` 复制到 `/var/ossec/etc/decoders/`。 3. 使用 [artifacts/configs/ossec_proofpoint.conf](artifacts/configs/ossec_proofpoint.conf) 中的示例，向 `/var/ossec/etc/ossec.conf` 添加一个 wodle 配置段。 4. 重启 Wazuh manager。 5. *（可选）* 通过 **Dashboard Management > Saved Objects > Import** 将 `artifacts/objects/proofpoint_tap_dash.ndjson` 导入 Wazuh/OpenSearch。这将添加 Proofpoint TAP 仪表板及其 9 个可视化组件。 有关 ossec.conf 示例，请参阅 [artifacts/configs/](artifacts/configs/)。Docker Compose 卷映射位于 [artifacts/overrides/](artifacts/overrides/)。 ## 仓库结构 ``` wazuh-proofpoint/ ├── wodle/ │ ├── proofpoint.py <- Entry point, CLI, orchestration │ ├── proofpoint_siem.py <- SIEM API module (messages + clicks) │ ├── proofpoint_people.py <- People API module (VAP + top clickers) │ ├── proofpoint_utils.py <- Auth, HTTP, atomic state, emit, logging, secrets │ ├── run.sh <- Runtime config wrapper (ossec.conf target) │ └── .secrets.example <- Credentials template (copy to .secrets) ├── rules/ │ ├── proofpoint_rules.xml <- Custom Wazuh rules (IDs 100600-100699) │ └── proofpoint_decoder.xml <- JSON decoder registration ├── artifacts/ │ ├── configs/ │ │ └── ossec_proofpoint.conf <- ossec.conf wodle stanza example │ ├── guides/ │ │ ├── configuration.md <- All env vars, CLI flags │ │ ├── rules-reference.md <- Rule catalog with field reference │ │ └── troubleshooting.md <- Test commands, common errors │ ├── objects/ │ │ └── proofpoint_tap_dash.ndjson <- OpenSearch dashboard export (9 visualizations) │ ├── overrides/ │ │ └── docker-compose.single-node.override.yml <- Docker volume mappings │ └── images/ │ ├── wazuh_pp_events_pv.png <- Threat Hunting screenshot │ └── wazuh_pp_tap_dash_pv.png <- TAP dashboard screenshot ├── CHANGELOG.md └── README.md ``` ## 工作原理 ``` ossec.conf └-> run.sh (sets runtime config; execs proofpoint.py) └-> proofpoint.py (parses args, loads state) ├-> proofpoint_siem.py -> http_get() -> emit() -> stdout └-> proofpoint_people.py -> http_get() -> emit() -> stdout | proofpoint_utils.py (auth, HTTP, atomic state, emit, secrets) | Secret priority chain (first match wins): [systemd $CREDENTIALS_DIRECTORY] > [.secrets file] > [env vars] stdout --> Wazuh wodle manager --> proofpoint_decoder.xml --> proofpoint_rules.xml | OpenSearch / Dashboard ``` 每个事件以单行 JSON 形式输出。所有 Proofpoint 数据都位于 `pp` 命名空间对象下，以避免与 Wazuh 的保留字段名冲突。在规则中，字段引用为 `pp.event_type`、`pp.senderIP` 等。在 OpenSearch 中，它们显示为 `data.pp.event_type`、`data.pp.senderIP`。 ## 系统要求 - Wazuh 4.4 或更高版本 - Wazuh manager 主机或 agent 上安装了 Python 3.8 或更高版本 - 网络可通过 HTTPS（端口 443）访问 `tap-api-v2.proofpoint.com` - Proofpoint TAP 服务主体和密钥 ## 参考文档 - [配置参考](artifacts/guides/configuration.md) — 所有环境变量、CLI 标志、多租户设置 - [规则参考](artifacts/guides/rules-reference.md) — 规则族、严重性映射、字段参考 - [故障排除](artifacts/guides/troubleshooting.md) — 测试命令、常见错误、状态重置、回填

标签：API 集成, asyncio, ATT&CK 框架, CISA项目, FTP漏洞扫描, HTTP/HTTPS抓包, Proofpoint TAP, Python, SIEM 集成, SOC 运维, Wazuh, Wodle, 不可变基础设施, 威胁情报, 安全编排, 开发者工具, 态势感知, 数据摄取, 无后门, 日志采集, 目标攻击防护, 逆向工具, 邮件安全