SuricataLog v1.1.6
解析、过滤和可视化 Suricata eve.json 日志，使用 CLI 工具处理警报、流量、DNS 和负载。包含一份用于学习 Suricata 和测试规则的教程。
SuricataLog
当我开始学习如何使用 Suricata 时，很快发现需要一个工具来检查 eve.json 文件；网上大多数教程和文档都建议安装一套环境来完成以下任务：
- 将日志集中存储
- 对事件（尤其是告警）进行标准化和丰富化
- 使用前端界面来深入分析数据
这非常有用，但如果我只是想快速查看事件呢？
迟早你会对像下面这样做而感到 无聊透顶：
cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode
SuricataLog 是一组用于解析和显示 Suricata 日志文件（如 /var/log/suricata/eve.json）的工具/脚本。
Eve JSON 格式 并不复杂，所以我编写了几个脚本，功能覆盖我认为对家庭网络分析最有用的方面。
作为额外内容，我将自己的学习经历写成了一篇 教程，你可以用它来学习 Suricata 以及如何测试它。
从 PIP 安装
在开始之前，请确保你的环境配置正确：
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
从 Pypi.org 安装
pip3 install --upgrade SuricataLog
从源码安装
git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade build
python3 -m build
pip3 install dist/SuricataLog-X.Y.Z-py3-none-any.whl
开发者安装
你想贡献代码？或者发现了 bug 并认为自己可以提交补丁？太好了！以下是开发模式下的安装步骤：
git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
pip install --upgrade pip
python -m pip install --upgrade build
pip install textual-dev
pip install --editable .
之后运行单元测试非常简单：
(SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py
.........
----------------------------------------------------------------------
Ran 9 tests in 0.334s
OK
如果单元测试失败，那多半是解决问题的首要入手点。
我还建议运行 textualize 控制台并查看控制台消息：
# textual console
textual console --exclude SYSTEM --exclude EVENT
然后在另一个终端中运行：
textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json
这会将调试消息打印到控制台（如果使用 '--exclude DEBUG' 重启控制台，可以排除这些消息）。
创建 Docker 镜像
请查看 DOCKER.md 了解更多详情。
运行脚本
一旦所有内容都安装在你的虚拟环境中，你应该能够调用这些脚本。
你可以通过自动补全来查看安装了哪些应用程序，激活虚拟环境后：
eve_[tab][tab]
如果你安装了 Bash 自动补全扩展，还会得到一些标志的提示。
简单的 EVE 日志解析器
最好亲自看看（记住，使用 --help 了解支持哪些选项）
表格格式：
eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json
使用 eve_json.py 的预定义报告
(suricatalog) [josevnz@dmaf5 SuricataLog]$ eve_json --help
usage: eve_json [-h] [--nxdomain | --payload | --flow | --netflow NETFLOW | --useragent] eve [eve ...]
该脚本受 [15.1.3. Eve JSON ‘jq’ 示例](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) 的启发。注意：* 输出使用彩色 JSON
位置参数:
eve 要解析的一个或多个 /var/log/suricata/eve.json 文件的路径。
可选参数:
-h, --help 显示此帮助信息并退出
--nxdomain 显示 NXDOMAIN 的 DNS 记录
--payload 显示包含可打印负载的告警
--flow 按协议和目标端口聚合的流量报告
--netflow NETFLOW 获取指定 IP 地址的网络流
--useragent HTTP 流量中最常用的用户代理
下面是一些示例：
NXDOMAIN
eve_json --nxdomain test/eve.json
PAYLOAD
eve_json --payload ~/Downloads/eve.json
FLOW
eve_json --flow test/eve_udp_flow.json
NETFLOW
eve_json --netflow 224.0.0.251 test/eve_udp_flow.json
USERAGENT
eve_json --useragent test/eve.json
在浏览器中运行 eve_* 应用程序
你可以通过使用 eve_server 包装器在浏览器中运行 Suricata Log 应用程序：
# 显示 eve.json 文件中的流量报告
eve_server --application eve_json -- --flow ~/eve.json
# 显示 NX 域报告
eve_server --application eve_json -- --nxdomain ~/eve.json
# 检查 eve.json 记录
eve_server --applications eve_log -- ~/eve.json
你需要传递 '--' 来告知服务器这些选项属于要调用的底层 eve_*。
从 Docker 运行
也可以从 Docker 容器运行 SuricataLog。请查看 DOCKER.md 了解更多详情。
使用 uv 运行
如果你有 uv，可以这样操作：
uvx --from SuricataLog eve_log /var/log/suricata/eve.json
uvx --from SuricataLog eve_json --useragent /var/log/suricata/eve.json
uvx --from SuricataLog eve_server --application eve_json -- --flow /var/log/suricata/eve.json
你应该明白了。
Bash 自动补全
我尽力遵循 8.6 Programmable Completion
我为最常见的标志提供了自动补全。你可以通过向任何脚本传递 '--help' 来了解所有标志。
安装自动补全命令
你可以为所有 SuricataLog 脚本安装 Bash 自动补全。只需运行 'eve_autocomplete' 并按照指示操作：
eve_autocomplete --help
支持的版本
我 在业余时间 从事这个项目，无法支持所有 Linux/Python 组合。以下是我当前的测试环境，可能随时更改而无事先通知。
| SuricataLog | 是否支持 | 操作系统 | Python | Suricata |
|---|---|---|---|---|
| <= 0.8 | 否 | 不适用 | < 3.8 | 6.04 |
| 0.9+ | 否 | fedora 37 | => 3.11.4 | 6.04 |
| 0.9+ | 否 | Armbian 23.02.2 Jammy | => 3.10.6 | 6.04 |
| 0.9+ | 否 | Ubuntu 20.04.4 LTS (Focal Fossa) | => 3.8.10 | 6.04 |
| 1.0.3+ | 是 | fedora 40 | => 3.11.4 | 7.0.6 |
非常欢迎你：
- 提交包含新功能和 bug 修复的补丁。
- 提交详细的 bug 报告。请尽可能详细，否则我别无选择只能关闭它。