OzarkMountainPirate/suricata-elk
GitHub: OzarkMountainPirate/suricata-elk
一套将 pfSense/Suricata 的 EVE 日志通过 TCP 完整推送至自托管 ELK Stack 并进行 GeoIP 富化的端到端部署方案。
Stars: 0 | Forks: 0
# suricata-elk
通过 **TCP** 将 pfSense/Suricata 的 EVE 日志推送到自托管的 ELK stack，并
进行 GeoIP 富化以及配置受限（非超级用户）的摄入路径。本文档记录了在 **elk-host**（Debian，Docker host）上运行并由 **gateway**（运行 Suricata + syslog-ng 的 pfSense 防火墙）提供数据的
实际部署方案。
## 为什么会有这个项目 / 最关键的那个决策
Suricata 可以直接将 EVE JSON 发送到 syslog，但在 pfSense 上，该路径会经过内置的
`syslogd`，这会**在 1024 字节处截断 UDP 数据报**。超长的 DNS/QUIC/TLS 记录会在 JSON 解析到一半时被截断，导致 Logstash 抛出解析
错误。解决方法在于架构调整，而不是简单调整配置参数：
1. 将 Suricata 的 **EVE Output Type 设置为 `File`**（而不是 Syslog）。Suricata 会将
完整的 JSON 写入 `eve.json`。
2. 使用 **syslog-ng 轮询该文件**，并通过 **TCP** 将其转发给 Logstash，
同时剥离所有 syslog 帧格式（`template("${MESSAGE}\n")`），确保最终抵达的
是原始的换行符分隔的 JSON。
3. Logstash 使用 `json_lines` codec 和提升后的
`decode_size_limit_bytes` 来读取数据，确保数据再也不会被截断。
本仓库中的所有其他配置都源于此。
## 数据流向
```
pfSense (gateway) elk-host (Docker host)
+------------------------------+ +------------------------------+
| Suricata (WAN + LAN ifaces) | | |
| EVE output type: File | | |
| /var/log/suricata/.../ | | |
| eve.json | | |
| | | | |
| v | | Logstash (network_mode host)|
| syslog-ng | TCP 5514 | tcp input :5514 |
| source: tail eve.json | --------------> | json_lines codec |
| dest: network() tcp | (raw JSON, | drop non-EVE |
| template ${MESSAGE}\n | newline- | date -> @timestamp |
| | delimited) | geoip src_ip / dest_ip |
+------------------------------+ | | |
| v |
| Elasticsearch :9200 (local) |
| index suricata-YYYY.MM.dd |
| user: logstash_internal |
| | |
| v |
| Kibana (Traefik, TLS) |
| kibana.lan.example.com |
+------------------------------+
```
## 仓库结构
```
elastic/ The ELK compose stack (mirrors /opt/containers/elastic)
docker-compose.yml ES + Kibana + Logstash, final hardened state
.env.example Secret placeholders (copy to .env, never commit .env)
logstash/config/ logstash.yml
logstash/pipeline/ suricata.conf <- the ingest pipeline
es-setup/ One-time Elasticsearch bootstrap (run once)
bootstrap-es.sh Creates index template + scoped role + ingest user
patch-existing-index.sh Optional: geo_point mapping for a pre-existing index
index-template-suricata.json
role-logstash_writer.json
geo-mapping-existing-index.json
pfsense/syslog-ng/ syslog-ng object parameters for the pfSense package
nftables/ Snippet to permit TCP 5514 from the pfSense host
kibana/ Vega Sankey spec + dashboard notes (WIP)
docs/ Full step-by-step walkthrough (start at 01)
```
## 快速开始
[`docs/`](docs/) 中的完整指南才是真正的指导文档；简而言之：
1. **ELK stack** — `cp elastic/.env.example elastic/.env`，填入密钥，
执行 `docker compose up -d`。设置 `kibana_system` 密码并将其同步到
`.env` 中。([docs/02](docs/02-elk-stack-deploy.md))
2. **ES bootstrap** — 在 `elastic/` 目录下，运行 `../es-setup/bootstrap-es.sh` 来
创建 index template、`logstash_writer` 角色以及
`logstash_internal` 用户。([docs/06](docs/06-security-hardening.md),
[docs/07](docs/07-geoip-enrichment.md))
3. **pfSense Suricata** — 在每个受监控的
接口上将 EVE Output Type 设置为 **File**。([docs/03](docs/03-pfsense-suricata.md))
4. **syslog-ng** — 创建 source/destination/log 对象。
([docs/04](docs/04-syslog-ng-forwarding.md))
5. **防火墙** — 允许来自 pfSense 主机的 TCP 5514 端口访问 elk-host。
([docs/01](docs/01-architecture.md))
6. **Kibana** — 创建 `suricata` data view 并构建仪表板
(WIP)。([docs/08](docs/08-kibana-dashboards.md))
## 适配您的环境
将以下示例值替换为您自己的配置：
| 本仓库中的值 | 含义 |
|-------------------------------|------------------------------------------|
| `192.168.1.10` | elk-host (Logstash/ELK host) LAN 地址 |
| `192.168.1.1` | gateway (pfSense/syslog-ng host) |
| `kibana.lan.example.com` | 内部 Kibana 主机名 (Traefik) |
| `suricata_` | WAN Suricata EVE 目录 (见下文) |
| `suricata_` | LAN Suricata EVE 目录 |
| `` | 仪表板过滤器中使用的 LAN NIC 名称 |
Suricata EVE 目录的名称因实例而异。在
pfSense 主机上使用 `ls /var/log/suricata/` 查找您的目录。
## 版本控制
采用语义化版本控制；在仪表板尚未稳定期间版本号为 `0.x`。参见
[`CHANGELOG.md`](CHANGELOG.md)。带标签的发布版本标志着重要的里程碑。
## License
GPL-3.0-or-later。参见 [`LICENSE`](LICENSE)。
标签：ELK Stack, Metaprompt, pfSense, Suricata, syslog-ng, 内容过滤, 应用安全, 版权保护, 现代安全运营, 请求拦截, 越狱测试, 运维