rknightion/opnsense2otel

# opnsense2otel：针对 OPNsense 防火墙的 Prometheus 和 OpenTelemetry 监控 [](https://m7kni.io/opnsense2otel/) [](https://github.com/rknightion/opnsense2otel/releases) [](https://github.com/rknightion/opnsense2otel/blob/main/LICENSE) [](https://github.com/rknightion/opnsense2otel/actions)  [](https://scorecard.dev/viewer/?uri=github.com/rknightion/opnsense2otel) **一款用于 [OPNsense](https://opnsense.org/) 防火墙的可观测性 agent。** 它可以暴露 Prometheus metrics，通过 OTLP 推送原生 OpenTelemetry 的 metrics 和 logs，接收并 丰富 syslog，并将 NetFlow 和 Zenarmor 的 flow 记录转化为有边界的流量指标。 只需一个二进制文件、一个 API 用户，且防火墙上无需安装任何 agent。 📖 **[完整文档：m7kni.io/opnsense2otel](https://m7kni.io/opnsense2otel/)** ## 本项目实现了其他 OPNsense exporter 没有做到的功能 大多数 OPNsense exporter 仅抓取少量 endpoint 并且只提供 `/metrics`。本项目涵盖了 离开防火墙的全部四种遥测路径，外加一个本地控制台： | 功能 | 你能得到什么 | 文档 | |---|---|---| | **原生 OpenTelemetry** | 通过 OTLP 将 metrics **和** logs 推送到任何 collector 或 Grafana Cloud，无需进行 Prometheus 抓取。它不是 sidecar 或转换层。 | [OTLP 导出](https://m7kni.io/opnsense2otel/configuration/) | | **Syslog 接收器** | OPNsense 将日志推送到 exporter，后者会解析 `filterlog`、sshd、DHCP、HAProxy 和 Suricata 的日志行，并通过 API 使用规则描述、接口名称和主机名对其进行丰富。通用的 collector 可以接收这些日志行，但无法理解其内容。 | [Syslog 接收器](https://m7kni.io/opnsense2otel/syslog-receiver/) | | **Zenarmor 接收器** | 通过伪装成 Zenarmor 的 Elasticsearch 流式传输目标，直接从中提取单连接、DNS、TLS/SNI、HTTP 和威胁警报记录。这是从 Home-tier 设备中导出该数据的唯一方法，因为 Zenarmor 的 syslog 导出功能受许可证限制。 | [Zenarmor 接收器](https://m7kni.io/opnsense2otel/zenarmor-receiver/) | | **NetFlow 与流量** | NetFlow v5/v9 接收器和 Zenarmor 连接记录提供一个有边界的汇总，因此你可以从 Prometheus 中了解“多少流量、哪个接口、哪个方向、哪个应用类别”长达数年，而无需每天扫描数 GB 的日志。 | [流量](https://m7kni.io/opnsense2otel/flow/) | | **操作控制台** | 在 `/` 路径下内置了一个 Web UI，显示 collector 健康状况、基数、有效配置和已发现的设备，且无需为了渲染这些信息而去抓取防火墙。 | [架构](https://m7kni.io/opnsense2otel/architecture/) | 在此之下：涵盖跨 65 个 collector 的 1002 个 metrics，包括防火墙和 PF 统计信息、 接口、网关、VPN (WireGuard、OpenVPN、IPsec)、DHCP (Kea、Dnsmasq、ISC)、Unbound DNS、 证书和 ACME、硬件温度、SMART 磁盘健康状态、系统资源等。 数据收集与抓取过程已解耦：每个 collector 按其各自的波动级别进行轮询，而 `/metrics` 则重放最新的快照，因此缓慢的防火墙 API 永远不会阻塞抓取过程。 ## 快速开始 创建一个 OPNsense API 用户（参见下方的[权限](#opnsense-user-permissions)），然后： ``` docker run -p 8080:8080 \ -e OPN2OTEL_OPS_API_KEY=your-api-key \ -e OPN2OTEL_OPS_API_SECRET=your-api-secret \ ghcr.io/rknightion/opnsense2otel:latest \ --opnsense.protocol=https \ --opnsense.address=ops.example.com ``` 现在，metrics 位于 `http://localhost:8080/metrics`，而操作控制台位于 `http://localhost:8080/`。instance 标签默认为配置的 OPNsense 地址；设置 `--exporter.instance-use-hostname` 可根据 API 报告的主机名来推导它。 对于生产环境，建议使用基于文件的秘密，而不是普通的明文环境变量： ``` services: opnsense2otel: image: ghcr.io/rknightion/opnsense2otel:latest restart: always command: - --opnsense.protocol=https - --opnsense.address=ops.example.com environment: OPS_API_KEY_FILE: /run/secrets/opnsense-api-key OPS_API_SECRET_FILE: /run/secrets/opnsense-api-secret secrets: - opnsense-api-key - opnsense-api-secret ports: - "8080:8080" secrets: opnsense-api-key: external: true opnsense-api-secret: external: true ``` 完整操作指南：[入门指南](https://m7kni.io/opnsense2otel/getting-started/)。其他 部署方式：[Docker & Compose](https://m7kni.io/opnsense2otel/deployment/docker/) · [Kubernetes](https://m7kni.io/opnsense2otel/deployment/kubernetes/) (manifests 位于 [`deploy/k8s/`](./deploy/k8s/)) · [Systemd](https://m7kni.io/opnsense2otel/deployment/systemd/) ## OpenTelemetry 与日志传输 OTLP 导出与日志传输相互独立，并且默认均为关闭状态。 ``` # 通过 OTLP 推送 metrics 和 logs 以代替（或伴随） Prometheus scrape --otlp.enabled --otlp.endpoint=https://otlp-gateway.example.com/otlp # 从防火墙接收 syslog 并将丰富后的事件发送到 Loki --logs.enabled --logs.syslog.enabled --logs.syslog.listen-udp=0.0.0.0:5140 # 接收 Zenarmor flow、DNS、TLS 和 alert 记录 --logs.zenarmor.enabled --logs.zenarmor.listen-http=0.0.0.0:9200 # 接收 NetFlow v5/v9 --flow.netflow.enabled --flow.netflow.listen=0.0.0.0:2055 ``` 高基数事件数据（地址、端口、Suricata SID、域名）作为 log body 和 结构化元数据进行传输，绝不会作为 metric 标签，也绝不会作为 Loki 标签。请参见 [日志传输](https://m7kni.io/opnsense2otel/log-shipping/) 和 [流量](https://m7kni.io/opnsense2otel/flow/)。 ## 配置 所有内容均通过 CLI flags 或 `OPN2OTEL_*` 环境变量进行配置。每个 collector 都可以单独关闭 (`--exporter.disable-`)；少数高成本或 高基数的 collector 为选填项 (`--exporter.enable-`)。此外还支持 Grafana Cloud Pyroscope 的持续性能分析。 生成的 flag 和 collector 参考文档位于 [配置文档](https://m7kni.io/opnsense2otel/configuration/) 和 [collector 参考](https://m7kni.io/opnsense2otel/collectors/reference/) 中。 ## Grafana 仪表盘 两个交叉链接的动态仪表盘涵盖了 56 个标签页中的全部 1042 个 metrics，并会为你未运行的 collectors 和 OPNsense 插件自动隐藏标签页和行。通过 Grafana UI、`gcx` 或 GitOps，为防火墙本身导入 [`grafana/dashboard.json`](./grafana/dashboard.json)，并为 exporter 自身的健康状态导入 [`grafana/dashboard-health.json`](./grafana/dashboard-health.json)。告警 和记录规则随附在 [`grafana/alerts/`](./grafana/alerts/) 中。请参见 [`grafana/README.md`](./grafana/README.md) 和 [集成与仪表盘](https://m7kni.io/opnsense2otel/integration-dashboards/)。 ## OPNsense 用户权限 使用生成的 [collector 到 ACL 对照表](https://m7kni.io/opnsense2otel/security/#generated-collector-to-acl-matrix) 仅授予你启用的 collectors 所需的权限。它记录了已知的、依赖于插件的以及明确未知的映射关系，包括可用的权限是否也能执行写操作。 必需的 OPNsense 设置： - Unbound collector：必须启用 *Unbound DNS > Advanced > Extended Statistics*。 详情、401/403 错误的排查方法以及 ACL 注意事项：[安全性](https://m7kni.io/opnsense2otel/security/)。 ## 兼容性 支持当前和上一版本的稳定版 OPNsense 发行版。受插件限制的 collectors 在 缺少插件时会静默失效，而不是抛出错误。请参见 [兼容性](https://m7kni.io/opnsense2otel/compatibility/) 和 [升级](https://m7kni.io/opnsense2otel/upgrading/)。 ## 文档 | | | |---|---| | [入门指南](https://m7kni.io/opnsense2otel/getting-started/) | API 密钥、首次部署、验证 metrics | | [配置](https://m7kni.io/opnsense2otel/configuration/) | 每个 flag 和环境变量 | | [Metrics 参考](https://m7kni.io/opnsense2otel/metrics/metrics/) | 包含类型、标签和 PromQL 的全部 1002 个 metrics | | [Collectors](https://m7kni.io/opnsense2otel/collectors/) | 每个（共 65 个）collector 涵盖的内容 | | [部署](https://m7kni.io/opnsense2otel/deployment/) | Docker、Kubernetes、systemd | | [日志传输](https://m7kni.io/opnsense2otel/log-shipping/) | Syslog、Zenarmor、NetFlow、Loki | | [架构](https://m7kni.io/opnsense2otel/architecture/) | 轮询调度器、快照模型、操作控制台 | | [故障排除](https://m7kni.io/opnsense2otel/troubleshooting/) | 常见故障及解读方法 | ## Fork 声明 本项目起初是 [AthennaMind/opnsense-exporter](https://github.com/AthennaMind/opnsense-exporter) 的一个 fork，并且由于更改与上游不兼容，在早期就进行了硬 fork。感谢 AthennaMind 的作者提供 本项目所基于的原始 exporter。有关发布历史，请参见 [CHANGELOG.md](./CHANGELOG.md)。 ## 贡献 欢迎在 [issues](https://github.com/rknightion/opnsense2otel/issues) 和 [discussions](https://github.com/rknightion/opnsense2otel/discussions) 中提交 Bug 报告、问题和想法。 请参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 和 [开发文档](https://m7kni.io/opnsense2otel/development/contributing/)。关于 metrics 和配置的文档均由代码生成；在更改 flags 或 collectors 后，请运行 `make docs`。 ## 许可证 [Apache-2.0](./LICENSE)

标签：API集成, EVTX分析, GET参数, Go, OpenTelemetry, Ruby工具, 可观测性, 子域名突变, 日志审计, 日志采集, 用户代理, 自定义请求头, 请求拦截, 运维监控, 防火墙